[PATCH v4 14/14] ima: add Documentation/security/IMA-digest-lists.txt

[Roberto Sassu <roberto.sassu@huawei.com>]

This patch adds the documentation of the IMA Digest Lists extension.

Signed-off-by: Roberto Sassu <roberto.sassu@huawei.com>
---
 Documentation/security/IMA-digest-lists.txt | 226 ++++++++++++++++++++
 1 file changed, 226 insertions(+)
 create mode 100644 Documentation/security/IMA-digest-lists.txt

diff --git a/Documentation/security/IMA-digest-lists.txt b/Documentation/security/IMA-digest-lists.txt
new file mode 100644
index 000000000000..dd9633e21304
--- /dev/null
+++ b/Documentation/security/IMA-digest-lists.txt
@@ -0,0 +1,226 @@
+==========================
+IMA Digest Lists Extension
+==========================
+
+INTRODUCTION
+============
+
+Integrity Measurement Architecture (IMA) is a security module that performs
+measurement of files accessed with the execve(), mmap() and open() system
+calls. File measurements can be used for different purposes. They can be
+added in a measurement list and sent to a remote verifier for an integrity
+evaluation. They can be compared to reference values provided by the
+software vendor and access can be denied if there is a mismatch. File
+measurements can also be included in system logs for auditing purposes.
+
+IMA Digest Lists is an extension providing additional functionality for
+the IMA submodules. Its main task is to load reference file digests in the
+kernel memory, and to communicate to IMA submodules (measurement and
+appraisal) whether the digest of a file being accessed is found in the
+uploaded digest lists.
+
+The IMA-Measure submodule uses the IMA Digest Lists extension to create
+a new measurement list (with a different PCR, for example 11) which
+contains the measurement of uploaded digest lists and unknown files. Since
+the loading of digest lists is sequential, the chosen PCR will have a
+predictable value for the whole boot cycle and can be used for sealing
+policies based on the OS software integrity.
+
+Both the standard and the new measurement list can be generated at the same
+time, allowing for implicit attestation based on the usage of a TPM key
+sealed to the OS, and for explicit attestation when a more precise
+integrity evaluation is necessary.
+
+The IMA-Appraise submodule uses the IMA Digest Lists extension to
+grant/deny access to the files depending on whether the file digest is
+found in the uploaded digest lists, instead of checking security.ima.
+
+The main advantage of the extension is that reference measurements used for
+the digest comparison can be extracted from already existing sources (for
+example RPM headers). Another benefit is that the overhead compared to file
+signatures is lower as only one signature is verified for all files
+included in the digest list. A disadvantage is that file metadata are not
+verified.
+
+
+
+WORKFLOW
+========
+
+The IMA workflow is modified as follows. The added steps are marked as
+[NEW].
+
+  +------------+
+  |  IMA hook  |
+  +------------+
+        |
+   +---------+
+   | collect |
+   +---------+
+        |                                           +---------------------+
++---------------+                       ------------| don't measure [NEW] |
+| digest lookup |                       | yes       +---------------------+
+|     [NEW]     |                 -------------- no +---------------------+
++---------------+           -----/ digest       \---| add to measurement  |
+        |                   |    \ found? [NEW] /   | list (PCR 11) [NEW] |
+        |                   |     --------------    +---------------------+
+  +----------+       +-------------+                +--------------------+
+  |  switch  |-------| IMA-Measure |----------------| add to measurement |
+  | (action) |       +-------------+                | list (PCR 10)      |
+  +----------+                                      +--------------------+
+        |
+        |
+        |       no xattr
++--------------+     ---------------  yes
+| IMA-Appraise |----/ filec created \-------------------------------
++--------------+    \ created [NEW] /                              |
+  xattr |            ---------------                               |
+        |                   | no                                   |
+        |           ------------------  no  --------------  yes  +--------+
+        |          / EVM initialized? \----/ digest       \------| grant  |
+        |          \ [NEW]            /    \ found? [NEW] /      | access |
+        |           ------------------      --------------       +--------+
+        |                   | yes                 | no
+        |                   |                     |              +--------+
+        |           -------------------  no       ---------------| deny   |
+        |          / digest-nometadata \-------------------------| access |
+        |          \ mode? [NEW]       /                         +--------+
+        |           -------------------
+        |               ^   | yes                                +--------+
+        |               |   -------------------------------------| grant  |
+        |               |                                        | access |
+        |               |                                        +--------+
+        |               | yes
+        |           -------------------------  no                +--------+
+        |----------/ security.ima (new type) \-------------------| deny   |
+        |          \ present and valid?      /                   | access |
+        |           -------------------------                    +--------+
+        |                                                            |
+        |           --------------------------  no                   |
+        -----------/ security.ima (cur types) \-----------------------
+                   \ present and valid?       /
+                    --------------------------
+                             | yes                               +--------+
+                             ------------------------------------| grant  |
+                                                                 | access |
+                                                                 +--------+
+
+After the file digest is calculated, it is searched in the hash table
+containing all digests extracted from the uploaded digest lists. Then, if
+the digest is found, a structure is returned to IMA with information
+associated to that digest. The structure is returned only to the IMA
+submodules that processed the digest lists (i.e. the action returned by
+ima_get_action() was 'measure' or 'appraise').
+
+IMA-Measure behavior depends on whether the digest list PCR has been
+specified in the kernel command line. If the PCR was not specified, the
+submodule behaves as before. If the PCR was specified, IMA-Measure creates
+a new measurement with that PCR, only if the file digest is not found in
+the digest lists. It additionally creates a measurement with the default
+PCR if '+' is added as a prefix to the PCR.
+
+IMA-Appraise behavior depends on whether either the 'digest' or
+'digest-nometadata' appraisal modes have been specified in the kernel
+command line. If they were not specified, IMA-Appraise relies solely on the
+security.ima xattr for verification. If the 'digest' mode was specified,
+verification succeeds if the file digest is found in the digest lists and
+EVM is not initialized, as there is no other way to verify file metadata.
+
+If the 'digest-nometadata' mode was specified, verification succeeds
+regardless of the fact that EVM is initialized or not. However, after a
+write, files for which access was granted without verifying metadata will
+have a new security.ima type, so that they can be identified also after
+reboot. Specifying 'digest-nometadata' is required also to access files
+with the new security.ima type.
+
+
+
+ARCHITECTURE
+============
+
++--------------+           8) digest lookup
+| IMA-Appraise |--------------------------------------
++--------------+                                     |
+                                                     |
++-------------+            7) digest lookup          |
+| IMA-Measure | -------------------------------------|
++-------------+                                     ||
+                                                   |||
++-------------+ 2a/5b) parse compact list +-------------------+
+| IMA (secfs) | ------------------------> | IMA Digests Lists |
++-------------+                           +-------------------+
+   ^        ^                                 |     | 3a/6b add digests
+   |        |                                 |  +------------+
+   |        |                                 |  | hash table |
+   |        |                                 |  +------------+
+   |        | 4b) upload compact list         |
+   |        |                                 |                kernel space
+---|--------|---------------------------------|-------------------------------
+   |        | 1b) open digest_list_data       |                user space
+   | +-------------+                          |
+   | |    Parser   |<--------------------------
+   | +-------------+   2b) check parser binary, shared libraries
+   |     ^  ^  ^           and actions (measure/appraise)
+   |    RPM | ...      3b) read and convert digest list
+   |     manifest
+   |
+1a) upload compact list
+
+The main addition to IMA is a new hash table (similar to that used to check
+for duplicate measurement entries), which contains file digests extracted
+from the digest lists.
+
+File digests can be uploaded to IMA through a new securityfs file named
+'digest_list_data' and must be sent in a format called compact list. Digest
+lists can be uploaded directly to the kernel, by specifying their path, or
+by executing a user space parser.
+
+The parser, called upload_digest_lists, converts digest lists from the
+original format defined by the software vendor (e.g. RPM package header) to
+the compact list format. It is executed by the kernel even before init,
+so that the hash table is populated before any file is accessed.
+
+Converted digest lists can be uploaded exclusively by the parser. The
+reason is that digest lists are measured only when they are accessed. If
+they were uploaded by any process there wouldn't be any guarantee that the
+converted lists contain the same digests as the original list. IMA checks
+that the digest of the executable that opened 'digest_list_data' as well as
+shared libraries supporting new digest list formats have type
+COMPACT_PARSER.
+
+As mentioned above, digest lists cannot be used unconditionally but must
+have been processed by the IMA submodule willing to use them. This is
+achieved by keeping track of the process that opens and closes
+digest_list_data, and checking the actions done by that process. If a file
+opened by the parser is not being measured, IMA-Measure will not be able
+to use digest lists until reboot. The same happens for IMA-Appraise.
+
+
+
+CONFIGURATION
+=============
+
+The first step consists in generating digest lists with the
+gen_digest_lists tool included in the digest-list-tools package.
+digest-list-tools can be retrieved at the URL:
+
+https://github.com/euleros/digest-list-tools
+
+gen_digest_lists can generate digest lists from different sources (for
+example: RPM package DB and IMA measurement list). By default, it saves
+generated digest lists in the /etc/ima/digest_lists directory.
+digest-list-tools includes also two bash scripts setup_ima_digest_lists and
+setup_digest_lists_demo to simplify the digest list generation for the
+users.
+
+To use the parser at boot, it is also necessary to generate a digest list
+for it. It is automatically generated by the setup_ima_digest_lists script,
+or it must be manually generated otherwise. If digest lists are used for
+appraisal, they must be signed with a key saved to /etc/keys/x509_ima.der
+and the key must be signed with a key in the primary or secondary kernel
+keyring.
+
+To use digest lists during early boot, it is necessary to regenerate the
+initial ram disk. Digest lists and the parser will be included in the ram
+disk by the new dracut/initramfs-tools modules, included in the
+digest-list-tools package.
-- 
2.17.1