[dm-devel] [RFC 7/7] dm: add documentation for IMA measurement support

[Tushar Sugandhi <tusharsu@linux.microsoft.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 <tusharsu@linux.microsoft.com>
---
 .../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_name_value>;new_uuid=<new_uuid_value>;
+
+
+(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
+---------
+<<documenatation in progress>>
+
+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
+-------------
+<<documenatation in progress>>
+
+
+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
+-------------
+<<documenatation in progress>>
+
+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
+------------
+<<documenatation in progress>>
+
+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
-- 
2.17.1


--
dm-devel mailing list
dm-devel@redhat.com
https://listman.redhat.com/mailman/listinfo/dm-devel