Rest API’s¶
All Keylime APIs use REST (Representational State Transfer).
Authentication¶
Most API interactions are secured using mTLS connections. There are up to three different CAs involved. (The revocation process also uses a CA, but this is a different to those CAs)
Verifier CA (CV CA)¶
This CA is used by the verifier to authenticate connections to it. The tenant requires a certificate from this CA to add/delete/list agents at the CV.
Registrar CA¶
This CA is used by the registrar to authenticate connections to it. The tenant and the verifier require certificate from this CA to get or delete agent information from the registrar. By default it is the same CA as the CV CA.
Note that the API endpoints from the registrar for the agent are unprotected by design.
Agent Keylime CA¶
The agent runs a HTTPS server and provides it’s certificate to the registrar (mtls_cert). All connections done to the agent are verified against the CA specified in the keylime_ca option. This ensures that only trusted systems can interact with the agents. By default the CV CA is used, but the CA certificate (cacert.crt) needs to be copied to the agents.
Registrar, tenant and verifier can configure this CA separately using the agent_mtls_* options.
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": "{}", "allowlist_len": 0, "mb_refstate_len": 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.
allowlist_len (int) – Length of the allowlist.
mb_refstate_len (int) – Length of the measured boot reference state policy.
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\"}", "allowlist": "{}", "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.
allowlist (string) – Allowlist JSON object string encoded.
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.
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.