Commit | Line | Data |
---|---|---|
7b05b116 KC |
1 | ================================= |
2 | IMA Template Management Mechanism | |
3 | ================================= | |
adf53a77 RS |
4 | |
5 | ||
7b05b116 KC |
6 | Introduction |
7 | ============ | |
adf53a77 | 8 | |
7b05b116 | 9 | The original ``ima`` template is fixed length, containing the filedata hash |
adf53a77 RS |
10 | and pathname. The filedata hash is limited to 20 bytes (md5/sha1). |
11 | The pathname is a null terminated string, limited to 255 characters. | |
12 | To overcome these limitations and to add additional file metadata, it is | |
13 | necessary to extend the current version of IMA by defining additional | |
14 | templates. For example, information that could be possibly reported are | |
15 | the inode UID/GID or the LSM labels either of the inode and of the process | |
16 | that is accessing it. | |
17 | ||
18 | However, the main problem to introduce this feature is that, each time | |
19 | a new template is defined, the functions that generate and display | |
20 | the measurements list would include the code for handling a new format | |
21 | and, thus, would significantly grow over the time. | |
22 | ||
23 | The proposed solution solves this problem by separating the template | |
24 | management from the remaining IMA code. The core of this solution is the | |
25 | definition of two new data structures: a template descriptor, to determine | |
26 | which information should be included in the measurement list; a template | |
27 | field, to generate and display data of a given type. | |
28 | ||
29 | Managing templates with these structures is very simple. To support | |
30 | a new data type, developers define the field identifier and implement | |
31 | two functions, init() and show(), respectively to generate and display | |
32 | measurement entries. Defining a new template descriptor requires | |
c2426d2a | 33 | specifying the template format (a string of field identifiers separated |
7b05b116 | 34 | by the ``|`` character) through the ``ima_template_fmt`` kernel command line |
c2426d2a RS |
35 | parameter. At boot time, IMA initializes the chosen template descriptor |
36 | by translating the format into an array of template fields structures taken | |
37 | from the set of the supported ones. | |
adf53a77 | 38 | |
7b05b116 | 39 | After the initialization step, IMA will call ``ima_alloc_init_template()`` |
adf53a77 RS |
40 | (new function defined within the patches for the new template management |
41 | mechanism) to generate a new measurement entry by using the template | |
42 | descriptor chosen through the kernel configuration or through the newly | |
7b05b116 | 43 | introduced ``ima_template`` and ``ima_template_fmt`` kernel command line parameters. |
c2426d2a RS |
44 | It is during this phase that the advantages of the new architecture are |
45 | clearly shown: the latter function will not contain specific code to handle | |
7b05b116 | 46 | a given template but, instead, it simply calls the ``init()`` method of the template |
c2426d2a RS |
47 | fields associated to the chosen template descriptor and store the result |
48 | (pointer to allocated data and data length) in the measurement entry structure. | |
adf53a77 RS |
49 | |
50 | The same mechanism is employed to display measurements entries. | |
7b05b116 | 51 | The functions ``ima[_ascii]_measurements_show()`` retrieve, for each entry, |
adf53a77 RS |
52 | the template descriptor used to produce that entry and call the show() |
53 | method for each item of the array of template fields structures. | |
54 | ||
55 | ||
56 | ||
7b05b116 KC |
57 | Supported Template Fields and Descriptors |
58 | ========================================= | |
adf53a77 RS |
59 | |
60 | In the following, there is the list of supported template fields | |
7b05b116 | 61 | ``('<identifier>': description)``, that can be used to define new template |
adf53a77 RS |
62 | descriptors by adding their identifier to the format string |
63 | (support for more data types will be added later): | |
64 | ||
65 | - 'd': the digest of the event (i.e. the digest of a measured file), | |
7b05b116 | 66 | calculated with the SHA1 or MD5 hash algorithm; |
adf53a77 RS |
67 | - 'n': the name of the event (i.e. the file name), with size up to 255 bytes; |
68 | - 'd-ng': the digest of the event, calculated with an arbitrary hash | |
64466462 | 69 | algorithm (field format: <hash algo>:digest); |
54f03916 | 70 | - 'd-ngv2': same as d-ng, but prefixed with the "ima" or "verity" digest type |
989dc725 | 71 | (field format: <digest type>:<hash algo>:digest); |
3878d505 | 72 | - 'd-modsig': the digest of the event without the appended modsig; |
ef8894b0 | 73 | - 'n-ng': the name of the event, without size limitations; |
398c42e2 MZ |
74 | - 'sig': the file signature, based on either the file's/fsverity's digest[1], |
75 | or the EVM portable signature, if 'security.ima' contains a file hash. | |
3878d505 | 76 | - 'modsig' the appended file signature; |
86b4da8c | 77 | - 'buf': the buffer data that was used to generate the hash without size limitations; |
026d7fc9 | 78 | - 'evmsig': the EVM portable signature; |
7dcfeacc RS |
79 | - 'iuid': the inode UID; |
80 | - 'igid': the inode GID; | |
f8216f6b | 81 | - 'imode': the inode mode; |
22a558f5 | 82 | - 'xattrnames': a list of xattr names (separated by ``|``), only if the xattr is |
8314b673 RS |
83 | present; |
84 | - 'xattrlengths': a list of xattr lengths (u32), only if the xattr is present; | |
85 | - 'xattrvalues': a list of xattr values; | |
adf53a77 RS |
86 | |
87 | ||
88 | Below, there is the list of defined template descriptors: | |
adf53a77 | 89 | |
7b05b116 KC |
90 | - "ima": its format is ``d|n``; |
91 | - "ima-ng" (default): its format is ``d-ng|n-ng``; | |
989dc725 | 92 | - "ima-ngv2": its format is ``d-ngv2|n-ng``; |
86b4da8c | 93 | - "ima-sig": its format is ``d-ng|n-ng|sig``; |
989dc725 | 94 | - "ima-sigv2": its format is ``d-ngv2|n-ng|sig``; |
86b4da8c | 95 | - "ima-buf": its format is ``d-ng|n-ng|buf``; |
3878d505 | 96 | - "ima-modsig": its format is ``d-ng|n-ng|sig|d-modsig|modsig``; |
88016de3 | 97 | - "evm-sig": its format is ``d-ng|n-ng|evmsig|xattrnames|xattrlengths|xattrvalues|iuid|igid|imode``; |
adf53a77 | 98 | |
7b05b116 KC |
99 | |
100 | Use | |
101 | === | |
adf53a77 RS |
102 | |
103 | To specify the template descriptor to be used to generate measurement entries, | |
104 | currently the following methods are supported: | |
105 | ||
106 | - select a template descriptor among those supported in the kernel | |
7b05b116 | 107 | configuration (``ima-ng`` is the default choice); |
adf53a77 | 108 | - specify a template descriptor name from the kernel command line through |
7b05b116 | 109 | the ``ima_template=`` parameter; |
c2426d2a | 110 | - register a new template descriptor with custom format through the kernel |
7b05b116 | 111 | command line parameter ``ima_template_fmt=``. |