IMA Configuration

Kernel Support

IMA is now compiled in by most distros. See the build flag CONFIG_IMA. Known distros are:

  • Fedora

  • CentOS

  • RHEL

  • Ubuntu

  • Debian

  • Alpine

  • OpenSuse

  • AltLinux

  • Gentoo

Configuration takes three forms:

Build Flags

Linux build flags are options that are passed to the compiler when building the kernel.

The state of build flags can be viewed with, e.g.,

cat /boot/config-`uname -r` | grep IMA_WRITE_POLICY

The boolean values are

  • “=y” if compiled statically into the kernel

  • “=m” if compiled in as a kernel module

  • “is not set” if that setting was commented out

  • not listed is the same as commented out

Relevant build flags are in https://github.com/torvalds/linux/blob/master/security/integrity/ima/Kconfig

General:

Compiled-In Policies:

Measure:

Appraise:

EVM Build Flags:

Keyring Configuration:

General

CONFIG_INTEGRITY

This boolean enables the integrity subsystem, which includes the Integrity Measurement Architecture (IMA), Extended Verification Module (EVM), the IMA-appraisal extension, the digital signature verification extension and audit measurement log support.

Each of these components can be enabled/disabled separately. Refer to the individual components for additional details.

CONFIG_IMA

This boolean enables IMA.

CONFIG_IMA_WRITE_POLICY

This boolean enables multiple appends to the custom IMA policy. See Runtime Custom Policy.

CONFIG_IMA_READ_POLICY

This boolean enables reading the current IMA policy. See Reading Policies. This option allows the root user to see the current policy rules.

If the boolean is false, either the policy file will not exist or the policy file will exist but the mode bits will not permit a read.

CONFIG_IMA_DEFAULT_HASH

This string specifies the file data hash algorithm for measurement, appraisal, and audit. It is overridden by the Boot Command Line Arguments ima_hash specifier. Both can be overridden by the hash used for the file signature algorithm.

Supported values are:

  • sha1

  • sha256

  • sha512

  • wp512

  • sm3

CONFIG_FS_VERITY

This boolean enables fs-verity read-only file-based authenticity protection.

Compiled-In Policies

Build flags can specify appraisal policy rules that are present at run time if the Boot Command Line Arguments are not used.

These are:

The rules determined by CONFIG_IMA_ARCH_POLICY persist - are not replaced. The other flags determine rules that can be replaced.

CONFIG_IMA_ARCH_POLICY

This boolean enables compiled-in architecture specific policy rules. If enabled, it loads its IMA appraise rules before other compiled-in or built-in command line appraise rules, so they cannot be overridden. They persist. I.e., they cannot be replaced by a Boot Time Custom Policy or Runtime Custom Policy, which might otherwise remove these rules.

Secure boot must appraise the entire boot software stack through the kernel. This includes the kernel kexec image and kernel modules. The kernel configuration includes a method using CONFIG_KEXEC_SIG and CONFIG_MODULE_SIG. If either is not enabled, IMA verifies (appraises) the signatures.

That is, if CONFIG_KEXEC_SIG is true, the kernel will require and verify the signature over the kernel image. If false, CONFIG_IMA_ARCH_POLICY will add an IMA appraise func=KEXEC_KERNEL_CHECK rule.

If CONFIG_MODULE_SIG is true, the kernel will verify a kernel module appended signature. If false, CONFIG_IMA_ARCH_POLICY will add an IMA appraise func=MODULE_CHECK rule.

In addition to the appraise rules, CONFIG_IMA_ARCH_POLICY always adds trusted boot measure rules for ARM and x86 UEFI based platforms.

These policy rules are based on the firmware boot status (e.g. ARM and x86 UEFI secure boot, PowerPC secure boot and trusted boot). See Secure Boot State for a method of determining whether secure and/or trusted boot is enabled.

ARM and x86

Warning

FIXME test this

If UEFI secure boot is enabled:

If CONFIG_KEXEC_SIG is false, CONFIG_IMA_ARCH_POLICY adds this rule to appraise the kernel:

appraise func=KEXEC_KERNEL_CHECK appraise_type=imasig

If CONFIG_MODULE_SIG is false, CONFIG_IMA_ARCH_POLICY adds this rule to appraise kernel modules:

appraise func=MODULE_CHECK appraise_type=imasig

Regardless of those configuration flags, CONFIG_IMA_ARCH_POLICY adds these rules to measure the kernel and kernel modules. It does not differentiate between secure and trusted boot.

measure func=KEXEC_KERNEL_CHECK
measure func=MODULE_CHECK
PowerPC

If firmware secure boot is enabled, CONFIG_IMA_ARCH_POLICY adds this rule:

appraise func=KEXEC_KERNEL_CHECK appraise_flag=check_blacklist appraise_type=imasig|modsig

and if CONFIG_MODULE_SIG is false, CONFIG_IMA_ARCH_POLICY adds this rule

appraise func=MODULE_CHECK appraise_flag=check_blacklist appraise_type=imasig|modsig

If only trusted boot is enabled, CONFIG_IMA_ARCH_POLICY adds these rules:

measure func=KEXEC_KERNEL_CHECK
measure func=MODULE_CHECK

If both firmware secure boot and trusted boot are enabled, CONFIG_IMA_ARCH_POLICY adds these rules:

measure func=KEXEC_KERNEL_CHECK template=ima-modsig
measure func=MODULE_CHECK template=ima-modsig
appraise func=KEXEC_KERNEL_CHECK appraise_flag=check_blacklist appraise_type=imasig|modsig

and if CONFIG_MODULE_SIG is false, CONFIG_IMA_ARCH_POLICY adds this rule

appraise func=MODULE_CHECK appraise_flag=check_blacklist appraise_type=imasig|modsig

CONFIG_MODULE_SIG

This boolean enables an alternative method (not IMA) for validating

appended signatures.

See CONFIG_IMA_ARCH_POLICY.

CONFIG_IMA_APPRAISE_BUILD_POLICY

This boolean enables compiled-in IMA policy rules. They are effective at runtime without needing an ima_policy on the boot command line. It loads its IMA appraise rules before other compiled-in or built-in command line appraise rules. Unlike CONFIG_IMA_ARCH_POLICY, these rules can be replaced by a Boot Time Custom Policy or Runtime Custom Policy.

If enabled CONFIG_IMA_APPRAISE_REQUIRE_FIRMWARE_SIGS, CONFIG_IMA_APPRAISE_REQUIRE_KEXEC_SIGS, CONFIG_IMA_APPRAISE_REQUIRE_MODULE_SIGS, and CONFIG_IMA_APPRAISE_REQUIRE_POLICY_SIGS determine the policy rules.

An alternative to the compiled-in policy rules is ima_policy=secure_boot on the boot command line.

CONFIG_IMA_APPRAISE_REQUIRE_FIRMWARE_SIGS

This boolean enables a policy rule to appraise firmware. CONFIG_IMA_APPRAISE_BUILD_POLICY enables this flag.

It requires all firmware to be signed. See func and appraise_type.

appraise func=FIRMWARE_CHECK appraise_type=imasig

CONFIG_IMA_APPRAISE_REQUIRE_KEXEC_SIGS

This boolean enables a policy rule to appraise kexec’ed kernel images. CONFIG_IMA_APPRAISE_BUILD_POLICY enables this flag.

It requires all kexec’ed kernel images to be signed and verified by a public key on the trusted IMA keyring. See func and appraise_type.

appraise func=KEXEC_KERNEL_CHECK appraise_type=imasig

CONFIG_IMA_APPRAISE_REQUIRE_MODULE_SIGS

This boolean enables a policy rule to appraise kernel module signatures. CONFIG_IMA_APPRAISE_BUILD_POLICY enables this flag.

It requires all kernel modules to be signed and verified by a public key on the trusted IMA keyring. See func and appraise_type.

appraise func=MODULE_CHECK appraise_type=imasig

CONFIG_IMA_APPRAISE_REQUIRE_POLICY_SIGS

This boolean enables a policy rule to appraise IMA policy signatures. CONFIG_IMA_APPRAISE_BUILD_POLICY enables this flag.

It requires the IMA policy to be signed and verified by a key on the trusted IMA keyring.See func, appraise_type, and Custom Policy.

appraise func=POLICY_CHECK appraise_type=imasig

Measure

The configuration flags affecting measurement are below. See Policy Rule Order.

CONFIG_IMA_DEFAULT_TEMPLATE

This string sets the default value for the IMA Event Log Built-in Templates, which specifies the IMA event log format.

The default value can be globally overridden by the Boot Command Line Arguments Template Specifiers. They can be overridden for a measurement by a Policy Syntax template.

The value depends upon the kernel release. A typical value is ima-ng or ima-sig.

CONFIG_IMA_MEASURE_PCR_IDX

This decimal number sets the PCR index used by IMA. The default is 10.

See also the policy rule pcr=value.

CONFIG_IMA_KEXEC

This boolean enables carrying the IMA measurement list across a kexec soft boot.

TPM PCRs are only reset on a hard reboot. In order to validate a TPM’s quote after a soft boot, the IMA measurement list of the running kernel must be saved and restored after the soft boot.

Depending on the IMA policy, the measurement list can grow to be very large.

CONFIG_IMA_DISABLE_HTABLE

This boolean affects measurement behavior. In detail, there are three factors:

  1. IMA status booleans, which indicate that the file has been opened for change since the last IMA measurement

  2. The IMA hash table, which tracks files already measured

  3. This kernel configuration flag CONFIG_IMA_DISABLE_HTABLE

The boolean is based on iversion for filesystems mounted with iversion. Without iversion, it is assumed that the file changed.

NOTE: So that IMA will process the same hash again when seen in different contexts, there are several boolean status bits:

  • ima_file

  • ima_mmap

  • ima_bprm

  • ima_read

  • ima_cred

  • evm

Warning

Add a definition of each status bit. Add cross references. How can the status bits be read?

In kernels that do not implement CONFIG_IMA_DISABLE_HTABLE, or if CONFIG_IMA_DISABLE_HTABLE is false, if the status is true and the file hash is not in the hash table, the file is measured. If the status is false (not changed) or the hash is in the hash table (already measured), the file is not measured.

The action is different if CONFIG_IMA_DISABLE_HTABLE is true. In this case, if the status is true, the file is measured, even if the hash is already in the hash table.

The intent of CONFIG_IMA_DISABLE_HTABLE true is to record the case where a file changed, but changed back before it triggered a measure policy. For example, if a file changed from hash1 to hash2 to hash1, three events would be measured. If CONFIG_IMA_DISABLE_HTABLE was false, the third event would not be measured, since hash1 was already in the hash table. An attester, in the latter case, would think the file was still in the hash2 state.

CONFIG_IMA_MEASURE_ASYMMETRIC_KEYS

This boolean enables measuring asymmetric keys when the key is loaded onto a keyring. IMA policy rules can either measure keys loaded onto any keyring or only measure keys loaded onto Keyrings specified through the keyrings condition.

Examples:

  • measure keys loaded onto any keyring

    measure func=KEY_CHECK

  • measure keys loaded onto the .ima keyring only for the root user

    measure func=KEY_CHECK uid=0 keyrings=.ima

  • measure keys on the .builtin_trusted_keys and .ima keyrings into a different PCR

    measure func=KEY_CHECK keyrings=".builtin_trusted_keys|.ima" pcr=11

CONFIG_IMA_LSM_RULES

This boolean enables policy rules containing LSM labels.

See obj_user=, obj_role=, obj_type=, subj_user=, subj_role= , and subj_type= for the policy rule syntax.

If this boolean is disabled, a policy containing these policy rules will be rejected. See Runtime Custom Policy.

CONFIG_IMA_QUEUE_EARLY_BOOT_KEYS

Built-in Policy Rules do not have rules to measure keys added to Keyrings. I.e., they do not have a func=KEY_CHECK rule.

When this boolean is set, keys added to keyrings at boot are queued. When a Custom Policy with a func=KEY_CHECK rule is specified, the queue is replayed so that each key can be measured.

Appraise

The configuration flags affecting appraisal are below. See Policy Rule Order.

CONFIG_IMA_APPRAISE

This boolean enables verifying local file integrity.

The default is enforce mode. See CONFIG_IMA_APPRAISE_BOOTPARAM and ima_appraise for options.

See also CONFIG_EVM.

CONFIG_IMA_APPRAISE_BOOTPARAM

This boolean allows the different ima_appraise modes to be specified on the boot command line.

False prevents disabling enforce mode on the boot command line for a production system.

True allows enforce mode to be disabled on the boot command line for debug or fixing hashes.

CONFIG_IMA_APPRAISE_MODSIG

This boolean adds support for signatures appended to files. The format of the appended signature is the same as that used for signed kernel modules. The modsig keyword can be as used in the IMA policy to allow a hook to accept such signatures.

See the policy rule appraise_type modsig.

CONFIG_IMA_TRUSTED_KEYRING

This boolean enables use of the trusted .ima and .evm keyrings, as opposed to the _ima and _evm keyrings.

CONFIG_INTEGRITY_SIGNATURE

This boolean enables signature verification. See CONFIG_INTEGRITY_ASYMMETRIC_KEYS.

CONFIG_INTEGRITY_ASYMMETRIC_KEYS

This boolean enables asymmetric key verification using asymmetric keys on the Keyrings.

See also CONFIG_INTEGRITY_SIGNATURE.

CONFIG_IMA_APPRAISE_SIGNED_INIT

This boolean causes the built-in ima_policy=appraise_tcb to load a policy rule requiring all root owned files be signed, as opposed to being hashed.

CONFIG_SYSTEM_BLACKLIST_KEYRING

When this boolean is set, the .blacklist keyring is checked before keys can be loaded onto Keyrings.

CONFIG_LOAD_UEFI_KEYS

When this boolean is set, the .platform keyring is provisioned with keys from the UEFI DB and the .blacklist keyring is provisioned with keys from the UEFI DBX.

CONFIG_LOAD_IPL_KEYS

When this boolean is set, the .platform keyring and the .blacklist keyring are provisioned for S390.

CONFIG_LOAD_PPC_KEYS

When this boolean is set, the .platform keyring and the .blacklist keyring are provisioned for POWER.

EVM Build Flags

The configuration flags affecting EVM are below:

CONFIG_EVM

This boolean enables EVM appraisal of extended attributes and file meta-data.

See Extended Verification Module (EVM).

CONFIG_ENCRYPTED_KEYS

This tristate enables EVM HMAC.

It can be set to either ‘y (built in to the kernel) or m if compiled as a kernel module. y is desired.

CONFIG_USER_DECRYPTED_DATA

This boolean permits the user to instantiate the EVM HMAC encrypted key with user-provided decrypted data using keyctl.

If not set, the kernel uses a random number.

It requires CONFIG_ENCRYPTED_KEYS.

See https://www.kernel.org/doc/html/latest/security/keys/trusted-encrypted.html

Warning

Add an example of keyctl.

CONFIG_TRUSTED_KEYS

This tristate enables the generation and load of a EVM HMAC master key. This is a trusted key type.

It can be set to either ‘y (built in to the kernel) or m if compiled as a kernel module. y is desired.

It requires CONFIG_ENCRYPTED_KEYS.

See https://www.kernel.org/doc/html/latest/security/keys/trusted-encrypted.html

CONFIG_EVM_ADD_XATTRS

This boolean permits the user to add additional EVM extended attributes (xattrs) at runtime.

When this option is enabled, root can add additional xattrs to the list used by EVM by writing them into /sys/kernel/security/integrity/evm/evm_xattrs.

See Extended Verification Module (EVM) for the default list.

CONFIG_EVM_EXTRA_SMACK_XATTRS

This boolean adds additional SMACK EVM extended attributes (xattrs) for the HMAC calculation. It adds:

  • security.SMACK64EXEC

  • security.SMACK64TRANSMUTE

  • security.SMACK64MMAP

Keyring Configuration

The configuration flags affecting trusted Keyrings are:

CONFIG_SECONDARY_TRUSTED_KEYRING

This boolean enables the .secondary_trusted_keys keyring to which extra keys may be added, provided those keys are not on a deny list and are vouched for by a key built into the kernel, a key on the .machine keyring, or a key already in the .secondary_trusted_keys keyring.

CONFIG_INTEGRITY_PLATFORM_KEYRING

This boolean enables the .platform keyring.

CONFIG_INTEGRITY_MACHINE_KEYRING

When this boolean is set, registered machine owner key certificates are loaded by default on the .machine keyring.

When it is clear, registered machine owner key certificates are loaded on the .platform keyring.

Note that this boolean is only supported for MOK keys on UEFI.

CONFIG_INTEGRITY_CA_MACHINE_KEYRING and CONFIG_INTEGRITY_CA_MACHINE_KEYRING_MAX can override the default.

CONFIG_INTEGRITY_CA_MACHINE_KEYRING

When this boolean is set, registered MOK key signing certificates (X.509 CA bit and keyCertSign true) are loaded on the .machine keyring. Others go on the .platform keyring.

See also CONFIG_INTEGRITY_CA_MACHINE_KEYRING_MAX.

Distribution

State

Ubuntu 23

not set

Fedora 39

set

CONFIG_INTEGRITY_CA_MACHINE_KEYRING_MAX

When this boolean is set, registered MOK key signing CA certificates (X.509 CA bit and keyCertSign true, and digitalSignature false) are loaded on the .machine keyring. Others go on the .platform keyring.

This boolean overrides CONFIG_INTEGRITY_CA_MACHINE_KEYRING.

Distribution

State

Ubuntu 23

not set

Fedora 39

set

Boot Command Line Arguments

These boot command line arguments can be added on the boot command line.

Hash Specifiers

ima_hash

The ima_hash= argument specifies the file data hash algorithm used. It overrides the CONFIG_IMA_DEFAULT_HASH algorithm.

Supported values are:

  • md5 supported only for ima_template =ima

  • sha1 ima_template =ima default

  • sha224

  • sha256 default

  • sha384

  • sha512

  • rmd128

  • rmd160

  • rmd256

  • rmd320

  • wp256

  • wp384

  • wp512

  • tgr128

  • tgr160

  • tgr192

  • sm3

  • streebog256

  • streebog512

If ima_template is ima, only md5 and sha1 are supported.

The values are taken from https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/crypto/hash_info.c.

Policy Specifiers

ima_policy

The ima_policy= argument specifies boot time IMA policy rules. There are several Built-in Policy Rules. Selecting an IMA built-in policy uses those formats. See Built-in Policy Rules for their effect.

The command line arguments ima_tcb and ima_appraise_tcb are deprecated in favor of ima_policy=tcb and ima_policy=appraise_tcb.

Multiple ima_policy specifiers can be used. Their policies are concatenated. The order is hard coded as shown in the below list.

The supported measure values for ima_policy= are:

  1. ima_policy=tcb - measure rules

  2. ima_policy=critical_data - measure rules

The supported appraise values for ima_policy= are:

  1. ima_policy=secure_boot

  2. ima_policy=appraise_tcb

  3. ima_policy=fail_securely

The two ways of using multiple specifiers are:

  • Multiple ima_policy= statements. For example:

ima_policy=tcb ima_policy=critical_data

  • Multiple specifiers using this divider line format. For example

ima_policy="tcb|critical_data"

This divider line format requires the terms to be in ". One can either edit the boot command line interactively or edit the grub boot file, e.g., /boot/loader/entries on Fedora. The grubby --args= method cannot be used because grubby does not parse the | or the " correctly.

Appraise Specifiers

ima_appraise

The ima_appraise= argument can change the default enforce appraise mode.

Note: The mode can only be changed if secure boot in the UEFI firmware is disabled. If UEFI secure boot is enabled, the default enforce cannot be changed. See Built-in Policy Rules. This is not the same as the ima_policy=secure_boot command line argument.

This command line argument is only available if CONFIG_IMA_APPRAISE_BOOTPARAM is set.

This specifies the effect of the policy rule appraise action. The four values are:

  • enforce causes IMA to appraise files . Access is denied to the appraised file if the stored hash is missing or does not match the collected value.

  • log is similar to enforce except access is not denied but only logged to /var/log/audit/audit.log.

  • off disables all appraisal. The stored hashes aren’t checked or logged. New stored hashes are not generated or updated.

  • fix enables the IMA repair mode. The stored hash reference value of a protected file can be created or updated. The file hash is (re)calculated and stored.

    fix is often used on first boot. This will allow the system to boot up even when no (or wrong) hashes are registered.

    fix only creates and updates hashes on files that would otherwise be appraised. If using a custom IMA policy, that policy must be loaded first. If neither ima_policy=appraise_tcb nor a custom policy is loaded, the default policy is to not appraise anything, and fix will have no effect. Additionally, this process may need to be repeated if there’s a change in the IMA policy.

    fix only updates hashes on files that have no signatures. It cannot create a file signature.

A typical procedure for adding file data hashes and meta-data HMAC is:

  • boot first in fix mode

  • open for read all files that will be appraised

    Example

    find / -fstype ext4 -type f -uid 0 -exec dd if='{}' of=/dev/null count=0 status=none \;

  • When done, the stored hash value should show as an extended attribute:

    Example

    getfattr -m - -d /sbin/init
# file: sbin/init
security.ima=0sAXr7Qmun5mkGDS286oZxCpdGEuKT
security.selinux="system_u:object_r:init_exec_t"

  • reboot in appraise mode

    The system should now run with appraisal enabled, causing the system to validate the hash against the stored value before using it. If it doesn’t match, then the file is not loaded and any access will be denied.

Note: Appraisal can be verified by booting with ima_appraise= off , changing the contents of a root-owned file (or the value of the extended attribute), and rebooting with ima_appraise= enforce.

evm

The evm argument can take one value, evm=fix. It requires ima_appraise =fix.

It has the same effect as ima_appraise =fix, but updates the EVM HMAC.

Template Specifiers

ima_template

The ima_template= argument specifies boot time IMA Event Log Built-in Templates. There are several Built-in Templates. See Built-in Templates for their effect.

Custom templates described in Template Data Fields are not supported. Some may work, but their use is deprecated. Use ima_template_fmt to specify custom templates.

The default value is compiled in as CONFIG_IMA_DEFAULT_TEMPLATE. The supported values for ima_template= are:

ima_canonical_fmt

The ima_canonical_fmt option sets the canonical format for the binary runtime measurements, instead of host native format.

It forces the event log to store all integral values as little endian on big endian machines.

Recommendation:

This option is suggested on all big endian machines, since a verifier may not be written to handle big endian event logs.

It is strongly suggested on a big endian machine that may receive a kexec(), since the event log may otherwise be a mix of big and little endian measurements.

Warning

FIXME Test this

ima_template_fmt

As an alternative to the built-in templates, a custom template can be specified using the fields from Template Data Fields, concatenated using the | character.

Use ima_template to specify the Built-in Templates.