From patchwork Wed Nov 15 13:39:25 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Roberto Sassu X-Patchwork-Id: 10059395 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id B95C6604D4 for ; Wed, 15 Nov 2017 13:41:25 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id A858529FF8 for ; Wed, 15 Nov 2017 13:41:25 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 9C5D129FFD; Wed, 15 Nov 2017 13:41:25 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-6.9 required=2.0 tests=BAYES_00,RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 58DDB2A001 for ; Wed, 15 Nov 2017 13:41:23 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S932681AbdKONlW (ORCPT ); Wed, 15 Nov 2017 08:41:22 -0500 Received: from lhrrgout.huawei.com ([194.213.3.17]:44160 "EHLO huawei.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S932444AbdKONlT (ORCPT ); Wed, 15 Nov 2017 08:41:19 -0500 Received: from lhreml705-cah.china.huawei.com (unknown [172.18.7.106]) by Forcepoint Email with ESMTP id A05D41A5EBC7E; Wed, 15 Nov 2017 13:41:15 +0000 (GMT) Received: from localhost.localdomain (10.204.65.254) by smtpsuk.huawei.com (10.201.108.46) with Microsoft SMTP Server (TLS) id 14.3.361.1; Wed, 15 Nov 2017 13:40:58 +0000 From: Roberto Sassu To: CC: , , Roberto Sassu Subject: [USER SPACE][RFC][PATCH 4/5] digest-list-tools: documentation Date: Wed, 15 Nov 2017 14:39:25 +0100 Message-ID: <20171115133926.20108-5-roberto.sassu@huawei.com> X-Mailer: git-send-email 2.11.0 In-Reply-To: <20171115133926.20108-1-roberto.sassu@huawei.com> References: <20171115133926.20108-1-roberto.sassu@huawei.com> MIME-Version: 1.0 X-Originating-IP: [10.204.65.254] X-CFilter-Loop: Reflected Sender: linux-integrity-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-integrity@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP This patch adds the documentation of the digest-list-tools package. Signed-off-by: Roberto Sassu --- README | 143 +++++++++++++++++++++++++++++++++++++++++ docs/gen_digest_lists.txt | 87 +++++++++++++++++++++++++ docs/setup_ima_digest_list.txt | 51 +++++++++++++++ docs/verify_digest_lists.txt | 52 +++++++++++++++ 4 files changed, 333 insertions(+) create mode 100644 README create mode 100644 docs/gen_digest_lists.txt create mode 100644 docs/setup_ima_digest_list.txt create mode 100644 docs/verify_digest_lists.txt diff --git a/README b/README new file mode 100644 index 0000000..e0a2a34 --- /dev/null +++ b/README @@ -0,0 +1,143 @@ +====== +README +====== + +IMA Boot-time Configuration +=========================== + +This section explains how to generate digest lists and how to include them into +an initial ram disk, so that generated digest lists are loaded early in the boot +process. + +Measurement +----------- + +Follow these steps to create digest lists from installed packages: + +1) execute setup_ima_digest_list + +# setup_ima_digest_list initial -e + +This command creates a file containing the RPM header for each installed package +and writes them to /etc/ima/digest_lists. Metadata are saved to +/etc/ima/digest_lists/metadata. If the RPM database is not available, digest +lists can be generated directly from the measurement list. Follow the steps +below, for generating the digest list of immutable and mutable files (the -a +option of setup_ima_digest_list can be removed for immutable files). + +2) edit the bootloader configuration file and add 'ima_policy=tcb' to the kernel + command line + +3) reboot + +After reboot, the measurement list will contain only unknown files. It is +possible to create the initial digest list without the RPM database with the +steps below. The initial digest list will be created from the measurement list. + + +Follow these steps to add an additional digest list with digests of immutable +files: + +1) execute setup_ima_digest_list + +# setup_ima_digest_list immutable -a -e + +This command reads files from the root filesystem, so that IMA creates a new +measurement entry if the calculate digest is not included in the currently +loaded digest lists. Afterwards, the vi editor is automatically opened so that +users can select the digests to include in the new digest list. The new list +will be saved to /etc/ima/digest_lists/compact-unknown_digests_immutable, and a +new record will be added to /etc/ima/digest_lists/metadata. + +2) reboot + + + +Appraisal +--------- + +To enable appraisal with digest list, it is necessary to mount the filesystem +as read-only, to calculate the correct digest of mutable files. Otherwise, if +those files are written before reboot, IMA will deny access to them, because the +new digest will not be found. + +1) copy /etc/fstab to /etc/fstab.orig + +2) edit /etc/fstab and add 'ro' mount option for the root filesystem + +3) remove security.ima and security.evm extended attributes + +# find / -xdev -uid 0 -type f -exec attr -S -r ima 2> /dev/null \{} \; + +# find / -xdev -uid 0 -type f -exec attr -S -r evm 2> /dev/null \{} \; + +4) reboot + +5) execute setup_ima_digest_list + +# setup_ima_digest_list mutable -a -e + +This command reads files in / and /boot. Since the initial and immutable digest +lists have been loaded, IMA creates a new measurement entry for each mutable +file. The user can select the digests after the vi editor is opened, and a new +digest list is saved to /etc/ima/digest_lists/compact-unknown_digests_mutable. +/etc/ima/digest_lists/metadata is also updated. + +6) edit the bootloader configuration file and add 'ima_policy=appraise_tcb + evm_xattrs=security.ima' to the kernel command line + +7) reboot + +8) remount the root filesystem as read-write + +# mount -o remount,rw / + +9) restore the original /etc/fstab + +10) reboot + +'evm_xattrs=security.ima' should be used only if no additional metadata should +be protected by EVM. If it has been specified, security.ima will be created only +for mutable files. Otherwise, they will be created also for immutable files. + + + + +IMA Run-time Configuration +========================== + +This section explains how to generate additional digest lists and how to upload +them to IMA, when the system is running. + +Generation +---------- + +Digest lists can be generated with the gen_digest_lists tool. A description of +this command can be found in docs/gen_digest_lists.txt. + + + +Upload +------ + +After digest lists have been generated, they can be uploaded by writing the path +of digest list metadata to /sys/kernel/security/ima/digest_lists. For example: + +echo "/etc/ima/digest_lists/metadata" > /sys/kernel/security/ima/digest_lists + + + +Digest List Integrity Verification +================================== + +The measurement list, after loading the digest lists will look like: + +10