This patch adds the documentation of the new IMA feature, to load and measure file digest lists. Signed-off-by: Roberto Sassu <roberto.sassu@xxxxxxxxxx> --- 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 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
