Feranor Keys API

openapi: 3.2.0
info:
  title: Feranor PQC Sidecar Keys API
  version: '1'
  summary: Post-quantum encryption and signature over HTTP, for applications in any language.
  description: 'The API of the Feranor PQC sidecar, version 1. Content goes in and out as raw bodies; messages are CMS (RFC 5652) in binary form, with the media types of RFC 8551; errors are problem details (RFC 9457) with a stable code. In JSON answers, members without a value are left out. The sidecar listens on a Unix socket by default (no server URL applies: send any Host, for example http://localhost), or on a loopback TCP port with an access token. The two alternatives of the security requirement are the two transports: the empty one, {}, is the Unix socket, where the socket''s file permissions decide who may call; on TCP the access token is required, and a request without it is answered 401. Every route, query parameter, header, media type, problem code and JSON member here is checked against the sidecar by its tests. The guide''s sidecar chapter tells how to deploy it.'
servers:
- url: http://localhost
  description: The Unix socket (Sidecar:UnixSocket, the default) or the TCP port (Sidecar:Port).
security:
- {}
- accessToken: []
tags:
- name: Keys
  description: The public half of the key store, for senders and verifiers.
paths:
  /v1/recipient:
    get:
      operationId: getRecipient
      tags:
      - Keys
      summary: What senders encrypt to
      description: 'The current encryption key''s certificate, or its public key when it has none, in PEM (RFC 7468). The key is first opened with the store''s secret: a key the store does not hold is never published.'
      responses:
        '200':
          description: The certificate or the public key, in PEM.
          headers:
            Feranor-License:
              $ref: '#/components/headers/Feranor-License'
          content:
            application/x-pem-file:
              schema:
                type: string
        '404':
          $ref: '#/components/responses/NoSuchKey'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v1/signer:
    get:
      operationId: getSigner
      tags:
      - Keys
      summary: What verifiers trust
      description: The current post-quantum signing certificate, in PEM, once its key opens with the store's secret.
      responses:
        '200':
          description: The certificate, in PEM.
          headers:
            Feranor-License:
              $ref: '#/components/headers/Feranor-License'
          content:
            application/x-pem-file:
              schema:
                type: string
        '404':
          $ref: '#/components/responses/NoSuchKey'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v1/co-signer:
    get:
      operationId: getCoSigner
      tags:
      - Keys
      summary: What verifiers of hybrid signatures trust too
      description: The current classical (ECDSA) co-signing certificate, in PEM, once its key opens with the store's secret; 404 when the store has none, signatures being post-quantum alone.
      responses:
        '200':
          description: The certificate, in PEM.
          headers:
            Feranor-License:
              $ref: '#/components/headers/Feranor-License'
          content:
            application/x-pem-file:
              schema:
                type: string
        '404':
          $ref: '#/components/responses/NoSuchKey'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  responses:
    NoSuchKey:
      description: 'invalid-request: the key store has no such key.'
      headers:
        Feranor-License:
          $ref: '#/components/headers/Feranor-License'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    ServiceUnavailable:
      description: 'key-store-unavailable: no key store, no signing key with a certificate (nor a co-signing key when Sidecar:HybridSignature is Required), or a store that can no longer be opened after the start, the cause being in the logs (a store that fails its checks at the start stops the sidecar instead); audit-journal-unavailable: the audit journal cannot be written, and every operation but inspect is refused until the sidecar restarts.'
      headers:
        Feranor-License:
          $ref: '#/components/headers/Feranor-License'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Forbidden:
      description: A request with an Origin header (from a web page), or /v1/operations and /v1/logs without the administration token. No code.
      headers:
        Feranor-License:
          $ref: '#/components/headers/Feranor-License'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Unauthorized:
      description: The access token is missing or wrong (TCP with Sidecar:AccessTokenFile).
      headers:
        WWW-Authenticate:
          schema:
            type: string
            const: Bearer
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  headers:
    Feranor-License:
      description: 'The state of the sidecar''s license key, on every answer under /v1/, errors included, but the refusals that come before it (Origin, Host, access token). The details are in GET /v1/version. It changes nothing in the answer: the sidecar works whatever the license.'
      schema:
        type: string
        enum:
        - valid
        - missing
        - invalid
        - expired
        - not-verifiable
  schemas:
    ProblemCode:
      type: string
      description: The stable error codes of the API.
      enum:
      - invalid-request
      - invalid-input
      - payload-too-large
      - recipient-not-found
      - authentication-failed
      - signature-invalid
      - signature-required
      - algorithm-not-allowed
      - key-store-unavailable
      - audit-journal-unavailable
    Problem:
      type: object
      description: Problem details (RFC 9457). The errors of the API carry code; the refusals before the API (Origin, Host, tokens, concurrency) and the framework's own (404, 405) do not.
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
        traceId:
          type: string
        code:
          $ref: '#/components/schemas/ProblemCode'
  securitySchemes:
    accessToken:
      type: http
      scheme: bearer
      description: 'The access token of Sidecar:AccessTokenFile, on TCP: sent with every request but the health checks, in exactly one Authorization header, and compared in constant time. Any address beyond loopback needs it. On the Unix socket, the default, the socket''s file permissions decide who may call, and no token is sent.'
    administrationToken:
      type: apiKey
      in: header
      name: Feranor-Administration-Token
      description: The administration token of Sidecar:AdministrationTokenFile, for /v1/operations and /v1/logs only. It differs from the access token, which is sent too on TCP.