Verifier

GET /v2.4/agents/{agent_id:UUID}

Get status of agent agent_id from Verifier

Example response:

{
  "code": 200,
  "status": "Success",
  "results": {
    "operational_state": 7,
    "v": "yyNnlWwFRz1ZUzSe2YEpz9A5urtv6oywgttTF7VbBP4=",
    "ip": "127.0.0.1",
    "port": 9002,
    "tpm_policy": "{\"22\": [\"0000000000000000000000000000000000000001\", \"0000000000000000000000000000000000000000000000000000000000000001\", \"000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001\", \"ffffffffffffffffffffffffffffffffffffffff\", \"ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff\", \"ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff\"], \"15\": [\"0000000000000000000000000000000000000000\", \"0000000000000000000000000000000000000000000000000000000000000000\", \"000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000\"], \"mask\": \"0x408000\"}",
    "vtpm_policy": "{\"23\": [\"ffffffffffffffffffffffffffffffffffffffff\", \"0000000000000000000000000000000000000000\"], \"15\": [\"0000000000000000000000000000000000000000\"], \"mask\": \"0x808000\"}",
    "meta_data": "{}",
    "has_mb_refstate": 0,
    "has_runtime_policy": 0,
    "accept_tpm_hash_algs": [
      "sha512",
      "sha384",
      "sha256",
      "sha1"
    ],
    "accept_tpm_encryption_algs": [
      "ecc",
      "rsa"
    ],
    "accept_tpm_signing_algs": [
      "ecschnorr",
      "rsassa"
    ],
    "hash_alg": "sha256",
    "enc_alg": "rsa",
    "sign_alg": "rsassa",
    "verifier_id": "default",
    "verifier_ip": "127.0.0.1",
    "verifier_port": 8881,
    "severity_level": 6,
    "last_event_id": "qoute_validation.quote_validation",
    "attestation_count": 240,
    "last_received_quote": 1676644582,
    "last_successful_attestation": 1676644462
  }
}
Response JSON Object:

  • code (int) – HTTP status code

  • status (string) – Status as string

  • results (object) – Results as a JSON object

  • operational_state (int) – Current state of the agent in the CV. Defined in https://github.com/keylime/keylime/blob/master/keylime/common/states.py

  • v (string) – V key for payload base64 encoded or null. Decoded length is 32 bytes

  • ip (string) – Agents contact ip address for the CV

  • port (string) – Agents contact port for the CV

  • tpm_policy (string) – Static PCR policy and mask for TPM

  • vtpm_policy (string) – Static PCR policy and mask for vTPM

  • meta_data (string) – Metadata about the agent. Normally contains certificate information if a CA is used.

  • has_mb_refstate (int) – 1 if a measured boot refstate was provided via tenant, 0 otherwise.

  • has_runtime_policy (int) – 1 if a runtime policy (allowlist and excludelist) was provided via tenant, 0 otherwise.

  • accept_tpm_hash_algs (list[string]) – Accepted TPM hashing algorithms. sha1 must be enabled for IMA validation to work.

  • accept_tpm_encryption_algs (list[string]) – Accepted TPM encryption algorithms.

  • accept_tpm_signing_algs (list[string]) – Accepted TPM signing algorithms.

  • hash_alg (string) – Used hashing algorithm.

  • enc_alg (string) – Used encryption algorithm.

  • sign_alg (string) – Used signing algorithm.

  • verifier_id (string) – Name of the verifier that is used. (Only important if multiple verifiers are used)

  • verifier_ip (string) – IP of the verifier that is used.

  • verifier_port (int) – Port of the verifier that is used.

  • severity_level (int) – Severity level of the agent. Might be null. Levels are the numeric representation of the severity labels.

  • last_event_id (string) – ID of the last revocation event. Might be null.

  • attestation_count (int) – Number of quotes received from the agent which have verified successfully.

  • last_received_quote (int) – Timestamp of the last quote received from the agent irrespective of validity. A value of 0 indicates no quotes have been received. May be null after upgrading from a previous Keylime version.

  • last_successful_attestation (int) – Timestamp of the last quote received from the agent which verified successfully. A value of 0 indicates no valid quotes have been received. May be null after upgrading from a previous Keylime version.

POST /v2.4/agents/{agent_id:UUID}

Add new agent instance_id to Verifier.

Example request:

{
  "v": "3HZMmIEc6yyjfoxdCwcOgPk/6X1GuNG+tlCmNgqBM/I=",
  "cloudagent_ip": "127.0.0.1",
  "cloudagent_port": 9002,
  "tpm_policy": "{\"22\": [\"0000000000000000000000000000000000000001\", \"0000000000000000000000000000000000000000000000000000000000000001\", \"000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001\", \"ffffffffffffffffffffffffffffffffffffffff\", \"ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff\", \"ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff\"], \"15\": [\"0000000000000000000000000000000000000000\", \"0000000000000000000000000000000000000000000000000000000000000000\", \"000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000\"], \"mask\": \"0x408000\"}",
  "ak_tpm": "ARgAAQALAAUAcgAAABAAFAALCAAAAAAAAQDjZ4J2HO7ekIONAX/eYIzt7ziiVAqE/1D7I9oEwIE88dIfqH0FQLJAg8u3+ZOgsJDQr9HiMhZRPhv8hRuia8ULdAomyOFA1cVzlBF+xcPUEemOIofbvcBNAoTY/x49r8LpqAEUBBiUeOniQbjfRaV2S5cEAA92wHLQAPLF9Sbf3zNxCnbhtRkEi6C3NYl8/FJqyu5Z9vvwEBBOFFTPasAxMtPm6a+Z5KJ4rDflipfaVcUvTKLIBRI7wkuXqhTR8BeIByK9upQ3iBo+FbYjWSf+BaN+wodMNgPbzxyL+tuxVqiPefBbv+sTWVxmYfo5i84FlbNOAW3APH8c+jZ3tgbt",
  "mtls_cert": "-----BEGIN CERTIFICATE----- (...) -----END CERTIFICATE-----",
  "runtime_policy_name": null,
  "runtime_policy": "",
  "runtime_policy_sig": "",
  "runtime_policy_key": "",
  "mb_refstate": "null",
  "ima_sign_verification_keys": "[]",
  "metadata": "{\"cert_serial\": 71906672046699268666356441515514540742724395900, \"subject\": \"/C=US/ST=MA/L=Lexington/O=Keylime/OU=53/CN=D432FBB3-D2F1-4A97-9EF7-75BD81C00000\"}",
  "revocation_key": "-----BEGIN PRIVATE KEY----- (...) -----END PRIVATE KEY-----\n",
  "accept_tpm_hash_algs": [
    "sha512",
    "sha384",
    "sha256",
    "sha1"
  ],
  "accept_tpm_encryption_algs": [
    "ecc",
    "rsa"
  ],
  "accept_tpm_signing_algs": [
    "ecschnorr",
    "rsassa"
  ],
  "supported_version": "2.0"
}
Request JSON Object:

  • v (string) – (Optional) V key for payload base64 encoded. Decoded length is 32 bytes.

  • cloudagent_ip (string) – Agents contact ip address for the CV.

  • cloudagent_port (string) – Agents contact port for the CV.

  • tpm_policy (string) – Static PCR policy and mask for TPM. Is a string encoded dictionary that also includes a mask for which PCRs should be included in a quote.

  • ak_tpm (string) – AK of the agent, base64-encoded, same as aik_tpm in the registrar.

  • mtls_cert (string) – MTLS certificate of the agent, PEM encoded, same as in the registrar.

  • runtime_policy_name (string) – Optional. If specified with a runtime_policy it is saved under that name, if specified without, then the policy with that name is loaded.

  • runtime_policy (string) – Runtime policy JSON object, base64 encoded.

  • runtime_policy_sig (string) – Optional runtime policy detached signature, base64-encoded. Must also provide runtime_policy_key.

  • runtime_policy_key (string) – Optional runtime policy detached signature key, base64-encoded. Must also provide runtime_policy_sig.

  • mb_refstate (string) – Measured boot reference state policy.

  • ima_sign_verification_keys (string) – IMA signature verification public keyring JSON object string encoded.

  • metadata (string) – Metadata about the agent. Contains cert_serial and subject if a CA is used with the tenant.

  • revocation_key (string) – Key which is used to sign the revocation message of the agent.

  • accept_tpm_hash_algs (list[string]) – Accepted TPM hashing algorithms. sha1 must be enabled for IMA validation to work.

  • accept_tpm_encryption_algs (list[string]) – Accepted TPM encryption algorithms.

  • accept_tpm_signing_algs (list[string]) – Accepted TPM signing algorithms.

  • supported_version (string) – supported API version of the agent. v prefix must not be included.

Example response:

{
  "code": 200,
  "status": "Success",
  "results": {}
}
Response JSON Object:

  • code (int) – HTTP status code

  • status (string) – Status as string

  • results (object) – Results as a JSON object (empty)

DELETE /v2.4/agents/{agent_id:UUID}

Terminate instance agent_id.

Example response:

{
  "code": 200,
  "status": "Success",
  "results": {}
}
PUT /v2.4/agents/{agent_id:UUID}/reactivate

Start agent agent_id (for an already bootstrapped agent_id node)

Example response:

{
  "code": 200,
  "status": "Success",
  "results": {}
}
Response JSON Object:

  • code (int) – HTTP status code

  • status (string) – Status as string

  • results (object) – Results as a JSON object (empty)

PUT /v2.4/agents/{agent_id:UUID}/stop

Stop Verifier polling on agent_id, but don’t delete (for an already started agent_id). This will make the agent verification fail.

Example response:

{
  "code": 200,
  "status": "Success",
  "results": {}
}
Response JSON Object:

  • code (int) – HTTP status code

  • status (string) – Status as string

  • results (object) – Results as a JSON object (empty)

POST /v2.4/allowlists/{runtime_policy_name:string}

Add new named IMA policy runtime_policy_name to Verifier.

Example request:

{
  "tpm_policy": "{\"22\": [\"0000000000000000000000000000000000000001\", \"0000000000000000000000000000000000000000000000000000000000000001\", \"000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001\", \"ffffffffffffffffffffffffffffffffffffffff\", \"ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff\", \"ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff\"], \"15\": [\"0000000000000000000000000000000000000000\", \"0000000000000000000000000000000000000000000000000000000000000000\", \"000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000\"], \"mask\": \"0x408000\"}",
  "runtime_policy": "",
  "runtime_policy_sig": "",
  "runtime_policy_key": ""
}
Request JSON Object:

  • tpm_policy (string) – Static PCR policy and mask for TPM. Is a string encoded dictionary that also includes a mask for which PCRs should be included in a quote.

  • runtime_policy (string) – Runtime policy JSON object, base64 encoded.

  • runtime_policy_sig (string) – Optional runtime policy detached signature, base64-encoded. Must also provide runtime_policy_key.

  • runtime_policy_key (string) – Optional runtime policy detached signature key, base64-encoded. Must also provide runtime_policy_sig.

GET /v2.4/allowlists/[runtime_policy_name:string]

If runtime_policy_name is provided, get the named runtime policies from the Verifier.

Example responses:

{
  "code": 200,
  "status": "Success",
  "results": {
    "name": "",
    "tpm_policy": "{\"22\": [\"0000000000000000000000000000000000000001\", \"0000000000000000000000000000000000000000000000000000000000000001\", \"000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001\", \"ffffffffffffffffffffffffffffffffffffffff\", \"ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff\", \"ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff\"], \"15\": [\"0000000000000000000000000000000000000000\", \"0000000000000000000000000000000000000000000000000000000000000000\", \"000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000\"], \"mask\": \"0x408000\"}",
    "runtime_policy": ""
  }
}
Response JSON Object:

  • code (int) – HTTP status code

  • status (string) – Status as string

  • results (object) – Results as a JSON object

  • name (string) – Name of the requested IMA policy.

  • tpm_policy (string) – Static PCR policy and mask for TPM. Is a string encoded dictionary that also includes a mask for which PCRs should be included in a quote.

  • runtime_policy (string) – Runtime policy JSON object, base64 encoded.

Otherwise, retrieve list of names of the runtime policies.

Example response:

{
  "code": 200,
  "status": "Success",
  "results": {
    "runtimepolicy names": [
        "runtimepolicyname1",
        "runtimepolicyname2"
    ],
  }
}
Response JSON Object:

  • code (int) – HTTP status code

  • status (string) – Status as string

  • results (object) – Results as a JSON object

  • names (list[string] runtimepolicy) – List of names of the runtime policies.

DELETE /v2.4/allowlist/{runtime_policy_name:string}

Delete IMA policy runtime_policy_name.

Example response:

{
  "code": 200,
  "status": "Success",
  "results": {}
}
Response JSON Object:

  • code (int) – HTTP status code

  • status (string) – Status as string

  • results (object) – Results as a JSON object (empty)

GET /v2.4/verify/identity

Verify the identity of a node monitored by keylime

Example request:

GET /v2.4/verify/identity?agent_uuid=e1ef9f28-be55-47b0-a6c1-8bef90294b93&hash_alg=sha256&nonce=DGHFH6EQVYGKP7YHNVEAFQQR5TN4W4JA&quote=r/1RDR4AYACIACzy[...] HTTP/1.1
Host: example.com
Accept: application/json
Query Parameters:

  • agent_uuid – The UUID of the Agent being verified.

  • hash_alg – The hash algorithm used by the Keylime agent and TPM.

  • nonce – The onetime nonce being used for identity verification.

  • quote – The TPM quoted nonce from the Keylime agent.

Example response:

{
  "code": 200,
  "status": "Success",
  "results": {
    "valid": 1
  }
}
Response JSON Object:

  • code (int) – HTTP status code

  • status (string) – Status as string

  • results (object) – Results as a JSON object

Request JSON Object:

  • valid (int) – A boolean 1 for valid, 0 for invalid identity.

GET /v2.4/mbpolicies/{policy_name:string}

Get the measured boot policy named policy_name

Example response:

{
  "code": 200,
  "status": "Success",
  "results": {
  }
}
Response JSON Object:

  • code (int) – HTTP status code

  • status (string) – Status as string

  • results (object) – Results as a JSON object

Request JSON Object:

  • valid (int) – A boolean 1 for valid, 0 for invalid identity.

POST /v2.4/verify/evidence

Verify the evidence against policy. This is useful for 3rd party integrations for things like: * CI/CD pipelines that generate policy * Fleet management systems that manage their own trust but want to check attestation evidence like TPM quotes, IMA logs, Measured Boot against some policy

Example request:

POST /v2.4/verify/evidence HTTP/1.1
Host: example.com
Accept: application/json

 {
   "nonce": "DGHFH6EQVYGKP7YHNVEAFQQR5TN4W4JA",
   "quote": "r/1RDR4AYACIACzy[...]",
   "hash_alg": "sha256",
   "tpm_ak": "ARgAAQALAAUAcgAAABAAFAALCAAA[...]",
   "tpm_ek": "BABEwIE88dIfqH0FQLJAg8u3+ZOg[...]",
   "tpm_policy": "{\"22\": [\"0000000000000000000000000000000000000001\", \"0000000000000000000000000000000000000000000000000000000000000001\",[...]",
   "runtime_policy": "{\"meta": {\"version\": 1, \"timestamp\": "2025-02-24 21:33:17.574168"}, \"digests\": {\"/boot/System.map-6.2.9-300.fc38.x86_64": ["dc720f9c236[...]",
   "mb_policy": "[...]",
   "ima_measurement_list": "10 0adefe762c149c7cec19da62f0da1297fcfbffff ima-ng sha256:0000000000000000000000000000000000000000000000000000000000000000 boot_aggregate[...]",
 }
Request JSON Object:

  • nonce (string) – The onetime nonce being used for identity verification.

  • quote (string) – The quote from the TPM

  • hash_alg (string) – The hashing algorithm used by the TPM

  • tpm_ak (string) – AK of the agent, base64-encoded.

  • tpm_ek (string) – EK of the agent, base64-encoded.

  • tpm_policy (string) – Static PCR policy and mask for TPM. Is a string encoded dictionary that also includes a mask for which PCRs should be included in a quote. Optional

  • runtime_policy (string) – JSON document of a Keylime Runtime (IMA) policy. Optional

  • mb_policy (string) – JSON document of a Keylime Measured Boot policy. Optional

  • ima_measurement_list (string) – The ASCII content of the IMA measurement list. Usually found at /sys/kernel/security/ima/ascii_runtime_measurements. Optional depending on runtime_policy.

  • mb_list (string) – The binary contents of the boot log. Usually found at something like /sys/kernel/security/tpm0/binary_bios_measurements. Optional depending on mb_policy.

Example response:

{
  "code": 200,
  "status": "Success",
  "results": {
    "valid": 0,
    "failures": [
        {
          "type": "ima.validation.ima-ng.not_in_allowlist",
          "context": { "message": "File not found in allowlist: /root/evil.sh" },
        }
    ]
  }
}
Response JSON Object:

  • code (int) – HTTP status code

  • status (string) – Status as string

  • results (object) – Results as a JSON object

Request JSON Object:

  • valid (int) – A boolean 1 for valid, 0 for invalid evidence

  • failures (array) – A list of optional failure objects for the different ways the evidence failed verification

  • type (string) – The Keylime specific type of failure

  • context (object) – More context, such as a human readable message about the failure