This patch adds the documentation of digest lists. Signed-off-by: Roberto Sassu <roberto.sassu@xxxxxxxxxx> --- Documentation/security/IMA-digest-lists.txt | 161 ++++++++++++++++++++++++++++ 1 file changed, 161 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..afa860bbe53e --- /dev/null +++ b/Documentation/security/IMA-digest-lists.txt @@ -0,0 +1,161 @@ +============ +Digest Lists +============ + + +INTRODUCTION +============ + +IMA is a security module with the objective of reporting or enforcing the +integrity of a system, by measuring files accessed with the execve(), +mmap() and open() system calls. For reporting, it takes advantage of the +TPM and extends a PCR with the digest of an evaluated event. For enforcing, +it returns a value which is zero if the operation should be allowed, +negative if it should be denied. + +Measuring files of an operating system introduces three main issues. First, +since the overhead introduced by the TPM is noticeable, the performance of +the system decreases linearly with the number of measurements taken. This +can be seen especially at boot time. Second, managing large measurement +lists requires computation power and network bandwidth. Third, it is +necessary to obtain reference measurements (i.e. digests of software known +to be good) to evaluate/enforce the integrity of the system. If file +signatures are used to enforce access, Linux distribution vendors have to +modify their building systems in order to include signatures in their +packages. + +Digest lists aim at mitigating these issues. A digest list is a list of +digests that are taken by IMA as reference measurements and loaded before +files are accessed. Then, IMA compares calculated digests of accessed files +with digests from loaded digest lists. If the digest is found, measurement, +appraisal and audit are not performed. + +Multiple digest lists can be loaded at the same time, by providing to IMA +metadata for each list: digest, signature and path. The digest is specified +so that loaded digest lists can be identified only with the measurement of +metadata. The signature is used for appraisal. If the verification +succeeds, IMA loads the digest list even if security.ima is missing. + +Digest lists address the first issue because the TPM is used only if the +digest of a measured file is unknown. On a minimal system, 10 of 1400 +measurements are unknown because of mutable files (e.g. log files). + +Digest lists mitigate the second issue because, since digest lists do not +change, they don't have to be sent at every remote attestation. Sending +unknown measurements and a reference to digest lists would be sufficient. + +Finally, digest lists address also the third issue because Linux +distribution vendors already provide the digests of files included in each +RPM package. The digest list is stored in the RPM header, signed by the +vendor. + +When using digest lists, a limitation must be considered. Since a +measurement is not reported if the digest of an accessed file is found in a +digest list, the measurement list does not show which files have been +actually accessed, and in which sequence. + +A possible solution would be to load a list with digest of files which are +usually accessed. Also, it is possible to selectively enable digest list +lookup only for a subset of IMA policy rules. For example, a policy could +enable digest lookup only for file accesses from the TCB and disable it +for execve() and mmap() from regular users. + + + +SETUP +===== + +Digest lists should be placed in the /etc/ima/digest_lists directory and +metadata should be written to /etc/ima/digest_lists/metadata. + +If digest lists are included in the initial ram disk, IMA will load them +early in the boot process. Otherwise, a patched systemd can check if the +file with digest list metadata exists in the filesystem and, if yes, send +the path to IMA through the 'digest_lists' securityfs interface. The main +use case for the patched systemd is to load digest lists of newly installed +packages, which are not included in the initial ram disk. + + + +FORMATS +======= + +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[2] + +algo and list_type are in 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 in little endian. + +entry_id can have values 0 or 1. If entry_id is 0, files with provided +digests are immutable. If entry_id is 1, files are mutable. '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 +================ + +If IMA loads the digest lists from the initial ram disk, the measurement +list should look like: + +10 <template digest> ima-ng sha1:<digest> boot_aggregate +10 <template digest> ima-ng sha1:<digest> /etc/ima/digest_lists/metadata + +For the integrity evaluation, metadata and digest lists must be provided to +verifiers. The digest of digest lists must be compared with the digest +included in the metadata, and the digest of metadata with the digest in the +measurement list. + + + +APPRAISAL +========= + +Appraisal verification consists on comparing the calculated digest of an +accessed file with the value of the security.ima extended attribute. With +digest lists, appraisal verification succeeds if the calculated digest is +included in a list. Since the digital signature of each digest list is +verified, it is not possible to allow access of unauthorized files. + +For mutable files, IMA writes the current digest to security.ima so that +next file accesses are allowed even if the files have been modified. For +immutable files, IMA writes security.ima only if also additional extended +attributes should be protected by EVM. Otherwise, security.ima would be +redundant, as digest lists provide reference values. + +When IMA writes security.ima, EVM calculates the HMAC based on the current +value of protected extended attributes. Without file signatures, initial +extended attribute values will not checked until digest lists include them. +When extended attribute values are available, IMA will check them as the +same as the digest, and will not write security.ima for immutable files if +values are provided for all extended attributes protected by EVM. -- 2.11.0
