An IMA attester and verifier design should note several differences from verifying a pre-OS log. They occur because IMA measurements can occur during the attestation, when the measurement log and quote are acquired.
An IMA event log append is not atomic with the TPM extend.
Since a TPM quote can be requested at any time, it is possible that the IMA event log can have extra events. However, there will never be a missing event in the log since the log-append comes before the PCR extend.
Further, an append-extend pair is atomic with other append-extend pairs, so the appends will never be out of order with the extends.
A TPM quote is not atomic with a TPM PCR read.
A PCR read before or after a quote may not reflect the quoted PCR.
This is different from TPM 1.2, where the quote command returned both the signature and the set of PCR values being quoted. In TPM 2.0, a quote and a PCR read are separate, not an atomic command.
IMA event logs are far larger than pre-OS logs.
While a pre-OS log may hold 50 events, an IMA log can hold 10K – 100K events.
An implementation of an attester and verifier should consider the following recommendations.
The verifier should account for extra events.
Replay the event log until the quote matches and then discard extra events. Extra events are not a failure.
There is no advantage in reading the IMA PCR (PCR 10) and sending it to the verifier.
Since the read is not atomic with the quote or the event log, a mismatch is not a failure.
Looping through quote / PCR read cycles until the quote matches the PCR read will lead to poor performance and perhaps timeouts, especially early when IMA is measuring many files.
Design for incremental attestations.
Until a reboot, the IMA event log receives only appends. Once the earlier measurements are verified, there is no need to verify them again. The verified PCR 10 value serves as state.
For a long lived platform, eventually most files will be measured and few or no new events need be processed.
IMA may extend to more than one PCR using the policy condition pcr-value
. Even in this case, the payload is added to the same IMA event log.
Because there is only one IMA event log, and because each append / extend operation is atomic with other pairs, the verification algorithm does not change: replay the event log until the calculated PCR digest matches that of the quote.
Note: It is important that future IMA kernel designs do not use different event logs. If that occurred, the verifier would replay multiple event logs, each of which could have extra events. Calculating the quoted PCR digest would become computationally difficult.
The Linux kernel creates and writes the IMA Event Log (also known as the measurement list or integrity log) pseudo-files.
There are two formats:
- The
ima-event-log-binary-format
is at/sys/kernel/security/ima/binary_runtime_measurements
. - The
ima-event-log-ascii-format
is at/sys/kernel/security/ima/ascii_runtime_measurements
.
In newer kernels, the logs are at: /sys/kernel/security/integrity/ima/binary_runtime_measurements
and /sys/kernel/security/integrity/ima/ascii_runtime_measurements
. /sys/kernel/security/ima
is linked to /sys/kernel/security/integrity/ima
for backward compatibility.
Normally, systemd mounts securityfs in the kernel. It is possible that this pseudo-file will not exist because securityfs is not mounted. Remedy this by adding this line to /etc/fstab
:
none /sys/kernel/security securityfs defaults 0 0
I.e.,
- filesystem none
- mount point /sys/kernel/security
- type securityfs
- options defaults
- dump 0
- pass 0
mount
should show
securityfs on /sys/kernel/security type securityfs (rw,nosuid,nodev,noexec,relatime)
The first reader is typically an attestation application, which sends the log along with a quote (a signature over the event log) to a verifier.
The attestation application sends log records to a verifier. There is currently no standard transmission format. The format must at least provide means to recreate the original record so that hashes can be verified. The verifier validates the log against the quote signature.
This details the binary IMA event log format, field by field.
Multi-byte integer values (PCR index, length, etc.) are in the byte order of the host where the event log was created, except where otherwise noted. The sender can convert to network byte order before transmission, as long as the values are not hashed. For values that are hashed, the receiver must know the byte order.
Sizes and lengths are always in bytes.
Fields are always concatenated with no padding.
The log has no specified maximum number of records. A faulty policy that measures rapidly changing files like /var/log can have 100,000's of records. A reasonable policy will trigger about 5000 entries at boot and the log can grow to 100,000 over time based on usage.
Warning
FIXME document the ascii format.
The log can be displayed in human-readable for using the recipe at ima-log-parsing
.
An IMA event record has the following fields.
This is a 4-byte integer representing the PCR Index.
The default value is PCR 10. See config-ima-measure-pcr-idx
and the policy rule condition pcr-value
.
Due to pcr-value
, the event log may contain events that have not been extended. E.g., the event log may contain PCR 17 or PCR 24.
This is normally a 20-byte SHA-1 hash of the Template Data field. It can also be all zeros.
Exception: For the
ima
template name, the Template Hash is a SHA-1 hash of the File Data Hash field and the File Name padded with zero bytes to a length of 256 bytes. The File Name Length field is not hashed.
An all zeros hash indicates a measurement log violation. IMA is invalidating an entry. Trust in entries after that are up to the end user. Cases include:
- if the policy rule includes
digest-type
=verity
and the fs-verity digest is not present. - if one process opens for read while another has it open for write.
There is no associated length or descriptor.
There are currently two PCR extend schemes. This document calls them Type 1 and Type 2 because there is no defacto term in use.
- PCR SHA-1 Bank
If the Template Hash is not all zeros, it is used directly in the extend operation.
If the Template Hash is all zeros, an all ones digest is extended.
- PCR SHA-256 Bank
The SHA-256 bank is extended with the SHA-1 value (the Template Hash or all ones) padded with 12 bytes of zero.
- PCR SHA-1 Bank
Same as Type 1.
- PCR SHA-256 (and other non SHA-1 banks)
If the Template Hash is not all zeros, the bank is extended with the hash of the Template Data field. See the exception in Template Hash.
If the Template Hash is all zeros, the bank is extended with all ones to the length of the hash algorithm,
This is a 4-byte integer representing the length of the Template Name field.
Question: What is the maximum length?
This is a printable string representing the template name.
The string is NOT nul terminated. It is guaranteed to be printable.
For legal names, see built-in-templates
and template-data-fields
.
This is a 4-byte integer representing the length of the Template Data field.
Note that there is redundancy, in that the data fields are self-describing. This can be checked for consistency.
See Template Data Fields for the contents of this field.
The template is specified in this order:
- Compile time
config-ima-default-template
- Boot time
template-specifiers
- Policy rule
template
The predefined / built-in template names below can be
- compiled in with
config-ima-default-template
- specified with
boot-command-line-arguments
- specified within a policy rule using
template
|
is the concatenation symbol.
Field | Built-in Templates Using the Field |
---|---|
d |
ima |
------------------- | ------------------------------------------------------------------------------------------------------------------------- |
n |
ima |
------------------- | ------------------------------------------------------------------------------------------------------------------------- |
d-ng |
ima-ng , ima-sig , ima-buf , ima-modsig , evm-sig |
------------------- | ------------------------------------------------------------------------------------------------------------------------- |
n-ng |
ima-ng , ima-sig , ima-buf , ima-modsig , ima-ngv2 , ima-sigv2 , evm-sig |
------------------- | ------------------------------------------------------------------------------------------------------------------------- |
sig |
ima-sig , ima-modsig , ima-sigv2 |
------------------- | ------------------------------------------------------------------------------------------------------------------------- |
buf |
ima-buf |
------------------- | ------------------------------------------------------------------------------------------------------------------------- |
d-modsig |
ima-modsig |
------------------- | ------------------------------------------------------------------------------------------------------------------------- |
modsig |
ima-modsig |
------------------- | ------------------------------------------------------------------------------------------------------------------------- |
d-ngv2 |
ima-ngv2 , ima-sigv2 |
------------------- | ------------------------------------------------------------------------------------------------------------------------- |
evmsig |
evm-sig |
------------------- | ------------------------------------------------------------------------------------------------------------------------- |
xattrnames |
evm-sig |
------------------- | ------------------------------------------------------------------------------------------------------------------------- |
xattrlengths |
evm-sig |
------------------- | ------------------------------------------------------------------------------------------------------------------------- |
iuid |
evm-sig |
------------------- | ------------------------------------------------------------------------------------------------------------------------- |
igid |
evm-sig |
------------------- | ------------------------------------------------------------------------------------------------------------------------- |
imode |
evm-sig |
SHA-1 digest and file name.
d
|n
Digest and file name.
d-ng
|n-ng
Digest, file name, and signature.
The
func-kexec-cmdline
,func-key-check
, andfunc-critical-data
policy rules force this template
d-ng | n-ng | sig | d-modsig | modsig
Note: This template has two digest fields, d-ng and d-modsig, and two signature fields, sig and modsig.
Note that:
- This template is only used for
appended-signatures
.- The d-modsig and modsig fields are only populated if both the
measure
andappraise
rules trigger. They are not independent in this case.- The d-modsig and modsig fields are only populated if there is an appended signature.
- It triggers on
func-kexec-kernel-check
andfunc-module-check
, but does not trigger forfunc-file-check
.
See func-module-check
for kernel module appraisal details. See func-kexec-kernel-check
for kexec appraisal details.
d-ng | n-ng | evmsig | xattrnames | xattrlengths | xattrvalues | iuid | igid | imode
Template data can have the following fields. Unless specified, each is preceded by a 4-byte length. Each entry is separated by a |
character and no spaces.
What happens if a field appears multiple times?
d
is 20-byte digest, SHA-1 or zero padded MD-5 (no length)
d-ng
is a hash-length
+ hash-algorithm
+ file-data-hash
.
The file-data-hash
is similar to d-modsig
. The hash input includes the appended signature if present in the file.
Note: A file signature verifier should use a hash of the file excluding the appended signature.
This is a 4-byte integer representing the combined length of the hash-algorithm
and file-data-hash
fields. Those fields do not have explicit lengths.
This is a string representing the hash algorithm of the File Data Hash field. The values are the same as those of ima-hash
in the boot-command-line-arguments
.
In the event log, the algorithm is followed by a :
and a nul terminator.
Note this redundancy, which can be checked for consistency:
- The Hash Length minus the length of the Hash Algorithm field (including the nul terminator) yields the size of the File Data Hash.
- The length of a hash based on the Hash Algorithm yields the size of the File Data Hash.
This is a hash of the file data. It can be either the IMA digest (a digest of the entire file) or the fs-verity digest.
Note that the fs-verity digest can also include an appended signature.
For d-ng
and d-ngv2
, the hash input includes an appended signature, if present. Therefore, it cannot be used to verify the signature sig of a file with an appended signature.
For d-modsig
, the hash input does not include the appended signature. It can be used to verify the signature sig of a file with an appended signature.
The length and hash algorithm are determined by the hash-algorithm
field.
d-modsig
is a hash-length
+ hash-algorithm
+ file-data-hash
. It is similar to d-ng, but the input to the file-data-hash
omits the appended signature. It is used to verify the appended signature.
Note: In order to check the modsig signature, d-modsig (the hash) must be included in the measurement list. The
ima-modsig
template does this.
When there is no appended signature, this field will have a hash-length
of zero.
d-ngv2
contains a 4-byte length + prefix + hash algorithm + file-data-hash
. The length is that of the prefix and hash algorithm, the nul terminator, and the digest.
See ima-hash
for hash algorithm strings.
The legal values for the prefix, determined by the digest-type
policy rule, are:
ima:
verity:
Warning
What is the maximum length of the prefix?
Examples of the prefix and hash algorithm are below. There is one nul terminator after the second :
.
ima:sha256:
verity:sha256:
n
is a file name within the ima
template. n
cannot be used in a custom template.
Unlike n-ng
:
- The file name is not nul terminated.
- If the length is greater than 255, the path is removed and only the file name is recorded.
See n-ng
file-name
for the description.
This is a 4-byte integer representing the length of the file name, including the nul terminator. The maximum value is MAXPATHLEN +1, currently 4097.
Note that there is often redundancy, in that the file name is nul terminated. This can be checked for consistency.
For n-ng
, this is a nul terminated string representing the name of the file that was measured.
The file name accurately records the full path that the kernel used to access the file. Because that path can be a hard or soft link, it may not represent the actual file location.
The file name is useful for forensics when the verifier detects an error. Typical errors are:
- a file data hash is not on an approved list
- the file is not signed when required
- the file is signed with an unknown public key
- the file signature verification failed
This field contains the file signature
. This field describes the signature-hash-algorithm
. The signature algorithm is derived from the public key, which is in turn derived from the public-key-identifier
.
This field holds the extended attribute signature, never the appended signature. See modsig
.
For the extended-verification-module
, it holds the signature over the meta-data.
- If
security.ima
has a file data signature, it is used. Else, if
security.ima
has a hash, then- If
security.evm
is a portable signature, it is used. - Else there is no signature.
- If
The security.evm
portable signature is over the file meta-data.
An example for add a security.evm
portable signature is at evmctl-portable-signature
.
IMA supports several signature algorithms, including:
- RSA-2048
- ECDSA
- ECRDSA (GOST)
- SM2
This is a 4-byte integer representing the total length of the Signature Header and Signature fields. The value may be zero, indicating that those two fields are not present.
This field is fixed at 9 bytes, consisting of 5 fields.
signature-type
signature-version
signature-hash-algorithm
public-key-identifier
signature-size
These fields do not encode the signature algorithm. That is determined by mapping the public-key-identifier
to the signing certificate, which contains the signature algorithm.
This is a 1-byte field.
The legal values are:
0x03
EVM_IMA_XATTR_DIGSIGFor this value, the
signature-version
is always 0x02.0x05
EVM_XATTR_PORTABLE_DIGSIGThis indicates that the signature is the portable signature of EVM file meta-data.
0x06
IMA_VERITY_DIGSIGThis is a signature over the fs-verity file digest.
signature-version
is always 0x03.
This is a 1-byte field.
The legal values are:
0x02
file digest0x03
verity file digest
This is a 1-byte field representing the hash algorithm used for the File Data Hash.
The values are:
0x00
: MD40x01
: MD50x02
: SHA-10x03
: RIPEMD-1600x04
: SHA-2560x05
: SHA-3840x06
: SHA-5120x07
: SHA-2250x08
: RIPEMD-1280x09
: RIPEMD-2560x0a
: RIPEMD-3200x0b
: Whirlpool-2560x0c
: Whirlpool-3840x0d
: Whirlpool-5120x0e
: Tiger-128 (removed from kernel)0x0f
: Tiger-160 (removed from kernel)0x10
: Tiger-192 (removed from kernel)0x11
: SM3-2560x12
: Streebog-2560x13
: Streebog-512Note that there is redundancy, in that this field must be consistent with the Hash Algorithm field on the Template Data.
This is a 4-byte field that identifies the public key. It is the last 4 bytes of the key's X.509 certificate Subject Key Identifier.
This is a 2-byte integer representing the size of the Signature field in big endian format.
Note that there is redundancy, in that this field must be consistent with the signing public key pointed to by the
public-key-identifier
.
This field represents the signature over the File Data Hash using the key specified by the Public Key Identifier and the hash algorithm represented by the (two) Hash Algorithm fields, the signature signature-hash-algorithm
and the file data hash-algorithm
.
evmsig
follows the format of sig
. The signature-type
is 0x05
EVM_XATTR_PORTABLE_DIGSIG.
If a signature exists in security.ima
it is stored. Otherwise, the signature in security.evm
is stored.
buf
is a 4 byte length plus a buffer.
Warning
What is the maximum length of this field?
The buffer contains a variable length buffer whose contents is determined by the n-ng
field. The n-ng
field is not a file name.
These policy rules create a non-zero length buf
.
measure func=KEY_CHECK
measure func=CRITICAL_DATA
measure func=KEXEC_CMDLINE
When triggered by the measure func-key-check
policy rule, it measures data as it is loaded on different keyrings
. The n-ng
field is the nul terminated name of the keyring.
buf
can be a DER encoded X.509 IMA certificate or a dot-blacklist
hash.
Warning
A sample had a 32-byte value which appeared to be a hash. If so, where does the hash algorithm come from?
When triggered by the measure func-critical-data
policy rule, it measures data such as the SELinux state. The n-ng
field may be:
selinux-state
- a non-nul terminated string holding the SELinux stateselinux-policy-hash
dm_table_load
dm_version
=n.n.n;device metadata
name
=device name,uuid
=uuid,major
=n,minor
=n,minor_count
=n,num_targets
=n;
table_load_data
target_index
=n,target_begin
=n,target_len
=n,target_name
=[linear/crypt/integrity],target_version
=n.n.ndevice_name
=n:n,start
=n;
dm_device_resume
dm_version
as above- device metadata as above
active_table_hash
= hash algorithm : hash;current_device_capacity
=n;
kernel_version
version string
Warning
Define all n-ng field names and the meaning of the strings.
When triggered by the measure func-kexec-cmdline
policy rule and a kexec() call, the n-ng
field is
kexec-cmdline
buf
is a non-nul terminated string of boot command line arguments.
Warning
document the boot_aggregate
measurement somewhere. What triggers it?
modsig
is a PKCS#7 DER encoding of the appended signature. See the CMS document as in RFC 5652.
For appended signatures, modsig
typically requires d-modsig
, the file-data-hash
calculated omitting the appended signature.
When there is no appended signature, this field will have a length of zero.
See the ima-modsig
template for limitations. The sign-file-appended-signature
utility can add an appended signature.
Warning
(undocumented)
iuid
is a 4-byte length plus the file user ID as in etc/passwd.
This measures the user ID of the original, actual file, not the idmapped user ID within a container.
The length will be zero if the item being measured is not a file. Examples are the boot aggregate or critical data.
iuid
is a 4-byte length plus the file group ID as in etc/passwd.
This measures the group ID of the original, actual file, not the idmapped group ID within a container.
The length will be zero if the item being measured is not a file. Examples are the boot aggregate or critical data.
imode
is a 4-byte length plus the file mode (e.g., user, group, other).
The length will be zero if the item being measured is not a file. Examples are the boot aggregate or critical data.
xattrnames
is a 4-byte length and a nul terminated text list of xattr names (separated by |
). The length can be zero if no xattrs are present.
Note:
xattrnames
,xattrlengths
, andxattrvalues
must be specified together.
For example names, see extended-verification-module
.
Note: There is redundancy that should be validated by the verifier.
- The 4-byte length should equal the string length plus one for the nul terminator.
Warning
This documentation needs a full specification of for each name's contents.
xattrlengths
is a 4-byte length plus a list of the 4-byte lengths of the xattrvalues
fields. The order of the lengths is determined by the order of the xattrnames
.
Note:
xattrnames
,xattrlengths
, andxattrvalues
must be specified together.Note: There is redundancy that should be validated by the verifier.
- The
xattrlengths
length should be a multiple of 4.- The number of
xattrnames
should equal the value of thexattrlengths
length divided by 4.
xattrvalues
is a 4-byte length of all the values plus a list of values. The order and content of the values are determined by the xattrnames
field. Their lengths are determined by the xattrlengths
field.
Note:
xattrnames
,xattrlengths
, andxattrvalues
must be specified together.Note: There is redundancy that should be validated by the verifier.
- The sum of the 4-byte lengths of the
xattrvalues
fields should equal the 4-byte length of thexattrvalues
field.
Multi-byte integer values (PCR index, length, etc.) are in the byte order of the host where the event log was created. The sender can convert to network byte order before transmission, as long as the values are not hashed. For values that are hashed, the receiver must know the byte order.
Sizes and lengths are always in bytes.
Fields are always concatenated with no padding.