0001 =================================
0002 IMA Template Management Mechanism
0003 =================================
0004
0005
0006 Introduction
0007 ============
0008
0009 The original ``ima`` template is fixed length, containing the filedata hash
0010 and pathname. The filedata hash is limited to 20 bytes (md5/sha1).
0011 The pathname is a null terminated string, limited to 255 characters.
0012 To overcome these limitations and to add additional file metadata, it is
0013 necessary to extend the current version of IMA by defining additional
0014 templates. For example, information that could be possibly reported are
0015 the inode UID/GID or the LSM labels either of the inode and of the process
0016 that is accessing it.
0017
0018 However, the main problem to introduce this feature is that, each time
0019 a new template is defined, the functions that generate and display
0020 the measurements list would include the code for handling a new format
0021 and, thus, would significantly grow over the time.
0022
0023 The proposed solution solves this problem by separating the template
0024 management from the remaining IMA code. The core of this solution is the
0025 definition of two new data structures: a template descriptor, to determine
0026 which information should be included in the measurement list; a template
0027 field, to generate and display data of a given type.
0028
0029 Managing templates with these structures is very simple. To support
0030 a new data type, developers define the field identifier and implement
0031 two functions, init() and show(), respectively to generate and display
0032 measurement entries. Defining a new template descriptor requires
0033 specifying the template format (a string of field identifiers separated
0034 by the ``|`` character) through the ``ima_template_fmt`` kernel command line
0035 parameter. At boot time, IMA initializes the chosen template descriptor
0036 by translating the format into an array of template fields structures taken
0037 from the set of the supported ones.
0038
0039 After the initialization step, IMA will call ``ima_alloc_init_template()``
0040 (new function defined within the patches for the new template management
0041 mechanism) to generate a new measurement entry by using the template
0042 descriptor chosen through the kernel configuration or through the newly
0043 introduced ``ima_template`` and ``ima_template_fmt`` kernel command line parameters.
0044 It is during this phase that the advantages of the new architecture are
0045 clearly shown: the latter function will not contain specific code to handle
0046 a given template but, instead, it simply calls the ``init()`` method of the template
0047 fields associated to the chosen template descriptor and store the result
0048 (pointer to allocated data and data length) in the measurement entry structure.
0049
0050 The same mechanism is employed to display measurements entries.
0051 The functions ``ima[_ascii]_measurements_show()`` retrieve, for each entry,
0052 the template descriptor used to produce that entry and call the show()
0053 method for each item of the array of template fields structures.
0054
0055
0056
0057 Supported Template Fields and Descriptors
0058 =========================================
0059
0060 In the following, there is the list of supported template fields
0061 ``('<identifier>': description)``, that can be used to define new template
0062 descriptors by adding their identifier to the format string
0063 (support for more data types will be added later):
0064
0065 - 'd': the digest of the event (i.e. the digest of a measured file),
0066 calculated with the SHA1 or MD5 hash algorithm;
0067 - 'n': the name of the event (i.e. the file name), with size up to 255 bytes;
0068 - 'd-ng': the digest of the event, calculated with an arbitrary hash
0069 algorithm (field format: <hash algo>:digest);
0070 - 'd-ngv2': same as d-ng, but prefixed with the "ima" or "verity" digest type
0071 (field format: <digest type>:<hash algo>:digest);
0072 - 'd-modsig': the digest of the event without the appended modsig;
0073 - 'n-ng': the name of the event, without size limitations;
0074 - 'sig': the file signature, based on either the file's/fsverity's digest[1],
0075 or the EVM portable signature, if 'security.ima' contains a file hash.
0076 - 'modsig' the appended file signature;
0077 - 'buf': the buffer data that was used to generate the hash without size limitations;
0078 - 'evmsig': the EVM portable signature;
0079 - 'iuid': the inode UID;
0080 - 'igid': the inode GID;
0081 - 'imode': the inode mode;
0082 - 'xattrnames': a list of xattr names (separated by ``|``), only if the xattr is
0083 present;
0084 - 'xattrlengths': a list of xattr lengths (u32), only if the xattr is present;
0085 - 'xattrvalues': a list of xattr values;
0086
0087
0088 Below, there is the list of defined template descriptors:
0089
0090 - "ima": its format is ``d|n``;
0091 - "ima-ng" (default): its format is ``d-ng|n-ng``;
0092 - "ima-ngv2": its format is ``d-ngv2|n-ng``;
0093 - "ima-sig": its format is ``d-ng|n-ng|sig``;
0094 - "ima-sigv2": its format is ``d-ngv2|n-ng|sig``;
0095 - "ima-buf": its format is ``d-ng|n-ng|buf``;
0096 - "ima-modsig": its format is ``d-ng|n-ng|sig|d-modsig|modsig``;
0097 - "evm-sig": its format is ``d-ng|n-ng|evmsig|xattrnames|xattrlengths|xattrvalues|iuid|igid|imode``;
0098
0099
0100 Use
0101 ===
0102
0103 To specify the template descriptor to be used to generate measurement entries,
0104 currently the following methods are supported:
0105
0106 - select a template descriptor among those supported in the kernel
0107 configuration (``ima-ng`` is the default choice);
0108 - specify a template descriptor name from the kernel command line through
0109 the ``ima_template=`` parameter;
0110 - register a new template descriptor with custom format through the kernel
0111 command line parameter ``ima_template_fmt=``.
