[PATCH 12/12] ima: added Documentation/security/IMA-digest-lists.txt

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

This patch adds the documentation of the new IMA feature, to load
and measure file digest lists.

Signed-off-by: Roberto Sassu <roberto.sassu@huawei.com>
---
 Documentation/security/IMA-digest-lists.txt | 150 ++++++++++++++++++++++++++++
 1 file changed, 150 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 0000000..f9eed21
--- /dev/null
+++ b/Documentation/security/IMA-digest-lists.txt
@@ -0,0 +1,150 @@
+                            File Digest Lists
+
+==== INTRODUCTION ====
+
+IMA, for each file matching policy rules, calculates a digest, creates
+a new entry in the measurement list and extends a TPM PCR with the digest
+of entry data. The last step causes a noticeable performance reduction.
+
+Since systems likely access the same files, repeating the above tasks at
+every boot can be avoided by replacing individual measurements of likely
+accessed files with only one measurement of their digests: the advantage
+is that the system performance significantly improves due to less PCR
+extend operations; on the other hand, the information about which files
+have exactly been accessed and in which sequence is lost.
+
+If this new measurement reports only good digests (e.g. those of
+files included in a Linux distribution), and if verifiers only check
+that a system executed good software and didn't access malicious data,
+the disadvantages reported earlier would be acceptable.
+
+The Trusted Computing paradigm measure & load is still respected by IMA
+with the proposed optimization. If a file being accessed is not in a
+measured digest list, a measurement will be recorded as before. If it is,
+the list has already been measured, and the verifier must assume that
+files with digest in the list have been accessed.
+
+Measuring digest lists gives the following benefits:
+
+- boot time reduction
+  For a minimal Linux installation with 1400 measurements, the boot time
+  decreases from 1 minute 30 seconds to 15 seconds, after loading to IMA
+  the digest of all files packaged by the distribution (32000). The new
+  list contains 92 entries. Without IMA, the boot time is 8.5 seconds.
+
+- lower network and CPU requirements for remote attestation
+  With the IMA optimization, both the measurement and digest lists
+  must be verified for a complete evaluation. However, since the lists
+  are fixed, they could be sent to and checked by the verifier only once.
+  Then, during a remote attestation, the only remaining task is to verify
+  the short measurement list.
+
+- signature-based remote attestation
+  Digest list signature can be used as a proof of the provenance for the
+  files whose digest is in the list. Then, if verifiers trust the signer
+  and only check provenance, remote attestation verification would simply
+  consist on checking digest lists signatures and that the measurement
+  list only contain list metadata digests (reference measurement databases
+  would be no longer required). An example of a signed digest list,
+  that can be parsed with this patch set, is the RPM package header.
+
+Digest lists are loaded in two stages by IMA through the new securityfs
+interface called 'digest_lists'. Users supply metadata, for the digest
+lists they want to load: path, format, digest, signature and algorithm
+of the digest.
+
+Then, after the metadata digest is added to the measurement list, IMA
+reads the digest lists at the path specified and loads the digests in
+a hash table (digest lists are not measured, since their digest is already
+included in the metadata). With metadata measurement instead of digest list
+measurement, it is possible to avoid a performance reduction that would
+occur by measuring many digest lists (e.g. RPM headers) individually.
+If, alternatively, digest lists are loaded together, their signature
+cannot be verified.
+
+Lastly, when a file is accessed, IMA searches the calculated digest in
+the hash table. Only if the digest is not found a new entry is added
+to the measurement list.
+
+
+
+==== FORMAT ====
+
+The format of digest list metadata is:
+
+algo[2] digest_len[4] digest[digest_len]
+        signature_len[4] signature[signature_len]
+        path_len[4] path[path_len]
+        ref_id_len[4] ref_id[ref_id_len]
+        list_type_len[4] list_type[list_type_len]
+
+algo, list_type and _len are little endian.
+
+
+algo values are defined in include/uapi/linux/hash_info.h. The algorithms
+in the list metadata must be the same of ima_hash_algo (algorithm used
+by IMA to calculate the file digest).
+
+list type values:
+
+0: compact digest list
+1: RPM package header
+
+
+The format of the compact digest list is:
+
+entry_id[2] count[4] data_len[4]
+data[data_len]
+[...]
+entry_id[2] count[4] data_len[4]
+data[data_len]
+
+entry_id, count and data_len are little endian.
+
+At the moment, entry_id can have value 0, which means that 'data' contains
+'count' digests concatenated together. For example, a compact digest list
+with 10 SHA256 digests will look like:
+
+0 10 320
+digest1..digest10
+
+
+
+==== MEASUREMENT LIST ====
+
+systemd has been modified to load the path of files containing digest list
+metadata to the new securityfs interface. Paths must be stored in
+/etc/ima/digest-lists. If digest lists, metadata and systemd configuration
+file are included in the initial ram disk, a typical measurement list
+will look like:
+
+10 <template digest> ima-ng sha1:<digest> boot_aggregate
+10 <template digest> ima-ng sha256:<digest> /usr/lib/systemd/systemd
+10 <template digest> ima-ng sha256:<digest> /usr/lib64/ld-2.17.so
+[...]
+10 <template digest> ima-ng sha256:<digest> /etc/ima/digest-lists
+10 <template digest> ima-ng sha256:<digest> /digests/headers
+[...]
+
+systemd executable and libraries still appear in the measurement list,
+even if they are in a digest list, because digests lists have not been
+loaded yet.
+
+Then, the next measurement should be for /etc/ima/digest-lists.
+At verification time, the file digest can be verified by calculating
+the digest of the path of list metadata (/digests/headers). If multiple
+metadata files are specified in /etc/ima/digest-lists, it is task of the
+system administrator to use appropriate names, so that a verifier can
+recognize them from the measurement list.
+
+The last measurement to verify is of /digests/headers. During remote
+attestation, the content of this file should be sent to the verifier,
+together with the digest lists (unless a reference ID is provided,
+so that lists can be fetched from a repository).
+
+A verifier should check if:
+
+1) the digest of received metadata matches that in the measurement list
+2) the digest of digest lists matches the digests in the list metadata
+3a) each file digest in the digest list is acceptable
+3b) the signature of the digest list is valid and the signer is trusted
-- 
2.9.3