Push-Model Attestation

Warning

Push-model attestation is currently experimental. The feature is functional but the API and configuration options may change in future releases.

Introduction

In the default pull model, the Keylime verifier continuously polls agents for attestation data. This requires the verifier to reach the agent over the network.

The push model reverses this: the agent initiates connections to the verifier and proactively sends attestation evidence. This is useful when the verifier cannot directly reach the agent, for example behind firewalls, NAT, or in edge/IoT deployments.

For a detailed description of how push-model attestation works, see Push-Model Attestation.

Prerequisites

  • Keylime verifier and registrar installed and running

  • The keylime-push-model-agent binary installed on the target machine

  • A TPM 2.0 device (hardware or emulated for development)

  • Network connectivity from the agent to the verifier and registrar (the reverse is not required)

  • The verifier’s CA certificate available on the agent machine

Configuring the Verifier for Push Mode

Set the verifier’s attestation mode to push in /etc/keylime/verifier.conf:

[verifier]
mode = push

Or use a configuration snippet in /etc/keylime/verifier.conf.d/:

# /etc/keylime/verifier.conf.d/001-push-mode.conf
[verifier]
mode = push

The verifier can also be configured via environment variable:

export KEYLIME_VERIFIER_MODE=push

Note

The mode setting affects all agents on this verifier. A verifier in push mode expects agents to submit attestation data; it does not poll agents. A single verifier cannot operate in both modes simultaneously.

Additional verifier settings relevant to push mode:

  • quote_interval: Used to calculate the agent timeout threshold (quote_interval * 5). Default: 2 seconds.

  • challenge_lifetime: How long a challenge nonce remains valid for evidence submission.

  • verification_timeout: Maximum time allowed for evidence verification.

After changing the configuration, restart the verifier:

sudo systemctl restart keylime_verifier

Configuring the Push-Model Agent

The push-model agent is a separate binary from the standard Keylime agent. It is installed as keylime_push_model_agent (or keylime-push-model-agent).

The agent is configured through /etc/keylime/agent.conf (TOML format), command-line arguments, or environment variables.

Key Configuration Options

The following options are specific to or particularly important for push-model operation:

Option

Default

Description

verifier_url

https://localhost:8881

URL of the verifier. Must use HTTPS.

verifier_tls_ca_cert

cv_ca/cacert.crt

Path to the CA certificate for verifying the verifier’s TLS certificate. Relative paths are resolved from keylime_dir.

attestation_interval_seconds

60

Interval in seconds between attestation cycles.

registrar_ip

127.0.0.1

IP address of the registrar.

registrar_port

8890

Port of the registrar.

registrar_tls_enabled

false

Enable TLS for registrar communication.

registrar_tls_ca_cert

cv_ca/cacert.crt

CA certificate for registrar TLS verification.

uuid

(generated)

Agent UUID. Can be a specific UUID, generate (random), or hash_ek (derived from the EK).

api_versions

3.0

API versions supported by the agent. Defaults to 3.0 for push model.

tpm_hash_alg

sha256

TPM hash algorithm (sha256, sha384, sha512).

tpm_signing_alg

rsassa

TPM signing algorithm (rsassa, ecdsa).

keylime_dir

/var/lib/keylime

Working directory for certificates and data files.

Example Minimal Configuration

# /etc/keylime/agent.conf (push-model agent)
[agent]
uuid = "d432fbb3-d2f1-4a97-9ef7-75bd81c00000"
verifier_url = "https://verifier.example.com:8881"
verifier_tls_ca_cert = "/var/lib/keylime/cv_ca/cacert.crt"
attestation_interval_seconds = 60
registrar_ip = "registrar.example.com"
registrar_port = 8890
tpm_hash_alg = "sha256"
tpm_signing_alg = "rsassa"

Command-Line Arguments

The push-model agent accepts the following command-line arguments, which override configuration file values:

--verifier-url <URL>                    Verifier URL (required)
--registrar-url <URL>                   Registrar URL (default: http://127.0.0.1:8888)
--agent-identifier <ID>                 Agent UUID
--attestation-interval-seconds <SECS>   Attestation interval (default: 60)
--ca-certificate <PATH>                 CA certificate for TLS verification
--api-version <VERSION>                 API version (default: v3.0)
--timeout <MS>                          Request timeout in milliseconds (default: 5000)
--insecure                              Accept invalid TLS certificates (testing only)
--avoid-tpm                             Use mock TPM (testing only)

Exponential Backoff

When the agent encounters errors (network failures, verifier unavailable), it uses exponential backoff for retries:

Option

Default

Description

exponential_backoff_initial_delay

10000

Initial delay in milliseconds (10 seconds)

exponential_backoff_max_retries

5

Maximum number of retry attempts

exponential_backoff_max_delay

300000

Maximum delay in milliseconds (5 minutes)

Systemd Service Management

The push-model agent is managed as a systemd service:

# Enable the service to start on boot
sudo systemctl enable keylime_push_model_agent

# Start the service
sudo systemctl start keylime_push_model_agent

# Check service status
sudo systemctl status keylime_push_model_agent

# View logs
sudo journalctl -u keylime_push_model_agent -f

Warning

The push-model agent service (keylime_push_model_agent.service) conflicts with the standard pull-model agent service (keylime_agent.service). Only one can run at a time on the same machine. Starting one will stop the other.

The service is configured to restart on failure with a 120-second delay between restart attempts.

Enrolling an Agent for Push-Model Attestation

Use the keylime_tenant tool with the --push-model flag to enroll an agent for push-model attestation:

# Add an agent in push mode
sudo keylime_tenant -c add --push-model -u <agent-uuid>

# Add with a runtime IMA policy
sudo keylime_tenant -c add --push-model -u <agent-uuid> \
    --runtime-policy-name <policy-name>

# Add with a measured boot policy
sudo keylime_tenant -c add --push-model -u <agent-uuid> \
    --mb-policy-name <policy-name>

Note

In push mode, the -t / --targethost option is not required because the verifier does not need to connect to the agent. The agent’s IP and port are set to None in the verifier’s database.

To check the status of a push-model agent:

sudo keylime_tenant -c cvstatus -u <agent-uuid>

To remove an agent:

sudo keylime_tenant -c delete -u <agent-uuid>

TLS Configuration for Push Model

The push model uses TLS differently from the pull model:

Agent-to-verifier connection:

  • The agent connects to the verifier over HTTPS

  • The agent verifies the verifier’s server certificate using the configured CA certificate (verifier_tls_ca_cert)

  • The agent does not present a client certificate (no mTLS)

  • Authentication is done via PoP bearer tokens (see Authentication)

Agent-to-registrar connection:

  • The agent connects to the registrar to register itself

  • TLS can be enabled with registrar_tls_enabled = true

  • The registrar CA certificate is configured with registrar_tls_ca_cert

Firewall considerations:

  • No inbound ports need to be opened on the agent machine

  • The agent needs outbound access to the verifier port (default: 8881)

  • The agent needs outbound access to the registrar port (default: 8890)

To set up TLS, copy the verifier’s CA certificate to the agent machine:

# On the verifier machine, the CA cert is typically at:
# /var/lib/keylime/cv_ca/cacert.crt

# Copy to the agent machine:
scp verifier:/var/lib/keylime/cv_ca/cacert.crt /var/lib/keylime/cv_ca/cacert.crt

Verifying the Deployment

After starting both the verifier (in push mode) and the push-model agent:

  1. Check agent registration in the registrar:

    sudo keylime_tenant -c regstatus -u <agent-uuid>

  2. Check attestation status in the verifier:

    sudo keylime_tenant -c cvstatus -u <agent-uuid>

  3. View verifier logs for attestation activity:

    sudo journalctl -u keylime_verifier -f

    Successful attestations will show evidence receipt and verification completion messages.

  4. View agent logs for attestation cycles:

    sudo journalctl -u keylime_push_model_agent -f

    The agent logs will show transitions through the state machine: registration, negotiation, and attestation phases.

Troubleshooting

Agent cannot connect to verifier

  • Verify the verifier_url is correct and uses HTTPS

  • Check that the verifier is running and listening on the configured port

  • Verify network connectivity from the agent to the verifier

  • Check that the CA certificate (verifier_tls_ca_cert) matches the verifier’s server certificate

Agent shows timeout failures

The verifier marks an agent as failed if it does not receive an attestation within quote_interval * 5 seconds.

  • Verify the attestation_interval_seconds on the agent is less than the verifier’s timeout threshold

  • Check for network instability between agent and verifier

  • Review agent logs for errors during attestation cycles

PoP authentication errors

  • Ensure the agent is properly registered in the registrar (the AK must be known)

  • Check that the TPM is accessible and functioning

  • Verify the agent UUID matches between agent configuration and verifier enrollment

Agent state stuck in Negotiating

  • The verifier may be rejecting capabilities. Check verifier logs for error details

  • Ensure the TPM algorithms configured on the agent are accepted by the verifier

  • Check that the api_versions setting includes 3.0

Service fails to start

  • Check that the pull-model agent service is not running (systemctl status keylime_agent)

  • Verify the configuration file syntax (TOML format)

  • Check file permissions on TLS certificates and TPM device