tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
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: Kees Cook <keescook@chromium.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
authored by
Kees Cook
and committed by
Jonathan Corbet
7b05b116
40fde647
+29
-23
-2
Documentation/security/00-INDEX
-2
Documentation/security/00-INDEX
+26
-20
Documentation/security/IMA-templates.txt
Documentation/security/IMA-templates.rst
+26
-20
Documentation/security/IMA-templates.txt
Documentation/security/IMA-templates.rst
···
1
-
IMA Template Management Mechanism
1
+
=================================
2
+
IMA Template Management Mechanism
3
+
=================================
2
4
3
5
4
-
==== INTRODUCTION ====
6
+
Introduction
7
+
============
5
8
6
-
The original 'ima' template is fixed length, containing the filedata hash
9
+
The original ``ima`` template is fixed length, containing the filedata hash
7
10
and pathname. The filedata hash is limited to 20 bytes (md5/sha1).
8
11
The pathname is a null terminated string, limited to 255 characters.
9
12
To overcome these limitations and to add additional file metadata, it is
···
31
28
two functions, init() and show(), respectively to generate and display
32
29
measurement entries. Defining a new template descriptor requires
33
30
specifying the template format (a string of field identifiers separated
34
-
by the '|' character) through the 'ima_template_fmt' kernel command line
31
+
by the ``|`` character) through the ``ima_template_fmt`` kernel command line
35
32
parameter. At boot time, IMA initializes the chosen template descriptor
36
33
by translating the format into an array of template fields structures taken
37
34
from the set of the supported ones.
38
35
39
-
After the initialization step, IMA will call ima_alloc_init_template()
36
+
After the initialization step, IMA will call ``ima_alloc_init_template()``
40
37
(new function defined within the patches for the new template management
41
38
mechanism) to generate a new measurement entry by using the template
42
39
descriptor chosen through the kernel configuration or through the newly
43
-
introduced 'ima_template' and 'ima_template_fmt' kernel command line parameters.
40
+
introduced ``ima_template`` and ``ima_template_fmt`` kernel command line parameters.
44
41
It is during this phase that the advantages of the new architecture are
45
42
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
43
+
a given template but, instead, it simply calls the ``init()`` method of the template
47
44
fields associated to the chosen template descriptor and store the result
48
45
(pointer to allocated data and data length) in the measurement entry structure.
49
46
50
47
The same mechanism is employed to display measurements entries.
51
-
The functions ima[_ascii]_measurements_show() retrieve, for each entry,
48
+
The functions ``ima[_ascii]_measurements_show()`` retrieve, for each entry,
52
49
the template descriptor used to produce that entry and call the show()
53
50
method for each item of the array of template fields structures.
54
51
55
52
56
53
57
-
==== SUPPORTED TEMPLATE FIELDS AND DESCRIPTORS ====
54
+
Supported Template Fields and Descriptors
55
+
=========================================
58
56
59
57
In the following, there is the list of supported template fields
60
-
('<identifier>': description), that can be used to define new template
58
+
``('<identifier>': description)``, that can be used to define new template
61
59
descriptors by adding their identifier to the format string
62
60
(support for more data types will be added later):
63
61
64
62
- 'd': the digest of the event (i.e. the digest of a measured file),
65
-
calculated with the SHA1 or MD5 hash algorithm;
63
+
calculated with the SHA1 or MD5 hash algorithm;
66
64
- 'n': the name of the event (i.e. the file name), with size up to 255 bytes;
67
65
- 'd-ng': the digest of the event, calculated with an arbitrary hash
68
-
algorithm (field format: [<hash algo>:]digest, where the digest
69
-
prefix is shown only if the hash algorithm is not SHA1 or MD5);
66
+
algorithm (field format: [<hash algo>:]digest, where the digest
67
+
prefix is shown only if the hash algorithm is not SHA1 or MD5);
70
68
- 'n-ng': the name of the event, without size limitations;
71
69
- 'sig': the file signature.
72
70
73
71
74
72
Below, there is the list of defined template descriptors:
75
-
- "ima": its format is 'd|n';
76
-
- "ima-ng" (default): its format is 'd-ng|n-ng';
77
-
- "ima-sig": its format is 'd-ng|n-ng|sig'.
73
+
74
+
- "ima": its format is ``d|n``;
75
+
- "ima-ng" (default): its format is ``d-ng|n-ng``;
76
+
- "ima-sig": its format is ``d-ng|n-ng|sig``.
78
77
79
78
80
79
81
-
==== USE ====
80
+
Use
81
+
===
82
82
83
83
To specify the template descriptor to be used to generate measurement entries,
84
84
currently the following methods are supported:
85
85
86
86
- select a template descriptor among those supported in the kernel
87
-
configuration ('ima-ng' is the default choice);
87
+
configuration (``ima-ng`` is the default choice);
88
88
- specify a template descriptor name from the kernel command line through
89
-
the 'ima_template=' parameter;
89
+
the ``ima_template=`` parameter;
90
90
- register a new template descriptor with custom format through the kernel
91
-
command line parameter 'ima_template_fmt='.
91
+
command line parameter ``ima_template_fmt=``.