keylime_agent

Keylime agent service for TPM-based attestation

Manual section:

8

Author:

Keylime Developers

Date:

September 2025

SYNOPSIS

keylime_agent

(Most operations require root privileges, use with sudo)

DESCRIPTION

The agent is a long-running service that runs on systems to be attested. It communicates with the TPM to generate quotes, collects IMA and measured boot event logs, and provides secure payload functionality. The service does not accept command-line options; behavior is configured via TOML configuration files.

CONFIGURATION

Primary configuration is read from /etc/keylime/agent.conf (or an override via env). Configuration uses TOML format. All options are under the [agent] section.

Drop-in overrides: files in /etc/keylime/agent.conf.d/ are applied in lexicographic order.

Essential configuration options:

uuid

Agent identifier (generate, hash_ek, environment, dmidecode, hostname, or explicit UUID)

ip, port

Bind address and port (default: 9002)

contact_ip, contact_port

External contact address (optional)

registrar_ip, registrar_port

Registrar endpoint

enable_agent_mtls

Enable mTLS communication

tls_dir

TLS material location (generate for auto-generate under $KEYLIME_DIR/cv_ca, default for $KEYLIME_DIR/secure)

server_key, server_key_password, server_cert

TLS files (self-signed cert)

trusted_client_ca

Trusted client CA list

enc_keyname

Payload encryption key file name

dec_payload_file

Decrypted payload file name

secure_size

tmpfs partition size for secure storage

tpm_ownerpassword

TPM owner password (generate for random)

extract_payload_zip

Auto-extract zip payloads (bool)

enable_revocation_notifications

Listen for revocation via ZeroMQ (bool)

revocation_notification_ip, revocation_notification_port

ZeroMQ endpoint

revocation_cert

Certificate to verify revocation messages

revocation_actions

Python scripts to run on revocation

payload_script

Script to run after payload extraction

enable_insecure_payload

Allow payloads without mTLS (insecure)

measure_payload_pcr

PCR to extend with payload (-1 to disable)

exponential_backoff, retry_interval, max_retries

TPM communication retry

tpm_hash_alg, tpm_encryption_alg, tpm_signing_alg

TPM algorithms

ek_handle

EK handle (generate or explicit handle like 0x81000000)

enable_iak_idevid

Enable IAK/IDevID usage (bool)

iak_idevid_template, iak_idevid_asymmetric_alg, iak_idevid_name_alg

IAK/IDevID config

idevid_password, idevid_handle, iak_password, iak_handle

Persistent key handles

iak_cert, idevid_cert

Certificate file names

run_as

User:group to drop privileges to

ima_ml_path

IMA measurement log path (default: /sys/kernel/security/ima/ascii_runtime_measurements)

measuredboot_ml_path

Measured boot log path (default: /sys/kernel/security/tpm0/binary_bios_measurements)

ENVIRONMENT

KEYLIME_AGENT_CONFIG

Path to agent.conf (highest priority)

KEYLIME_LOGGING_CONFIG

Path to logging.conf

KEYLIME_DIR

Working directory (default: /var/lib/keylime)

KEYLIME_AGENT_UUID

UUID when uuid = environment

KEYLIME_AGENT_IAK_CERT

Override iak_cert path

KEYLIME_AGENT_IDEVID_CERT

Override idevid_cert path

KEYLIME_TEST

on/true/1 enables testing mode

FILES

/etc/keylime/agent.conf

TOML format configuration file

/etc/keylime/agent.conf.d/

Drop-in snippets; read in lexicographic order

/etc/keylime/logging.conf

Logging configuration

$KEYLIME_DIR/secure/

Secure tmpfs mount for keys/payloads

$KEYLIME_DIR/cv_ca/

TLS certificates when tls_dir = generate

$KEYLIME_DIR/tpmdata.yml

TPM state persistence

RUNTIME

Start from system install:

sudo keylime_agent

Start as a systemd service:

sudo systemctl enable --now keylime_agent

Open firewall port:

sudo firewall-cmd --add-port=9002/tcp
sudo firewall-cmd --runtime-to-permanent

PREREQUISITES

  • Root privileges (use sudo)

  • TPM 2.0 available (verify with tpm2_pcrread)

  • IMA enabled in kernel

  • Network connectivity to registrar

NOTES

  • Agent uses TOML configuration format (unlike other Keylime components).

  • The Rust agent is the current implementation; Python agent is deprecated.

  • Agent generates self-signed certificates for mTLS if not provided.

SEE ALSO

keylime_verifier(8), keylime_registrar(8), keylime_tenant(1)

BUGS

Report bugs at https://github.com/keylime/rust-keylime/issues