==========
Rest API's
==========
All Keylime APIs use `REST (Representational State Transfer)`.

Check the :ref:`Changelog` section for the differences between versions

.. toctree::
   :maxdepth: 2
   :caption: API versions

   rest_apis/2_1/2_1.rst
   rest_apis/2_2/2_2.rst
   rest_apis/2_3/2_3.rst
   rest_apis/2_4/2_4.rst
   rest_apis/2_5/2_5.rst
   rest_apis/3_0/3_0.rst

Changelog
_________

Changes from v2.5 to v3.0
~~~~~~~~~~~~~~~~~~~~~~~~~

API version 3.0 introduces push-model attestation. Unlike previous versions where
the verifier polls agents, in v3.0 agents initiate connections and submit
attestation evidence to the verifier. The v3.0 endpoints are served by the
verifier only; the push-model agent does not expose HTTP endpoints.

* Added `POST /v3/agents/{agent_id}/attestations` endpoint to the verifier:
    * Allows agents to submit attestation capabilities (Phase 1 of push protocol)
    * Returns challenge nonce for TPM quote generation
* Added `PATCH /v3/agents/{agent_id}/attestations/latest` endpoint:
    * Allows agents to submit attestation evidence (Phase 2 of push protocol)
    * Returns `202 Accepted` for asynchronous verification
* Added `PATCH /v3/agents/{agent_id}/attestations/{index}` endpoint:
    * Submit evidence for a specific attestation by index
* Added `GET /v3/agents/{agent_id}/attestations` endpoint:
    * Lists all attestation records for an agent
* Added `GET /v3/agents/{agent_id}/attestations/latest` endpoint:
    * Returns the most recent attestation for an agent, including verification status
* Added `GET /v3/agents/{agent_id}/attestations/{index}` endpoint:
    * Returns a specific attestation by its index
* Added `POST /v3/sessions` endpoint:
    * Creates a PoP authentication session and returns a challenge nonce for the agent
* Added `PATCH /v3/sessions/{session_id}` endpoint:
    * Completes PoP authentication by submitting the TPM-signed challenge response
* Introduced PoP (Proof of Possession) bearer token authentication for
  agent-to-verifier communication

API version 3.0 also introduces RFC 9110-compliant registrar routes:

* Added ``GET /v3.0/`` version root probe endpoint to the registrar, allowing
  clients to check whether the server supports API version 3.0.
* Agent registration now uses ``POST /v3.0/agents/`` (collection-level endpoint).
  The ``agent_id`` is sent in the JSON request body instead of the URL path.
* Agent activation now uses ``POST /v3.0/agents/{agent_id}/activate`` instead of
  ``PUT``, following correct HTTP method semantics.
* Removed legacy backwards-compatibility routes from the registrar:
    * ``POST /agents/{agent_id}`` (use ``POST /agents/`` instead)
    * ``PUT /agents/{agent_id}/activate`` (use ``POST /agents/{agent_id}/activate``)
    * ``PUT /agents/{agent_id}`` (use ``POST /agents/{agent_id}/activate``)

Changes from v2.4 to v2.5
~~~~~~~~~~~~~~~~~~~~~~~~~
API version 2.5 was first implemented in Keylime 7.14.0.

* Modified `POST /v2.5/verify/evidence` endpoint:
    * Changed `valid` response field from integer (1/0) to boolean (true/false)
    * Added `claims` field to response containing verified claims
    * Added TEE (Trusted Execution Environment) verification support
* Modified `GET /v2.5/quotes/integrity` endpoint:
    * `enc_alg` field in agent responses were modified to return explicit
      bit-length formats (e.g., ``rsa2048``, ``rsa3072``, ``ecc256``,
      ``ecc384``)
* Server-side automatic normalization ensures backward compatibility:
    * ``rsa`` → ``rsa2048``
    * ``ecc`` → ``ecc256``
* Enhanced `GET /version` endpoint to support API version negotiation:
    * Added `supported_versions` field containing an array of all API versions
      the agent supports
    * Retained `supported_version` field for backward compatibility (contains
      latest version)
    * Tenant and verifier now negotiate to use the highest mutually supported
      API version instead of blindly using the agent's latest version
    * Prevents compatibility issues when newer agents communicate with older
      tenants/verifiers
* Added attestation monitoring fields to `GET /v2.5/agents/{agent_id}` response:
    * `attestation_status`: Current attestation status (``"PASS"``, ``"FAIL"``, or ``"PENDING"``)
    * `attestation_period`: Configured attestation interval derived from ``quote_interval``
    * `maximum_attestation_interval`: Maximum time allowed between attestations in PUSH mode

Changes from v2.3 to v2.4
~~~~~~~~~~~~~~~~~~~~~~~~~
API version 2.4 was first implemented in Keylime 7.13.0.

* Added `POST /v2.4/verify/evidence` experimental endpoint to the verifier:
    * Allows 3rd party verification of TPM attestation evidence (quotes, IMA logs, measured boot) against policies
    * Returns `valid` field (integer: 1 for valid, 0 for invalid) and `failures` array with validation errors

Changes from v2.2 to v2.3
~~~~~~~~~~~~~~~~~~~~~~~~~
API version 2.3 was first implemented in Keylime 7.12.0.

* Added `GET /v2.3/mbpolicies/{name}` endpoint to the verifier
* Added `POST /v2.3/mbpolicies/{name}` endpoint to the verifier
* Added `PUT /v2.3/mbpolicies/{name}` endpoint to the verifier
* Added `DELETE /v2.3/mbpolicies/{name}` endpoint to the verifier
* Added `GET /version` endpoint to the registrar

Changes from v2.1 to v2.2
~~~~~~~~~~~~~~~~~~~~~~~~~
API version 2.2 was first implemented in Keylime 7.11.0.

* Added `GET /v2.2/verify/identity` endpoint to the verifier
* Added `GET /v2.2/agent/info` endpoint to the agent

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 verifier.
 * Added `mtls_cert` field to `POST /v2.1/agents/{agent_id:UUID}` in verifier.
 * Removed `vmask` parameter from `GET /v2.1/quotes/integrity` in agent

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

RESTful API for Keylime
-----------------------
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
~~~~~~~~~~~~~~~~~~~

.. http:any:: /

    Generic fields in responses

    :>json int code: HTTP status code
    :>json string status: textual context of that status
    :>json object results: Holds the actual data.

