Commit | Line | Data |
---|---|---|
adf53a77 RS |
1 | IMA Template Management Mechanism |
2 | ||
3 | ||
4 | ==== INTRODUCTION ==== | |
5 | ||
6 | The original 'ima' template is fixed length, containing the filedata hash | |
7 | and pathname. The filedata hash is limited to 20 bytes (md5/sha1). | |
8 | The pathname is a null terminated string, limited to 255 characters. | |
9 | To overcome these limitations and to add additional file metadata, it is | |
10 | necessary to extend the current version of IMA by defining additional | |
11 | templates. For example, information that could be possibly reported are | |
12 | the inode UID/GID or the LSM labels either of the inode and of the process | |
13 | that is accessing it. | |
14 | ||
15 | However, the main problem to introduce this feature is that, each time | |
16 | a new template is defined, the functions that generate and display | |
17 | the measurements list would include the code for handling a new format | |
18 | and, thus, would significantly grow over the time. | |
19 | ||
20 | The proposed solution solves this problem by separating the template | |
21 | management from the remaining IMA code. The core of this solution is the | |
22 | definition of two new data structures: a template descriptor, to determine | |
23 | which information should be included in the measurement list; a template | |
24 | field, to generate and display data of a given type. | |
25 | ||
26 | Managing templates with these structures is very simple. To support | |
27 | a new data type, developers define the field identifier and implement | |
28 | two functions, init() and show(), respectively to generate and display | |
29 | measurement entries. Defining a new template descriptor requires | |
c2426d2a RS |
30 | specifying the template format (a string of field identifiers separated |
31 | by the '|' character) through the 'ima_template_fmt' kernel command line | |
32 | parameter. At boot time, IMA initializes the chosen template descriptor | |
33 | by translating the format into an array of template fields structures taken | |
34 | from the set of the supported ones. | |
adf53a77 RS |
35 | |
36 | After the initialization step, IMA will call ima_alloc_init_template() | |
37 | (new function defined within the patches for the new template management | |
38 | mechanism) to generate a new measurement entry by using the template | |
39 | descriptor chosen through the kernel configuration or through the newly | |
c2426d2a RS |
40 | introduced 'ima_template' and 'ima_template_fmt' kernel command line parameters. |
41 | It is during this phase that the advantages of the new architecture are | |
42 | clearly shown: the latter function will not contain specific code to handle | |
43 | a given template but, instead, it simply calls the init() method of the template | |
44 | fields associated to the chosen template descriptor and store the result | |
45 | (pointer to allocated data and data length) in the measurement entry structure. | |
adf53a77 RS |
46 | |
47 | The same mechanism is employed to display measurements entries. | |
48 | The functions ima[_ascii]_measurements_show() retrieve, for each entry, | |
49 | the template descriptor used to produce that entry and call the show() | |
50 | method for each item of the array of template fields structures. | |
51 | ||
52 | ||
53 | ||
54 | ==== SUPPORTED TEMPLATE FIELDS AND DESCRIPTORS ==== | |
55 | ||
56 | In the following, there is the list of supported template fields | |
57 | ('<identifier>': description), that can be used to define new template | |
58 | descriptors by adding their identifier to the format string | |
59 | (support for more data types will be added later): | |
60 | ||
61 | - 'd': the digest of the event (i.e. the digest of a measured file), | |
62 | calculated with the SHA1 or MD5 hash algorithm; | |
63 | - 'n': the name of the event (i.e. the file name), with size up to 255 bytes; | |
64 | - 'd-ng': the digest of the event, calculated with an arbitrary hash | |
65 | algorithm (field format: [<hash algo>:]digest, where the digest | |
66 | prefix is shown only if the hash algorithm is not SHA1 or MD5); | |
ef8894b0 MZ |
67 | - 'n-ng': the name of the event, without size limitations; |
68 | - 'sig': the file signature. | |
adf53a77 RS |
69 | |
70 | ||
71 | Below, there is the list of defined template descriptors: | |
72 | - "ima": its format is 'd|n'; | |
ef8894b0 MZ |
73 | - "ima-ng" (default): its format is 'd-ng|n-ng'; |
74 | - "ima-sig": its format is 'd-ng|n-ng|sig'. | |
adf53a77 RS |
75 | |
76 | ||
77 | ||
78 | ==== USE ==== | |
79 | ||
80 | To specify the template descriptor to be used to generate measurement entries, | |
81 | currently the following methods are supported: | |
82 | ||
83 | - select a template descriptor among those supported in the kernel | |
84 | configuration ('ima-ng' is the default choice); | |
85 | - specify a template descriptor name from the kernel command line through | |
c2426d2a RS |
86 | the 'ima_template=' parameter; |
87 | - register a new template descriptor with custom format through the kernel | |
88 | command line parameter 'ima_template_fmt='. |