diff --git a/0019-Added-manpages-for-keylime-services-and-the-tenant.patch b/0019-Added-manpages-for-keylime-services-and-the-tenant.patch new file mode 100644 index 0000000..ca0d572 --- /dev/null +++ b/0019-Added-manpages-for-keylime-services-and-the-tenant.patch @@ -0,0 +1,974 @@ +From af74d817bd7c8c2a2e014e1728b46f41049ac066 Mon Sep 17 00:00:00 2001 +From: Marek Safarik +Date: Tue, 14 Oct 2025 15:14:26 +0200 +Subject: [PATCH] Added manpages for keylime services and the tenant + +Here I am adding manpages for keylime tenant, verifier, registrar, policy. +The RST formatting has been fixed for rst2man compatibility. + +Co-authored-by: Marek Safarik +Co-authored-by: Sergio Correia +--- + docs/man/keylime-policy.1.rst | 179 +++++++++++++++++++++ + docs/man/keylime_agent.8.rst | 218 +++++++++++++++++++++++++ + docs/man/keylime_registrar.8.rst | 142 +++++++++++++++++ + docs/man/keylime_tenant.1.rst | 263 +++++++++++++++++++++++++++++++ + docs/man/keylime_verifier.8.rst | 116 ++++++++++++++ + 5 files changed, 918 insertions(+) + create mode 100644 docs/man/keylime-policy.1.rst + create mode 100644 docs/man/keylime_agent.8.rst + create mode 100644 docs/man/keylime_registrar.8.rst + create mode 100644 docs/man/keylime_tenant.1.rst + create mode 100644 docs/man/keylime_verifier.8.rst + +diff --git a/docs/man/keylime-policy.1.rst b/docs/man/keylime-policy.1.rst +new file mode 100644 +index 0000000..b24c372 +--- /dev/null ++++ b/docs/man/keylime-policy.1.rst +@@ -0,0 +1,179 @@ ++============== ++keylime-policy ++============== ++ ++------------------------------------------ ++Keylime policy creation and signing tool ++------------------------------------------ ++ ++:Manual section: 1 ++:Author: Keylime Developers ++:Date: September 2025 ++ ++SYNOPSIS ++======== ++ ++**keylime-policy** {create,sign} [*OPTIONS*] ++ ++(Requires root privileges, use with sudo) ++ ++DESCRIPTION ++=========== ++ ++keylime-policy is a utility for creating and signing Keylime policies. It supports creating ++runtime policies (for IMA/filesystem attestation) and measured boot policies (for boot-time ++attestation), as well as signing runtime policies using DSSE (Dead Simple Signing Envelope). ++ ++COMMANDS ++======== ++ ++**keylime-policy create runtime** [*OPTIONS*] ++ ++ Create runtime policies from filesystem, allowlists, RPM repositories, or IMA measurement lists. ++ ++ Options: ++ ++ **-o, --output** *OUTPUT* ++ Output file (defaults to stdout) ++ ++ **-p, --base-policy** *BASE_POLICY* ++ Merge new data into existing JSON runtime policy ++ ++ **-k, --keyrings** ++ Create keyrings policy entries ++ ++ **-b, --ima-buf** ++ Process ima-buf entries other than keyrings ++ ++ **-a, --allowlist** *ALLOWLIST* ++ Read checksums from plain-text allowlist ++ ++ **-e, --excludelist** *EXCLUDE_LIST_FILE* ++ Add IMA exclude list to policy ++ ++ **-m, --ima-measurement-list** *[IMA_MEASUREMENT_LIST]* ++ Use IMA measurement list for hash/keyring extraction ++ ++ **--ignored-keyrings** *IGNORED_KEYRINGS* ++ Ignore specified keyring (repeatable) ++ ++ **--add-ima-signature-verification-key** *IMA_SIGNATURE_KEYS* ++ Add x509/key to tenant_keyring (repeatable) ++ ++ **--show-legacy-allowlist** ++ Display digests in legacy allowlist format ++ ++ **-v, --verbose** ++ Set log level to DEBUG ++ ++ Filesystem scanning: ++ ++ **--algo** *{sha1,sha256,sha384,sha512,sm3_256}* ++ Checksum algorithm ++ ++ **--ramdisk-dir** *RAMDISK_DIR* ++ Path to initrds (e.g., /boot) ++ ++ **--rootfs** *ROOTFS* ++ Path to root filesystem (e.g., /) ++ ++ **-s, --skip-path** *SKIP_PATH* ++ Comma-separated directories to skip ++ ++ Repository scanning: ++ ++ **--local-rpm-repo** *LOCAL_RPM_REPO* ++ Local RPM repository directory ++ ++ **--remote-rpm-repo** *REMOTE_RPM_REPO* ++ Remote RPM repository URL ++ ++**keylime-policy create measured-boot** [*OPTIONS*] ++ ++ Create measured boot reference state policies from UEFI event logs. ++ ++ Options: ++ ++ **-e, --eventlog-file** *EVENTLOG_FILE* ++ Binary UEFI eventlog (required) ++ ++ **--without-secureboot, -i** ++ Create policy without SecureBoot (MeasuredBoot only) ++ ++ **-o, --output** *OUTPUT* ++ Output path for generated measured boot policy ++ ++**keylime-policy sign runtime** [*OPTIONS*] ++ ++ Sign runtime policies using DSSE. ++ ++ Options: ++ ++ **-o, --output** *OUTPUT_FILE* ++ Output file for DSSE-signed policy ++ ++ **-r, --runtime-policy** *POLICY* ++ Runtime policy file to sign (required) ++ ++ **-k, --keyfile** *KEYFILE* ++ EC private key for signing ++ ++ **-p, --keypath** *KEYPATH* ++ Output filename for created private key ++ ++ **-b, --backend** *{ecdsa,x509}* ++ DSSE backend (ecdsa or x509) ++ ++ **-c, --cert-outfile** *CERT_OUTFILE* ++ Output file for x509 certificate (x509 backend) ++ ++EXAMPLES ++======== ++ ++**Create runtime policy from filesystem:** ++ ++.. code-block:: bash ++ ++ sudo keylime-policy create runtime --rootfs / --output my-policy.json ++ ++**Create runtime policy from allowlist:** ++ ++.. code-block:: bash ++ ++ sudo keylime-policy create runtime --allowlist my-allowlist.txt --output policy.json ++ ++**Create measured boot policy:** ++ ++.. code-block:: bash ++ ++ sudo keylime-policy create measured-boot -e /sys/kernel/security/tpm0/binary_bios_measurements -o mb-policy.json ++ ++**Sign runtime policy:** ++ ++.. code-block:: bash ++ ++ sudo keylime-policy sign runtime -r policy.json -k signing-key.pem -o signed-policy.json ++ ++ENVIRONMENT ++=========== ++ ++**KEYLIME_LOGGING_CONFIG** ++ Path to logging.conf ++ ++NOTES ++===== ++ ++- All operations require root privileges ++- Runtime policies use JSON format ++- Measured boot policies require binary UEFI event logs ++- DSSE signing supports both ECDSA and x509 backends ++ ++SEE ALSO ++======== ++ ++**keylime_tenant**\(1), **keylime_verifier**\(8), **keylime_registrar**\(8) ++ ++BUGS ++==== ++ ++Report bugs at https://github.com/keylime/keylime/issues +diff --git a/docs/man/keylime_agent.8.rst b/docs/man/keylime_agent.8.rst +new file mode 100644 +index 0000000..dffcc09 +--- /dev/null ++++ b/docs/man/keylime_agent.8.rst +@@ -0,0 +1,218 @@ ++============= ++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: ++ ++.. code-block:: bash ++ ++ sudo keylime_agent ++ ++Start as a systemd service: ++ ++.. code-block:: bash ++ ++ sudo systemctl enable --now keylime_agent ++ ++Open firewall port: ++ ++.. code-block:: bash ++ ++ 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 +diff --git a/docs/man/keylime_registrar.8.rst b/docs/man/keylime_registrar.8.rst +new file mode 100644 +index 0000000..9841c34 +--- /dev/null ++++ b/docs/man/keylime_registrar.8.rst +@@ -0,0 +1,142 @@ ++================= ++keylime_registrar ++================= ++ ++------------------------------------------------ ++Keylime registrar service for agent registration ++------------------------------------------------ ++ ++:Manual section: 8 ++:Author: Keylime Developers ++:Date: September 2025 ++ ++SYNOPSIS ++======== ++ ++**keylime_registrar** ++ ++(Most operations require root privileges, use with sudo) ++ ++DESCRIPTION ++=========== ++ ++The registrar is a long-running service used by agents. It maintains its own database where it stores data ++of registered agents. The service does not accept command-line options; behavior is ++configured via configuration files and environment variables, and is managed by keylime tenant. ++ ++CONFIGURATION ++============= ++ ++Primary configuration is read from ``/etc/keylime/registrar.conf`` (or an override via env). ++All options are under the ``[registrar]`` section. ++ ++Essential configuration options: ++ ++**ip** ++ Bind address ++ ++**port** ++ HTTP port ++ ++**tls_port** ++ HTTPS port ++ ++**tls_dir** ++ TLS material location (``generate`` for auto-generate CA, keys, certs under ``$KEYLIME_DIR/reg_ca``, ``default`` for shared verifier CA under ``$KEYLIME_DIR/cv_ca``) ++ ++**server_key**, **server_key_password**, **server_cert**, **trusted_client_ca** ++ TLS files ++ ++**database_url** ++ SQLAlchemy URL; value ``sqlite`` maps to ``$KEYLIME_DIR/reg_data.sqlite`` ++ ++**database_pool_sz_ovfl** ++ Pool size, overflow (non-sqlite) ++ ++**auto_migrate_db** ++ Apply DB migrations on startup ++ ++**max_upload_size** ++ Request body limit (bytes) ++ ++**tpm_identity** ++ Allowed identity (``default``, ``ek_cert_or_iak_idevid``, ``ek_cert``, ``iak_idevid``) ++ ++**malformed_cert_action** ++ ``warn`` (default), ``reject``, or ``ignore`` ++ ++**durable_attestation_import** (optional) ++ Python import path to enable Durable Attestation ++ ++ENVIRONMENT ++=========== ++ ++**KEYLIME_REGISTRAR_CONFIG** ++ Path to registrar.conf (highest priority) ++ ++**KEYLIME_LOGGING_CONFIG** ++ Path to logging.conf ++ ++**KEYLIME_DIR** ++ Working directory (default: ``/var/lib/keylime``) ++ ++**KEYLIME_TEST** ++ ``on/true/1`` enables testing mode (looser checks; WORK_DIR becomes CWD) ++ ++FILES ++===== ++ ++``/etc/keylime/registrar.conf`` ++ Registrar configuration file ++ ++``/etc/keylime/logging.conf`` ++ Logging configuration ++ ++``$KEYLIME_DIR/reg_data.sqlite`` ++ Database file when ``database_url = sqlite`` ++ ++``$KEYLIME_DIR/reg_ca`` ++ TLS certificates when ``tls_dir = generate`` ++ ++``$KEYLIME_DIR/cv_ca`` ++ Shared verifier certificates when ``tls_dir = default`` ++ ++RUNTIME ++======= ++ ++Start from system install: ++ ++.. code-block:: bash ++ ++ sudo keylime_registrar ++ ++Start as a systemd service: ++ ++.. code-block:: bash ++ ++ systemctl enable --now keylime_registrar ++ ++Open firewall ports (adjust if you changed ports): ++ ++.. code-block:: bash ++ ++ firewall-cmd --add-port=8890/tcp --add-port=8891/tcp ++ firewall-cmd --runtime-to-permanent ++ ++NOTES ++===== ++ ++- HTTPS is required for routes unless explicitly allowed insecure by the service. ++- With ``tls_dir = default``, start the verifier before the registrar so the shared CA/certs exist in ``$KEYLIME_DIR/cv_ca``. ++- The service forks worker processes (default: CPU count). ++- Registrar and verifier may run on the same host or on separate hosts. ++ ++SEE ALSO ++======== ++ ++**keylime_verifier**\(8), **keylime_tenant**\(1), **keylime_agent**\(8) ++ ++BUGS ++==== ++ ++Report bugs at https://github.com/keylime/keylime/issues +diff --git a/docs/man/keylime_tenant.1.rst b/docs/man/keylime_tenant.1.rst +new file mode 100644 +index 0000000..7be1319 +--- /dev/null ++++ b/docs/man/keylime_tenant.1.rst +@@ -0,0 +1,263 @@ ++============== ++keylime_tenant ++============== ++ ++--------------------------------------------------------------------------- ++Keylime tenant management tool for agent provisioning and policy management ++--------------------------------------------------------------------------- ++ ++:Manual section: 1 ++:Author: Keylime Developers ++:Date: July 2025 ++ ++SYNOPSIS ++======== ++ ++**keylime_tenant** [*OPTIONS*] [*COMMAND*] ++ ++(Most operations require root privileges, use with sudo) ++ ++DESCRIPTION ++=========== ++ ++keylime_tenant is the primary command-line interface for managing Keylime agents and policies. ++It allows users to provision agents with TPM-based attestation, manage runtime policies, ++measured boot policies, and interact with Keylime registrar and verifier services. ++ ++The tenant can add, delete, update, and monitor agents, as well as manage various types of ++policies including runtime policies (for IMA/EVM attestation) and measured boot policies ++(for boot-time attestation). It supports both push and pull models for agent communication. ++ ++You can run keylime_tenant on the same system as the Keylime registrar or verifier, or on a separate system. ++ ++COMMANDS ++======== ++ ++**-c, --command** *COMMAND* ++ Specify the command to execute. Valid commands are: ++ ++ - **add**: Add a new agent to the system (default) ++ - **delete**: Remove an agent from the system ++ - **update**: Update an existing agent's configuration ++ - **regstatus**: Show agent status from registrar ++ - **cvstatus**: Show agent status from cloud verifier ++ - **status**: Show combined agent status ++ - **reglist**: List all agents in registrar ++ - **cvlist**: List all agents in cloud verifier ++ - **reactivate**: Reactivate a failed agent ++ - **regdelete**: Delete agent from registrar only ++ - **bulkinfo**: Get bulk information about agents ++ - **addruntimepolicy**: Add a runtime policy (requires --runtime-policy or --allowlist) ++ - **showruntimepolicy**: Display a runtime policy (requires --runtime-policy-name) ++ - **deleteruntimepolicy**: Remove a runtime policy (requires --runtime-policy-name) ++ - **updateruntimepolicy**: Update a runtime policy (requires --runtime-policy-name) ++ - **listruntimepolicy**: List all runtime policies ++ - **addmbpolicy**: Add a measured boot policy (requires --mb-policy-name) ++ - **showmbpolicy**: Display a measured boot policy (requires --mb-policy-name) ++ - **deletembpolicy**: Remove a measured boot policy (requires --mb-policy-name) ++ - **updatembpolicy**: Update a measured boot policy (requires --mb-policy-name) ++ - **listmbpolicy**: List all measured boot policies ++ ++OPTIONS ++======= ++ ++**-h, --help** ++ Show help message and exit ++ ++**--push-model** ++ Enable push model (avoid requests to keylime-agent) ++ ++**-t, --targethost** *AGENT_IP* ++ The IP address of the host to provision ++ ++**-tp, --targetport** *AGENT_PORT* ++ The port of the host to provision ++ ++**-r, --registrarhost** *REGISTRAR_IP* ++ The IP address of the registrar where to retrieve the agents data from ++ ++**-rp, --registrarport** *REGISTRAR_PORT* ++ The port of the registrar ++ ++**--cv_targethost** *CV_AGENT_IP* ++ The IP address of the host to provision that the verifier will use (optional). ++ Use only if different than argument to option -t/--targethost ++ ++**-v, --cv** *VERIFIER_IP* ++ The IP address of the cloud verifier ++ ++**-vp, --cvport** *VERIFIER_PORT* ++ The port of the cloud verifier ++ ++**-vi, --cvid** *VERIFIER_ID* ++ The unique identifier of a cloud verifier ++ ++**-nvc, --no-verifier-check** ++ Disable the check to confirm if the agent is being processed by the specified verifier. ++ Use only with -c/--command delete or reactivate ++ ++**-u, --uuid** *AGENT_UUID* ++ UUID for the agent to provision ++ ++**-f, --file** *FILE* ++ Deliver the specified plaintext file to the provisioned agent ++ ++**--cert** *CA_DIR* ++ Create and deliver a certificate using a CA created by ca-util. ++ Pass in the CA directory or use "default" to use the standard directory ++ ++**-k, --key** *KEYFILE* ++ An intermediate key file produced by user_data_encrypt ++ ++**-p, --payload** *PAYLOAD* ++ Specify the encrypted payload to deliver with encrypted keys specified by -k ++ ++**--include** *INCL_DIR* ++ Include additional files in provided directory in certificate zip file. ++ Must be specified with --cert ++ ++**--runtime-policy** *RUNTIME_POLICY* ++ Specify the file path of a runtime policy ++ ++**--runtime-policy-checksum** *RUNTIME_POLICY_CHECKSUM* ++ Specify the SHA-256 checksum of a runtime policy ++ ++**--runtime-policy-sig-key** *RUNTIME_POLICY_SIG_KEY* ++ Specify the public key file used to validate the runtime policy signature ++ ++**--runtime-policy-url** *RUNTIME_POLICY_URL* ++ Specify the URL of a remote runtime policy ++ ++**--runtime-policy-name** *RUNTIME_POLICY_NAME* ++ The name of the runtime policy to operate with ++ ++**--mb-policy** *MB_POLICY* ++ The measured boot policy to operate with ++ ++**--mb-policy-name** *MB_POLICY_NAME* ++ The name of the measured boot policy to operate with ++ ++**--tpm_policy** *TPM_POLICY* ++ Specify a TPM policy in JSON format. ++ Example: {"15":"0000000000000000000000000000000000000000"} ++ ++**--verify** ++ Block on cryptographically checked key derivation confirmation from the agent ++ once it has been provisioned ++ ++**--supported-version** *SUPPORTED_VERSION* ++ API version that is supported by the agent. Detected automatically by default ++ ++DEPRECATED OPTIONS ++================== ++ ++The following options are deprecated and may be removed in future versions: ++ ++**--allowlist** *ALLOWLIST* ++ **DEPRECATED**: Migrate to runtime policies for continued functionality. ++ Specify the file path of an allowlist ++ ++**--allowlist-url** *ALLOWLIST_URL* ++ **DEPRECATED**: Migrate to runtime policies for continued functionality. ++ Specify the URL of a remote allowlist ++ ++**--allowlist-name** *ALLOWLIST_NAME* ++ **DEPRECATED**: Migrate to runtime policies for continued functionality. ++ The name of allowlist to operate with ++ ++**--exclude** *IMA_EXCLUDE* ++ **DEPRECATED**: Migrate to runtime policies for continued functionality. ++ Specify the location of an IMA exclude list ++ ++**--mb_refstate** *MB_POLICY* ++ **DEPRECATED**: Use --mb-policy instead. ++ Specify the location of a measured boot reference state ++ ++**--signature-verification-key** *IMA_SIGN_VERIFICATION_KEYS* ++ **DEPRECATED**: Provide verification keys as part of a runtime policy for continued functionality. ++ Specify an IMA file signature verification key ++ ++EXAMPLES ++======== ++ ++**Add a new agent:** ++ ++.. code-block:: bash ++ ++ sudo keylime_tenant -c add -t 192.168.1.100 -u agent-001 ++ ++**Add an agent with runtime policy:** ++ ++.. code-block:: bash ++ ++ sudo keylime_tenant -c add -t 192.168.1.100 -u agent-001 --runtime-policy /path/to/policy.json ++ ++**Check agent status:** ++ ++.. code-block:: bash ++ ++ sudo keylime_tenant -c status -u agent-001 ++ ++**Delete an agent:** ++ ++.. code-block:: bash ++ ++ sudo keylime_tenant -c delete -u agent-001 ++ ++**List all agents:** ++ ++.. code-block:: bash ++ ++ sudo keylime_tenant -c cvlist ++ ++**Add a runtime policy:** ++ ++.. code-block:: bash ++ ++ sudo keylime_tenant -c addruntimepolicy --runtime-policy-name my-policy --runtime-policy /path/to/policy.json ++ ++**Add a measured boot policy:** ++ ++.. code-block:: bash ++ ++ sudo keylime_tenant -c addmbpolicy --mb-policy-name my-mb-policy --mb-policy /path/to/mb-policy.json ++ ++**Provision agent with certificate delivery:** ++ ++.. code-block:: bash ++ ++ sudo keylime_tenant -c add -t 192.168.1.100 -u agent-001 --cert default ++ ++**Provision agent with custom verifier:** ++ ++.. code-block:: bash ++ ++ sudo keylime_tenant -c add -t 192.168.1.100 -u agent-001 -v 192.168.1.200 -vp 8881 ++ ++FILES ++===== ++ ++/etc/keylime/tenant.conf ++ Default configuration file for keylime_tenant. Contains all tenant related settings. ++ ++ ++PREREQUISITES ++============= ++ ++- Keylime verifier service running (default: 127.0.0.1:8881) ++- Keylime registrar service running (default: 127.0.0.1:8891) ++- Root privileges (use sudo) ++- Network connectivity to registrar and verifier services ++- Valid TLS configuration in /etc/keylime/tenant.conf ++ ++SEE ALSO ++======== ++ ++**keylime_verifier**\(8), **keylime_registrar**\(8), **keylime_agent**\(8) ++ ++For more information about Keylime, visit: https://keylime.dev ++ ++BUGS ++==== ++ ++Report bugs to the Keylime project at: https://github.com/keylime/keylime/issues +diff --git a/docs/man/keylime_verifier.8.rst b/docs/man/keylime_verifier.8.rst +new file mode 100644 +index 0000000..fd7cfb9 +--- /dev/null ++++ b/docs/man/keylime_verifier.8.rst +@@ -0,0 +1,116 @@ ++================ ++keylime_verifier ++================ ++ ++---------------------------------------------- ++Keylime verifier service for agent attestation ++---------------------------------------------- ++ ++:Manual section: 8 ++:Author: Keylime Developers ++:Date: September 2025 ++ ++SYNOPSIS ++======== ++ ++**keylime_verifier** ++ ++(Most operations require root privileges, use with sudo) ++ ++DESCRIPTION ++=========== ++ ++The verifier is a long-running service that attests registered agents. It accesses ++the registrar database to obtain agent data, and optionally performs measured boot evaluation and durable ++attestation. The service does not accept command-line options; its behavior is configured via ++configuration files and environment variables, and it is managed by keylime tenant. ++ ++CONFIGURATION ++============= ++ ++Primary configuration is read from ``/etc/keylime/verifier.conf`` (or an override via env). ++All options are under the ``[verifier]`` section. ++ ++Essentials: ++- **uuid**: Unique identifier for this verifier instance ++- **ip**, **port**: Bind address and HTTP port ++- **registrar_ip**, **registrar_port**: Registrar endpoint ++- **enable_agent_mtls**: Enable mTLS with agents and tenant ++- **tls_dir**: TLS material location ++ ++ - ``generate``: auto-generate CA, client and server keys/certs under ``$KEYLIME_DIR/cv_ca`` ++ - ``default``: use existing materials under ``$KEYLIME_DIR/cv_ca`` ++ ++- **server_key**, **server_key_password**, **server_cert**: Server TLS files ++- **client_key**, **client_key_password**, **client_cert**: Client TLS files ++- **trusted_client_ca**, **trusted_server_ca**: CA lists ++- **database_url**: SQLAlchemy URL; value ``sqlite`` maps to ``$KEYLIME_DIR/cv_data.sqlite`` ++- **database_pool_sz_ovfl**: Pool size, overflow (non-sqlite) ++- **auto_migrate_db**: Apply DB migrations on startup ++- **num_workers**: Number of worker processes (``0`` = CPU count) ++- **exponential_backoff**, **retry_interval**, **max_retries**: Retry behavior for agent comm ++- **quote_interval**: Time between integrity checks (seconds) ++- **max_upload_size**: Upload size limit (bytes) ++- **request_timeout**: Agent request timeout (seconds) ++- **measured_boot_policy_name**, **measured_boot_imports**, **measured_boot_evaluate**: measured boot policy settings ++- **severity_labels**, **severity_policy**: revocation severity config ++- **ignore_tomtou_errors**: handle ToMToU IMA entries (bool) ++- **durable_attestation_import** and related **persistent_store_url**, **transparency_log_url**, ++ **time_stamp_authority_url**, **time_stamp_authority_certs_path**, **persistent_store_format**, ++ **persistent_store_encoding**, **transparency_log_sign_algo**, **signed_attributes**: durable attestation ++- **require_allow_list_signatures**: require signed allowlists (bool) ++ ++ENVIRONMENT ++=========== ++ ++- **KEYLIME_VERIFIER_CONFIG**: Path to verifier.conf (highest priority) ++- **KEYLIME_LOGGING_CONFIG**: Path to logging.conf ++- **KEYLIME_DIR**: Working directory (default: ``/var/lib/keylime``) ++- **KEYLIME_TEST**: ``on/true/1`` enables testing mode (looser checks; WORK_DIR becomes CWD) ++ ++FILES ++===== ++ ++- ``/etc/keylime/verifier.conf`` ++- ``/etc/keylime/logging.conf`` ++- ``$KEYLIME_DIR/cv_data.sqlite`` (when ``database_url = sqlite``) ++- ``$KEYLIME_DIR/cv_ca`` (when ``tls_dir = default`` or ``generate``) ++- systemd unit: ``keylime_verifier.service`` ++ ++RUNTIME ++======= ++ ++Start from system install: ++ ++.. code-block:: bash ++ ++ sudo keylime_verifier ++ ++Start as a systemd service: ++ ++.. code-block:: bash ++ ++ systemctl enable --now keylime_verifier ++ ++Open firewall ports (adjust if you changed ports): ++ ++.. code-block:: bash ++ ++ firewall-cmd --add-port 8881/tcp ++ firewall-cmd --runtime-to-permanent ++ ++NOTES ++===== ++ ++- Verifier initializes measured boot components on startup. ++- With ``tls_dir = generate``, the verifier creates CA/keys/certs in ``$KEYLIME_DIR/cv_ca`` used by other components. ++ ++SEE ALSO ++======== ++ ++**keylime_registrar**\(8), **keylime_tenant**\(1), **keylime_agent**\(8) ++ ++BUGS ++==== ++ ++Report bugs at https://github.com/keylime/keylime/issues +-- +2.51.0 + diff --git a/keylime.spec b/keylime.spec index 1da7f06..9b13060 100644 --- a/keylime.spec +++ b/keylime.spec @@ -9,7 +9,7 @@ Name: keylime Version: 7.12.1 -Release: 12%{?dist} +Release: 13%{?dist} Summary: Open source TPM software for Bootstrapping and Maintaining Trust URL: https://github.com/keylime/keylime @@ -60,6 +60,11 @@ Patch: 0016-tpm-fix-ECC-P-521-coordinate-validation.patch Patch: 0017-tpm-fix-ECC-P-521-credential-activation-with-consist.patch Patch: 0018-tpm-fix-ECC-signature-parsing-to-support-variable-le.patch +# Backported from: +# - https://github.com/keylime/keylime/pull/1802 +# - https://github.com/keylime/keylime/pull/1813 +Patch: 0019-Added-manpages-for-keylime-services-and-the-tenant.patch + # Main program: Apache-2.0 # Icons: MIT License: Apache-2.0 AND MIT @@ -85,6 +90,7 @@ BuildRequires: systemd-rpm-macros BuildRequires: rpm-sign BuildRequires: createrepo_c BuildRequires: tpm2-tools +BuildRequires: python3-docutils Requires: python3-%{srcname} = %{version}-%{release} Requires: %{srcname}-base = %{version}-%{release} @@ -253,6 +259,12 @@ bzip2 -9 %{srcname}.pp %build %py3_build +mkdir -p manpages +rst2man --syntax-highlight=none docs/man/keylime_tenant.1.rst manpages/keylime_tenant.1 +rst2man --syntax-highlight=none docs/man/keylime-policy.1.rst manpages/keylime-policy.1 +rst2man --syntax-highlight=none docs/man/keylime_registrar.8.rst manpages/keylime_registrar.8 +rst2man --syntax-highlight=none docs/man/keylime_verifier.8.rst manpages/keylime_verifier.8 + %install %py3_install mkdir -p %{buildroot}/%{_sharedstatedir}/%{srcname} @@ -305,6 +317,14 @@ done install -p -D -m 0644 %{SOURCE2} %{buildroot}/%{_sysusersdir}/%{srcname}.conf install -p -D -m 0644 %{SOURCE3} %{buildroot}/%{_tmpfilesdir}/%{name}.conf +# Install manpages +install -d %{buildroot}%{_mandir}/man1 +install -d %{buildroot}%{_mandir}/man8 +install -m 644 manpages/keylime_tenant.1 %{buildroot}%{_mandir}/man1/ +install -m 644 manpages/keylime-policy.1 %{buildroot}%{_mandir}/man1/ +install -m 644 manpages/keylime_registrar.8 %{buildroot}%{_mandir}/man8/ +install -m 644 manpages/keylime_verifier.8 %{buildroot}%{_mandir}/man8/ + %check # Create the default configuration files to be used by the tests. # Also set the associated environment variables so that the tests @@ -420,6 +440,7 @@ fi %{_bindir}/%{srcname}_verifier %{_bindir}/%{srcname}_ca %{_unitdir}/keylime_verifier.service +%{_mandir}/man8/keylime_verifier.8* %files registrar %license LICENSE @@ -427,6 +448,7 @@ fi %config(noreplace) %verify(not md5 size mode mtime) %attr(400,%{srcname},%{srcname}) %{_sysconfdir}/%{srcname}/registrar.conf %{_bindir}/%{srcname}_registrar %{_unitdir}/keylime_registrar.service +%{_mandir}/man8/keylime_registrar.8* %if 0%{?with_selinux} %files selinux @@ -440,6 +462,7 @@ fi %attr(500,%{srcname},%{srcname}) %dir %{_sysconfdir}/%{srcname}/tenant.conf.d %config(noreplace) %verify(not md5 size mode mtime) %attr(400,%{srcname},%{srcname}) %{_sysconfdir}/%{srcname}/tenant.conf %{_bindir}/%{srcname}_tenant +%{_mandir}/man1/keylime_tenant.1* %files -n python3-%{srcname} %license LICENSE @@ -447,6 +470,7 @@ fi %{python3_sitelib}/%{srcname} %{_bindir}/keylime_attest %{_bindir}/keylime-policy +%{_mandir}/man1/keylime-policy.1* %files tools