Feranor Operations API

openapi: 3.2.0
info:
  title: Feranor PQC Sidecar Operations 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: Operations
  description: 'Encryption, decryption, signature, verification and inspection: each is recorded in the audit journal when one is configured.'
paths:
  /v1/encrypt:
    post:
      operationId: encrypt
      tags:
      - Operations
      summary: Encrypt content for one or more recipients
      description: Encrypts the body, of any size, as an AuthEnvelopedData (RFC 5083) for the recipients of the Feranor-Recipient headers. The message is written to a temporary file and sent once the whole request is read; only ciphertext touches the disk. With sign=true, the content is signed first with the current signing key, in memory within Sidecar:MaxInMemorySize, and co-signed with the classical key as Sidecar:HybridSignature says.
      parameters:
      - name: sign
        in: query
        required: false
        description: Sign the content before encrypting it. Absent means false; any other value than true or false is refused with invalid-request.
        schema:
          type: boolean
          default: false
      - $ref: '#/components/parameters/Feranor-Recipient'
      requestBody:
        required: true
        description: The content. Any Content-Type is accepted; the body is read as bytes.
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
              contentMediaType: application/octet-stream
      responses:
        '200':
          description: The encrypted message, CMS in binary form (DER, or BER for large content).
          headers:
            Feranor-License:
              $ref: '#/components/headers/Feranor-License'
          content:
            application/pkcs7-mime; smime-type=authEnveloped-data:
              schema:
                type: string
                format: binary
                contentMediaType: application/pkcs7-mime
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v1/decrypt:
    post:
      operationId: decrypt
      tags:
      - Operations
      summary: Decrypt a message with the key store
      description: 'Decrypts an AuthEnvelopedData of any size with the sidecar''s key store. A signed message is verified too, in memory within Sidecar:MaxInMemorySize, and its signer reported in the Feranor-Signer headers. A message that is not encrypted, or a classical one (an EnvelopedData, or RSA or ECDH recipients), is refused with invalid-request: fpqc reencrypt brings a classical message to post-quantum cryptography. An unsigned message proves nothing about its sender: use requireSignature=true, or the Sidecar:RequireSignature setting, where a signature is expected.'
      parameters:
      - name: requireSignature
        in: query
        required: false
        description: Refuse an unsigned message with signature-required (422). The Sidecar:RequireSignature setting does the same for every request. Absent means false; any other value than true or false is refused with invalid-request.
        schema:
          type: boolean
          default: false
      requestBody:
        required: true
        description: An AuthEnvelopedData, as encrypt answers it. Any Content-Type is accepted.
        content:
          application/pkcs7-mime; smime-type=authEnveloped-data:
            schema:
              type: string
              format: binary
              contentMediaType: application/pkcs7-mime
          application/octet-stream:
            schema:
              type: string
              format: binary
              contentMediaType: application/octet-stream
      responses:
        '200':
          description: The decrypted content. Feranor-Signed is false for an unsigned message; for a signed one, the signer headers describe the verified signer.
          headers:
            Feranor-License:
              $ref: '#/components/headers/Feranor-License'
            Feranor-Signed:
              $ref: '#/components/headers/Feranor-Signed'
            Feranor-Signer:
              $ref: '#/components/headers/Feranor-Signer'
            Feranor-Signer-Thumbprint:
              $ref: '#/components/headers/Feranor-Signer-Thumbprint'
            Feranor-Signature-Algorithm:
              $ref: '#/components/headers/Feranor-Signature-Algorithm'
            Feranor-Hybrid:
              $ref: '#/components/headers/Feranor-Hybrid'
            Feranor-Co-Signer:
              $ref: '#/components/headers/Feranor-Co-Signer'
            Feranor-Co-Signature-Algorithm:
              $ref: '#/components/headers/Feranor-Co-Signature-Algorithm'
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
                contentMediaType: application/octet-stream
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v1/sign:
    post:
      operationId: sign
      tags:
      - Operations
      summary: Sign content
      description: Signs the body with the current post-quantum signing key, co-signed with the classical key as Sidecar:HybridSignature says. By default the content goes inside the SignedData, in memory within Sidecar:MaxInMemorySize. With detached=true, the body is read as a stream, of any size, and the answer is the signature alone, once the whole body is read.
      parameters:
      - name: detached
        in: query
        required: false
        description: Answer with a detached signature (application/pkcs7-signature) rather than a SignedData holding the content. Absent means false; any other value than true or false is refused with invalid-request.
        schema:
          type: boolean
          default: false
      requestBody:
        required: true
        description: The content. Any Content-Type is accepted.
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
              contentMediaType: application/octet-stream
      responses:
        '200':
          description: A SignedData holding the content, or with detached=true the detached signature.
          headers:
            Feranor-License:
              $ref: '#/components/headers/Feranor-License'
          content:
            application/pkcs7-mime; smime-type=signed-data:
              schema:
                type: string
                format: binary
                contentMediaType: application/pkcs7-mime
            application/pkcs7-signature:
              schema:
                type: string
                format: binary
                contentMediaType: application/pkcs7-signature
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v1/verify:
    post:
      operationId: verify
      tags:
      - Operations
      summary: Verify a signature
      description: Verifies a SignedData against the sidecar's trust settings (Sidecar:TrustedCertificates, Sidecar:Revocation, Sidecar:RequireHybridSignature and the others). Either the body is a SignedData holding its content, answered with the content; or the body is multipart/form-data (RFC 7578) with one signature part and one content part, answered with 204. The content part is verified as a stream, of any size, when it follows the signature part; before it, it is read in memory within Sidecar:MaxInMemorySize. The signer is reported in the Feranor-Signer headers.
      requestBody:
        required: true
        description: A SignedData holding its content (any Content-Type but multipart/form-data), or the detached signature and its content as multipart/form-data.
        content:
          application/pkcs7-mime; smime-type=signed-data:
            schema:
              type: string
              format: binary
              contentMediaType: application/pkcs7-mime
          application/octet-stream:
            schema:
              type: string
              format: binary
              contentMediaType: application/octet-stream
          multipart/form-data:
            schema:
              type: object
              required:
              - signature
              - content
              properties:
                signature:
                  type: string
                  format: binary
                  contentMediaType: application/pkcs7-signature
                  description: The detached signature. Put it first, so that the content is verified as a stream.
                content:
                  type: string
                  format: binary
                  contentMediaType: application/octet-stream
                  description: The signed content.
            encoding:
              signature:
                contentType: application/pkcs7-signature
              content:
                contentType: application/octet-stream
      responses:
        '200':
          description: 'The signature is valid: the signed content, for a SignedData body.'
          headers:
            Feranor-License:
              $ref: '#/components/headers/Feranor-License'
            Feranor-Signed:
              $ref: '#/components/headers/Feranor-Signed'
            Feranor-Signer:
              $ref: '#/components/headers/Feranor-Signer'
            Feranor-Signer-Thumbprint:
              $ref: '#/components/headers/Feranor-Signer-Thumbprint'
            Feranor-Signature-Algorithm:
              $ref: '#/components/headers/Feranor-Signature-Algorithm'
            Feranor-Hybrid:
              $ref: '#/components/headers/Feranor-Hybrid'
            Feranor-Co-Signer:
              $ref: '#/components/headers/Feranor-Co-Signer'
            Feranor-Co-Signature-Algorithm:
              $ref: '#/components/headers/Feranor-Co-Signature-Algorithm'
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
                contentMediaType: application/octet-stream
        '204':
          description: The signature is valid, for a multipart body.
          headers:
            Feranor-License:
              $ref: '#/components/headers/Feranor-License'
            Feranor-Signed:
              $ref: '#/components/headers/Feranor-Signed'
            Feranor-Signer:
              $ref: '#/components/headers/Feranor-Signer'
            Feranor-Signer-Thumbprint:
              $ref: '#/components/headers/Feranor-Signer-Thumbprint'
            Feranor-Signature-Algorithm:
              $ref: '#/components/headers/Feranor-Signature-Algorithm'
            Feranor-Hybrid:
              $ref: '#/components/headers/Feranor-Hybrid'
            Feranor-Co-Signer:
              $ref: '#/components/headers/Feranor-Co-Signer'
            Feranor-Co-Signature-Algorithm:
              $ref: '#/components/headers/Feranor-Co-Signature-Algorithm'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v1/inspect:
    post:
      operationId: inspect
      tags:
      - Operations
      summary: Describe a message without any key
      description: 'Reads a message without any key and verifies nothing: its type, algorithms (as OIDs), recipients or signers, and sizes read from the encoding. An encrypted message of any size is read as a stream; a SignedData is read in memory within Sidecar:MaxInMemorySize. The whole body is read before the answer, a refused one included. Served even while the audit journal cannot be written.'
      requestBody:
        required: true
        description: 'A CMS message: AuthEnvelopedData, SignedData or a classical EnvelopedData. Any Content-Type is accepted.'
        content:
          application/pkcs7-mime:
            schema:
              type: string
              format: binary
              contentMediaType: application/pkcs7-mime
          application/octet-stream:
            schema:
              type: string
              format: binary
              contentMediaType: application/octet-stream
      responses:
        '200':
          description: What the message is. Nothing in it is verified.
          headers:
            Feranor-License:
              $ref: '#/components/headers/Feranor-License'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InspectionReport'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  headers:
    Feranor-Co-Signature-Algorithm:
      description: The OID of the classical co-signature algorithm, such as 1.2.840.10045.4.3.3 (ecdsa-with-SHA384) for P-384; for a hybrid signature only.
      schema:
        type: string
        pattern: ^[0-2](\.[0-9]+)+$
    Feranor-Signature-Algorithm:
      description: The OID of the post-quantum signature algorithm.
      schema:
        type: string
        pattern: ^[0-2](\.[0-9]+)+$
    Feranor-Signer-Thumbprint:
      description: SHA-256 of the signer's certificate, in hexadecimal.
      schema:
        type: string
        pattern: ^[0-9A-F]{64}$
    Feranor-Co-Signer:
      description: The classical co-signer's subject, percent-encoded UTF-8; for a hybrid signature only.
      schema:
        type: string
    Feranor-Hybrid:
      description: true when a classical co-signer was verified next to the post-quantum signer.
      schema:
        type: string
        enum:
        - 'true'
        - 'false'
    Feranor-Signed:
      description: Whether the content was signed.
      schema:
        type: string
        enum:
        - 'true'
        - 'false'
    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
    Feranor-Signer:
      description: The signer's subject, percent-encoded UTF-8.
      schema:
        type: string
  parameters:
    Feranor-Recipient:
      name: Feranor-Recipient
      in: header
      required: true
      description: 'The recipients, each the base64 of a DER certificate or SubjectPublicKeyInfo, separated by commas; or one per header, the header repeated. At most 1024 recipients, and the headers may total 1 MiB, which bounds them well below that in practice (about 15 certificates signed with SLH-DSA at 67 KB of base64 each, about 465 hybrid ML-KEM certificates, thousands of public keys): beyond, 431 before anything is read.'
      schema:
        type: string
        minLength: 1
  responses:
    Unprocessable:
      description: recipient-not-found, authentication-failed, signature-invalid, signature-required or algorithm-not-allowed.
      headers:
        Feranor-License:
          $ref: '#/components/headers/Feranor-License'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    PayloadTooLarge:
      description: 'payload-too-large: beyond Sidecar:MaxInMemorySize (100 MiB by default, or less to fit the memory) for an operation in memory, or Sidecar:MaxStreamSize (16 GiB by default) for any request.'
      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'
    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'
    TooManyRequests:
      description: 'Too many operations at once (Sidecar:MaxConcurrentRequests, by default the number of processors and at least 4, with a queue four times as long), or a body sent without Content-Length that the memory budget has no more room for as it arrives: retry later. 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'
    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'
  schemas:
    InspectionReport:
      type: object
      additionalProperties: false
      required:
      - type
      - contentType
      - encrypted
      - classical
      - signed
      - hybrid
      - recipients
      - signers
      - sizes
      properties:
        type:
          type: string
          enum:
          - AuthEnvelopedData
          - SignedData
          - EnvelopedData
          description: EnvelopedData for a classical message.
        contentType:
          type: string
          pattern: ^[0-2](\.[0-9]+)+$
          description: The outer content type.
        encapsulatedContentType:
          type: string
          pattern: ^[0-2](\.[0-9]+)+$
          description: The type of the content it holds (id-signedData for a signed then encrypted message).
        encrypted:
          type: boolean
        classical:
          type: boolean
          description: true for a classical message (RSA or ECDH recipients), which decrypt refuses and fpqc reencrypt migrates.
        signed:
          type: boolean
        hybrid:
          type: boolean
          description: true for a SignedData that states both a post-quantum signer and a classical co-signer; nothing verified.
        contentEncryptionAlgorithm:
          type: string
          pattern: ^[0-2](\.[0-9]+)+$
        recipients:
          type: array
          items:
            $ref: '#/components/schemas/RecipientReport'
          description: For an encrypted message.
        signers:
          type: array
          items:
            $ref: '#/components/schemas/SignerReport'
          description: 'For a SignedData. A signed then encrypted message lists none: its signers are encrypted.'
        sizes:
          $ref: '#/components/schemas/MessageSizes'
    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'
    SignerSizes:
      type: object
      additionalProperties: false
      required:
      - signature
      properties:
        signature:
          type: integer
          format: int32
          description: The signature value.
    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
    RecipientSizes:
      type: object
      additionalProperties: false
      required:
      - entry
      - kemCiphertext
      - encryptedKey
      properties:
        entry:
          type: integer
          format: int32
          description: The whole RecipientInfo as encoded.
        kemCiphertext:
          type: integer
          format: int32
        encryptedKey:
          type: integer
          format: int32
          description: The wrapped content key.
    SignerReport:
      type: object
      additionalProperties: false
      required:
      - postQuantum
      - sizes
      properties:
        signatureAlgorithm:
          type: string
          pattern: ^[0-2](\.[0-9]+)+$
        digestAlgorithm:
          type: string
          pattern: ^[0-2](\.[0-9]+)+$
        subject:
          type: string
          description: From the certificate the message carries, as the other certificate members.
        issuer:
          type: string
        serialNumber:
          type: string
        thumbprint:
          type: string
          pattern: ^[0-9A-F]{64}$
          description: SHA-256 of the certificate.
        signingTime:
          type: string
          format: date-time
        postQuantum:
          type: boolean
          description: false for an ECDSA co-signer.
        sizes:
          $ref: '#/components/schemas/SignerSizes'
    RecipientReport:
      type: object
      additionalProperties: false
      required:
      - kind
      - sizes
      properties:
        kind:
          type: string
          enum:
          - kem
          - key-transport
          - key-agreement
          - kek
          - password
          - other
        identifier:
          type: string
          description: The recipient identifier.
        kem:
          type: string
          pattern: ^[0-2](\.[0-9]+)+$
          description: The KEM, or the key-encryption algorithm of a classical entry.
        kdf:
          type: string
          pattern: ^[0-2](\.[0-9]+)+$
        keyWrap:
          type: string
          pattern: ^[0-2](\.[0-9]+)+$
        sizes:
          $ref: '#/components/schemas/RecipientSizes'
    MessageSizes:
      type: object
      additionalProperties: false
      required:
      - message
      description: In bytes, read from the encoding, never estimated. Structural elements (recipientInfos, authentication, certificates) include their tag and length octets; content is the value's own bytes.
      properties:
        message:
          type: integer
          format: int64
        recipientInfos:
          type: integer
          format: int64
          description: 'Encrypted message: the element holding every entry.'
        content:
          type: integer
          format: int64
          description: The encrypted content (the sum of its segments in BER), or the signed content, absent for a detached signature.
        authentication:
          type: integer
          format: int64
          description: 'Encrypted message: the authentication tag, with the authenticated attributes when present.'
        certificates:
          type: integer
          format: int64
          description: 'SignedData: the certificates element, absent when the message carries none.'
  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.