linux-integrity.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Roberto Sassu <roberto.sassu@huawei.com>
To: <zohar@linux.ibm.com>
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 03/12] digest_lists: Basic definitions
Date: Fri, 25 Jun 2021 18:56:05 +0200	[thread overview]
Message-ID: <20210625165614.2284243-4-roberto.sassu@huawei.com> (raw)
In-Reply-To: <20210625165614.2284243-1-roberto.sassu@huawei.com>

This patch introduces the basic definitions, exported to user space, to use
digest lists. The definitions, added to include/uapi/linux/digest_lists.h,
are documented in Documentation/security/digest_lists.rst.

Signed-off-by: Roberto Sassu <roberto.sassu@huawei.com>
---
 Documentation/security/digest_lists.rst | 119 ++++++++++++++++++++++++
 MAINTAINERS                             |   1 +
 include/uapi/linux/digest_lists.h       |  43 +++++++++
 3 files changed, 163 insertions(+)
 create mode 100644 include/uapi/linux/digest_lists.h

diff --git a/Documentation/security/digest_lists.rst b/Documentation/security/digest_lists.rst
index 8980be7836f8..995260294783 100644
--- a/Documentation/security/digest_lists.rst
+++ b/Documentation/security/digest_lists.rst
@@ -226,3 +226,122 @@ the digest list) (step 5).
 
 Finally, digests can be searched from user space through a securityfs file
 (step 6) or by the kernel itself.
+
+
+Implementation
+==============
+
+This section describes the implementation of Huawei Digest Lists.
+
+
+Basic Definitions
+-----------------
+
+This section introduces the basic definitions required to use digest lists.
+
+
+Compact Digest List Format
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Compact digest lists consist of one or multiple headers defined as:
+
+::
+
+	struct compact_list_hdr {
+		__u8 version;
+		__u8 _reserved;
+		__le16 type;
+		__le16 modifiers;
+		__le16 algo;
+		__le32 count;
+		__le32 datalen;
+	} __packed;
+
+which characterize the subsequent block of concatenated digests.
+
+The ``algo`` field specifies the algorithm used to calculate the digest.
+
+The ``count`` field specifies how many digests are stored in the subsequent
+block of digests.
+
+The ``datalen`` field specifies the length of the subsequent block of
+digests (it is redundant, it is the same as
+``hash_digest_size[algo] * count``).
+
+
+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 Huawei Digest Lists 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 Huawei Digest Lists 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 how the database was populated.
+
+
+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/MAINTAINERS b/MAINTAINERS
index cba3d82fee43..ccf555862673 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -8387,6 +8387,7 @@ 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/digest_lists.rst
+F:	uapi/linux/digest_lists.h
 
 HUAWEI ETHERNET DRIVER
 M:	Bin Luo <luobin9@huawei.com>
diff --git a/include/uapi/linux/digest_lists.h b/include/uapi/linux/digest_lists.h
new file mode 100644
index 000000000000..9545a8aaa231
--- /dev/null
+++ b/include/uapi/linux/digest_lists.h
@@ -0,0 +1,43 @@
+/* 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>
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License as
+ * published by the Free Software Foundation, version 2 of the
+ * License.
+ *
+ * File: digest_lists.h
+ *      Digest list definitions exported to user space.
+ */
+
+#ifndef _UAPI__LINUX_DIGEST_LISTS_H
+#define _UAPI__LINUX_DIGEST_LISTS_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 {
+	__u8 version;
+	__u8 _reserved;
+	__le16 type;
+	__le16 modifiers;
+	__le16 algo;
+	__le32 count;
+	__le32 datalen;
+} __packed;
+#endif
-- 
2.25.1


  parent reply	other threads:[~2021-06-25 16:56 UTC|newest]

Thread overview: 25+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-06-25 16:56 [RFC][PATCH 00/12] Huawei Digest Lists Roberto Sassu
2021-06-25 16:56 ` [RFC][PATCH 01/12] ima: Add digest, algo, measured parameters to ima_measure_critical_data() Roberto Sassu
2021-06-25 18:26   ` Mimi Zohar
2021-06-25 16:56 ` [RFC][PATCH 02/12] digest_lists: Overview Roberto Sassu
2021-06-25 16:56 ` Roberto Sassu [this message]
2021-06-27 10:53   ` [RFC][PATCH 03/12] digest_lists: Basic definitions Greg KH
2021-06-27 15:23     ` Matthew Wilcox
2021-06-27 15:35       ` Greg KH
2021-06-28  8:30     ` Roberto Sassu
2021-06-28  8:46       ` Greg KH
2021-06-28  9:27         ` Roberto Sassu
2021-06-28  9:32           ` Greg KH
2021-06-28  9:51             ` Roberto Sassu
2021-06-25 16:56 ` [RFC][PATCH 04/12] digest_lists: Objects Roberto Sassu
2021-06-27 10:56   ` Greg KH
2021-06-28  8:14     ` Roberto Sassu
2021-06-28  8:47       ` Greg KH
2021-06-25 16:56 ` [RFC][PATCH 05/12] digest_lists: Methods Roberto Sassu
2021-06-25 16:56 ` [RFC][PATCH 06/12] digest_lists: Parser Roberto Sassu
2021-06-25 16:56 ` [RFC][PATCH 07/12] digest_lists: Interfaces - digest_list_add, digest_list_del Roberto Sassu
2021-06-25 16:56 ` [RFC][PATCH 08/12] digest_lists: Interfaces - digest_lists_loaded Roberto Sassu
2021-06-25 16:56 ` [RFC][PATCH 09/12] digest_lists: Interfaces - digest_label Roberto Sassu
2021-06-25 16:56 ` [RFC][PATCH 10/12] digest_lists: Interfaces - digest_query Roberto Sassu
2021-06-25 16:56 ` [RFC][PATCH 11/12] digest_lists: Interfaces - digests_count Roberto Sassu
2021-06-25 16:56 ` [RFC][PATCH 12/12] digest_lists: 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=20210625165614.2284243-4-roberto.sassu@huawei.com \
    --to=roberto.sassu@huawei.com \
    --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=zohar@linux.ibm.com \
    --subject='Re: [RFC][PATCH 03/12] digest_lists: Basic definitions' \
    /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

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).