1====== 2dm-ima 3====== 4 5For a given system, various external services/infrastructure tools 6(including the attestation service) interact with it - both during the 7setup and during rest of the system run-time. They share sensitive data 8and/or execute critical workload on that system. The external services 9may want to verify the current run-time state of the relevant kernel 10subsystems before fully trusting the system with business-critical 11data/workload. 12 13Device mapper plays a critical role on a given system by providing 14various important functionalities to the block devices using various 15target types like crypt, verity, integrity etc. Each of these target 16types’ functionalities can be configured with various attributes. 17The attributes chosen to configure these target types can significantly 18impact the security profile of the block device, and in-turn, of the 19system itself. For instance, the type of encryption algorithm and the 20key size determines the strength of encryption for a given block device. 21 22Therefore, verifying the current state of various block devices as well 23as their various target attributes is crucial for external services before 24fully trusting the system with business-critical data/workload. 25 26IMA kernel subsystem provides the necessary functionality for 27device mapper to measure the state and configuration of 28various block devices - 29 - BY device mapper itself, from within the kernel, 30 - in a tamper resistant way, 31 - and re-measured - triggered on state/configuration change. 32 33Setting the IMA Policy: 34======================= 35For IMA to measure the data on a given system, the IMA policy on the 36system needs to be updated to have following line, and the system needs 37to be restarted for the measurements to take effect. 38 39/etc/ima/ima-policy 40 measure func=CRITICAL_DATA label=device-mapper template=ima-buf 41 42The measurements will be reflected in the IMA logs, which are located at: 43 44/sys/kernel/security/integrity/ima/ascii_runtime_measurements 45/sys/kernel/security/integrity/ima/binary_runtime_measurements 46 47Then IMA ASCII measurement log has the following format: 48PCR TEMPLATE_DIGEST TEMPLATE ALG:EVENT_DIGEST EVENT_NAME EVENT_DATA 49 50PCR := Platform Configuration Register, in which the values are registered. 51 This is applicable if TPM chip is in use. 52TEMPLATE_DIGEST := Template digest of the IMA record. 53TEMPLATE := Template that registered the integrity value (e.g. ima-buf). 54ALG:EVENT_DIGEST = Algorithm to compute event digest, followed by digest of event data 55EVENT_NAME := Description of the event (e.g. 'table_load'). 56EVENT_DATA := The event data to be measured. 57 58The DM target data measured by IMA subsystem can alternatively 59be queried from userspace by setting DM_IMA_MEASUREMENT_FLAG with 60DM_TABLE_STATUS_CMD. 61 62Supported Device States: 63======================== 64Following device state changes will trigger IMA measurements. 6501. Table load 6602. Device resume 6703. Device remove 6804. Table clear 6905. Device rename 70 7101. Table load: 72--------------- 73When a new table is loaded in a device's inactive table slot, 74the device information and target specific details from the 75targets in the table are measured. 76 77For instance, if a linear device is created with the following table entries, 78# dmsetup create linear1 790 2 linear /dev/loop0 512 802 2 linear /dev/loop0 512 814 2 linear /dev/loop0 512 826 2 linear /dev/loop0 512 83 84Then IMA ASCII measurement log will have an entry with: 85EVENT_NAME := table_load 86EVENT_DATA := [device_data];[target_data_row_1];[target_data_row_2];...[target_data_row_n]; 87 88E.g. 89(converted from ASCII to text for readability) 9010 a8c5ff755561c7a28146389d1514c318592af49a ima-buf sha256:4d73481ecce5eadba8ab084640d85bb9ca899af4d0a122989252a76efadc5b72 91table_load 92name=linear1,uuid=,major=253,minor=0,minor_count=1,num_targets=4; 93target_index=0,target_begin=0,target_len=2,target_name=linear,target_version=1.4.0,device_name=7:0,start=512; 94target_index=1,target_begin=2,target_len=2,target_name=linear,target_version=1.4.0,device_name=7:0,start=512; 95target_index=2,target_begin=4,target_len=2,target_name=linear,target_version=1.4.0,device_name=7:0,start=512; 96target_index=3,target_begin=6,target_len=2,target_name=linear,target_version=1.4.0,device_name=7:0,start=512; 97 9802. Device resume: 99------------------ 100When a suspended device is resumed, the device information and a sha256 hash of the 101data from previous load of an active table are measured. 102 103For instance, if a linear device is resumed with the following command, 104#dmsetup resume linear1 105 106Then IMA ASCII measurement log will have an entry with: 107EVENT_NAME := device_resume 108EVENT_DATA := [device_data];active_table_hash=(sha256hash([device_data];[target_data_row_1];...[target_data_row_n]); 109 current_device_capacity=<N>; 110 111E.g. 112(converted from ASCII to text for readability) 11310 56c00cc062ffc24ccd9ac2d67d194af3282b934e ima-buf sha256:e7d12c03b958b4e0e53e7363a06376be88d98a1ac191fdbd3baf5e4b77f329b6 114device_resume 115name=linear1,uuid=,major=253,minor=0,minor_count=1,num_targets=4; 116active_table_hash=4d73481ecce5eadba8ab084640d85bb9ca899af4d0a122989252a76efadc5b72;current_device_capacity=8; 117 11803. Device remove: 119------------------ 120When a device is removed, the device information and a sha256 hash of the 121data from an active and inactive table are measured. 122 123For instance, if a linear device is removed with the following command, 124# dmsetup remove linear1 125 126Then IMA ASCII measurement log will have an entry with: 127EVENT_NAME := device_remove 128EVENT_DATA := [device_active_metadata];[device_inactive_metadata]; 129 [active_table_hash=(sha256hash([device_active_metadata];[active_table_row_1];...[active_table_row_n]), 130 [inactive_table_hash=(sha256hash([device_inactive_metadata];[inactive_table_row_1];...[inactive_table_row_n]), 131 remove_all=[y|n];current_device_capacity=<N>; 132 133E.g 134(converted from ASCII to text for readability) 13510 499812b621b705061c4514d643894483e16d2619 ima-buf sha256:c3f26b02f09bf5b464925589454bdd4d354077ce430fd1e75c9e96ce29cd1cad 136device_remove 137device_active_metadata=name=linear1,uuid=,major=253,minor=0,minor_count=1,num_targets=4; 138device_inactive_metadata=name=linear1,uuid=,major=253,minor=0,minor_count=1,num_targets=2; 139active_table_hash=4d73481ecce5eadba8ab084640d85bb9ca899af4d0a122989252a76efadc5b72, 140inactive_table_hash=5596cc857b0e887fd0c5d58dc6382513284596b07f09fd37efae2da224bd521d,remove_all=n; 141current_device_capacity=8; 142 143 14404. Table clear: 145---------------- 146When an inactive table is cleared from the device, the device information and a sha256 hash of the 147data from an inactive table are measured. 148 149For instance, if a linear device's inactive table is cleared with the following command, 150 151# dmsetup clear linear1 152 153Then IMA ASCII measurement log will have an entry with: 154EVENT_NAME := table_clear 155EVENT_DATA := [device_data];inactive_table_hash=(sha256hash([device_data];[inactive_table_row_1];...[inactive_table_row_n]); 156current_device_capacity=<N>; 157 158E.g. 159(converted from ASCII to text for readability) 16010 9c11e284d792875352d51c09f6643c96649484be ima-buf sha256:84b22b364ea4d8264fa33c38635c18ef448fa9077731fa7e5f969b1da2003ea4 161table_clear 162name=linear1,uuid=,major=253,minor=0,minor_count=1,num_targets=2; 163inactive_table_hash=5596cc857b0e887fd0c5d58dc6382513284596b07f09fd37efae2da224bd521d;current_device_capacity=0; 164 165 16605. Device rename: 167------------------ 168When an device's NAME or UUID is changed, the device information and the new NAME and UUID 169are measured. 170 171For instance, if a linear device's name is changed with the following command, 172 173#dmsetup rename linear1 linear=2 174Then IMA ASCII measurement log will have an entry with: 175EVENT_NAME := device_rename 176EVENT_DATA := [current_device_data];new_name=<new_name_value>;new_uuid=<new_uuid_value>;current_device_capacity=<N>; 177 178E.g 1: 179#dmsetup rename linear1 --setuuid 1234-5678 180 181IMA Log entry: 182(converted from ASCII to text for readability) 18310 7380ef4d1349fe1ebd74affa54e9fcc960e3cbf5 ima-buf sha256:9759e36a17a967ea43c1bf3455279395a40bd0401105ec5ad8edb9a52054efc7 184device_rename 185name=linear1,uuid=,major=253,minor=0,minor_count=1,num_targets=1;new_name=linear1,new_uuid=1234-5678;current_device_capacity=2; 186 187E.g 2: 188# dmsetup rename linear1 linear=2 18910 092c8266fc36e44f74c59f123ecfe15310f249f4 ima-buf sha256:4cf8b85c81fa6fedaeb602b05019124dbbb0605dce58fcdeea56887a8a3874cd 190device_rename 191name=linear1,uuid=1234-5678,major=253,minor=0,minor_count=1,num_targets=1;new_name=linear\=2,new_uuid=1234-5678;current_device_capacity=2; 192 193 194Supported targets: 195================== 196Following targets are supported to measure their data using IMA. 197 19801. cache 19902. crypt 20003. integrity 20104. linear 20205. mirror 20306. multipath 20407. raid 20508. snapshot 20609. striped 20710. verity 208 20901. cache 210--------- 211<<documenatation in progress>> 212 21302. crypt 214--------- 215When a crypt target is loaded, then IMA ASCII measurement log will have an entry 216similar to the following, depicting what crypt attributes are measured in EVENT_DATA. 217 218(converted from ASCII to text for readability) 21910 fe3b80a35b155bd282df778e2625066c05fc068c ima-buf sha256:2d86ce9d6f16a4a97607318aa123ae816e0ceadefeea7903abf7f782f2cb78ad 220table_load 221name=test-crypt,uuid=,major=253,minor=0,minor_count=1,num_targets=1; 222target_index=0,target_begin=0,target_len=1953125,target_name=crypt,target_version=1.23.0, 223allow_discards=y,same_cpu=n,submit_from_crypt_cpus=n,no_read_workqueue=n,no_write_workqueue=n, 224iv_large_sectors=n,cipher_string=aes-xts-plain64,key_size=32,key_parts=1,key_extra_size=0,key_mac_size=0; 225 22603. integrity 227------------- 228<<documenatation in progress>> 229 230 23104. linear 232---------- 233When a linear target is loaded, then IMA ASCII measurement log will have an entry 234similar to the following, depicting what linear attributes are measured in EVENT_DATA. 235 236(converted from ASCII to text for readability) 23710 a8c5ff755561c7a28146389d1514c318592af49a ima-buf sha256:4d73481ecce5eadba8ab084640d85bb9ca899af4d0a122989252a76efadc5b72 238table_load 239name=linear1,uuid=,major=253,minor=0,minor_count=1,num_targets=4; 240target_index=0,target_begin=0,target_len=2,target_name=linear,target_version=1.4.0,device_name=7:0,start=512; 241target_index=1,target_begin=2,target_len=2,target_name=linear,target_version=1.4.0,device_name=7:0,start=512; 242target_index=2,target_begin=4,target_len=2,target_name=linear,target_version=1.4.0,device_name=7:0,start=512; 243target_index=3,target_begin=6,target_len=2,target_name=linear,target_version=1.4.0,device_name=7:0,start=512; 244 24505. mirror 246---------- 247When a mirror target is loaded, then IMA ASCII measurement log will have an entry 248similar to the following, depicting what mirror attributes are measured in EVENT_DATA. 249 250(converted from ASCII to text for readability) 25110 90ff9113a00c367df823595dc347425ce3bfc50a ima-buf sha256:8da0678ed3bf616533573d9e61e5342f2bd16cb0b3145a08262641a743806c2e 252table_load 253name=test-mirror,uuid=,major=253,minor=4,minor_count=1,num_targets=1; 254target_index=0,target_begin=0,target_len=1953125,target_name=mirror,target_version=1.14.0, 255nr_mirrors=2,mirror_device_0=253:2,mirror_device_0_status=A,mirror_device_1=253:3,mirror_device_1_status=A, 256handle_errors=y,keep_log=n,log_type_status=; 257 25806. multipath 259------------- 260<<documenatation in progress>> 261 26207. raid 263-------- 264When a raid target is loaded, then IMA ASCII measurement log will have an entry 265similar to the following, depicting what raid attributes are measured in EVENT_DATA. 266 267(converted from ASCII to text for readability) 26810 76cb30d0cd0fe099966f20f5c82e3a2ac29b21a0 ima-buf sha256:52250f20b27376fcfb348bdfa1e1cf5acfd6646e0f3ad1a72952cffd9f818753 269table_load 270name=test-raid1,uuid=,major=253,minor=2,minor_count=1,num_targets=1; 271target_index=0,target_begin=0,target_len=1953125,target_name=raid,target_version=1.15.1, 272raid_type=raid1,raid_disks=2,raid_state=idle,raid_device_0_status=A,raid_device_1_status=A; 273 27408. snapshot 275------------ 276<<documenatation in progress>> 277 27809. striped 279----------- 280When a linear target is loaded, then IMA ASCII measurement log will have an entry 281similar to the following, depicting what linear attributes are measured in EVENT_DATA. 282 283(converted from ASCII to text for readability) 28410 7bd94fa8f799169b9f12d97b9dbdce4dc5509233 ima-buf sha256:0d148eda69887f7833f1a6042767b54359cd23b64fa941b9e1856879eee1f778 285table_load 286name=test-raid0,uuid=,major=253,minor=8,minor_count=1,num_targets=1; 287target_index=0,target_begin=0,target_len=7812096,target_name=striped,target_version=1.6.0,stripes=4,chunk_size=128, 288stripe_0_device_name=253:1,stripe_0_physical_start=0,stripe_0_status=A, 289stripe_1_device_name=253:3,stripe_1_physical_start=0,stripe_1_status=A, 290stripe_2_device_name=253:5,stripe_2_physical_start=0,stripe_2_status=A, 291stripe_3_device_name=253:7,stripe_3_physical_start=0,stripe_3_status=A; 292 29310. verity 294---------- 295When a verity target is loaded, then IMA ASCII measurement log will have an entry 296similar to the following, depicting what verity attributes are measured in EVENT_DATA. 297 298(converted from ASCII to text for readability) 29910 fced5f575b140fc0efac302c88a635174cd663da ima-buf sha256:021370c1cc93929460b06922c606334fb1d7ea5ecf04f2384f3157a446894283 300table_load 301name=test-verity,uuid=,major=253,minor=2,minor_count=1,num_targets=1; 302target_index=0,target_begin=0,target_len=1953120,target_name=verity,target_version=1.8.0,hash_failed=V, 303verity_version=1,data_device_name=253:1,hash_device_name=253:0,verity_algorithm=sha256, 304root_digest=29cb87e60ce7b12b443ba6008266f3e41e93e403d7f298f8e3f316b29ff89c5e, 305salt=e48da609055204e89ae53b655ca2216dd983cf3cb829f34f63a297d106d53e2d, 306ignore_zero_blocks=n,check_at_most_once=n; 307