9. Appendix C: Key Capsules API, version 2.1.0 of cdoc2services API¶

openapi: 3.0.3
info:
contact:
    url: http://ria.ee
title: cdoc2-key-capsules
version: 2.1.0
description: API for exchanging CDOC2 ephemeral key material in key capsules
servers:
- url: 'https://localhost:8443'
    description: no auth (for creating key capsules). Regular TLS (no mutual TLS required).
- url: 'https://localhost:8444'
    description: mutual TLS authentication (for retrieving key capsules)

paths:
'/key-capsules/{transactionId}':
    get:
    summary: Get key capsule for transactionId
    description: Get key capsule for transactionId
    tags:
        - cdoc2-key-capsules
    parameters:
        - name: transactionId
        in: path
        schema:
            type: string
            minLength: 18
            maxLength: 34
        required: true
        description: transaction id from recipients.KeyServerCapsule.transaction_id (fbs)
    responses:
        '200':
        description: OK
        content:
            application/json:
            schema:
                $ref: '#/components/schemas/Capsule'
        headers:
            x-expiry-time:
            schema:
                type: string
                format: date-time
            description: Key capsule may be deleted by server after expiry time. Format rfc3339#section-5.6
        '400':
        description: 'Bad request. Client error.'
        '401':
        description: 'Unauthorized. Client certificate was not presented with the request.'
        '404':
        description: 'Not Found. 404 is also returned, when recipient id in record does not match with public key in client certificate.'
    operationId: getCapsuleByTransactionId
    security:
        - mutualTLS: []

/key-capsules:
    post:
    summary: Add Key Capsule
    description: Save Capsule and generate transaction id using secure random. Generated transactionId is returned in Location header
    operationId: createCapsule
    parameters:
        - schema:
            type: string
            format: date-time
        in: header
        name: x-expiry-time
        description: Key capsule may be deleted by server after expiry time. Format rfc3339#section-5.6
        required: false
    requestBody:
        required: true
        content:
        application/json:
            schema:
            $ref: '#/components/schemas/Capsule'
    responses:
        '201':
        description: Created
        headers:
            Location:
            schema:
                type: string
                example: /key-capsules/KC0123456789ABCDEF
            description: 'URI of created resource. TransactionId can be extracted from URI as it follows pattern /key-capsules/{transactionId}'
        '400':
        description: Bad request. Client error.
    security: []
    tags:
        - cdoc2-key-capsules

components:
schemas:
    Capsule:
    title: Capsule
    type: object
    properties:
        recipient_id:
        type: string
        format: byte
        minLength: 97 # EC public key
        maxLength: 2100 # 16 K RSA public key = 2086 bytes
        description: 'Binary format is defined by capsule_type'
        ephemeral_key_material:
        type: string
        format: byte
        maxLength: 2100
        description: 'Binary format is defined by capsule_type'
        capsule_type:
        type: string
        enum:
            - ecc_secp384r1
            - rsa
        description: |
            Depending on capsule type, Capsule fields have the following contents:
            - ecc_secp384r1:
                * recipient_id is EC pub key with secp384r1 curve in TLS format (0x04 + X coord 48 bytes + Y coord 48 bytes) (https://www.rfc-editor.org/rfc/rfc8446#section-4.2.8.2)
                * ephemeral_key_material contains sender public EC key (generated) in TLS format.
            - rsa:
                * recipient_id is DER encoded RSA recipient public key - RsaPublicKey encoding [RFC8017 RSA Public Key Syntax A.1.1](https://www.rfc-editor.org/rfc/rfc8017#page-54)
                * ephemeral_key_material contains KEK encrypted with recipient public RSA key
    required:
        - recipient_id
        - ephemeral_key_material
        - capsule_type
securitySchemes:
    mutualTLS:
    # since mutualTLS is not supported by OAS 3.0.x, then define it as http basic auth. MutualTLS must be implemented
    # manually anyway
    #type: mutualTLS
    type: http
    scheme: basic
tags:
- name: cdoc2-key-capsules