Commit 7b05b116 authored by Kees Cook's avatar Kees Cook Committed by Jonathan Corbet

doc: ReSTify IMA-templates.txt

Adjust IMA-templates.txt for ReST markup and add to the index for
security/, under the Kernel API Documentation.

Cc: Mimi Zohar <zohar@linux.vnet.ibm.com>
Signed-off-by: default avatarKees Cook <keescook@chromium.org>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent 40fde647
...@@ -22,5 +22,3 @@ keys.txt ...@@ -22,5 +22,3 @@ keys.txt
- description of the kernel key retention service. - description of the kernel key retention service.
tomoyo.txt tomoyo.txt
- documentation on the TOMOYO Linux Security Module. - documentation on the TOMOYO Linux Security Module.
IMA-templates.txt
- documentation on the template management mechanism for IMA.
IMA Template Management Mechanism =================================
IMA Template Management Mechanism
=================================
==== INTRODUCTION ==== Introduction
============
The original 'ima' template is fixed length, containing the filedata hash The original ``ima`` template is fixed length, containing the filedata hash
and pathname. The filedata hash is limited to 20 bytes (md5/sha1). and pathname. The filedata hash is limited to 20 bytes (md5/sha1).
The pathname is a null terminated string, limited to 255 characters. The pathname is a null terminated string, limited to 255 characters.
To overcome these limitations and to add additional file metadata, it is To overcome these limitations and to add additional file metadata, it is
...@@ -28,61 +31,64 @@ a new data type, developers define the field identifier and implement ...@@ -28,61 +31,64 @@ a new data type, developers define the field identifier and implement
two functions, init() and show(), respectively to generate and display two functions, init() and show(), respectively to generate and display
measurement entries. Defining a new template descriptor requires measurement entries. Defining a new template descriptor requires
specifying the template format (a string of field identifiers separated specifying the template format (a string of field identifiers separated
by the '|' character) through the 'ima_template_fmt' kernel command line by the ``|`` character) through the ``ima_template_fmt`` kernel command line
parameter. At boot time, IMA initializes the chosen template descriptor parameter. At boot time, IMA initializes the chosen template descriptor
by translating the format into an array of template fields structures taken by translating the format into an array of template fields structures taken
from the set of the supported ones. from the set of the supported ones.
After the initialization step, IMA will call ima_alloc_init_template() After the initialization step, IMA will call ``ima_alloc_init_template()``
(new function defined within the patches for the new template management (new function defined within the patches for the new template management
mechanism) to generate a new measurement entry by using the template mechanism) to generate a new measurement entry by using the template
descriptor chosen through the kernel configuration or through the newly descriptor chosen through the kernel configuration or through the newly
introduced 'ima_template' and 'ima_template_fmt' kernel command line parameters. introduced ``ima_template`` and ``ima_template_fmt`` kernel command line parameters.
It is during this phase that the advantages of the new architecture are It is during this phase that the advantages of the new architecture are
clearly shown: the latter function will not contain specific code to handle clearly shown: the latter function will not contain specific code to handle
a given template but, instead, it simply calls the init() method of the template a given template but, instead, it simply calls the ``init()`` method of the template
fields associated to the chosen template descriptor and store the result fields associated to the chosen template descriptor and store the result
(pointer to allocated data and data length) in the measurement entry structure. (pointer to allocated data and data length) in the measurement entry structure.
The same mechanism is employed to display measurements entries. The same mechanism is employed to display measurements entries.
The functions ima[_ascii]_measurements_show() retrieve, for each entry, The functions ``ima[_ascii]_measurements_show()`` retrieve, for each entry,
the template descriptor used to produce that entry and call the show() the template descriptor used to produce that entry and call the show()
method for each item of the array of template fields structures. method for each item of the array of template fields structures.
==== SUPPORTED TEMPLATE FIELDS AND DESCRIPTORS ==== Supported Template Fields and Descriptors
=========================================
In the following, there is the list of supported template fields In the following, there is the list of supported template fields
('<identifier>': description), that can be used to define new template ``('<identifier>': description)``, that can be used to define new template
descriptors by adding their identifier to the format string descriptors by adding their identifier to the format string
(support for more data types will be added later): (support for more data types will be added later):
- 'd': the digest of the event (i.e. the digest of a measured file), - 'd': the digest of the event (i.e. the digest of a measured file),
calculated with the SHA1 or MD5 hash algorithm; calculated with the SHA1 or MD5 hash algorithm;
- 'n': the name of the event (i.e. the file name), with size up to 255 bytes; - 'n': the name of the event (i.e. the file name), with size up to 255 bytes;
- 'd-ng': the digest of the event, calculated with an arbitrary hash - 'd-ng': the digest of the event, calculated with an arbitrary hash
algorithm (field format: [<hash algo>:]digest, where the digest algorithm (field format: [<hash algo>:]digest, where the digest
prefix is shown only if the hash algorithm is not SHA1 or MD5); prefix is shown only if the hash algorithm is not SHA1 or MD5);
- 'n-ng': the name of the event, without size limitations; - 'n-ng': the name of the event, without size limitations;
- 'sig': the file signature. - 'sig': the file signature.
Below, there is the list of defined template descriptors: Below, there is the list of defined template descriptors:
- "ima": its format is 'd|n';
- "ima-ng" (default): its format is 'd-ng|n-ng';
- "ima-sig": its format is 'd-ng|n-ng|sig'.
- "ima": its format is ``d|n``;
- "ima-ng" (default): its format is ``d-ng|n-ng``;
- "ima-sig": its format is ``d-ng|n-ng|sig``.
==== USE ====
Use
===
To specify the template descriptor to be used to generate measurement entries, To specify the template descriptor to be used to generate measurement entries,
currently the following methods are supported: currently the following methods are supported:
- select a template descriptor among those supported in the kernel - select a template descriptor among those supported in the kernel
configuration ('ima-ng' is the default choice); configuration (``ima-ng`` is the default choice);
- specify a template descriptor name from the kernel command line through - specify a template descriptor name from the kernel command line through
the 'ima_template=' parameter; the ``ima_template=`` parameter;
- register a new template descriptor with custom format through the kernel - register a new template descriptor with custom format through the kernel
command line parameter 'ima_template_fmt='. command line parameter ``ima_template_fmt=``.
====================== ======================
Security documentation Security Documentation
====================== ======================
.. toctree:: .. toctree::
:maxdepth: 1
IMA-templates
tpm/index tpm/index
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment