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