Feranor Administration API

openapi: 3.2.0
info:
  title: Feranor PQC Sidecar Administration 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: Administration
  description: Version, operations and logs, for the console and the administrator.
paths:
  /v1/version:
    get:
      operationId: getVersion
      tags:
      - Administration
      summary: Product, version, profile, platform and license
      description: For clients that show them, such as the console. The license key is checked at each call; its state never changes what the sidecar does.
      responses:
        '200':
          description: The version report.
          headers:
            Feranor-License:
              $ref: '#/components/headers/Feranor-License'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionReport'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v1/operations:
    get:
      operationId: getOperations
      tags:
      - Administration
      summary: The last operations
      description: The last cryptographic operations (a POST to a route of /v1), most recent first, from memory, emptied by a restart. Nothing about the content. Needs the administration token; without the Sidecar:AdministrationTokenFile setting, the answer is 403. The audit journal keeps the same operations on disk, chained.
      security:
      - administrationToken: []
      - administrationToken: []
        accessToken: []
      parameters:
      - name: limit
        in: query
        required: false
        description: How many operations, at most. Brought within 1 and the capacity.
        schema:
          type: integer
          format: int32
          default: 200
      responses:
        '200':
          description: The operations.
          headers:
            Feranor-License:
              $ref: '#/components/headers/Feranor-License'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationsReport'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v1/logs:
    get:
      operationId: getLogs
      tags:
      - Administration
      summary: The last log entries
      description: 'The last log entries at level or above, most recent first, from memory, emptied by a restart: the events of the container''s output and of the telemetry, kept from Information up whatever the output''s level (from Warning up for the framework''s own categories). Needs the administration token, as /v1/operations.'
      security:
      - administrationToken: []
      - administrationToken: []
        accessToken: []
      parameters:
      - name: limit
        in: query
        required: false
        description: How many entries, at most. Brought within 1 and the capacity.
        schema:
          type: integer
          format: int32
          default: 200
      - name: level
        in: query
        required: false
        description: The lowest level returned, case ignored. Any other value is refused with invalid-request.
        schema:
          type: string
          enum:
          - Information
          - Warning
          - Error
          - Critical
          default: Information
      responses:
        '200':
          description: The log entries.
          headers:
            Feranor-License:
              $ref: '#/components/headers/Feranor-License'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogsReport'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  schemas:
    OperationRecord:
      type: object
      additionalProperties: false
      required:
      - at
      - operation
      - status
      - aborted
      - durationMs
      properties:
        at:
          type: string
          format: date-time
          description: When the operation was answered.
        operation:
          type: string
          enum:
          - encrypt
          - decrypt
          - sign
          - verify
          - inspect
        flags:
          type: string
          description: The query flags set to true (sign, requireSignature, detached), separated by commas.
        status:
          type: integer
          format: int32
          description: What the client got; 499 when the client went away.
        code:
          $ref: '#/components/schemas/ProblemCode'
        aborted:
          type: boolean
          description: true for an answer cut short after it had started.
        inputSize:
          type: integer
          format: int64
          description: The size the request announced.
        durationMs:
          type: number
          format: double
        signer:
          type: string
          description: As Feranor-Signer reported it.
        signatureAlgorithm:
          type: string
          description: As Feranor-Signature-Algorithm reported it.
        hybrid:
          type: string
          enum:
          - 'true'
          - 'false'
          description: As Feranor-Hybrid reported it.
        signed:
          type: string
          enum:
          - 'true'
          - 'false'
          description: As Feranor-Signed reported it.
    OperationsReport:
      type: object
      additionalProperties: false
      required:
      - capacity
      - operations
      properties:
        capacity:
          type: integer
          format: int32
          description: How many operations are kept in memory (1000).
        operations:
          type: array
          items:
            $ref: '#/components/schemas/OperationRecord'
    LogsReport:
      type: object
      additionalProperties: false
      required:
      - capacity
      - logs
      properties:
        capacity:
          type: integer
          format: int32
          description: How many entries are kept in memory (2000).
        logs:
          type: array
          items:
            $ref: '#/components/schemas/LogRecord'
    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
    VersionReport:
      type: object
      additionalProperties: false
      required:
      - product
      - version
      - profile
      - platform
      - deployment
      - license
      properties:
        product:
          type: string
          const: Feranor PQC Sidecar
        version:
          type: string
          description: 1.0.0+<commit> for a release.
        profile:
          type: string
          examples:
          - ANSSI
          - Standard
        platform:
          type: string
          description: .NET, the operating system and OpenSSL, as fpqc info prints them.
        deployment:
          type: string
          enum:
          - Default
          - Regulated
        license:
          $ref: '#/components/schemas/LicenseReport'
    LicenseReport:
      type: object
      additionalProperties: false
      required:
      - status
      - expiresSoon
      properties:
        status:
          type: string
          enum:
          - Valid
          - Missing
          - Invalid
          - Expired
          - NotVerifiable
        message:
          type: string
        licenseId:
          type: string
        licensee:
          type: string
        edition:
          type: string
        expiresOn:
          type: string
          format: date
        expiresSoon:
          type: boolean
        daysLeft:
          type: integer
          format: int32
    LogRecord:
      type: object
      additionalProperties: false
      required:
      - at
      - level
      - category
      properties:
        at:
          type: string
          format: date-time
        level:
          type: string
          enum:
          - Information
          - Warning
          - Error
          - Critical
        category:
          type: string
        eventId:
          type: integer
          format: int32
        eventName:
          type: string
        message:
          type: string
        exceptionType:
          type: string
          description: An exception's type, never its message, which may hold a server path.
    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'
  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
  responses:
    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'
    BadRequest:
      description: 'invalid-request: a missing or malformed header, part or parameter, a query parameter the operation does not take, an empty body to sign, or a message sent to the wrong operation; invalid-input: not a valid message, key or certificate. On TCP, a Host header that is neither localhost, an IP address nor a name of Sidecar:AllowedHosts is refused too, without a 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'
  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.