[PATCH v4 14/14] ima: add Documentation/security/IMA-digest-lists.txt
From: Roberto Sassu
Date: Fri Jun 14 2019 - 14:10:32 EST
This patch adds the documentation of the IMA Digest Lists extension.
Signed-off-by: Roberto Sassu <roberto.sassu@xxxxxxxxxx>
---
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