Rest API’s

All Keylime APIs use REST (Representational State Transfer).

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)

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.

RESTful API for Keylime (v2.1)

Keylime API is versioned. More information can be found here: https://github.com/keylime/enhancements/blob/master/45_api_versioning.md

Warning

API version 1.0 will no longer be officially supported starting with Keylime 6.4.0.

General responses

ANY /

Generic fields in responses

Response JSON Object

  • code (int) – HTTP status code

  • status (string) – textual context of that status

  • results (object) – Holds the actual data.

Cloud verifier (CV)

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

Get status of agent agent_id from CV

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"
  }
}
Response JSON Object

  • code (int) – HTTP status code

  • status (string) – Status as string

  • 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. 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.

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

Add new agent instance_id to CV.

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\"}",
  "vtpm_policy": "{\"23\": [\"ffffffffffffffffffffffffffffffffffffffff\", \"0000000000000000000000000000000000000000\"], \"15\": [\"0000000000000000000000000000000000000000\"], \"mask\": \"0x808000\"}",
  "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=MITLL/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) – 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.

  • vtpm_policy (string) – Static PCR policy and mask for vTPM. Same as tpm_policy.

  • 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.

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

Terminate instance agent_id.

Example response:

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

Start agent agent_id (for an already bootstrapped agent_id node)

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

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

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

Add new named IMA policy runtime_policy_name to CV.

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.1/allowlists/{runtime_policy_name:string}

Retrieve named runtime policy runtime_policy_name from CV.

Example response:

{
  "code": 200,
  "status": "Success",
  "results": {
    "name": "",
    "tpm_policy": "{\"22\": [\"0000000000000000000000000000000000000001\", \"0000000000000000000000000000000000000000000000000000000000000001\", \"000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001\", \"ffffffffffffffffffffffffffffffffffffffff\", \"ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff\", \"ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff\"], \"15\": [\"0000000000000000000000000000000000000000\", \"0000000000000000000000000000000000000000000000000000000000000000\", \"000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000\"], \"mask\": \"0x408000\"}",
    "runtime_policy": "",
  }
}
Request 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.

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

Delete IMA policy runtime_policy_name.

Example response:

{
  "code": 200,
  "status": "Success",
  "results": {}
}

Cloud Agent

GET /v2.1/keys/pubkey

Retrieves agents public key.

Example response:

{
  "code": 200,
  "status": "Success",
  "results": {
    "pubkey": "-----BEGIN PUBLIC KEY----- (...) -----END PUBLIC KEY-----\n"
  }
}
Response JSON Object

  • pubkey (string) – Public rsa key of the agent used for encrypting V and U key.

GET /version

Returns what API version the agent supports. This endpoint might not be implemented by all agents.

Example response:

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

  • supported_version (string) – The latest version the agent supports.

POST /v2.1/keys/vkey

Send v_key to node.

Example request:

{
  "encrypted_key": "MN/F33jjuLiIuRH8fF7pMtw6Hoe2KG10zg+/xuuZLa5d1WB2aR6feVCwknZDe/dhG51yB0tKau8fCNUz8KMxyWoFkalIY4vVG6DNpLouDjb+vMvI6RmVmCBwO5zx6R802wK2z2yUbcn11TU/k2zHq34CNFIgI5pQu7cnLMzCLW6NLEp8N0IOQL6D+uV9emkheJH1g40xYwUaKoABWjZeaJN5dvKwbkpIf2m+CROmCNPCidh87J0g7BENUvlSUO1FPfRjch4kyxLrp+aMu9zmzF/tZErh1zk+nUamtrgl25pEImw+Cn9RIVTd6fBkmzlGzch5foAqZCyZ0AhQ0ONuWw==",
}
Request JSON Object

  • encrypted_key (string) – V key encrypted with agents public key base64 encoded.

POST /v2.1/keys/ukey

Send u_key to node (with optional payload)

Example request:

{
  "auth_tag" : "3876c08b30c16c4140ee04300bb4262bbcc9034d8a2ed8c90784f13b484a570bf9da3d5c372141bd16d85de05c4c7cce",
  "encrypted_key": "iAckMZgZc8r43pF0iW8iwwAorD+rvnvF7AShhlz6+am+ryqW+907UynOrWrIrAseyVRE7ouHpr547gnwfF7oKeBFlEdWnE6FbQl9o6tk86BzQy3PImBLxJD/y/MmSuNR5pGQwZCueKI0ji3Nqq6heOgSvnMRC0PHgyumOsYiAnbDNyryvfwO4HsqdqMcEsBu1IVzU3EtJWhfQ8i/UpvHy6Jq4bBh+mw5HZwmK93bmsLXNKgjPWAicsCZINUAPVMCUL7dcDd4zijsBxMxiZF7Js7V25wKKFer2zqKsE5omLy9sKotFfWjgaROPLrKXxuDgNmlONJnD0btLZBa9T+mmA==",
  "payload": "WcXpUr4G9yfvVaojNx6K2XZuDYRkFoZQhHrvZB+TKZqsq41g"
}
Request JSON Object

  • auth_tag (string) – HMAC calculated with K key as key and UUID as data, using SHA-384 as the underlying hash algorithm

  • encrypted_key (string) – U key encrypted with agents public key base64 encoded

  • payload (string) – (optional) payload encrypted with K key base64 encoded.

GET /v2.1/keys/verify

Get confirmation of bootstrap key derivation

Example request:

/v2.1/keys/verify?challenge=1234567890ABCDEFHIJ
Parameters

  • challenge (string) – 20 character random string with [a-Z,0-9] as symbols.

Example response:

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

  • hmac (string) – hmac with K key as key and the challenge

GET /v2.1/quotes/integrity

Get integrity quote from node

Example request:

/v2.1/quotes/integrity?nonce=1234567890ABCDEFHIJ&mask=0x10401&partial=0
Parameters

  • nonce (string) – 20 character random string with [a-Z,0-9] as symbols.

  • mask (string) – Mask for what PCRs from the TPM are included in the quote.

  • partial (string) – Is either “0” or “1”. If set to “1” the public key is excluded in the response.

  • ima_ml_entry (string) – (optional) Line offset of the IMA entry list. If not present, 0 is assumed.

Example Response:

{
  "code": 200,
  "status": "Success",
  "results": {
    "quote": "r/1RDR4AYABYABPihP2yz+HcGF0vD0c4qiKt4nvSOAARURVNUAAAAAAAyQ9AAAAAAAAAAAAEgGRAjABY2NgAAAAEABAMAAAEAFCkk4YmhQECgWR+MnHqT9zftc3J8:ABQABAEAQ8IwX6Ak83zGhF6w8vOKOxsyTbxACQakYWGJaan3ewf+2O9TtiH5TLB1PXrPdhknsR/yx6OVUze9jTDvML9xkkK1ghXObCJ5gH+QX0udKfrLacm/iMds28SBtVO0rjqDIoYqGgXhH2ZhwGNDwjRCp6HquvtBe7pGEgtZlxf7Hr3wQRLO3FtliBPBR6gjOo7NC/uGsuPjdPU7c9ls29NgYSqdwShuNdRzwmZrF57umuUgF6GREFlxqLkGcbDIT1itV4zJZtI1caLVxqiH0Qv3sNqlNLsSHggkgc5S2EvNqwv/TsEZOq/leCoLtyVGYghPeGwg0RJfbe8cdyBWCQ6nOA==:AQAAAAQAAwAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQAAAAEAAAAUABdJ/ntmsqy2aDi6NhKnLKz4k4uEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
    "hash_alg": "sha256",
    "enc_alg": "rsa",
    "sign_alg": "rsassa",
    "pubkey": "-----BEGIN PUBLIC KEY----- (...) -----END PUBLIC KEY-----\n"
    "boottime": 123456,
    "ima_measurement_list": "10 367a111b682553da5340f977001689db8366056a ima-ng sha256:94c0ac6d0ff747d8f1ca7fac89101a141f3e8f6a2c710717b477a026422766d6 boot_aggregate\n",
    "ima_measurement_list_entry": 0,
    "mb_measurement_list": "AAAAAAMAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACEAAABTcGVjIElEIEV2ZW50MDMAAAAAAAACAAIBAAAACwAgAAAAAAAACAAAAAEAAAALAJailtIk8oXGe [....]"
  }
}
Response JSON Object

  • quote (string) – TPM integrity quote

  • hash_alg (string) – Used hash algorithm used in the quote (e.g. sha1, sha256, sha512).

  • enc_alg (string) – Encryption algorithm used in the quote (ecc, rsa).

  • sign_alg (string) – Signing algorthm used in the quote (rsassa, rsapss, ecdsa, ecdaa or ecschnorr).

  • pubkey (string) – PEM encoded public portion of the NK (digest is measured into PCR 16).

  • boottime (int) – Seconds since the system booted

  • ima_measurement_list (string) – (optional) IMA entry list. Is included if IMA_PCR (10) is included in the mask

  • ima_measurement_list_entry (int) – (optional) Starting line offset of the IMA entry list returned

  • mb_measurement_list (string) – (optional) UEFI Eventlog list base64 encoded. Is included if PCR 0 is included in the mask

Quote format: The quote field contains the quote, the signature and the PCR values that make up the quote.

QUOTE_DATA := rTPM_QUOTE:TPM_SIG:TPM_PCRS
TPM_QUOTE  := base64(TPMS_ATTEST)
TPM_SIG    := base64(TPMT_SIGNATURE)
TPM_PCRS   := base64(tpm2_pcrs) // Can hold more that 8 PCR entries. This is a data structure generated by tpm2_quote
GET /v2.1/quotes/identity

Get identity quote from node

Example request:

/v2.1/quotes/identity?nonce=1234567890ABCDEFHIJ
Parameters

  • nonce (string) – 20 character random string with [a-Z,0-9] as symbols.

Example response:

{
  "code": 200,
  "status": "Success",
  "results": {
    "quote": "r/1RDR4AYABYABPihP2yz+HcGF0vD0c4qiKt4nvSOAARURVNUAAAAAAAyQ9AAAAAAAAAAAAEgGRAjABY2NgAAAAEABAMAAAEAFCkk4YmhQECgWR+MnHqT9zftc3J8:ABQABAEAQ8IwX6Ak83zGhF6w8vOKOxsyTbxACQakYWGJaan3ewf+2O9TtiH5TLB1PXrPdhknsR/yx6OVUze9jTDvML9xkkK1ghXObCJ5gH+QX0udKfrLacm/iMds28SBtVO0rjqDIoYqGgXhH2ZhwGNDwjRCp6HquvtBe7pGEgtZlxf7Hr3wQRLO3FtliBPBR6gjOo7NC/uGsuPjdPU7c9ls29NgYSqdwShuNdRzwmZrF57umuUgF6GREFlxqLkGcbDIT1itV4zJZtI1caLVxqiH0Qv3sNqlNLsSHggkgc5S2EvNqwv/TsEZOq/leCoLtyVGYghPeGwg0RJfbe8cdyBWCQ6nOA==:AQAAAAQAAwAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQAAAAEAAAAUABdJ/ntmsqy2aDi6NhKnLKz4k4uEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
    "hash_alg": "sha256",
    "enc_alg": "rsa",
    "sign_alg": "rsassa",
    "pubkey": "-----BEGIN PUBLIC KEY----- (...) -----END PUBLIC KEY-----\n"
    "boottime": 123456
  }
}
Response JSON Object

  • quote (string) – See quotes/integrity

  • hash_alg (string) – See quotes/integrity

  • enc_alg (string) – See quotes/integrity

  • sign_alg (string) – See quotes/integrity

  • pubkey (string) – See quotes/integrity

  • boottime (int) – See quotes/integrity

Cloud Registrar

GET /v2.1/agents/

Get ordered list of registered agents

Example response:

{
  "code": 200,
  "status": "Success",
  "results": {
    "uuids": [
      "5e600bce-a5cb-4f5a-bf08-46d0b45081c5",
      "6dab10e4-6619-4ff9-9062-ee6ad23ec24d",
      "d432fbb3-d2f1-4a97-9ef7-75bd81c00000"
    ]
  }
}
GET /v2.1/agents/{agent_id:UUID}

Get EK certificate, AIK and optinal contact ip and port of agent agent_id.

Example response:

{
  "code": 200,
  "status": "Success",
  "results": {
    "aik_tpm": "ARgAAQALAAUAcgAAABAAFAALCAAAAAAAAQDjZ4J2HO7ekIONAX/eYIzt7ziiVAqE/1D7I9oEwIE88dIfqH0FQLJAg8u3+ZOgsJDQr9HiMhZRPhv8hRuia8ULdAomyOFA1cVzlBF+xcPUEemOIofbvcBNAoTY/x49r8LpqAEUBBiUeOniQbjfRaV2S5cEAA92wHLQAPLF9Sbf3zNxCnbhtRkEi6C3NYl8/FJqyu5Z9vvwEBBOFFTPasAxMtPm6a+Z5KJ4rDflipfaVcUvTKLIBRI7wkuXqhTR8BeIByK9upQ3iBo+FbYjWSf+BaN+wodMNgPbzxyL+tuxVqiPefBbv+sTWVxmYfo5i84FlbNOAW3APH8c+jZ3tgbt",
    "ek_tpm": "AToAAQALAAMAsgAgg3GXZ0SEs/gakMyNRqXXJP1S124GUgtk8qHaGzMUaaoABgCAAEMAEAgAAAAAAAEA0YwlPPIoXryMvbD5cIokN9OkljL2mV1oDxy7ETBXBe1nL9OWrLNO8Nbf8EaSNCtYCo5iqCwatnVRMPqNXcX8mQP0f/gDAqXryb+F192IJLKShHYSN32LJjCYOKrvNX1lrmr377juICFSRClE4q+pCfzhNj0Izw/eplaAI7gq41vrlnymWYGIEi4McErWG7qwr7LR9CXwiM7nhBYGtvobqoaOm4+f6zo3jQuks/KYjk0BR3mgAec/Qkfefw2lgSSYaPNl/8ytg6Dhla1LK8f7wWy/bv+3z7L11KLr8DZiFAzKBMiIDfaqNGYPhiFLKAMJ0MmJx63obCqx9z5BltV5YQ==",
    "ekcert": "MIIEGTCCAoGgAwIBAgIBBTANBgkqhkiG9w0BAQsFADAYMRYwFAYDVQQDEw1zd3RwbS1sb2NhbGNhMB4XDTIxMDQwOTEyNDAyNVoXDTMxMDQwNzEyNDAyNVowODE2MDQGA1UEAxMtZmVkb3JhMzM6NDdjYzJlMDMtNmRmMi00OGMyLWFmNGUtMDg1MWY1MWQyODJiMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0YwlPPIoXryMvbD5cIokN9OkljL2mV1oDxy7ETBXBe1nL9OWrLNO8Nbf8EaSNCtYCo5iqCwatnVRMPqNXcX8mQP0f/gDAqXryb+F192IJLKShHYSN32LJjCYOKrvNX1lrmr377juICFSRClE4q+pCfzhNj0Izw/eplaAI7gq41vrlnymWYGIEi4McErWG7qwr7LR9CXwiM7nhBYGtvobqoaOm4+f6zo3jQuks/KYjk0BR3mgAec/Qkfefw2lgSSYaPNl/8ytg6Dhla1LK8f7wWy/bv+3z7L11KLr8DZiFAzKBMiIDfaqNGYPhiFLKAMJ0MmJx63obCqx9z5BltV5YQIDAQABo4HNMIHKMBAGA1UdJQQJMAcGBWeBBQgBMFIGA1UdEQEB/wRIMEakRDBCMRYwFAYFZ4EFAgEMC2lkOjAwMDAxMDE0MRAwDgYFZ4EFAgIMBXN3dHBtMRYwFAYFZ4EFAgMMC2lkOjIwMTkxMDIzMAwGA1UdEwEB/wQCMAAwIgYDVR0JBBswGTAXBgVngQUCEDEOMAwMAzIuMAIBAAICAKIwHwYDVR0jBBgwFoAUaO+9FEi5yX/GEnU+Vc6b3Si6JeAwDwYDVR0PAQH/BAUDAwcgADANBgkqhkiG9w0BAQsFAAOCAYEAaP/jI2i/hXDrthtaZypQ8VUG5AWFnMDtgiMhDSaKwOBfyxiUiYMTggGYXLOXGIu1SJGBtRJsh3QSYgs2tJCnntWF9Jcpmk6kIW/MC8shE+hdu/gQZKjAPZS4QCLIldv+GVZdNYEIv2FYDsKl6Bq1qUsYhAb7z29Nu1itpdvja2qy7ODJ0u+ThccBuH60VGFclFdJg19dvVQMnffxzjwxxJTMnVPmGoEdR94O0z7yxvqQ22+ITD9s1c3AfWcV+yLEpHqhXRqtKGdkAM5kU85kEs/ZPTLNutJHmF0/Vk9W2pRym8SrUe8G6mwxVW8lP9M7fhovKTzoXVFW3gQWQeUxhvWOncXxtARFLp/+f2mzGBRWxIslW17vpZ3QLlCdJ2C7P3U8x2tvkuyyDfz3/pq+8ECupZhdSvpHlBnWvqs1tAWKW0qI9d0xNYjj3Kfl3Lfy7kqqe6FIkvbDlVhw3vnJlclW+M6D86jBulL9ze+3zyMxy2z8m7UHiLCbamSe6m7W",
    "mtls_cert": "-----BEGIN CERTIFICATE----- (...) -----END CERTIFICATE-----",
    "ip": "127.0.0.1",
    "port": 9002,
    "regcount": 1
  }
}
Response JSON Object

  • aik_tpm (string) – base64 encoded AIK. The AIK format is TPM2B_PUBLIC from tpm2-tss.

  • ek_tpm (string) – base64 encoded EK. When a ekcert is submitted it will be the public key of that certificate.

  • ekcert (string) – base64 encoded EK certificate. Should be in DER format. Gets extracted from NV 0x1c00002.

  • mtls_cert (string) – Agent HTTPS server certificate. PEM encoded.

  • ip (string) – IPv4 address for contacting the agent. Might be null.

  • port (integer) – Port for contacting the agent. Might be null.

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

Add agent agent_id to registrar.

Example request:

{
  "ekcert": "MIIEGTCCAoGgAwIBAgIBBTANBgkqhkiG9w0BAQsFADAYMRYwFAYDVQQDEw1zd3RwbS1sb2NhbGNhMB4XDTIxMDQwOTEyNDAyNVoXDTMxMDQwNzEyNDAyNVowODE2MDQGA1UEAxMtZmVkb3JhMzM6NDdjYzJlMDMtNmRmMi00OGMyLWFmNGUtMDg1MWY1MWQyODJiMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0YwlPPIoXryMvbD5cIokN9OkljL2mV1oDxy7ETBXBe1nL9OWrLNO8Nbf8EaSNCtYCo5iqCwatnVRMPqNXcX8mQP0f/gDAqXryb+F192IJLKShHYSN32LJjCYOKrvNX1lrmr377juICFSRClE4q+pCfzhNj0Izw/eplaAI7gq41vrlnymWYGIEi4McErWG7qwr7LR9CXwiM7nhBYGtvobqoaOm4+f6zo3jQuks/KYjk0BR3mgAec/Qkfefw2lgSSYaPNl/8ytg6Dhla1LK8f7wWy/bv+3z7L11KLr8DZiFAzKBMiIDfaqNGYPhiFLKAMJ0MmJx63obCqx9z5BltV5YQIDAQABo4HNMIHKMBAGA1UdJQQJMAcGBWeBBQgBMFIGA1UdEQEB/wRIMEakRDBCMRYwFAYFZ4EFAgEMC2lkOjAwMDAxMDE0MRAwDgYFZ4EFAgIMBXN3dHBtMRYwFAYFZ4EFAgMMC2lkOjIwMTkxMDIzMAwGA1UdEwEB/wQCMAAwIgYDVR0JBBswGTAXBgVngQUCEDEOMAwMAzIuMAIBAAICAKIwHwYDVR0jBBgwFoAUaO+9FEi5yX/GEnU+Vc6b3Si6JeAwDwYDVR0PAQH/BAUDAwcgADANBgkqhkiG9w0BAQsFAAOCAYEAaP/jI2i/hXDrthtaZypQ8VUG5AWFnMDtgiMhDSaKwOBfyxiUiYMTggGYXLOXGIu1SJGBtRJsh3QSYgs2tJCnntWF9Jcpmk6kIW/MC8shE+hdu/gQZKjAPZS4QCLIldv+GVZdNYEIv2FYDsKl6Bq1qUsYhAb7z29Nu1itpdvja2qy7ODJ0u+ThccBuH60VGFclFdJg19dvVQMnffxzjwxxJTMnVPmGoEdR94O0z7yxvqQ22+ITD9s1c3AfWcV+yLEpHqhXRqtKGdkAM5kU85kEs/ZPTLNutJHmF0/Vk9W2pRym8SrUe8G6mwxVW8lP9M7fhovKTzoXVFW3gQWQeUxhvWOncXxtARFLp/+f2mzGBRWxIslW17vpZ3QLlCdJ2C7P3U8x2tvkuyyDfz3/pq+8ECupZhdSvpHlBnWvqs1tAWKW0qI9d0xNYjj3Kfl3Lfy7kqqe6FIkvbDlVhw3vnJlclW+M6D86jBulL9ze+3zyMxy2z8m7UHiLCbamSe6m7W",
  "aik_tpm": "ARgAAQALAAUAcgAAABAAFAALCAAAAAAAAQCg5mMzNFqdlUbW8uI/GuMcIIvOXXTohHFTas59JlwrJQVed+5klWP+j7tI7492YPmCnoZvP4T4YdT1PN7tHHGfF81AeMnuw5GV5RkW/QeSD+ssB4f6AfuzYJgBkc28zKmpRRHUbwN4rb/HnJgRXdXsuIcnOqGcC39pD0kiu5TrN6hekjxTQtfAbIlQwwDwHCxKWdtH5x7avd15hqc6cBc2gjTQksXrk+OiMwOFTJ68n0qY+dQYuBTjE66YXn9S8cdU9sbjCTSdLRqFEpAyfkSV8F2An7N3DWNIA+PW/mVmd8XhPeYUoMlweXBOwc3e9zM9lZmMvregrFHKYc7CXChz",
  "mtls_cert": "-----BEGIN CERTIFICATE----- (...) -----END CERTIFICATE-----",
  "ip": "127.0.0.1",
  "port": "9002"
}
Request JSON Object

  • ekcert (string) – base64 encoded EK certificate. Should be in DER format. Gets extracted from NV 0x1c00002.

  • aik_tpm (string) – base64 encoded AIK. The AIK format is TPM2B_PUBLIC from tpm2-tss.

  • mtls_cert (string) – Agent HTTPS server certificate. PEM encoded.

  • ip (string) – (Optional) contact IPv4 address for the verifier and tenant to use.

  • port (string) – (Optional) contact port for the verifier and tenant to use.

Example response:

{
  "code": 200,
  "status": "Success",
  "results": {
    "blob": "utzA3gAAAAEARAAgC/w9LP1PKZ9thEk+GkMg4m+tkc9TkavcvFiFL6xbXM2q2fTRyKmQnxuCJc0tQdgsRXMftGiKJyA/SUo8kGNVmcNfAQCs79kl9Ir49JJ8rfyMfDIqOuSVlu9PhxGUOeVzAdxyUmPxq5Qp0s431n/KeL/5nUaVXC+qpOftF4bmVtXwLGTTUbKtyT3GG+9ujkjiwHCQhSKTQ8HiuARgXXh13ntFsJ75PBD5dWauLTuciYZI/WQDVXAcgMnQNxodJUi9ir1GxJWz8zufjVQTVjrlgsgeBdOKbB6+H81K1d9prWhZaVLP+wIwO3YuWgtNHNi90E1z/dah2pzfUpLvJo3lNZ4bJgrJUR507AokGKIFm7EfOf+5WWWAvGxGtgqTJB27vgE0CVBLEuDUHoRcLVBi1Np4GGNTByalxbulg8x1eGtZyuQF"
  }
}
Response JSON Object

  • blob (string) – base64 encoded blob containing the aik_tpm name and a challenge. Is encrypted with ek_tpm.

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

Remove agent agent_id from registrar.

Example response:

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

Activate physical agent agent_id

Example request:

{
  "auth_tag": "7087ba88746886262de743587ed97aea6b6e3f32755de5d85415c40feef3169bc58d38855ddb96e32efdd8745d0bdfef"
}
Request JSON Object

  • auth_tag (string) – hmac containing the challenge from blob and the agent_id.

PUT /v2.1/agents/{agent_id:UUID}/vactivate

Activate virtual (vTPM) agent agent_id

Requires JSON Body:

{
  "deepquote" : b64,
}

Changelog

Changes between the different API versions.

Changes from v2.0 to v2.1

API version 2.1 was first implemented in Keylime 6.4.0.

  • Added ak_tpm field to POST /v2.1/agents/{agent_id:UUID} in cloud verifier.

  • Added mtls_cert field to POST /v2.1/agents/{agent_id:UUID} in cloud verifier.

  • Removed vmask parameter from

This removed the requirement for the verifier to connect to the registrar.

Changes from v1.0 to v2.0

API version 2.0 was first implemented in Keylime 6.3.0.

  • Added mTLS authentication to agent endpoints.

  • Added supported_version field to POST /v2.0/agents/{agent_id:UUID} in cloud verifier.

  • Added mtls_cert field to POST/GET /v2.0/agents/{agent_id:UUID} in registrar.

  • Added /version endpoint to agent. Note that this endpoint is not implemented by all agents.

  • Dropped zlib encryption for quote field data in GET /v2.0/quotes/integrity/GET /v2.0/quotes/identity.