| Message ID | 20210726163700.2092768-3-roberto.sassu@huawei.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | integrity: Introduce DIGLIM | expand |
On Mon, Jul 26, 2021 at 06:36:50PM +0200, Roberto Sassu wrote: > --- /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) I do not understand this description, what does it mean? > + * @algo: digest algorithm Is this also a #define or an enum? Where is the list of them? > + * @count: number of digests > + * @datalen: length of concatenated digests Where does this count and length come into play as nothing else is in this structure? > + * > + * 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; You MUST check this for 0 today, and document it above. If not, you can never use it in the future. > + __le16 type; > + __le16 modifiers; > + __le16 algo; > + __le32 count; > + __le32 datalen; > +} __packed; > +#endif /*_UAPI__LINUX_DIGLIM_H*/ > -- > 2.25.1 >
> From: Greg KH [mailto:gregkh@linuxfoundation.org] > Sent: Tuesday, July 27, 2021 4:44 PM > On Mon, Jul 26, 2021 at 06:36:50PM +0200, Roberto Sassu wrote: > > --- /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) > > I do not understand this description, what does it mean? Hi Greg yes, it is not very clear. @modifiers is a bitmask where each bit corresponds to a different attribute. enum compact_modifiers defines which bit position is assigned to each attribute. > > + * @algo: digest algorithm > > Is this also a #define or an enum? Where is the list of them? @algo is an enum defined in include/uapi/linux/hash_info.h. > > + * @count: number of digests > > + * @datalen: length of concatenated digests > > Where does this count and length come into play as nothing else is in > this structure? Each digest list must begin with this structure. From it, the parser knows how much data it should expect afterwards. After the data, there could be another or more blocks of this structure and following data. There is an example in the 'Compact Digest List Example' subsection, in Documentation/security/diglim/implementation.rst. > > + * > > + * 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; > > You MUST check this for 0 today, and document it above. If not, you can > never use it in the future. Ok, yes. I will add it. Thanks Roberto HUAWEI TECHNOLOGIES Duesseldorf GmbH, HRB 56063 Managing Director: Li Peng, Li Jian, Shi Yanli > > + __le16 type; > > + __le16 modifiers; > > + __le16 algo; > > + __le32 count; > > + __le32 datalen; > > +} __packed; > > +#endif /*_UAPI__LINUX_DIGLIM_H*/ > > -- > > 2.25.1 > >
On Tue, Jul 27, 2021 at 03:35:16PM +0000, Roberto Sassu wrote: > > From: Greg KH [mailto:gregkh@linuxfoundation.org] > > Sent: Tuesday, July 27, 2021 4:44 PM > > On Mon, Jul 26, 2021 at 06:36:50PM +0200, Roberto Sassu wrote: > > > --- /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) > > > > I do not understand this description, what does it mean? > > Hi Greg > > yes, it is not very clear. > > @modifiers is a bitmask where each bit corresponds to a different > attribute. enum compact_modifiers defines which bit position is > assigned to each attribute. Watch out with endian issues and bitmasks... Anyway, please document this. > > > > + * @algo: digest algorithm > > > > Is this also a #define or an enum? Where is the list of them? > > @algo is an enum defined in include/uapi/linux/hash_info.h. Please say that. > > > + * @count: number of digests > > > + * @datalen: length of concatenated digests > > > > Where does this count and length come into play as nothing else is in > > this structure? > > Each digest list must begin with this structure. From it, the parser knows > how much data it should expect afterwards. After the data, there could be > another or more blocks of this structure and following data. Ah, that was not obvious at all :) Why do you not have a __u8 data[]; type field as the last one here for that memory so you can access it easier? thanks, greg k-h
> From: Greg KH [mailto:gregkh@linuxfoundation.org] > Sent: Tuesday, July 27, 2021 5:44 PM > On Tue, Jul 27, 2021 at 03:35:16PM +0000, Roberto Sassu wrote: > > > From: Greg KH [mailto:gregkh@linuxfoundation.org] > > > Sent: Tuesday, July 27, 2021 4:44 PM > > > On Mon, Jul 26, 2021 at 06:36:50PM +0200, Roberto Sassu wrote: > > > > --- /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) > > > > > > I do not understand this description, what does it mean? > > > > Hi Greg > > > > yes, it is not very clear. > > > > @modifiers is a bitmask where each bit corresponds to a different > > attribute. enum compact_modifiers defines which bit position is > > assigned to each attribute. > > Watch out with endian issues and bitmasks... Anyway, please document > this. > > > > > > > + * @algo: digest algorithm > > > > > > Is this also a #define or an enum? Where is the list of them? > > > > @algo is an enum defined in include/uapi/linux/hash_info.h. > > Please say that. > > > > > + * @count: number of digests > > > > + * @datalen: length of concatenated digests > > > > > > Where does this count and length come into play as nothing else is in > > > this structure? > > > > Each digest list must begin with this structure. From it, the parser knows > > how much data it should expect afterwards. After the data, there could be > > another or more blocks of this structure and following data. > > Ah, that was not obvious at all :) > > Why do you not have a __u8 data[]; type field as the last one here for > that memory so you can access it easier? After the digest list is parsed, I'm accessing the digest with the offset from the beginning of the digest list. If the offset was relative to the header, it could have been useful. I could add the new field, but I'm afraid of the incompatibility with existing tools that we have. Thanks Roberto HUAWEI TECHNOLOGIES Duesseldorf GmbH, HRB 56063 Managing Director: Li Peng, Li Jian, Shi Yanli > thanks, > > greg k-h
On Tue, Jul 27, 2021 at 04:09:37PM +0000, Roberto Sassu wrote: > > From: Greg KH [mailto:gregkh@linuxfoundation.org] > > Sent: Tuesday, July 27, 2021 5:44 PM > > On Tue, Jul 27, 2021 at 03:35:16PM +0000, Roberto Sassu wrote: > > > > From: Greg KH [mailto:gregkh@linuxfoundation.org] > > > > Sent: Tuesday, July 27, 2021 4:44 PM > > > > On Mon, Jul 26, 2021 at 06:36:50PM +0200, Roberto Sassu wrote: > > > > > --- /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) > > > > > > > > I do not understand this description, what does it mean? > > > > > > Hi Greg > > > > > > yes, it is not very clear. > > > > > > @modifiers is a bitmask where each bit corresponds to a different > > > attribute. enum compact_modifiers defines which bit position is > > > assigned to each attribute. > > > > Watch out with endian issues and bitmasks... Anyway, please document > > this. > > > > > > > > > > + * @algo: digest algorithm > > > > > > > > Is this also a #define or an enum? Where is the list of them? > > > > > > @algo is an enum defined in include/uapi/linux/hash_info.h. > > > > Please say that. > > > > > > > + * @count: number of digests > > > > > + * @datalen: length of concatenated digests > > > > > > > > Where does this count and length come into play as nothing else is in > > > > this structure? > > > > > > Each digest list must begin with this structure. From it, the parser knows > > > how much data it should expect afterwards. After the data, there could be > > > another or more blocks of this structure and following data. > > > > Ah, that was not obvious at all :) > > > > Why do you not have a __u8 data[]; type field as the last one here for > > that memory so you can access it easier? > > After the digest list is parsed, I'm accessing the digest with the offset from > the beginning of the digest list. If the offset was relative to the header, it could > have been useful. I could add the new field, but I'm afraid of the incompatibility > with existing tools that we have. What tools? This isn't a feature in the kernel yet, so we have no legacy to support, right? thanks, greg k-h
> From: Greg KH [mailto:gregkh@linuxfoundation.org] > Sent: Tuesday, July 27, 2021 6:13 PM > On Tue, Jul 27, 2021 at 04:09:37PM +0000, Roberto Sassu wrote: > > > From: Greg KH [mailto:gregkh@linuxfoundation.org] > > > Sent: Tuesday, July 27, 2021 5:44 PM > > > On Tue, Jul 27, 2021 at 03:35:16PM +0000, Roberto Sassu wrote: > > > > > From: Greg KH [mailto:gregkh@linuxfoundation.org] > > > > > Sent: Tuesday, July 27, 2021 4:44 PM > > > > > On Mon, Jul 26, 2021 at 06:36:50PM +0200, Roberto Sassu wrote: > > > > > > --- /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) > > > > > > > > > > I do not understand this description, what does it mean? > > > > > > > > Hi Greg > > > > > > > > yes, it is not very clear. > > > > > > > > @modifiers is a bitmask where each bit corresponds to a different > > > > attribute. enum compact_modifiers defines which bit position is > > > > assigned to each attribute. > > > > > > Watch out with endian issues and bitmasks... Anyway, please document > > > this. > > > > > > > > > > > > > + * @algo: digest algorithm > > > > > > > > > > Is this also a #define or an enum? Where is the list of them? > > > > > > > > @algo is an enum defined in include/uapi/linux/hash_info.h. > > > > > > Please say that. > > > > > > > > > + * @count: number of digests > > > > > > + * @datalen: length of concatenated digests > > > > > > > > > > Where does this count and length come into play as nothing else is in > > > > > this structure? > > > > > > > > Each digest list must begin with this structure. From it, the parser knows > > > > how much data it should expect afterwards. After the data, there could > be > > > > another or more blocks of this structure and following data. > > > > > > Ah, that was not obvious at all :) > > > > > > Why do you not have a __u8 data[]; type field as the last one here for > > > that memory so you can access it easier? > > > > After the digest list is parsed, I'm accessing the digest with the offset from > > the beginning of the digest list. If the offset was relative to the header, it > could > > have been useful. I could add the new field, but I'm afraid of the > incompatibility > > with existing tools that we have. > > What tools? This isn't a feature in the kernel yet, so we have no > legacy to support, right? Yes, right. We shouldn't be limited by previously written code. Thanks Roberto HUAWEI TECHNOLOGIES Duesseldorf GmbH, HRB 56063 Managing Director: Li Peng, Li Jian, Shi Yanli > thanks, > > greg k-h
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. Thanks, Mauro
> 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
Em Wed, 28 Jul 2021 11:45:02 +0000 Roberto Sassu <roberto.sassu@huawei.com> escreveu: > > 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: > > > > > +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? It shouldn't matter what kind of endness software vendors use on userspace (either CPU or a fixed endiannes - either LE or BE). I mean, I won't doubt that some package tools use LE while others would use BE. At some point, this needs to be converted to CPU endiannes. IMO, the best would be to isolate whatever RPM/DEB/... endianness is used on userspace from what the Kernel will use internally. Just my 2 cents. Regards, Mauro
> From: Mauro Carvalho Chehab [mailto:mchehab+huawei@kernel.org] > Sent: Wednesday, July 28, 2021 3:08 PM > Em Wed, 28 Jul 2021 11:45:02 +0000 > Roberto Sassu <roberto.sassu@huawei.com> escreveu: > > > > 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: > > > > > > > > +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? > > It shouldn't matter what kind of endness software vendors use on > userspace (either CPU or a fixed endiannes - either LE or BE). > > I mean, I won't doubt that some package tools use LE while others > would use BE. At some point, this needs to be converted to > CPU endiannes. If you let digest list generators decide the endianness, probably it is necessary to also add the endianness information in the structure. Otherwise, the kernel wouldn't know what to do. If the kernel knows that the digest list is always in little endian, it simply calls le32_to_cpu(). > IMO, the best would be to isolate whatever RPM/DEB/... endianness > is used on userspace from what the Kernel will use internally. This is a different case. The conversion happens if the digest list is not in native format. The kernel can also parse an untouched digest list if it is in native format. Thanks Roberto HUAWEI TECHNOLOGIES Duesseldorf GmbH, HRB 56063 Managing Director: Li Peng, Li Jian, Shi Yanli > Just my 2 cents. > > Regards, > Mauro
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*/
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