IMA Event Log

IMA Log Verification

IMA Attestation Background

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.

IMA Attestation Recommendations

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.

Multiple PCRs

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.

IMA Event Log Location

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.

IMA Event Log Format

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.

IMA Event Log Ascii Format

Warning

FIXME document the ascii format.

IMA Event Log Binary 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.

PCR Index

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.

Template Hash

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 Extend Type 1 (zero pad)

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 Extend Type 2 (hash)

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,

Template Name Length

This is a 4-byte integer representing the length of the Template Name field.

Question: What is the maximum length?

Template Name

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.

Template Data Length

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.

Template Data

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

Built-in Templates

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

ima

SHA-1 digest and file name.

d | n

ima-ng

Digest and file name.

d-ng | n-ng

ima-sig

Digest, file name, and signature.

d-ng | n-ng | sig

ima-buf

d-ng | n-ng | buf

The func=KEXEC_CMDLINE, func=KEY_CHECK, and func=CRITICAL_DATA policy rules force this template

ima-modsig

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 and appraise 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 and func=MODULE_CHECK, but does not trigger for func=FILE_CHECK.

See func=MODULE_CHECK for kernel module appraisal details. See func=KEXEC_KERNEL_CHECK for kexec appraisal details.

ima-ngv2

d-ngv2 | n-ng

ima-sigv2

d-ngv2 | n-ng | sig

evm-sig

d-ng | n-ng | evmsig | xattrnames | xattrlengths | xattrvalues | iuid | igid | imode

Template Data Fields

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

d is 20-byte digest, SHA-1 or zero padded MD-5 (no length)

d-ng

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.

Hash Length

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.

Hash Algorithm

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.

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

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

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

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.

n-ng

File Name Length

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.

File Name

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

sig

This field contains the file Signature. This field describes the 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 (EVM), 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.

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

Signature Length

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.

Signature Header

This field is fixed at 9 bytes, consisting of 5 fields.

Signature Type
Signature Version
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.

Signature Type

This is a 1-byte field.

The legal values are:

0x03 EVM_IMA_XATTR_DIGSIG

For this value, the Signature Version is always 0x02.
0x05 EVM_XATTR_PORTABLE_DIGSIG

This indicates that the signature is the portable signature of EVM file meta-data.
0x06 IMA_VERITY_DIGSIG

This is a signature over the fs-verity file digest. Signature Version is always 0x03.

Signature Version

This is a 1-byte field.

The legal values are:

0x02 file digest
0x03 verity file digest

Hash Algorithm

This is a 1-byte field representing the hash algorithm used for the File Data Hash.

The values are:

0x00: MD4
0x01: MD5
0x02: SHA-1
0x03: RIPEMD-160
0x04: SHA-256
0x05: SHA-384
0x06: SHA-512
0x07: SHA-225
0x08: RIPEMD-128
0x09: RIPEMD-256
0x0a: RIPEMD-320
0x0b: Whirlpool-256
0x0c: Whirlpool-384
0x0d: Whirlpool-512
0x0e: Tiger-128 (removed from kernel)
0x0f: Tiger-160 (removed from kernel)
0x10: Tiger-192 (removed from kernel)
0x11: SM3-256
0x12: Streebog-256
0x13: Streebog-512

Note that there is redundancy, in that this field must be consistent with the Hash Algorithm field on the Template Data.

Public Key Identifier

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.

Signature Size

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.

Signature

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 Hash Algorithm and the file data Hash Algorithm.

evmsig

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

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

func=KEY_CHECK

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 .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?

func=CRITICAL_DATA

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 state
selinux-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.n
  
  device_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.

func=KEXEC_CMDLINE

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

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.

uuid

Warning

(undocumented)

iuid

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.

igid

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

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

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, and xattrvalues must be specified together.

For example names, see Extended Verification Module (EVM).

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

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, and xattrvalues 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 the xattrlengths length divided by 4.

xattrvalues

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, and xattrvalues 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 the xattrvalues field.

Integer Format

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.