From: Roberto Sassu <roberto.sassu@huawei.com>
To: <zohar@linux.ibm.com>, <gregkh@linuxfoundation.org>,
<mchehab+huawei@kernel.org>
Cc: <linux-integrity@vger.kernel.org>,
<linux-security-module@vger.kernel.org>,
<linux-doc@vger.kernel.org>, <linux-kselftest@vger.kernel.org>,
<linux-kernel@vger.kernel.org>,
Roberto Sassu <roberto.sassu@huawei.com>
Subject: [RFC][PATCH v2 02/12] diglim: Basic definitions
Date: Mon, 26 Jul 2021 18:36:50 +0200 [thread overview]
Message-ID: <20210726163700.2092768-3-roberto.sassu@huawei.com> (raw)
In-Reply-To: <20210726163700.2092768-1-roberto.sassu@huawei.com>
Introduce the basic definitions, exported to user space, to use digest
lists. The definitions, added to include/uapi/linux/diglim.h, are
documented in Documentation/security/diglim/implementation.rst.
Signed-off-by: Roberto Sassu <roberto.sassu@huawei.com>
---
.../security/diglim/implementation.rst | 97 +++++++++++++++++++
Documentation/security/diglim/index.rst | 1 +
MAINTAINERS | 2 +
include/uapi/linux/diglim.h | 51 ++++++++++
4 files changed, 151 insertions(+)
create mode 100644 Documentation/security/diglim/implementation.rst
create mode 100644 include/uapi/linux/diglim.h
diff --git a/Documentation/security/diglim/implementation.rst b/Documentation/security/diglim/implementation.rst
new file mode 100644
index 000000000000..59a180b3bb3f
--- /dev/null
+++ b/Documentation/security/diglim/implementation.rst
@@ -0,0 +1,97 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Implementation
+==============
+
+This section describes the implementation of DIGLIM.
+
+
+Basic Definitions
+-----------------
+
+This section introduces the basic definitions required to use DIGLIM.
+
+
+Compact Digest List Format
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. kernel-doc:: include/uapi/linux/diglim.h
+ :identifiers: compact_list_hdr
+
+Compact Types
+.............
+
+Digests can be of different types:
+
+- ``COMPACT_PARSER``: digests of executables which are given the ability to
+ parse digest lists not in the compact format and to upload to the kernel
+ the digest list converted to the compact format;
+- ``COMPACT_FILE``: digests of regular files;
+- ``COMPACT_METADATA``: digests of file metadata (e.g. the digest
+ calculated by EVM to verify a portable signature);
+- ``COMPACT_DIGEST_LIST``: digests of digest lists (only used internally by
+ the kernel).
+
+Different users of DIGLIM might query digests with different compact types.
+For example, IMA would be interested in COMPACT_FILE, as it deals with
+regular files, while EVM would be interested in COMPACT_METADATA, as it
+verifies file metadata.
+
+
+Compact Modifiers
+.................
+
+Digests can also have specific attributes called modifiers (bit position):
+
+- ``COMPACT_MOD_IMMUTABLE``: file content or metadata should not be
+ modifiable.
+
+IMA might use this information to deny open for writing, or EVM to deny
+setxattr operations.
+
+
+Actions
+.......
+
+This section defines a set of possible actions that have been executed on
+the digest lists (bit position):
+
+- ``COMPACT_ACTION_IMA_MEASURED``: the digest list has been measured by
+ IMA;
+- ``COMPACT_ACTION_IMA_APPRAISED``: the digest list has been successfully
+ appraised by IMA;
+- ``COMPACT_ACTION_IMA_APPRAISED_DIGSIG``: the digest list has been
+ successfully appraised by IMA by verifying a digital signature.
+
+This information might help users of DIGLIM to decide whether to use the
+result of a queried digest.
+
+For example, if a digest belongs to a digest list that was not measured
+before, IMA should ignore the result of the query, as the measurement list
+sent to remote verifiers would lack which digests have been uploaded to the
+kernel.
+
+
+Compact Digest List Example
+...........................
+
+::
+
+ version: 1, type: 2, modifiers: 0 algo: 4, count: 3, datalen: 96
+ <SHA256 digest1><SHA256 digest2><SHA256 digest3>
+ version: 1, type: 3, modifiers: 1 algo: 6, count: 2, datalen: 128
+ <SHA512 digest1><SHA512 digest2>
+
+This digest list consists of two blocks. The first block contains three
+SHA256 digests of regular files. The second block contains two SHA512
+digests of immutable metadata.
+
+
+Compact Digest List Operations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Finally, this section defines the possible operations that can be performed
+with digest lists:
+
+- ``DIGEST_LIST_ADD``: the digest list is being added;
+- ``DIGEST_LIST_DEL``: the digest list is being deleted.
diff --git a/Documentation/security/diglim/index.rst b/Documentation/security/diglim/index.rst
index 0fc5ab019bc0..4771134c2f0d 100644
--- a/Documentation/security/diglim/index.rst
+++ b/Documentation/security/diglim/index.rst
@@ -9,3 +9,4 @@ Digest Lists Integrity Module (DIGLIM)
introduction
architecture
+ implementation
diff --git a/MAINTAINERS b/MAINTAINERS
index c914dadd7e65..f61f5239468a 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -5458,8 +5458,10 @@ L: linux-integrity@vger.kernel.org
S: Supported
T: git://git.kernel.org/pub/scm/linux/kernel/git/zohar/linux-integrity.git
F: Documentation/security/diglim/architecture.rst
+F: Documentation/security/diglim/implementation.rst
F: Documentation/security/diglim/index.rst
F: Documentation/security/diglim/introduction.rst
+F: include/uapi/linux/diglim.h
DIOLAN U2C-12 I2C DRIVER
M: Guenter Roeck <linux@roeck-us.net>
diff --git a/include/uapi/linux/diglim.h b/include/uapi/linux/diglim.h
new file mode 100644
index 000000000000..8a33d1f0fefb
--- /dev/null
+++ b/include/uapi/linux/diglim.h
@@ -0,0 +1,51 @@
+/* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
+/*
+ * Copyright (C) 2017-2021 Huawei Technologies Duesseldorf GmbH
+ *
+ * Author: Roberto Sassu <roberto.sassu@huawei.com>
+ *
+ * DIGLIM definitions exported to user space, useful for generating digest
+ * lists.
+ */
+
+#ifndef _UAPI__LINUX_DIGLIM_H
+#define _UAPI__LINUX_DIGLIM_H
+
+#include <linux/types.h>
+#include <linux/hash_info.h>
+
+enum compact_types { COMPACT_KEY, COMPACT_PARSER, COMPACT_FILE,
+ COMPACT_METADATA, COMPACT_DIGEST_LIST, COMPACT__LAST };
+
+enum compact_modifiers { COMPACT_MOD_IMMUTABLE, COMPACT_MOD__LAST };
+
+enum compact_actions { COMPACT_ACTION_IMA_MEASURED,
+ COMPACT_ACTION_IMA_APPRAISED,
+ COMPACT_ACTION_IMA_APPRAISED_DIGSIG,
+ COMPACT_ACTION__LAST };
+
+enum ops { DIGEST_LIST_ADD, DIGEST_LIST_DEL, DIGEST_LIST_OP__LAST };
+
+/**
+ * struct compact_list_hdr - header of the following concatenated digests
+ * @version: version of the digest list
+ * @_reserved: field reserved for future use
+ * @type: type of digest list among enum compact_types
+ * @modifiers: additional attributes among (1 << enum compact_modifiers)
+ * @algo: digest algorithm
+ * @count: number of digests
+ * @datalen: length of concatenated digests
+ *
+ * A digest list is a set of blocks composed by struct compact_list_hdr and
+ * the following concatenated digests.
+ */
+struct compact_list_hdr {
+ __u8 version;
+ __u8 _reserved;
+ __le16 type;
+ __le16 modifiers;
+ __le16 algo;
+ __le32 count;
+ __le32 datalen;
+} __packed;
+#endif /*_UAPI__LINUX_DIGLIM_H*/
--
2.25.1
next prev parent reply other threads:[~2021-07-26 16:40 UTC|newest]
Thread overview: 47+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-07-26 16:36 [RFC][PATCH v2 00/12] integrity: Introduce DIGLIM Roberto Sassu
2021-07-26 16:36 ` [RFC][PATCH v2 01/12] diglim: Overview Roberto Sassu
2021-07-28 11:10 ` Mauro Carvalho Chehab
2021-07-28 11:40 ` Roberto Sassu
2021-07-26 16:36 ` Roberto Sassu [this message]
2021-07-27 14:43 ` [RFC][PATCH v2 02/12] diglim: Basic definitions Greg KH
2021-07-27 15:35 ` Roberto Sassu
2021-07-27 15:44 ` Greg KH
2021-07-27 16:09 ` Roberto Sassu
2021-07-27 16:13 ` Greg KH
2021-07-28 6:59 ` Roberto Sassu
2021-07-28 11:31 ` Mauro Carvalho Chehab
2021-07-28 11:45 ` Roberto Sassu
2021-07-28 13:08 ` Mauro Carvalho Chehab
2021-07-28 13:47 ` Roberto Sassu
2021-07-26 16:36 ` [RFC][PATCH v2 03/12] diglim: Objects Roberto Sassu
2021-07-28 11:38 ` Mauro Carvalho Chehab
2021-07-28 11:47 ` Roberto Sassu
2021-07-26 16:36 ` [RFC][PATCH v2 04/12] diglim: Methods Roberto Sassu
2021-07-28 12:18 ` Mauro Carvalho Chehab
2021-07-28 12:30 ` Roberto Sassu
2021-07-26 16:36 ` [RFC][PATCH v2 05/12] diglim: Parser Roberto Sassu
2021-07-28 12:35 ` Mauro Carvalho Chehab
2021-07-26 16:36 ` [RFC][PATCH v2 06/12] diglim: Interfaces - digest_list_add, digest_list_del Roberto Sassu
2021-07-28 12:38 ` Mauro Carvalho Chehab
2021-07-29 21:20 ` Mimi Zohar
2021-07-30 7:16 ` Roberto Sassu
2021-07-30 12:39 ` Mimi Zohar
2021-07-30 13:16 ` Roberto Sassu
2021-07-30 14:03 ` Mimi Zohar
2021-07-30 14:24 ` Roberto Sassu
2021-08-02 8:14 ` Roberto Sassu
2021-08-02 15:01 ` Mimi Zohar
2021-08-02 14:42 ` Mimi Zohar
2021-08-02 15:12 ` Roberto Sassu
2021-08-02 16:54 ` Roberto Sassu
2021-08-05 15:38 ` Mimi Zohar
2021-08-05 17:04 ` Roberto Sassu
2021-07-26 16:36 ` [RFC][PATCH v2 07/12] diglim: Interfaces - digest_lists_loaded Roberto Sassu
2021-07-26 16:36 ` [RFC][PATCH v2 08/12] diglim: Interfaces - digest_label Roberto Sassu
2021-07-26 16:36 ` [RFC][PATCH v2 09/12] diglim: Interfaces - digest_query Roberto Sassu
2021-07-26 16:36 ` [RFC][PATCH v2 10/12] diglim: Interfaces - digests_count Roberto Sassu
2021-07-28 12:45 ` Mauro Carvalho Chehab
2021-07-26 16:36 ` [RFC][PATCH v2 11/12] diglim: Remote Attestation Roberto Sassu
2021-07-28 12:47 ` Mauro Carvalho Chehab
2021-07-28 12:54 ` Roberto Sassu
2021-07-26 16:37 ` [RFC][PATCH v2 12/12] diglim: Tests Roberto Sassu
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20210726163700.2092768-3-roberto.sassu@huawei.com \
--to=roberto.sassu@huawei.com \
--cc=gregkh@linuxfoundation.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-integrity@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-kselftest@vger.kernel.org \
--cc=linux-security-module@vger.kernel.org \
--cc=mchehab+huawei@kernel.org \
--cc=zohar@linux.ibm.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).