Authentication

Most API interactions are secured using mTLS connections. By default there are two CAs involved, but the components can be configured to accommodate more complex setups.

(The revocation process also uses a CA, but this is different to those CAs)

In push mode, the PoP (Proof of Possession) authentication is mandatory for requests by agents for attestation operations.

Security Note: Never distribute client certificates signed by the verifier’s trusted CA to agents. In push-attestation, agents should only authenticate using PoP tokens. In pull-model, agent should use its self-signed server certificate. If an agent had a valid client certificate AND didn’t send an Authorization header, they would be identified as an admin by the verifier.

Server Components CA

This CA is created by verifier on startup. It contains the server certificates and keys used by the verifier and registrar for their respective HTTPS interfaces. Then it also contains the client certificates and keys that are used by the tenant to connect to the registrar, verifier and agent. Also the verifier uses that certificate to authenticate itself against the agent.

Agent Keylime CA

The agent runs an HTTPS server and provides its certificate to the registrar (mtls_cert).

The server component CA certificate is also required on the agent to authenticate connections from the tenant and verifier. By default /var/lib/keylime/cv_ca/cacert.crt is used.

Authorization Framework

Starting from version 7.14.0 (API version 2.5), Keylime implements a pluggable authorization framework to control access to API operations. The framework separates authentication (proving identity) from authorization (permission to perform actions).

Overview

Keylime’s authorization framework is pluggable, allowing different authorization providers to implement various access control policies. Each provider can define its own rules for determining which identities can perform which operations.

Authorization Providers

The authorization provider is configured separately for each component:

Verifier Configuration

[verifier]
authorization_provider = simple

Registrar Configuration

[registrar]
authorization_provider = simple

Available Providers

  • simple (default): Role-based access control with strict separation between agent and admin authentication methods

Future providers may include LDAP, OPA (Open Policy Agent), or custom implementations for enterprise deployments requiring fine-grained RBAC.

SimpleAuthProvider

The simple provider is the default authorization provider. It classifies operations into four categories:

  • Public operations: No authentication required

    • Version information (GET /versions)

    • Server information (GET /)

    • Identity verification (GET /verify/identity)

    • Evidence verification (POST /verify/evidence)

    • Session creation for push attestation (POST /sessions)

    • Session update/extend (PATCH /sessions/:session_id)

  • Agent-only operations: Requires PoP bearer token authentication

    • Agents can only access their own resources (identity must match resource)

    • Submit attestations (POST /agents/:agent_id/attestations)

  • Agent-or-admin operations: Accessible by both roles with different scopes

    • GET /agents/:agent_id - Agents can read own status only, admins can read any agent

  • Admin operations: Requires mTLS client certificate authentication

    • Full access to all management operations

    • Create/delete/update agents

    • Manage IMA and UEFI policies

    • View attestation results for any agent

The simple provider implements strict separation between agent and admin authentication methods:

Authentication Method Separation

Authorization Header

Authentication Path

Identity Type

Present (Bearer token)

Agent path

agent or anonymous

Absent

Admin path (mTLS)

admin or anonymous

Critical Security Rule: If an Authorization header is present in a request, the request is always treated as an agent authentication attempt. There is no fallback to mTLS authentication. This prevents privilege escalation attacks where an attacker might send an invalid bearer token while having a valid mTLS certificate.

Authorization Rules

  1. Public actions: Always allowed regardless of identity

  2. Agent-only actions: Requires identity_type == "agent" AND identity == resource

  3. Agent-or-admin actions: Agent with identity == resource OR admin

  4. Admin actions: Requires identity_type == "admin"

Certificate Requirements

The security model relies on proper certificate management:

Role

Authentication

Certificate Requirements

Agent (pull mode)

N/A (agent is server)

Self-signed server cert acceptable. If CA-issued, must have Server Auth EKU only.

Agent (push mode)

PoP bearer token

No client certs from trusted CA. Use PoP tokens only.

Admin/Tenant

mTLS client cert

Signed by verifier’s trusted CA with Client Auth EKU.

Security Note: Never distribute client certificates signed by the verifier’s trusted CA to agents. Agents should only authenticate using PoP tokens. If an agent had a valid client certificate AND didn’t send an Authorization header, they would be identified as an admin.

Pull Mode Agent Certificates

Pull mode agents act as servers (the verifier connects to them). Their certificates have no security relevance for authorization because:

  1. Trust is established via TPM quote, not the certificate

  2. The agent’s certificate is added to the verifier’s client-side trust store only for that specific connection

  3. The agent never connects to the verifier as a client

Self-signed certificates are acceptable for pull mode agents.

If the pull mode agent certificate is issued by the trusted CA (instead of self-signed), it must have the Server Authentication EKU (OID 1.3.6.1.5.5.7.3.1). This prevents the certificate from being used for client authentication, which would grant admin access.

Default Configuration (Development/Testing)

When the verifier is configured with tls_dir = generate, it automatically creates:

  • A Certificate Authority (CA)

  • Server certificates for the verifier

  • Client certificates for admin operations

The automatically generated client certificate has:

  • Common Name (CN): client

  • Location: /var/lib/keylime/cv_ca/client-cert.crt

  • Private Key: /var/lib/keylime/cv_ca/client-private.pem

The tenant tool (used for admin operations) is configured to use this certificate by default:

[tenant]
tls_dir = default
client_cert = default      # Uses /var/lib/keylime/cv_ca/client-cert.crt
client_key = default       # Uses /var/lib/keylime/cv_ca/client-private.pem

What This Means

With default configuration:

  • The verifier automatically generates all necessary certificates on startup

  • The tenant tool automatically uses the generated client certificate

  • Admin operations work out-of-the-box without manual certificate management

  • This setup is suitable for development, testing, and single-admin deployments

Production Configuration (Multi-Admin Deployments)

For production deployments with multiple administrators, you should generate unique certificates for each administrator.

Step 1: Generate Admin Certificates

For each administrator, generate a unique certificate:

# Generate certificate for admin1
keylime_ca -d /var/lib/keylime/cv_ca create -n admin1.example.com

# Generate certificate for admin2
keylime_ca -d /var/lib/keylime/cv_ca create -n admin2.example.com

Step 2: Package and Distribute Certificates

Create certificate packages for distribution:

# Create package for admin1
keylime_ca -d /var/lib/keylime/cv_ca pkg -n admin1.example.com

# This creates: admin1.example.com-pkg.zip

Distribute the certificate package securely to each administrator (encrypted email, secure file transfer, etc.).

Step 3: Configure Tenant Tool

Each administrator should extract their certificate package and configure the tenant tool:

# Extract certificate package
unzip admin1.example.com-pkg.zip -d ~/keylime-certs/

# Configure tenant tool
cat > ~/.keylime/tenant.conf <<EOF
[tenant]
tls_dir = ~/keylime-certs/
client_cert = admin1.example.com-cert.crt
client_key = admin1.example.com-private.pem
trusted_server_ca = [cacert.crt]
EOF

Admin Operations Reference

The following operations require admin authentication (mTLS client certificate signed by the verifier’s trusted CA):

Agent Management

  • GET /v3/agents - List all agents

  • POST /v3/agents - Create/enroll a new agent

  • GET /v3/agents/:agent_id - View agent details (admin can view any agent)

  • PATCH /v3/agents/:agent_id - Update agent configuration

  • DELETE /v3/agents/:agent_id - Delete an agent

  • PUT /v3/agents/:agent_id/reactivate - Reactivate an agent

  • PUT /v3/agents/:agent_id/stop - Stop agent verification

IMA Policy Management

  • GET /v3/policies/ima - List IMA policies

  • POST /v3/policies/ima - Create IMA policy

  • GET /v3/policies/ima/:name - View IMA policy

  • PATCH /v3/policies/ima/:name - Update IMA policy

  • DELETE /v3/policies/ima/:name - Delete IMA policy

UEFI/Measured Boot Policy Management

  • GET /v3/refstates/uefi - List UEFI reference states

  • POST /v3/refstates/uefi - Create UEFI reference state

  • GET /v3/refstates/uefi/:name - View UEFI reference state

  • PATCH /v3/refstates/uefi/:name - Update UEFI reference state

  • DELETE /v3/refstates/uefi/:name - Delete UEFI reference state

Attestation Viewing (Push Mode)

  • GET /v3/agents/:agent_id/attestations - View all attestations for an agent

  • GET /v3/agents/:agent_id/attestations/:index - View specific attestation

  • GET /v3/agents/:agent_id/attestations/latest - View latest attestation

Agent-Only Operations Reference

The following operations require agent authentication (PoP bearer token) and are exclusively for agents - admins cannot access these endpoints:

Attestation Submission (Push Mode)

  • POST /v3/agents/:agent_id/attestations - Submit attestation (own agent_id only)

  • PATCH /v3/agents/:agent_id/attestations/:index - Update attestation

  • PATCH /v3/agents/:agent_id/attestations/latest - Update latest attestation

Note on Session Management

Session operations (POST /v3/sessions, PATCH /v3/sessions/:session_id) are public at the authorization layer. The session controller validates the PoP response or existing token internally. This allows agents to complete initial PoP authentication (when they don’t yet have a token) and extend existing sessions.

Agent-or-Admin Operations Reference

The following operations are accessible to both agents and admins:

  • GET /v3/agents/:agent_id - Agent can read own status (agent_id must match token), admin can read any agent

Security Considerations

Authentication Method Separation

The strict separation between bearer token and mTLS authentication is a critical security feature:

  1. If an Authorization header is present, mTLS is never used

  2. This prevents an attacker with both a valid mTLS cert and an expired/invalid token from falling back to admin authentication

  3. Agents should never have client certificates signed by the trusted CA

Certificate Validation

The verifier validates admin mTLS certificates as follows:

  1. Certificate Trust: The certificate must be signed by a CA trusted by the verifier (configured via trusted_client_ca)

  2. Certificate Validity: The certificate must not be expired or revoked

  3. EKU Check: The certificate must have Client Authentication EKU

Registrar Authorization

The registrar uses a simpler authorization model than the verifier. Since the registrar is primarily used for agent registration (which must be public) and administrative queries, it has only two categories of operations:

Public Operations (No Authentication Required)

  • POST /v2/agents - Agent registration

  • POST /v2/agents/:agent_id - Agent registration (legacy endpoint)

  • POST /v2/agents/:agent_id/activate - Agent activation

  • PUT /v2/agents/:agent_id/activate - Agent activation (legacy endpoint)

  • PUT /v2/agents/:agent_id - Agent activation (legacy endpoint)

  • GET /version - Version information

Admin Operations (Requires mTLS Client Certificate)

  • GET /v2/agents - List all registered agents

  • GET /v2/agents/:agent_id - View agent registration details

  • DELETE /v2/agents/:agent_id - Delete agent registration

Registrar Security Model

Unlike the verifier, the registrar does not use PoP bearer tokens. The security model is:

  1. Public endpoints: Agent registration endpoints are accessible without authentication because agents need to register before they have any credentials

  2. Admin endpoints: All management operations (list, view, delete) require mTLS client certificate authentication

Configuration

The registrar has its own TLS configuration and can use a completely separate CA from the verifier. Admin operations require a client certificate signed by the CA specified in the registrar’s trusted_client_ca configuration:

[registrar]
# Use a dedicated CA for the registrar
tls_dir = /var/lib/keylime/reg_ca
server_key = server-private.pem
server_cert = server-cert.crt
trusted_client_ca = [cacert.crt]

# Or use 'generate' to auto-generate certificates
# tls_dir = generate

For convenience during development and testing, the default configuration shares certificates with the verifier:

[registrar]
tls_dir = default              # Uses /var/lib/keylime/cv_ca
server_key = default           # Uses server-private.pem
server_cert = default          # Uses server-cert.crt
trusted_client_ca = default    # Uses [cacert.crt]

When using the default shared configuration, admin certificates valid for the verifier will also work for registrar operations. In production deployments with separate CAs, administrators need certificates from each component’s respective CA.

Troubleshooting

Error: “Action requires admin authentication (mTLS certificate)”

Cause: The request doesn’t have a valid mTLS client certificate.

Solution: Verify tenant configuration includes:

[tenant]
tls_dir = default  # Or path to certificate directory
client_cert = default  # Or specific certificate file
client_key = default   # Or specific key file

Ensure the certificate is signed by a CA in the verifier’s trusted_client_ca list.

Error: “Action requires agent authentication (PoP token)”

Cause: The PoP token is missing on the request header. Maybe an admin (mTLS) is trying to access an agent-only endpoint.

Solution: Agent endpoints can only be accessed using PoP bearer tokens obtained through the push attestation authentication flow. Admins should use admin endpoints to view agent data.

Error: “Agent cannot access resource (ownership required)”

Cause: An agent is trying to access another agent’s resources.

Solution: Agents can only access their own resources. The agent_id in the URL must match the agent_id associated with the bearer token.

Verifying Certificate EKU

To check the Extended Key Usage of a certificate:

openssl x509 -in /var/lib/keylime/cv_ca/client-cert.crt -noout -text | grep -A1 "Extended Key Usage"
# Should show: TLS Web Client Authentication