[RFC][PATCH v2 02/12] diglim: Basic definitions

Wed Jul 28 11:31:02 UTC 2021

Em Mon, 26 Jul 2021 18:36:50 +0200
Roberto Sassu <roberto.sassu at 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 at 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 at 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 at 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 at 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