From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1757362AbdKGKrB (ORCPT ); Tue, 7 Nov 2017 05:47:01 -0500 Received: from lhrrgout.huawei.com ([194.213.3.17]:39786 "EHLO lhrrgout.huawei.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752862AbdKGKq6 (ORCPT ); Tue, 7 Nov 2017 05:46:58 -0500 From: Roberto Sassu To: CC: , , , , , Roberto Sassu Subject: [PATCH v2 15/15] ima: add Documentation/security/IMA-digest-lists.txt Date: Tue, 7 Nov 2017 11:37:10 +0100 Message-ID: <20171107103710.10883-16-roberto.sassu@huawei.com> X-Mailer: git-send-email 2.11.0 In-Reply-To: <20171107103710.10883-1-roberto.sassu@huawei.com> References: <20171107103710.10883-1-roberto.sassu@huawei.com> MIME-Version: 1.0 Content-Type: text/plain X-Originating-IP: [10.204.65.254] X-CFilter-Loop: Reflected X-Mirapoint-Virus-RAPID-Raw: score=unknown(0), refid=str=0001.0A020203.5A018F20.00BA,ss=1,re=0.000,recu=0.000,reip=0.000,cl=1,cld=1,fgs=0, ip=0.0.0.0, so=2013-06-18 04:22:30, dmn=2013-03-21 17:37:32 X-Mirapoint-Loop-Id: e5c0a9620a611df6bfe11d965b1283a6 Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org This patch adds the documentation of digest lists. Signed-off-by: Roberto Sassu --- 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