Skip to content

Commit 00d4399

Browse files
Tushar Sugandhisnitm
Tushar Sugandhi
authored and
snitm
committed
dm: add documentation for IMA measurement support
To interpret various DM target measurement data in IMA logs, a separate documentation page is needed under Documentation/admin-guide/device-mapper. Add documentation to help system administrators and attestation client/server component owners to interpret the measurement data generated by various DM targets, on various device/table state changes. Signed-off-by: Tushar Sugandhi <[email protected]> Signed-off-by: Mike Snitzer <[email protected]>
1 parent 8ec4566 commit 00d4399

File tree

2 files changed

+307
-0
lines changed

2 files changed

+307
-0
lines changed

‎Documentation/admin-guide/device-mapper/dm-ima.rst

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

‎Documentation/admin-guide/device-mapper/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ Device Mapper
1313
dm-dust
1414
dm-ebs
1515
dm-flakey
16+
dm-ima
1617
dm-init
1718
dm-integrity
1819
dm-io

0 commit comments

Comments
 (0)