rpms/keylime
7
0
Fork 0
Code Issues Pull Requests Releases Activity
c10s
keylime/0016-docs-push-attestation-config-tables.patch
Anderson Toshiyuki Sasaki eca2d398c1
Implement verifier graceful shutdown 
The included patches implement graceful shutdown for both pull and push
models, cancelling pending operations, and waiting for critical
in-flight operations to finish before shutting down.

Backport the following upstream PRs:
 - https://github.com/keylime/keylime/pull/1809
   - Document supported configuration options
   - Sync missing and removed options from configuration templates
 - https://github.com/keylime/keylime/pull/1868
   - Remove 'enable_authentication' from agent config templates
 - https://github.com/keylime/keylime/pull/1855
   - Add push-model documentation
 - https://github.com/keylime/keylime/pull/1869
   - Add verifier graceful shutdown
 - https://github.com/keylime/keylime/pull/1883
   - Ignore SIGTERM and SIGINT signals on Manager and parent processes
 - https://github.com/keylime/keylime/pull/1886
   - Move socket from /tmp to /var/run/keylime

Also, update the keylime-selinux to the latest release (43.2.1) to
include the following changes:

 - https://github.com/RedHat-SP-Security/keylime-selinux/pull/33
   - Allow Keylime to perform socket operation on /var/run/keylime
 - https://github.com/RedHat-SP-Security/keylime-selinux/pull/34
   - Allow Keylime to read /proc/net to populate certificates Subject
     Alternative Names (SAN)

Documentation updates and configuration template updates were included
to allow the graceful shutdown patch to apply cleanly.

This also modifies the test runner to use pytest, adding python3-pytest
to the BuildRequires. This was necessary to make the fixtures created in
conftest.py to be used, which is not available when running with
unittest.

Resolves: RHEL-151493
Resolves: RHEL-151408

Signed-off-by: Anderson Toshiyuki Sasaki <ansasaki@redhat.com>
2026-04-17 17:09:33 +02:00

1165 lines
36 KiB
Diff
Raw Permalink Blame History

From 4a36422caa40bf914b1b9f7ed86efc802e183ef1 Mon Sep 17 00:00:00 2001
From: Anderson Toshiyuki Sasaki <ansasaki@redhat.com>
Date: Tue, 24 Mar 2026 18:04:55 +0100
Subject: [PATCH 1/3] templates: Remove unused ima_ml_count_file option
This option was defined in the 2.5 config template and mapping but
never used. Remove it to avoid confusion.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Anderson Toshiyuki Sasaki <ansasaki@redhat.com>
---
templates/2.5/agent.j2 | 3 ---
templates/2.5/mapping.json | 1 -
2 files changed, 4 deletions(-)
diff --git a/templates/2.5/agent.j2 b/templates/2.5/agent.j2
index 5e9a1a706..f56010e87 100644
--- a/templates/2.5/agent.j2
+++ b/templates/2.5/agent.j2
@@ -47,9 +47,6 @@ verifier_url = "{{ agent_verifier_url }}"
# Server identifier for certification keys
certification_keys_server_identifier = "{{ agent_certification_keys_server_identifier }}"
-# File to store the IMA measurement list count
-ima_ml_count_file = "{{ agent_ima_ml_count_file }}"
-
# Evidence version for UEFI logs
uefi_logs_evidence_version = "{{ agent_uefi_logs_evidence_version }}"
diff --git a/templates/2.5/mapping.json b/templates/2.5/mapping.json
index 4b198e768..04f89e77a 100644
--- a/templates/2.5/mapping.json
+++ b/templates/2.5/mapping.json
@@ -10,7 +10,6 @@
"exponential_backoff_initial_delay": "10000",
"exponential_backoff_max_delay": "360000",
"certification_keys_server_identifier": "ak",
- "ima_ml_count_file": "/tmp/ima_ml_count",
"uefi_logs_evidence_version": "1.0",
"tls_accept_invalid_certs": "false",
"tls_accept_invalid_hostnames": "false"
From baf182680ffd60ab0b4ef8bf42bba3d02208b392 Mon Sep 17 00:00:00 2001
From: Anderson Toshiyuki Sasaki <ansasaki@redhat.com>
Date: Fri, 27 Mar 2026 10:55:35 +0100
Subject: [PATCH 2/3] templates: Sync agent config options with
keylime-agent.conf
Add missing agent options to the 2.5 upgrade templates and mapping
that are present in keylime-agent.conf and used in the agent code:
Common options:
- keylime_dir: working directory path
- payload_key: payload encryption private key
- payload_key_password: password for payload key
- revocation_actions_dir: path to pre-installed revocation scripts
- allow_payload_revocation_actions: control payload revocation actions
Push model options:
- verifier_tls_ca_cert: CA cert for verifier TLS verification
- registrar_tls_port: TLS port for registrar communication
- registrar_tls_enabled: enable TLS with registrar
- registrar_tls_ca_cert: CA cert for registrar TLS verification
- registrar_api_versions: API version negotiation with registrar
Fix default values to match keylime-agent.conf:
- exponential_backoff_max_delay: 360000 -> 300000
- uefi_logs_evidence_version: "1.0" -> "2.1"
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Anderson Toshiyuki Sasaki <ansasaki@redhat.com>
---
templates/2.5/agent.j2 | 40 ++++++++++++++++++++++++++++++++++++++
templates/2.5/mapping.json | 14 +++++++++++--
2 files changed, 52 insertions(+), 2 deletions(-)
diff --git a/templates/2.5/agent.j2 b/templates/2.5/agent.j2
index f56010e87..9f85f8411 100644
--- a/templates/2.5/agent.j2
+++ b/templates/2.5/agent.j2
@@ -44,6 +44,11 @@ agent_data_path = "{{ agent_data_path }}"
# Verifier URL
verifier_url = "{{ agent_verifier_url }}"
+# Verifier TLS CA certificate (Push Model specific).
+# Used to verify the verifier's server certificate.
+# If set as "default", the "cv_ca/cacert.crt" value relative to keylime_dir is used.
+verifier_tls_ca_cert = "{{ agent.verifier_tls_ca_cert }}"
+
# Server identifier for certification keys
certification_keys_server_identifier = "{{ agent_certification_keys_server_identifier }}"
@@ -54,11 +59,31 @@ uefi_logs_evidence_version = "{{ agent_uefi_logs_evidence_version }}"
registrar_ip = "{{ agent.registrar_ip }}"
registrar_port = {{ agent.registrar_port }}
+# The TLS port of the registrar server (Push Model specific).
+# Used when registrar_tls_enabled is set to true.
+registrar_tls_port = {{ agent.registrar_tls_port }}
+
+# Enable TLS communication between agent and registrar (Push Model specific).
+# When enabled, the agent uses TLS (server verification only) with the registrar.
+registrar_tls_enabled = {{ agent.registrar_tls_enabled }}
+
+# TLS CA certificate for verifying the registrar's server certificate (Push Model specific).
+# Only used when registrar_tls_enabled is true.
+# If set as "default", the "cv_ca/cacert.crt" value relative to keylime_dir is used.
+registrar_tls_ca_cert = "{{ agent.registrar_tls_ca_cert }}"
+
+# The API versions to use when communicating with the registrar (Push Model specific).
+# Supports "default" (all supported), "latest", or a comma-separated list.
+registrar_api_versions = "{{ agent.registrar_api_versions }}"
+
# Enable mTLS communication between agent, verifier and tenant.
# Details on why setting it to "False" is generally considered insecure can be found
# on https://github.com/keylime/keylime/security/advisories/GHSA-2m39-75g9-ff5r
enable_agent_mtls = {{ agent.enable_agent_mtls }}
+# The keylime working directory.
+keylime_dir = "{{ agent.keylime_dir }}"
+
# Accept invalid TLS certificates (INSECURE - for testing only)
# When enabled, the agent will accept self-signed or invalid certificates
# This option is specific to the push attestation model.
@@ -100,6 +125,14 @@ server_key = "{{ agent.server_key }}"
# If left empty, the private key will not be encrypted.
server_key_password = "{{ agent.server_key_password }}"
+# The name of the file containing the payload encryption private key.
+# If set as "default", the "payload-private.pem" value is used.
+payload_key = "{{ agent.payload_key }}"
+
+# Set the password used to encrypt the payload private key file.
+# If left empty, the private key will not be encrypted.
+payload_key_password = "{{ agent.payload_key_password }}"
+
# The name of the file containing the X509 certificate used as the Keylime agent
# server TLS certificate.
# This certificate must be self signed.
@@ -159,6 +192,9 @@ revocation_cert = "{{ agent.revocation_cert }}"
# action_list in the unzipped payload content.
revocation_actions = "{{ agent.revocation_actions }}"
+# The path to the directory containing pre-installed revocation action scripts.
+revocation_actions_dir = "{{ agent.revocation_actions_dir }}"
+
# A script to execute after unzipping the tenant payload. This is like
# cloud-init lite =) Keylime will run it with a /bin/sh environment and
# with a working directory of /var/lib/keylime/secure/unzipped.
@@ -171,6 +207,10 @@ payload_script = "{{ agent.payload_script }}"
# https://github.com/keylime/keylime/security/advisories/GHSA-2m39-75g9-ff5r
enable_insecure_payload = {{ agent.enable_insecure_payload }}
+# Whether to allow running revocation actions sent as part of the payload.
+# Setting to false limits revocation actions to pre-installed ones.
+allow_payload_revocation_actions = {{ agent.allow_payload_revocation_actions }}
+
# Maximum number of retries for exponential backoff
exponential_backoff_max_retries = {{ agent.exponential_backoff_max_retries }}
# Initial delay in milliseconds for exponential backoff
diff --git a/templates/2.5/mapping.json b/templates/2.5/mapping.json
index 04f89e77a..f3eaf8dbb 100644
--- a/templates/2.5/mapping.json
+++ b/templates/2.5/mapping.json
@@ -4,13 +4,23 @@
"components": {
"agent": {
"add": {
+ "keylime_dir": "/var/lib/keylime",
+ "payload_key": "default",
+ "payload_key_password": "",
+ "revocation_actions_dir": "/usr/libexec/keylime",
+ "allow_payload_revocation_actions": "true",
"agent_data_path": "/var/lib/keylime/agent_data.json",
"verifier_url": "https://localhost:8881",
+ "verifier_tls_ca_cert": "default",
+ "registrar_tls_port": "8891",
+ "registrar_tls_enabled": "false",
+ "registrar_tls_ca_cert": "default",
+ "registrar_api_versions": "default",
"exponential_backoff_max_retries": "5",
"exponential_backoff_initial_delay": "10000",
- "exponential_backoff_max_delay": "360000",
+ "exponential_backoff_max_delay": "300000",
"certification_keys_server_identifier": "ak",
- "uefi_logs_evidence_version": "1.0",
+ "uefi_logs_evidence_version": "2.1",
"tls_accept_invalid_certs": "false",
"tls_accept_invalid_hostnames": "false"
}
From bd392633a36839dfa51f86a1568370a87b3ecd37 Mon Sep 17 00:00:00 2001
From: Anderson Toshiyuki Sasaki <ansasaki@redhat.com>
Date: Fri, 27 Mar 2026 10:57:04 +0100
Subject: [PATCH 3/3] docs: Add tables with push-attestation configuration
options
Add comprehensive configuration reference tables for all Keylime
components documenting option names, defaults, config versions, and
environment variable overrides. Tables are organized by component and
separated into common, pull-model, and push-model sections.
Mark removed agent options with "(removed in 2.5)" and version range
2.0-2.4:
- measure_payload_pcr
- exponential_backoff
- retry_interval
- max_retries
Add missing agent common options:
- keylime_dir
- payload_key
- payload_key_password
- revocation_actions_dir
- allow_payload_revocation_actions
Add missing agent push-model options:
- attestation_interval_seconds
- verifier_tls_ca_cert
- registrar_tls_port
- registrar_tls_enabled
- registrar_tls_ca_cert
- registrar_api_versions
Fix default values to match keylime-agent.conf:
- exponential_backoff_max_delay: 360000 -> 300000
- uefi_logs_evidence_version: "1.0" -> "2.1"
Use consistent formatting for default values (unquoted for INI
components, quoted strings and unquoted booleans/integers for TOML).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Anderson Toshiyuki Sasaki <ansasaki@redhat.com>
---
docs/user_guide/configuration.rst | 897 +++++++++++++++++++++++++++++-
1 file changed, 893 insertions(+), 4 deletions(-)
diff --git a/docs/user_guide/configuration.rst b/docs/user_guide/configuration.rst
index 2e50757df..aae534423 100644
--- a/docs/user_guide/configuration.rst
+++ b/docs/user_guide/configuration.rst
@@ -117,7 +117,7 @@ The environment variables are defined as
The section can be omitted if the option to set is located in the main section
(the section named after the component). Otherwise the section is required.
-For example, to set the ``webhook_url` option from the `[revocations]`` section in
+For example, to set the ``webhook_url`` option from the ``[revocations]`` section in
the ``verifier.conf`` file, the environment variable to set is
``KEYLIME_VERIFIER_REVOCATIONS_WEBHOOK_URL``.
@@ -126,7 +126,7 @@ option from the ``[verifier]`` section in the ``verifier.conf``, the environment
variable to set is ``KEYLIME_VERIFIER_SERVER_KEY`` (note that the section can be
omitted).
-Configuraton upgrades
+Configuration upgrades
---------------------
When updating keylime, it is also recommended to upgrade the configuration to
@@ -183,9 +183,9 @@ configuration files are kept intact as backup and renamed with the ``.bkp`` exte
appended to the file names.
In case the ``--output`` option is provided to the ``keylime_upgrade_config``
-script, the configuration files are written even when they were alredy
+script, the configuration files are written even when they were already
up-to-date using the available templates. It can be seen as a way to force the
-creation of the configuration fiels, fitting the options read into the new
+creation of the configuration files, fitting the options read into the new
templates.
Passing the ``--debug`` option to the ``keylime_upgrade_config``, the logging level
@@ -211,3 +211,892 @@ To ignore the input files and use the default value for all options, the
Finally, to process a single mapping file, the mapping file path can be passed
via the ``--mapping`` option
+
+Attestation Models: Pull vs Push
+---------------------------------
+
+Keylime supports two attestation models that determine how the verifier obtains
+attestation evidence from agents:
+
+Pull Model (Traditional)
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In the pull model, the verifier actively polls agents at regular intervals to
+retrieve attestation evidence. This is the default and traditional mode of
+operation.
+
+**Use Cases:**
+
+* Traditional deployments where the verifier can directly connect to agents
+* Environments with stable network connectivity
+* When you need fine-grained control over attestation frequency
+
+Push Model (Agent-Driven)
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In the push model, agents periodically push their attestation evidence to the
+verifier. This mode is useful when the verifier cannot directly connect to
+agents (e.g., agents behind firewalls or NAT).
+
+**Use Cases:**
+
+* Agents deployed behind firewalls or NAT
+* Cloud or edge deployments where direct connectivity is limited
+* When agents need to control their own attestation schedule
+
+.. note::
+ The push model options were introduced in configuration version 2.5 and
+ require the push attestation agent.
+
+Configuration Options Reference
+--------------------------------
+
+This section provides comprehensive tables of all configuration options for each
+Keylime component, including default values, environment variable overrides, and
+applicability to pull/push attestation models.
+
+Verifier Configuration (``/etc/keylime/verifier.conf``)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Common Options (Both Models)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. list-table::
+ :header-rows: 1
+ :widths: 25 12 15 48
+
+ * - Option
+ - Default
+ - Version
+ - Environment Variable
+ * - ``version``
+ - ``2.5``
+ - 2.0
+ - ``KEYLIME_VERIFIER_VERSION``
+ * - ``uuid``
+ - ``default``
+ - 2.0
+ - ``KEYLIME_VERIFIER_UUID``
+ * - ``ip``
+ - ``127.0.0.1``
+ - 2.0
+ - ``KEYLIME_VERIFIER_IP``
+ * - ``port``
+ - ``8881``
+ - 2.0
+ - ``KEYLIME_VERIFIER_PORT``
+ * - ``registrar_ip``
+ - ``127.0.0.1``
+ - 2.0
+ - ``KEYLIME_VERIFIER_REGISTRAR_IP``
+ * - ``registrar_port``
+ - ``8891``
+ - 2.0
+ - ``KEYLIME_VERIFIER_REGISTRAR_PORT``
+ * - ``enable_agent_mtls``
+ - ``True``
+ - 2.0
+ - ``KEYLIME_VERIFIER_ENABLE_AGENT_MTLS``
+ * - ``tls_dir``
+ - ``generate``
+ - 2.0
+ - ``KEYLIME_VERIFIER_TLS_DIR``
+ * - ``server_key``
+ - ``default``
+ - 2.0
+ - ``KEYLIME_VERIFIER_SERVER_KEY``
+ * - ``server_key_password``
+ - (empty)
+ - 2.0
+ - ``KEYLIME_VERIFIER_SERVER_KEY_PASSWORD``
+ * - ``server_cert``
+ - ``default``
+ - 2.0
+ - ``KEYLIME_VERIFIER_SERVER_CERT``
+ * - ``trusted_client_ca``
+ - ``default``
+ - 2.0
+ - ``KEYLIME_VERIFIER_TRUSTED_CLIENT_CA``
+ * - ``client_key``
+ - ``default``
+ - 2.0
+ - ``KEYLIME_VERIFIER_CLIENT_KEY``
+ * - ``client_key_password``
+ - (empty)
+ - 2.0
+ - ``KEYLIME_VERIFIER_CLIENT_KEY_PASSWORD``
+ * - ``client_cert``
+ - ``default``
+ - 2.0
+ - ``KEYLIME_VERIFIER_CLIENT_CERT``
+ * - ``trusted_server_ca``
+ - ``default``
+ - 2.0
+ - ``KEYLIME_VERIFIER_TRUSTED_SERVER_CA``
+ * - ``database_url``
+ - ``sqlite``
+ - 2.0
+ - ``KEYLIME_VERIFIER_DATABASE_URL``
+ * - ``database_pool_sz_ovfl``
+ - ``5,10``
+ - 2.0
+ - ``KEYLIME_VERIFIER_DATABASE_POOL_SZ_OVFL``
+ * - ``auto_migrate_db``
+ - ``True``
+ - 2.0
+ - ``KEYLIME_VERIFIER_AUTO_MIGRATE_DB``
+ * - ``num_workers``
+ - ``0``
+ - 2.0
+ - ``KEYLIME_VERIFIER_NUM_WORKERS``
+ * - ``max_upload_size``
+ - ``104857600``
+ - 2.0
+ - ``KEYLIME_VERIFIER_MAX_UPLOAD_SIZE``
+ * - ``measured_boot_policy_name``
+ - ``accept-all``
+ - 2.0
+ - ``KEYLIME_VERIFIER_MEASURED_BOOT_POLICY_NAME``
+ * - ``measured_boot_imports``
+ - ``[]``
+ - 2.0
+ - ``KEYLIME_VERIFIER_MEASURED_BOOT_IMPORTS``
+ * - ``measured_boot_evaluate``
+ - ``once``
+ - 2.0
+ - ``KEYLIME_VERIFIER_MEASURED_BOOT_EVALUATE``
+ * - ``severity_labels``
+ - ``["info", "notice", ...]``
+ - 2.0
+ - ``KEYLIME_VERIFIER_SEVERITY_LABELS``
+ * - ``severity_policy``
+ - ``[{"event_id": ".*", ...}]``
+ - 2.0
+ - ``KEYLIME_VERIFIER_SEVERITY_POLICY``
+ * - ``ignore_tomtou_errors``
+ - ``False``
+ - 2.0
+ - ``KEYLIME_VERIFIER_IGNORE_TOMTOU_ERRORS``
+ * - ``durable_attestation_import``
+ - (empty)
+ - 2.0
+ - ``KEYLIME_VERIFIER_DURABLE_ATTESTATION_IMPORT``
+ * - ``persistent_store_url``
+ - (empty)
+ - 2.0
+ - ``KEYLIME_VERIFIER_PERSISTENT_STORE_URL``
+ * - ``transparency_log_url``
+ - (empty)
+ - 2.0
+ - ``KEYLIME_VERIFIER_TRANSPARENCY_LOG_URL``
+ * - ``time_stamp_authority_url``
+ - (empty)
+ - 2.0
+ - ``KEYLIME_VERIFIER_TIME_STAMP_AUTHORITY_URL``
+ * - ``time_stamp_authority_certs_path``
+ - (empty)
+ - 2.0
+ - ``KEYLIME_VERIFIER_TIME_STAMP_AUTHORITY_CERTS_PATH``
+ * - ``persistent_store_format``
+ - ``json``
+ - 2.0
+ - ``KEYLIME_VERIFIER_PERSISTENT_STORE_FORMAT``
+ * - ``persistent_store_encoding``
+ - (empty)
+ - 2.0
+ - ``KEYLIME_VERIFIER_PERSISTENT_STORE_ENCODING``
+ * - ``transparency_log_sign_algo``
+ - ``sha256``
+ - 2.0
+ - ``KEYLIME_VERIFIER_TRANSPARENCY_LOG_SIGN_ALGO``
+ * - ``signed_attributes``
+ - (empty)
+ - 2.0
+ - ``KEYLIME_VERIFIER_SIGNED_ATTRIBUTES``
+ * - ``require_allow_list_signatures``
+ - ``False``
+ - 2.0
+ - ``KEYLIME_VERIFIER_REQUIRE_ALLOW_LIST_SIGNATURES``
+ * - ``authorization_provider``
+ - ``simple``
+ - 2.5
+ - ``KEYLIME_VERIFIER_AUTHORIZATION_PROVIDER``
+ * - ``cert_subject_alternative_names``
+ - (empty)
+ - 2.5
+ - ``KEYLIME_VERIFIER_CERT_SUBJECT_ALTERNATIVE_NAMES``
+
+Pull Model Specific Options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. list-table::
+ :header-rows: 1
+ :widths: 25 12 15 48
+
+ * - Option
+ - Default
+ - Version
+ - Environment Variable
+ * - ``quote_interval``
+ - ``2``
+ - 2.0
+ - ``KEYLIME_VERIFIER_QUOTE_INTERVAL``
+ * - ``retry_interval``
+ - ``2``
+ - 2.0
+ - ``KEYLIME_VERIFIER_RETRY_INTERVAL``
+ * - ``max_retries``
+ - ``5``
+ - 2.0
+ - ``KEYLIME_VERIFIER_MAX_RETRIES``
+ * - ``exponential_backoff``
+ - ``True``
+ - 2.0
+ - ``KEYLIME_VERIFIER_EXPONENTIAL_BACKOFF``
+ * - ``request_timeout``
+ - ``60.0``
+ - 2.0
+ - ``KEYLIME_VERIFIER_REQUEST_TIMEOUT``
+
+Push Model Specific Options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. list-table::
+ :header-rows: 1
+ :widths: 25 12 15 48
+
+ * - Option
+ - Default
+ - Version
+ - Environment Variable
+ * - ``mode``
+ - ``pull``
+ - 2.5
+ - ``KEYLIME_VERIFIER_MODE``
+ * - ``challenge_lifetime``
+ - ``1800``
+ - 2.5
+ - ``KEYLIME_VERIFIER_CHALLENGE_LIFETIME``
+ * - ``verification_timeout``
+ - ``0``
+ - 2.5
+ - ``KEYLIME_VERIFIER_VERIFICATION_TIMEOUT``
+ * - ``session_create_rate_limit_per_ip``
+ - ``50``
+ - 2.5
+ - ``KEYLIME_VERIFIER_SESSION_CREATE_RATE_LIMIT_PER_IP``
+ * - ``session_create_rate_limit_window_ip``
+ - ``60``
+ - 2.5
+ - ``KEYLIME_VERIFIER_SESSION_CREATE_RATE_LIMIT_WINDOW_IP``
+ * - ``session_create_rate_limit_per_agent``
+ - ``15``
+ - 2.5
+ - ``KEYLIME_VERIFIER_SESSION_CREATE_RATE_LIMIT_PER_AGENT``
+ * - ``session_create_rate_limit_window_agent``
+ - ``60``
+ - 2.5
+ - ``KEYLIME_VERIFIER_SESSION_CREATE_RATE_LIMIT_WINDOW_AGENT``
+ * - ``session_lifetime``
+ - ``180``
+ - 2.5
+ - ``KEYLIME_VERIFIER_SESSION_LIFETIME``
+ * - ``extend_token_on_attestation``
+ - ``True``
+ - 2.5
+ - ``KEYLIME_VERIFIER_EXTEND_TOKEN_ON_ATTESTATION``
+
+Revocations Section
+^^^^^^^^^^^^^^^^^^^
+
+.. list-table::
+ :header-rows: 1
+ :widths: 30 12 15 43
+
+ * - Option
+ - Default
+ - Version
+ - Environment Variable
+ * - ``enabled_revocation_notifications``
+ - ``['agent']``
+ - 2.0
+ - ``KEYLIME_VERIFIER_REVOCATIONS_ENABLED_REVOCATION_NOTIFICATIONS``
+ * - ``zmq_ip``
+ - ``127.0.0.1``
+ - 2.0
+ - ``KEYLIME_VERIFIER_REVOCATIONS_ZMQ_IP``
+ * - ``zmq_port``
+ - ``8992``
+ - 2.0
+ - ``KEYLIME_VERIFIER_REVOCATIONS_ZMQ_PORT``
+ * - ``webhook_url``
+ - (empty)
+ - 2.0
+ - ``KEYLIME_VERIFIER_REVOCATIONS_WEBHOOK_URL``
+
+Registrar Configuration (``/etc/keylime/registrar.conf``)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+ :header-rows: 1
+ :widths: 30 12 15 43
+
+ * - Option
+ - Default
+ - Version
+ - Environment Variable
+ * - ``version``
+ - ``2.5``
+ - 2.0
+ - ``KEYLIME_REGISTRAR_VERSION``
+ * - ``ip``
+ - ``127.0.0.1``
+ - 2.0
+ - ``KEYLIME_REGISTRAR_IP``
+ * - ``port``
+ - ``8890``
+ - 2.0
+ - ``KEYLIME_REGISTRAR_PORT``
+ * - ``tls_port``
+ - ``8891``
+ - 2.0
+ - ``KEYLIME_REGISTRAR_TLS_PORT``
+ * - ``tls_dir``
+ - ``default``
+ - 2.0
+ - ``KEYLIME_REGISTRAR_TLS_DIR``
+ * - ``server_key``
+ - ``default``
+ - 2.0
+ - ``KEYLIME_REGISTRAR_SERVER_KEY``
+ * - ``server_key_password``
+ - (empty)
+ - 2.0
+ - ``KEYLIME_REGISTRAR_SERVER_KEY_PASSWORD``
+ * - ``server_cert``
+ - ``default``
+ - 2.0
+ - ``KEYLIME_REGISTRAR_SERVER_CERT``
+ * - ``trusted_client_ca``
+ - ``default``
+ - 2.0
+ - ``KEYLIME_REGISTRAR_TRUSTED_CLIENT_CA``
+ * - ``database_url``
+ - ``sqlite``
+ - 2.0
+ - ``KEYLIME_REGISTRAR_DATABASE_URL``
+ * - ``database_pool_sz_ovfl``
+ - ``5,10``
+ - 2.0
+ - ``KEYLIME_REGISTRAR_DATABASE_POOL_SZ_OVFL``
+ * - ``auto_migrate_db``
+ - ``True``
+ - 2.0
+ - ``KEYLIME_REGISTRAR_AUTO_MIGRATE_DB``
+ * - ``durable_attestation_import``
+ - (empty)
+ - 2.0
+ - ``KEYLIME_REGISTRAR_DURABLE_ATTESTATION_IMPORT``
+ * - ``persistent_store_url``
+ - (empty)
+ - 2.0
+ - ``KEYLIME_REGISTRAR_PERSISTENT_STORE_URL``
+ * - ``transparency_log_url``
+ - (empty)
+ - 2.0
+ - ``KEYLIME_REGISTRAR_TRANSPARENCY_LOG_URL``
+ * - ``time_stamp_authority_url``
+ - (empty)
+ - 2.0
+ - ``KEYLIME_REGISTRAR_TIME_STAMP_AUTHORITY_URL``
+ * - ``time_stamp_authority_certs_path``
+ - (empty)
+ - 2.0
+ - ``KEYLIME_REGISTRAR_TIME_STAMP_AUTHORITY_CERTS_PATH``
+ * - ``persistent_store_format``
+ - ``json``
+ - 2.0
+ - ``KEYLIME_REGISTRAR_PERSISTENT_STORE_FORMAT``
+ * - ``persistent_store_encoding``
+ - (empty)
+ - 2.0
+ - ``KEYLIME_REGISTRAR_PERSISTENT_STORE_ENCODING``
+ * - ``transparency_log_sign_algo``
+ - ``sha256``
+ - 2.0
+ - ``KEYLIME_REGISTRAR_TRANSPARENCY_LOG_SIGN_ALGO``
+ * - ``signed_attributes``
+ - ``ek_tpm,aik_tpm,ekcert``
+ - 2.0
+ - ``KEYLIME_REGISTRAR_SIGNED_ATTRIBUTES``
+ * - ``tpm_identity``
+ - ``default``
+ - 2.1
+ - ``KEYLIME_REGISTRAR_TPM_IDENTITY``
+ * - ``malformed_cert_action``
+ - ``warn``
+ - 2.4
+ - ``KEYLIME_REGISTRAR_MALFORMED_CERT_ACTION``
+ * - ``authorization_provider``
+ - ``simple``
+ - 2.5
+ - ``KEYLIME_REGISTRAR_AUTHORIZATION_PROVIDER``
+ * - ``cert_subject_alternative_names``
+ - (empty)
+ - 2.5
+ - ``KEYLIME_REGISTRAR_CERT_SUBJECT_ALTERNATIVE_NAMES``
+
+Tenant Configuration (``/etc/keylime/tenant.conf``)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+ :header-rows: 1
+ :widths: 30 12 15 43
+
+ * - Option
+ - Default
+ - Version
+ - Environment Variable
+ * - ``version``
+ - ``2.5``
+ - 2.0
+ - ``KEYLIME_TENANT_VERSION``
+ * - ``verifier_ip``
+ - ``127.0.0.1``
+ - 2.0
+ - ``KEYLIME_TENANT_VERIFIER_IP``
+ * - ``verifier_port``
+ - ``8881``
+ - 2.0
+ - ``KEYLIME_TENANT_VERIFIER_PORT``
+ * - ``registrar_ip``
+ - ``127.0.0.1``
+ - 2.0
+ - ``KEYLIME_TENANT_REGISTRAR_IP``
+ * - ``registrar_port``
+ - ``8891``
+ - 2.0
+ - ``KEYLIME_TENANT_REGISTRAR_PORT``
+ * - ``tls_dir``
+ - ``default``
+ - 2.0
+ - ``KEYLIME_TENANT_TLS_DIR``
+ * - ``enable_agent_mtls``
+ - ``True``
+ - 2.0
+ - ``KEYLIME_TENANT_ENABLE_AGENT_MTLS``
+ * - ``client_key``
+ - ``default``
+ - 2.0
+ - ``KEYLIME_TENANT_CLIENT_KEY``
+ * - ``client_key_password``
+ - (empty)
+ - 2.0
+ - ``KEYLIME_TENANT_CLIENT_KEY_PASSWORD``
+ * - ``client_cert``
+ - ``default``
+ - 2.0
+ - ``KEYLIME_TENANT_CLIENT_CERT``
+ * - ``trusted_server_ca``
+ - ``default``
+ - 2.0
+ - ``KEYLIME_TENANT_TRUSTED_SERVER_CA``
+ * - ``tpm_cert_store``
+ - ``/var/lib/keylime/tpm_cert_store``
+ - 2.0
+ - ``KEYLIME_TENANT_TPM_CERT_STORE``
+ * - ``max_payload_size``
+ - ``1048576``
+ - 2.0
+ - ``KEYLIME_TENANT_MAX_PAYLOAD_SIZE``
+ * - ``accept_tpm_hash_algs``
+ - ``['sha512', 'sha384', 'sha256']``
+ - 2.0
+ - ``KEYLIME_TENANT_ACCEPT_TPM_HASH_ALGS``
+ * - ``accept_tpm_encryption_algs``
+ - ``['ecc', 'rsa']``
+ - 2.0
+ - ``KEYLIME_TENANT_ACCEPT_TPM_ENCRYPTION_ALGS``
+ * - ``accept_tpm_signing_algs``
+ - ``['ecschnorr', 'rsassa']``
+ - 2.0
+ - ``KEYLIME_TENANT_ACCEPT_TPM_SIGNING_ALGS``
+ * - ``exponential_backoff``
+ - ``True``
+ - 2.0
+ - ``KEYLIME_TENANT_EXPONENTIAL_BACKOFF``
+ * - ``retry_interval``
+ - ``2``
+ - 2.0
+ - ``KEYLIME_TENANT_RETRY_INTERVAL``
+ * - ``max_retries``
+ - ``5``
+ - 2.0
+ - ``KEYLIME_TENANT_MAX_RETRIES``
+ * - ``request_timeout``
+ - ``60``
+ - 2.0
+ - ``KEYLIME_TENANT_REQUEST_TIMEOUT``
+ * - ``require_ek_cert``
+ - ``True``
+ - 2.0
+ - ``KEYLIME_TENANT_REQUIRE_EK_CERT``
+ * - ``ek_check_script``
+ - (empty)
+ - 2.0
+ - ``KEYLIME_TENANT_EK_CHECK_SCRIPT``
+ * - ``mb_refstate``
+ - (empty)
+ - 2.0
+ - ``KEYLIME_TENANT_MB_REFSTATE``
+
+CA Configuration (``/etc/keylime/ca.conf``)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+ :header-rows: 1
+ :widths: 30 15 15 40
+
+ * - Option
+ - Default
+ - Version
+ - Environment Variable
+ * - ``version``
+ - ``2.5``
+ - 2.0
+ - ``KEYLIME_CA_VERSION``
+ * - ``password``
+ - ``default``
+ - 2.0
+ - ``KEYLIME_CA_PASSWORD``
+ * - ``cert_country``
+ - ``US``
+ - 2.0
+ - ``KEYLIME_CA_CERT_COUNTRY``
+ * - ``cert_ca_name``
+ - ``Keylime Certificate Authority``
+ - 2.0
+ - ``KEYLIME_CA_CERT_CA_NAME``
+ * - ``cert_state``
+ - ``MA``
+ - 2.0
+ - ``KEYLIME_CA_CERT_STATE``
+ * - ``cert_locality``
+ - ``Lexington``
+ - 2.0
+ - ``KEYLIME_CA_CERT_LOCALITY``
+ * - ``cert_organization``
+ - ``MITLL``
+ - 2.0
+ - ``KEYLIME_CA_CERT_ORGANIZATION``
+ * - ``cert_org_unit``
+ - ``53``
+ - 2.0
+ - ``KEYLIME_CA_CERT_ORG_UNIT``
+ * - ``cert_ca_lifetime``
+ - ``3650``
+ - 2.0
+ - ``KEYLIME_CA_CERT_CA_LIFETIME``
+ * - ``cert_lifetime``
+ - ``365``
+ - 2.0
+ - ``KEYLIME_CA_CERT_LIFETIME``
+ * - ``cert_bits``
+ - ``2048``
+ - 2.0
+ - ``KEYLIME_CA_CERT_BITS``
+ * - ``cert_crl_dist``
+ - ``http://localhost:38080/crl``
+ - 2.0
+ - ``KEYLIME_CA_CERT_CRL_DIST``
+
+Agent Configuration (``/etc/keylime/agent.conf``)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. warning::
+ The Python agent is deprecated and will be removed in version 7.0.0!
+ Please migrate to the Rust-based agent from https://github.com/keylime/rust-keylime/
+
+Common Options (Both Models)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. list-table::
+ :header-rows: 1
+ :widths: 28 12 12 48
+
+ * - Option
+ - Default
+ - Version
+ - Environment Variable
+ * - ``version``
+ - ``"2.5"``
+ - 2.0
+ - ``KEYLIME_AGENT_VERSION``
+ * - ``api_versions``
+ - ``"default"``
+ - 2.4
+ - ``KEYLIME_AGENT_API_VERSIONS``
+ * - ``uuid``
+ - ``"d432fbb3-d2f1-4a97-9ef7-75bd81c00000"``
+ - 2.0
+ - ``KEYLIME_AGENT_UUID``
+ * - ``ip``
+ - ``"127.0.0.1"``
+ - 2.0
+ - ``KEYLIME_AGENT_IP``
+ * - ``port``
+ - ``9002``
+ - 2.0
+ - ``KEYLIME_AGENT_PORT``
+ * - ``contact_ip``
+ - ``"127.0.0.1"``
+ - 2.0
+ - ``KEYLIME_AGENT_CONTACT_IP``
+ * - ``contact_port``
+ - ``9002``
+ - 2.0
+ - ``KEYLIME_AGENT_CONTACT_PORT``
+ * - ``registrar_ip``
+ - ``"127.0.0.1"``
+ - 2.0
+ - ``KEYLIME_AGENT_REGISTRAR_IP``
+ * - ``registrar_port``
+ - ``8890``
+ - 2.0
+ - ``KEYLIME_AGENT_REGISTRAR_PORT``
+ * - ``enable_agent_mtls``
+ - ``true``
+ - 2.0
+ - ``KEYLIME_AGENT_ENABLE_AGENT_MTLS``
+ * - ``tls_dir``
+ - ``"default"``
+ - 2.0
+ - ``KEYLIME_AGENT_TLS_DIR``
+ * - ``server_key``
+ - ``"default"``
+ - 2.0
+ - ``KEYLIME_AGENT_SERVER_KEY``
+ * - ``server_key_password``
+ - ``""``
+ - 2.0
+ - ``KEYLIME_AGENT_SERVER_KEY_PASSWORD``
+ * - ``server_cert``
+ - ``"default"``
+ - 2.0
+ - ``KEYLIME_AGENT_SERVER_CERT``
+ * - ``trusted_client_ca``
+ - ``"default"``
+ - 2.0
+ - ``KEYLIME_AGENT_TRUSTED_CLIENT_CA``
+ * - ``enc_keyname``
+ - ``"derived_tci_key"``
+ - 2.0
+ - ``KEYLIME_AGENT_ENC_KEYNAME``
+ * - ``dec_payload_file``
+ - ``"decrypted_payload"``
+ - 2.0
+ - ``KEYLIME_AGENT_DEC_PAYLOAD_FILE``
+ * - ``secure_size``
+ - ``"1m"``
+ - 2.0
+ - ``KEYLIME_AGENT_SECURE_SIZE``
+ * - ``tpm_ownerpassword``
+ - ``""``
+ - 2.0
+ - ``KEYLIME_AGENT_TPM_OWNERPASSWORD``
+ * - ``extract_payload_zip``
+ - ``true``
+ - 2.0
+ - ``KEYLIME_AGENT_EXTRACT_PAYLOAD_ZIP``
+ * - ``enable_revocation_notifications``
+ - ``true``
+ - 2.0
+ - ``KEYLIME_AGENT_ENABLE_REVOCATION_NOTIFICATIONS``
+ * - ``revocation_notification_ip``
+ - ``"127.0.0.1"``
+ - 2.0
+ - ``KEYLIME_AGENT_REVOCATION_NOTIFICATION_IP``
+ * - ``revocation_notification_port``
+ - ``8992``
+ - 2.0
+ - ``KEYLIME_AGENT_REVOCATION_NOTIFICATION_PORT``
+ * - ``revocation_cert``
+ - ``"default"``
+ - 2.0
+ - ``KEYLIME_AGENT_REVOCATION_CERT``
+ * - ``revocation_actions``
+ - ``"[]"``
+ - 2.0
+ - ``KEYLIME_AGENT_REVOCATION_ACTIONS``
+ * - ``payload_script``
+ - ``"autorun.sh"``
+ - 2.0
+ - ``KEYLIME_AGENT_PAYLOAD_SCRIPT``
+ * - ``enable_insecure_payload``
+ - ``false``
+ - 2.0
+ - ``KEYLIME_AGENT_ENABLE_INSECURE_PAYLOAD``
+ * - ``measure_payload_pcr``
+ - ``-1``
+ - 2.0
+ - ``KEYLIME_AGENT_MEASURE_PAYLOAD_PCR``
+ * - ``exponential_backoff``
+ - ``true``
+ - 2.0
+ - ``KEYLIME_AGENT_EXPONENTIAL_BACKOFF``
+ * - ``retry_interval``
+ - ``2``
+ - 2.0
+ - ``KEYLIME_AGENT_RETRY_INTERVAL``
+ * - ``max_retries``
+ - ``4``
+ - 2.0
+ - ``KEYLIME_AGENT_MAX_RETRIES``
+ * - ``tpm_hash_alg``
+ - ``"sha256"``
+ - 2.0
+ - ``KEYLIME_AGENT_TPM_HASH_ALG``
+ * - ``tpm_encryption_alg``
+ - ``"rsa"``
+ - 2.0
+ - ``KEYLIME_AGENT_TPM_ENCRYPTION_ALG``
+ * - ``tpm_signing_alg``
+ - ``"rsassa"``
+ - 2.0
+ - ``KEYLIME_AGENT_TPM_SIGNING_ALG``
+ * - ``ek_handle``
+ - ``"generate"``
+ - 2.0
+ - ``KEYLIME_AGENT_EK_HANDLE``
+ * - ``enable_iak_idevid``
+ - ``false``
+ - 2.1
+ - ``KEYLIME_AGENT_ENABLE_IAK_IDEVID``
+ * - ``iak_idevid_template``
+ - ``"detect"``
+ - 2.1
+ - ``KEYLIME_AGENT_IAK_IDEVID_TEMPLATE``
+ * - ``iak_idevid_asymmetric_alg``
+ - ``"rsa"``
+ - 2.1
+ - ``KEYLIME_AGENT_IAK_IDEVID_ASYMMETRIC_ALG``
+ * - ``iak_idevid_name_alg``
+ - ``"sha256"``
+ - 2.1
+ - ``KEYLIME_AGENT_IAK_IDEVID_NAME_ALG``
+ * - ``idevid_password``
+ - ``""``
+ - 2.3
+ - ``KEYLIME_AGENT_IDEVID_PASSWORD``
+ * - ``idevid_handle``
+ - ``""``
+ - 2.3
+ - ``KEYLIME_AGENT_IDEVID_HANDLE``
+ * - ``iak_password``
+ - ``""``
+ - 2.3
+ - ``KEYLIME_AGENT_IAK_PASSWORD``
+ * - ``iak_handle``
+ - ``""``
+ - 2.3
+ - ``KEYLIME_AGENT_IAK_HANDLE``
+ * - ``iak_cert``
+ - ``"default"``
+ - 2.1
+ - ``KEYLIME_AGENT_IAK_CERT``
+ * - ``idevid_cert``
+ - ``"default"``
+ - 2.1
+ - ``KEYLIME_AGENT_IDEVID_CERT``
+ * - ``run_as``
+ - ``"keylime:tss"``
+ - 2.0
+ - ``KEYLIME_AGENT_RUN_AS``
+ * - ``ima_ml_path``
+ - ``"default"``
+ - 2.2
+ - ``KEYLIME_AGENT_IMA_ML_PATH``
+ * - ``measuredboot_ml_path``
+ - ``"default"``
+ - 2.2
+ - ``KEYLIME_AGENT_MEASUREDBOOT_ML_PATH``
+
+Push Model Specific Options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. list-table::
+ :header-rows: 1
+ :widths: 35 12 12 41
+
+ * - Option
+ - Default
+ - Version
+ - Environment Variable
+ * - ``agent_data_path``
+ - ``"/var/lib/keylime/agent_data.json"``
+ - 2.5
+ - ``KEYLIME_AGENT_AGENT_DATA_PATH``
+ * - ``verifier_url``
+ - ``"https://localhost:8881"``
+ - 2.5
+ - ``KEYLIME_AGENT_VERIFIER_URL``
+ * - ``certification_keys_server_identifier``
+ - ``"ak"``
+ - 2.5
+ - ``KEYLIME_AGENT_CERTIFICATION_KEYS_SERVER_IDENTIFIER``
+ * - ``uefi_logs_evidence_version``
+ - ``"1.0"``
+ - 2.5
+ - ``KEYLIME_AGENT_UEFI_LOGS_EVIDENCE_VERSION``
+ * - ``tls_accept_invalid_certs``
+ - ``false``
+ - 2.5
+ - ``KEYLIME_AGENT_TLS_ACCEPT_INVALID_CERTS``
+ * - ``tls_accept_invalid_hostnames``
+ - ``false``
+ - 2.5
+ - ``KEYLIME_AGENT_TLS_ACCEPT_INVALID_HOSTNAMES``
+ * - ``exponential_backoff_max_retries``
+ - ``5``
+ - 2.5
+ - ``KEYLIME_AGENT_EXPONENTIAL_BACKOFF_MAX_RETRIES``
+ * - ``exponential_backoff_initial_delay``
+ - ``10000``
+ - 2.5
+ - ``KEYLIME_AGENT_EXPONENTIAL_BACKOFF_INITIAL_DELAY``
+ * - ``exponential_backoff_max_delay``
+ - ``360000``
+ - 2.5
+ - ``KEYLIME_AGENT_EXPONENTIAL_BACKOFF_MAX_DELAY``
+
+Logging Configuration (``/etc/keylime/logging.conf``)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The logging configuration follows Python's standard logging configuration format.
+See the Python logging documentation for details on configuring handlers, formatters,
+and loggers. The version option can be overridden with ``KEYLIME_LOGGING_VERSION``.
+
+Configuration Version History
+------------------------------
+
+.. list-table::
+ :header-rows: 1
+ :widths: 15 70
+
+ * - Version
+ - Changes
+ * - 2.0
+ - Base configuration structure, pull model support
+ * - 2.1
+ - Added IAK/IDevID support, ``tpm_identity`` for registrar
+ * - 2.2
+ - Added ``ima_ml_path`` and ``measuredboot_ml_path`` configuration
+ * - 2.3
+ - Added persisted key handles for IAK/IDevID (``iak_handle``, ``idevid_handle``)
+ * - 2.4
+ - Added ``api_versions`` for agent, ``malformed_cert_action`` for registrar
+ * - 2.5
+ - **Push model support**: Added ``mode``, ``challenge_lifetime``, ``verification_timeout``, session rate limiting and lifetime options for verifier; ``verifier_url``, ``agent_data_path``, TLS validation, exponential backoff options for agent. Added ``authorization_provider`` and ``cert_subject_alternative_names`` for verifier and registrar
+
+For detailed information on all configuration options for each component, refer
+to the configuration files in ``/etc/keylime/`` and their inline documentation.
Reference in New Issue View Git Blame Copy Permalink