From patchwork Wed May 26 00:59:54 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Tushar Sugandhi X-Patchwork-Id: 12280465 X-Patchwork-Delegate: snitzer@redhat.com Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-13.8 required=3.0 tests=BAYES_00, HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id BC22EC4707F for ; Wed, 26 May 2021 01:10:19 +0000 (UTC) Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [216.205.24.124]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 5064F613F1 for ; Wed, 26 May 2021 01:10:19 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 5064F613F1 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=linux.microsoft.com Authentication-Results: mail.kernel.org; spf=tempfail smtp.mailfrom=dm-devel-bounces@redhat.com Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-131-TAD_IjCiM8e0-XH3wo2t6Q-1; Tue, 25 May 2021 21:10:14 -0400 X-MC-Unique: TAD_IjCiM8e0-XH3wo2t6Q-1 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 74F4118397BA; Wed, 26 May 2021 01:10:09 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 27C9C1F0E6; Wed, 26 May 2021 01:10:09 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id E8A011801262; Wed, 26 May 2021 01:10:08 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.rdu2.redhat.com [10.11.54.5]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 14Q19jfx020115 for ; Tue, 25 May 2021 21:09:46 -0400 Received: by smtp.corp.redhat.com (Postfix) id D532DF5669; Wed, 26 May 2021 01:09:45 +0000 (UTC) Received: from mimecast-mx02.redhat.com (mimecast03.extmail.prod.ext.rdu2.redhat.com [10.11.55.19]) by smtp.corp.redhat.com (Postfix) with ESMTPS id D0105C2105 for ; Wed, 26 May 2021 01:09:43 +0000 (UTC) Received: from us-smtp-1.mimecast.com (us-smtp-delivery-1.mimecast.com [207.211.31.120]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 1AEF480D0E2 for ; Wed, 26 May 2021 01:09:43 +0000 (UTC) Received: from linux.microsoft.com (linux.microsoft.com [13.77.154.182]) by relay.mimecast.com with ESMTP id us-mta-243-oKyX9LYeOKaTx8ZPDYAL8g-1; Tue, 25 May 2021 21:09:41 -0400 X-MC-Unique: oKyX9LYeOKaTx8ZPDYAL8g-1 Received: from tusharsu-Ubuntu.lan (c-71-197-163-6.hsd1.wa.comcast.net [71.197.163.6]) by linux.microsoft.com (Postfix) with ESMTPSA id 674FB20B8013; Tue, 25 May 2021 18:00:06 -0700 (PDT) DKIM-Filter: OpenDKIM Filter v2.11.0 linux.microsoft.com 674FB20B8013 From: Tushar Sugandhi To: dm-devel@redhat.com Date: Tue, 25 May 2021 17:59:54 -0700 Message-Id: <20210526005954.31564-8-tusharsu@linux.microsoft.com> In-Reply-To: <20210526005954.31564-1-tusharsu@linux.microsoft.com> References: <20210526005954.31564-1-tusharsu@linux.microsoft.com> MIME-Version: 1.0 X-Mimecast-Impersonation-Protect: Policy=CLT - Impersonation Protection Definition; Similar Internal Domain=false; Similar Monitored External Domain=false; Custom External Domain=false; Mimecast External Domain=false; Newly Observed Domain=false; Internal User Name=false; Custom Display Name List=false; Reply-to Address Mismatch=false; Targeted Threat Dictionary=false; Mimecast Threat Dictionary=false; Custom Threat Dictionary=false X-Scanned-By: MIMEDefang 2.79 on 10.11.54.5 X-MIME-Autoconverted: from quoted-printable to 8bit by lists01.pubmisc.prod.ext.phx2.redhat.com id 14Q19jfx020115 X-loop: dm-devel@redhat.com Cc: tusharsu@linux.microsoft.com, nramas@linux.microsoft.com, zohar@linux.ibm.com, snitzer@redhat.com, agk@redhat.com Subject: [dm-devel] [RFC 7/7] dm: add documentation for IMA measurement support X-BeenThere: dm-devel@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: device-mapper development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: dm-devel-bounces@redhat.com Errors-To: dm-devel-bounces@redhat.com X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=dm-devel-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com System administrators need instructions to set the IMA policy correctly to enable measurement of various DM targets using IMA. Various attestation client/server component owners also need the detailed information on how to interpret the IMA measurement data emitted by DM targets. To address that, a separate documentation page is needed. Add documentation to admin-guide to help system administrators and attestation client/server component owners interpret the measurement data generated by various DM targets, on various device / table state changes. Signed-off-by: Tushar Sugandhi --- .../admin-guide/device-mapper/dm-ima.rst | 271 ++++++++++++++++++ .../admin-guide/device-mapper/index.rst | 1 + 2 files changed, 272 insertions(+) create mode 100644 Documentation/admin-guide/device-mapper/dm-ima.rst diff --git a/Documentation/admin-guide/device-mapper/dm-ima.rst b/Documentation/admin-guide/device-mapper/dm-ima.rst new file mode 100644 index 000000000000..f7b486ed2ca1 --- /dev/null +++ b/Documentation/admin-guide/device-mapper/dm-ima.rst @@ -0,0 +1,271 @@ +====== +dm-ima +====== + +For a given system, various external services/infrastructure tools +(including the attestation service) interact with it - both during the +setup and during rest of the system run-time. They share sensitive data +and/or execute critical workload on that system. The external services +may want to verify the current run-time state of the relevant kernel +subsystems before fully trusting the system with business-critical +data/workload. + +Device mapper plays a critical role on a given system by providing +various important functionalities to the block devices using various +target types like crypt, verity, integrity etc. Each of these target +types’ functionalities can be configured with various attributes. +The attributes chosen to configure these target types can significantly +impact the security profile of the block device, and in-turn, of the +system itself. For instance, the type of encryption algorithm and the +key size determines the strength of encryption for a given block device. + +Therefore, verifying the current state of various block devices as well +as their various target attributes is crucial for external services before +fully trusting the system with business-critical data/workload. + +IMA kernel subsystem provides the necessary functionality for +device mapper to measure the state and configuration of +various block devices - + - BY device mapper itself, from within the kernel, + - in a tamper resistant way, + - and re-measured - triggered on state/configuration change. + +Setting the IMA Policy: +======================= +For IMA to measure the data on a given system, the IMA policy on the +system needs to be updated to have following line, and the system needs +to be restarted for the measurements to take effect. + +/etc/ima/ima-policy + measure func=CRITICAL_DATA label=device-mapper template=ima-buf + +The measurements will be reflected in the IMA logs, which are located at: + +/sys/kernel/security/integrity/ima/ascii_runtime_measurements +/sys/kernel/security/integrity/ima/binary_runtime_measurements + +Supported Device States: +======================== +Following device state changes will trigger IMA measurements. +01. Table load +02. Device resume +03. Device remove +04. Table clear +05. Device rename + +01. Table load: +--------------- +When a new table is loaded in a device's inactive table slot, +the device information and target specific details from the +targets in the table are measured. + +For instance, if a linear device is created with the following table entries, +#dmsetup create linear1 +0 1 linear /dev/loop0 8192 +1 1 linear /dev/loop1 8192 +2 1 linear /dev/loop2 8192 +3 1 linear /dev/loop3 8192 + +Then IMA ASCII measurement log will have an entry similar to the following, +with the format: +[device_data];[target_data_row_1];[target_data_row_2];...[target_data_row_n]; + +(converted from ASCII to text for readability) + +10 0d27cf7227d473d1c2b56b0433ca0215f2aefa0f ima-buf sha1:ec047e05fa07a9b477631d298539dcac8bdd3025 +table_load name=linear1;uuid=;capacity=0;major=253;minor=0;minor_count=1;num_targets=4; +target_type_name=linear;target_type_version=1.4.0;device_name=7:0;start=8192; +target_type_name=linear;target_type_version=1.4.0;device_name=7:1;start=8192; +target_type_name=linear;target_type_version=1.4.0;device_name=7:2;start=8192; +target_type_name=linear;target_type_version=1.4.0;device_name=7:3;start=8192; + +02. Device resume: +------------------ +When a suspended device is resumed, the device information and a sha256 hash of the +data from previous load of an active table are measured. + +For instance, if a linear device is resumed with the following command, +#dmsetup resume linear1 + +Then IMA ASCII measurement log will have an entry similar to the following, +with the format: +[device_data];active_table_hash=(sha256hash([device_data];[target_data_row_1];...[target_data_row_n]); + +(converted from ASCII to text for readability) + +10 e36dce92b9070434876d01bfc8e3cc942dbe3ce2 ima-buf sha1:fb5c71b7dc91bcc64bcae552694e809bfcb4e52e +device_resume name=linear1;uuid=;capacity=0;major=253;minor=0;minor_count=1;num_targets=4; +active_table_hash=07b98a0b742f8a45588118632cef4c5706579caa552585ec5ddb50fe03aa083b; + + + +03. Device remove: +------------------ +When a device is removed, the device information and a sha256 hash of the +data from an active and inactive table are measured. + +For instance, if a linear device is removed with the following command, +# dmsetup remove linear1 + +Then IMA ASCII measurement log will have an entry similar to the following, +with the format: +[device_data];active_table_hash=(sha256hash([device_data];[rows_from_active_table]]); +inactive_table_hash=(sha256hash([device_data];[rows_from_inactive_table]]); + +(converted from ASCII to text for readability) + +10 724e209d998546427f70ce45b508a42eeebb9d0a ima-buf sha1:27f7bc1380d38058025007df0fff94a5e8fe2374 +device_remove name=linear1;uuid=1234;capacity=4;major=253;minor=0;minor_count=1;num_targets=4; +active_table_hash=07b98a0b742f8a45588118632cef4c5706579caa552585ec5ddb50fe03aa083b; +inactive_table_hash=07b98a0b742f8a45588118632cef4c5706579caa552585ec5ddb50fe03aa083b; + + +04. Table clear: +---------------- +When an inactive table is cleared from the device, the device information and a sha256 hash of the +data from an inactive table are measured. + +For instance, if a linear device's inactive table is cleared with the following command, + +# dmsetup clear linear1 + +Then IMA ASCII measurement log will have an entry similar to the following, +with the format: +[device_data];inactive_table_hash=(sha256hash([device_data];[rows_from_inactive_table]]); + +(converted from ASCII to text for readability) + +10 5f9ae8da02ab2abde3b92df20d6d3f8b8d3369db ima-buf sha1:0105b5946801e6e42e6f42b5d90f7583e98b08c5 +table_clear name=linear1;uuid=1234;capacity=4;major=253;minor=0;minor_count=1;num_targets=4; +inactive_table_hash=80bfc94f14f7f5a3d68ea6dbbd53064f90cdd30e0ea1cbdb593f7a1f2b0e96c7; + + +05. Device rename: +------------------ +When an device's NAME or UUID is changed, the device information and the new NAME and UUID +are measured. + +For instance, if a linear device's name is changed with the following command, + +#dmsetup rename linear1 linear=2 +Then IMA ASCII measurement log will have an entry similar to the following, +with the format: +[current_device_data];new_name=;new_uuid=; + + +(converted from ASCII to text for readability) +10 10b599505894c0885aeef801ede7e04a87b4245e ima-buf sha1:b0abee16f7caa778035b49c1c8119186248b44a4 +device_rename name=linear1;uuid=1234;capacity=4;major=253;minor=0;minor_count=1;num_targets=4; +new_name=linear\=2;new_uuid=1234; + + +Supported targets: +================== +Following targets are supported to measure their data using IMA. + +01. cache +02. crypt +03. integrity +04. linear +05. mirror +06. multipath +07. raid +08. snapshot +09. striped +10. verity + +01. cache +--------- +<> + +02. crypt +----- +When a crypt target is loaded, then IMA ASCII measurement log will have an entry +similar to the following, depicting what crypt attributes are measured. + +(converted from ASCII to text for readability) + +10 7852bada6bb36d59cdc9a17369f9b9f71f46c1eb ima-buf sha1:c84c1680a37f049a01430dd3886f20a597f9fec8 + table_load name=luks-2777bb3d-6160-4dcd-8722-a86a519a95c1; + uuid=CRYPT-LUKS1-2777bb3d61604dcd8722a86a519a95c1-luks-2777bb3d-6160-4dcd-8722-a86a519a95c1; + capacity=0;major=253;minor=15;minor_count=1;num_targets=1;target_type_name=crypt; + target_type_version=1.23.0;allow_discards=n;same_cpu=n;submit_from_crypt_cpus=n;no_read_workqueue=n; + no_write_workqueue=n;iv_large_sectors=y;cipher_string=aes-xts-plain64;key_size=32;key_parts=1; + key_extra_size=0;key_mac_size=0; + +03. integrity +------------- +<> + + +04. linear +---------- +When a linear target is loaded, then IMA ASCII measurement log will have an entry +similar to the following, depicting what linear attributes are measured. + +(converted from ASCII to text for readability) +10 8fb70d291178abcc2acca33ef57adc0d3ff0e67a ima-buf sha1:4b9ae1ae655505054b0ab37181e2f9f8d847f675 +table_load name=linear1;uuid=1234;capacity=4;major=253;minor=0;minor_count=1;num_targets=4; +target_type_name=linear;target_type_version=1.4.0;device_name=7:0;start=8192; + + +05. mirror +---------- +When a mirror target is loaded, then IMA ASCII measurement log will have an entry +similar to the following, depicting what mirror attributes are measured. + +(converted from ASCII to text for readability) +10 4dd208e0fd00a5b5ca358364b5a90eb2c4f2013e ima-buf sha1:7bf75a5db56958ec07ee3f5ae356e58d52fe8910 +table_load name=test-mirror;uuid=;capacity=0;major=253;minor=7;minor_count=1;num_targets=1; +target_type_name=mirror;target_type_version=1.14.0;mirrors=2;mirror_device_0=253:2; +mirror_device_0_status=A;mirror_device_1=253:6;mirror_device_1_status=A;handle_errors=y; +keep_log=n;log_type_status=; + +06. multipath +------------- +<> + +07. raid +-------- +When a raid target is loaded, then IMA ASCII measurement log will have an entry +similar to the following, depicting what raid attributes are measured. + +(converted from ASCII to text for readability) +10 ad7ce5156f6675bacf07e57fc7d24b52128682a6 ima-buf sha1:024b05c82badd4edf8a1e877f8fc558e8de80acb +table_load name=test-raid1;uuid=;capacity=0;major=253;minor=2;minor_count=1;num_targets=1; +target_type_name=raid;target_type_version=1.15.1;raid_type=raid1;raid_disks=2;raid_state=idle; +raid_device_0_status=A;raid_device_1_status=A; + +08. snapshot +------------ +<> + +09. striped +---------- +When a linear target is loaded, then IMA ASCII measurement log will have an entry +similar to the following, depicting what linear attributes are measured. + +(converted from ASCII to text for readability) +10 b75993407d68c74de8a13a9467049a57013fb855 ima-buf sha1:fa75997f2bf9b87ee4b4dff5bd420055b22f938a +table_load name=test-raid0;uuid=;capacity=0;major=253;minor=11;minor_count=1;num_targets=1; +target_type_name=striped;target_type_version=1.6.0;stripes=4;chunk_size=128; +stripe_0_device_name=253:1;stripe_0_physical_start=0;stripe_0_status=A; +stripe_1_device_name=253:6;stripe_1_physical_start=0;stripe_1_status=A; +stripe_2_device_name=253:8;stripe_2_physical_start=0;stripe_2_status=A; +stripe_3_device_name=253:10;stripe_3_physical_start=0;stripe_3_status=A; + +10. verity +---------- +When a verity target is loaded, then IMA ASCII measurement log will have an entry +similar to the following, depicting what verity attributes are measured. + +(converted from ASCII to text for readability) + +0 c5188b404e70166baa1573fb289eea81981d5164 ima-buf sha1:a2cc6780198ede624d4f0864ffa76741332f85d3 +table_load name=vr2;uuid=CRYPT-VERITY-c5203ede74d349d89941a46c51a6784f-vr2;capacity=0;major=253;minor=16; +minor_count=1;num_targets=1; +target_type_name=verity;target_type_version=1.8.0;hash_failed=V;verity_version=1; +data_device_name=8:49;hash_device_name=8:33;verity_algorithm=sha256; +root_digest=6dbfd48cd67e5c94df25db02f15c621595675cceb39e1e88a8ccd773e408decc; +salt=daab90c9f8a164c02c59f494fa7d5cde91c415ebe0b0fb9b068c2c9d3b57a787; +ignore_zero_blocks=n;check_at_most_once=n; diff --git a/Documentation/admin-guide/device-mapper/index.rst b/Documentation/admin-guide/device-mapper/index.rst index 6cf8adc86fa8..cde52cc09645 100644 --- a/Documentation/admin-guide/device-mapper/index.rst +++ b/Documentation/admin-guide/device-mapper/index.rst @@ -13,6 +13,7 @@ Device Mapper dm-dust dm-ebs dm-flakey + dm-ima dm-init dm-integrity dm-io