[lkml]   [2017]   [Jul]   [25]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
Messages in this thread
Patch in this message
Subject[PATCH 12/12] ima: added Documentation/security/IMA-digest-lists.txt
This patch adds the documentation of the new IMA feature, to load
and measure file digest lists.

Signed-off-by: Roberto Sassu <>
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
+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]
+entry_id[2] count[4] data_len[4]
+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
+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/
+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
 \ /
  Last update: 2017-07-25 17:54    [W:0.244 / U:1.100 seconds]
©2003-2018 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site