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