Documentation/security/IMA-templates.rst

   1 =================================
   2 IMA Template Management Mechanism
   3 =================================
   4
   5
   6 Introduction
   7 ============
   8
   9 The original ``ima`` template is fixed length, containing the filedata hash
  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
  33 specifying the template format (a string of field identifiers separated
  34 by the ``|`` character) through the ``ima_template_fmt`` kernel command line
  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.
  38
  39 After the initialization step, IMA will call ``ima_alloc_init_template()``
  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
  43 introduced ``ima_template`` and ``ima_template_fmt`` kernel command line parameters.
  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
  46 a given template but, instead, it simply calls the ``init()`` method of the template
  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.
  49
  50 The same mechanism is employed to display measurements entries.
  51 The functions ``ima[_ascii]_measurements_show()`` retrieve, for each entry,
  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
  57 Supported Template Fields and Descriptors
  58 =========================================
  59
  60 In the following, there is the list of supported template fields
  61 ``('<identifier>': description)``, that can be used to define new template
  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),
  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, where the digest
  70    prefix is shown only if the hash algorithm is not SHA1 or MD5);
  71  - 'n-ng': the name of the event, without size limitations;
  72  - 'sig': the file signature;
  73  - 'buf': the buffer data that was used to generate the hash without size limitations;
  74
  75
  76 Below, there is the list of defined template descriptors:
  77
  78  - "ima": its format is ``d|n``;
  79  - "ima-ng" (default): its format is ``d-ng|n-ng``;
  80  - "ima-sig": its format is ``d-ng|n-ng|sig``;
  81  - "ima-buf": its format is ``d-ng|n-ng|buf``;
  82
  83
  84 Use
  85 ===
  86
  87 To specify the template descriptor to be used to generate measurement entries,
  88 currently the following methods are supported:
  89
  90  - select a template descriptor among those supported in the kernel
  91    configuration (``ima-ng`` is the default choice);
  92  - specify a template descriptor name from the kernel command line through
  93    the ``ima_template=`` parameter;
  94  - register a new template descriptor with custom format through the kernel
  95    command line parameter ``ima_template_fmt=``.