From: Mauro Carvalho Chehab [mailto:mchehab+huawei@kernel.org] Sent: Wednesday, July 28, 2021 1:31 PM Em Mon, 26 Jul 2021 18:36:50 +0200 Roberto Sassu roberto.sassu@huawei.com escreveu:
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*/
Besides Greg's notes, I'm wondering why to enforce a particular endness here. I mean, this is uAPI. I would expect it to use the CPU endianness instead, in order to avoid uneeded conversions.
Also Greg had the same concern. I hoped the Lifecycle section clarified the fact that digest lists are generated by software vendors not the local system. Should I add something more in the documentation?
Thanks
Roberto
HUAWEI TECHNOLOGIES Duesseldorf GmbH, HRB 56063 Managing Director: Li Peng, Li Jian, Shi Yanli
Thanks, Mauro