kbs.yaml

openapi: 3.1.0
info:
  title: Key Broker Service (KBS) API
  description: HTTP based API for describing the communication between a Key
               Broker Client (KBC) in a confidential guest and a trusted Key
               Broker Service.
  version: 0.1.0
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html

servers:
- url: http://<kbs>/kbs/v0

paths:
  /auth:
    post:
      operationId: attestationAuth
      summary: Initiate an attestation authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'

      responses:
        200:
          description: >-
            The KBS attestation challenge.
            The KBS session ID is returned in a cookie named `kbs-session-id`.
          headers:
            Set-Cookie:
              schema:
                type: string
                example: kbs-session-id=1234
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Challenge'
        400:
          description: The request content or format is not supported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInformation'
  /attest:
    post:
      operationId: attestationEvidence
      summary: Send an attestation evidence and receive an attestation results token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Attestation'

      parameters:
        - in: cookie
          name: kbs-session-id
          schema:
            type: string

      responses:
        200:
          description: The attestation evidence is authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttestationToken'
        401:
          description: Missing or invalid session ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInformation'

  /attestation-policy:
    post:
      operationId: setAttestationPolicy
      summary: Set attestation verification policy
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttestationPolicy'
  
  /resource-policy:
    post:
      operationId: setResourcePolicy
      summary: Set resource distribution policy
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResourcePolicy'

  /resource/{repository}/{type}/{tag}:
    get:
      operationId: getResource
      summary: Get a secret resource from the Key Broker Service.
      parameters:
        - in: cookie
          name: kbs-session-id
          schema:
            type: string
          required: false
        - name: repository
          in: path
          description: A parent path of resource, can be empty to use the default repository.
          schema:
            type: string
          required: false
        - name: type
          in: path
          description: Resource type name
          schema:
            type: string
          required: true
        - name: tag
          in: path
          description: Resource instance tag
          schema:
            type: string
          required: true
      responses:
        200:
          description: >-
            The KBS reponse including the resource.
            The KBS session ID is returned in a cookie named `kbs-session-id`.
          headers:
            Set-Cookie:
              schema:
                type: string
                example: kbs-session-id=1234
          content:
            application/jwe:
              schema:
                $ref: '#/components/schemas/Response'
        401:
          description: Missing or invalid session ID
        403:
          description: The KBC is not allowed to get that resource
        404:
          description: The requested resource does not exist
    post:
      operationId: registerSecretResource
      summary: Register a secret resource into the Key Broker Service.
      requestBody:
        required: true
        content: '*'
      parameters:
        - name: repository
          in: path
          description: A parent path of resource, can be empty to use the default repository.
          schema:
            type: string
          required: false
        - name: type
          in: path
          description: Resource type name
          schema:
            type: string
          required: true
        - name: tag
          in: path
          description: Resource instance tag
          schema:
            type: string
          required: true


components:
  schemas:

    Request:
      required:
        - version
        - tee
      type: object
      properties:
        version:
          type: string
        tee:
          type: string
          enum: [amd-sev, intel-sgx, intel-tdx]
        extra-params:
          description: >-
            Freely formatted JSON object used for HW-TEE specific attestation
            processes.
          type: object
      description: KBC attestation authentication request

    Challenge:
      required:
        - nonce
      type: object
      properties:
        nonce:
          type: string
        extra-params:
          description:
            Freely formatted JSON object used for HW-TEE specific attestation
            processes.
          type: object
      description:
        KBS attestation challenge, sent in response to the KBC Request.

    Attestation:
      required:
        - tee-pubkey
        - tee-evidence
      type: object
      properties:
        tee-pubkey:
          $ref: '#/components/schemas/PublicKey'
        tee-evidence:
          description: HW-TEE specific attestation evidence.
          type: object
      description: >-
        KBS attestation challenge, sent in response to the KBC Request.

    Response:
      required:
        - protected
        - encrypted_key
        - iv
        - ciphertext
      type: object
      properties:
        protected:
          description: A Base64-url encoding of '#/components/schemas/KeyHeader'
          type: string
        ciphertext:
          type: string
          description: A Base64-url encoding of the encrypted reponse data.
        encrypted_key:
          type: string
          description: >-
            A Base64-url encoding of the encrypted key used for encrypting the
            response data.
        iv:
          type: string
          description: >-
            A Base64-url encoding of the encryption algorithm initialisation
            vector.
        tag:
          type: string
      description: >-
        A JSON Web Encryption (https://www.rfc-editor.org/rfc/rfc7516)
        formatted object.

    KeyHeader:
      required:
        - alg
        - enc
      properties:
        alg:
          type: string
          description: The signature algorithm
        enc:
          type: string
          description: >-
            Encryption algorithm used to encrypt the response payload.

    AttestationPolicy:
      required:
        - type
        - policy_id
        - policy
      properties:
        type:
          type: string
          description: >-
            Policy Engine type, for example: "opa"
        policy_id:
          type: string
          description: >-
            ID used to identify the policy, use "default" to set default policy
        policy:
          type: string
          description: >-
            Base64 encoded attestation verification policy.

    ResourcePolicy:
      required:
        - policy
      properties:
        policy:
          type: string
          description: >-
            Base64 encoded resource distribution policy.

    AttestationToken:
      required:
        - token
      type: object
      properties:
        token:
          type: string
          description: >-
            A serialized JSON Web Token (https://jwt.io).
            The token value is a string, which is made of 3 strings, separated
            by dots.
            The first string is a Base64-url encoding of
            '#/components/schemas/AttestationTokenHeader'.
            The second string is a Base64-url encoding of
            '#/components/schemas/AttestationTokenPayload'.
            The third string is a Base64-url encoding of the token signature.

    AttestationTokenHeader:
      required:
        - typ
        - alg
      properties:
        typ:
          enum: [JWT]
          type: string
          description: The JWS header type. This must be `JWT`.
        alg:
          type: string
          description: The signature algorithm

    AttestationTokenPayload:
      required:
        - ext
        - iat
        - iss
        - jwk
        - tee-pubkey
        - tcb-status
        - evaluation-report
      properties:
        ext:
          type: integer
          description: The token expiration date, in seconds since the Epoch.
        iat:
          type: integer
          description: The token issuing time, in seconds since the Epoch.
        iss:
          type: string
          description: The token issuer URL.
        jwk:
          type: string
          description: >-
            A JSON Web Key (https://www.rfc-editor.org/rfc/rfc7517) formatted RSA Public Key for token signature verification.
        tee-pubkey:
          $ref: '#/components/schemas/PublicKey'
        tcb-status:
          type: string
          description: Parsed claims from TEE evidence.
        evaluation-report:
          type: string
          description: Evaluation report of TEE evidence.

    PublicKey:
      required:
        - kty
        - alg
        - n
        - e
      properties:
        kty:
          type: stinrg
          description: Key Type
        alg:
          type: string
          description: Key Algorithm
        n:
          type: string
          description: Key modulus
        e:
          type: string
          description: Key exponent
      description: >-
        A JSON Web Key (https://www.rfc-editor.org/rfc/rfc7517) formatted RSA Public Key.

    ErrorInformation:
      required:
        - type
        - detail
      properties:
        type:
          description: >-
            https://github.com/confidential-containers/kbs/errors/<problem-type>
          type: string
        detail:
          type: string
      description: >-
        A Problem Details for HTTP APIs (https://www.rfc-editor.org/rfc/rfc7807)
        formatted payload.