cppki.gen.yml

# GENERATED FILE DO NOT EDIT
openapi: 3.0.2
info:
  description: SCION CPPKI API
  title: API to retrieve SCION control plane PKI (CPPKI) information.
  version: 0.1.0
paths:
  /trcs:
    get:
      tags:
        - cppki
      summary: List the TRCs
      description: >-
        List the latest SCION Trust Root Configurations for each ISD that are
        known to the control service. The result can be filtered by ISD.
        Optionally, all TRCs can be requested instead of only the latest ones.
      operationId: get-trcs
      parameters:
        - in: query
          name: isd
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: false
        - in: query
          name: all
          schema:
            type: boolean
      responses:
        '200':
          description: List of applicable TRCs.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TRCBrief'
        '400':
          $ref: '#/components/responses/BadRequest'
  /trcs/isd{isd}-b{base}-s{serial}:
    get:
      tags:
        - cppki
      summary: Get the TRC
      description: |
        Get the SCION Trust Root Configuration.
      operationId: get-trc
      parameters:
        - in: path
          name: isd
          required: true
          schema:
            type: integer
            example: 42
        - in: path
          name: base
          required: true
          schema:
            type: integer
            example: 1
        - in: path
          name: serial
          required: true
          schema:
            type: integer
            example: 3
      responses:
        '200':
          description: TRC.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TRC'
        '400':
          $ref: '#/components/responses/BadRequest'
  /trcs/isd{isd}-b{base}-s{serial}/blob:
    get:
      tags:
        - cppki
      summary: Get the TRC blob
      description: |
        Get the SCION Trust Root Configuration as PEM encoded byte blob.
      operationId: get-trc-blob
      parameters:
        - in: path
          name: isd
          required: true
          schema:
            type: integer
            example: 42
        - in: path
          name: base
          required: true
          schema:
            type: integer
            example: 1
        - in: path
          name: serial
          required: true
          schema:
            type: integer
            example: 3
      responses:
        '200':
          description: TRC blob
          content:
            application/x-pem-file:
              example: |
                -----BEGIN TRC-----
                ZjAwOjA6MTEwI ...
                -----END TRC-----
        '400':
          $ref: '#/components/responses/BadRequest'
  /certificates:
    get:
      tags:
        - cppki
      summary: List the certificate chains
      description: |
        List the currently active certificate chains that are known to the
        control service. The result can be filtered by ISD-AS. Furthermore,
        one can pass a particular point in time at which the certificate
        chains are valid as input. A boolean can be provided to return all
        certificates, regardless of their period of vailidity.
      operationId: get-certificates
      parameters:
        - in: query
          name: isd_as
          schema:
            $ref: '#/components/schemas/IsdAs'
        - in: query
          name: valid_at
          schema:
            type: string
            format: date-time
        - in: query
          name: all
          schema:
            type: boolean
      responses:
        '200':
          description: List of certificate chains
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ChainBrief'
        '400':
          description: Invalid request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /certificates/{chain-id}:
    get:
      tags:
        - cppki
      summary: Get the certificate chain
      description: |
        Get the certificate chain for a given ChainID.
      operationId: get-certificate
      parameters:
        - in: path
          name: chain-id
          required: true
          schema:
            $ref: '#/components/schemas/ChainID'
      responses:
        '200':
          description: Certificate chain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chain'
        '400':
          description: Invalid request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /certificates/{chain-id}/blob:
    get:
      tags:
        - cppki
      summary: Get the certificate chain blob
      description: |
        Get the certificate chain encoded as PEM bytes blob for a given ChainID.
      operationId: get-certificate-blob
      parameters:
        - in: path
          name: chain-id
          required: true
          schema:
            $ref: '#/components/schemas/ChainID'
      responses:
        '200':
          description: Certificate chain blob
          content:
            application/x-pem-file:
              example: |
                -----BEGIN CERTIFICATE-----
                ASCertificate ...
                -----END CERTIFICATE-----
                -----BEGIN CERTIFICATE-----
                CACertificate ...
                -----END CERTIFICATE-----
        '400':
          description: Invalid request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
components:
  schemas:
    TRCBrief:
      title: Brief TRC description
      type: object
      required:
        - id
      properties:
        id:
          $ref: '#/components/schemas/TRCID'
    TRCID:
      title: TRC Identifier
      type: object
      required:
        - isd
        - base_number
        - serial_number
      properties:
        isd:
          type: integer
          example: 42
        base_number:
          type: integer
          example: 1
        serial_number:
          type: integer
          example: 3
    TRC:
      title: TRC description
      type: object
      required:
        - id
        - validity
        - core_ases
        - authoritative_ases
        - description
      properties:
        id:
          $ref: '#/components/schemas/TRCID'
        validity:
          $ref: '#/components/schemas/Validity'
        core_ases:
          type: array
          items:
            $ref: '#/components/schemas/IsdAs'
        authoritative_ases:
          type: array
          items:
            $ref: '#/components/schemas/IsdAs'
        description:
          type: string
    ChainID:
      title: Certificate chain Identifier
      type: string
      example: fa53a04a
      format: hex-string
    ChainBrief:
      title: Brief certificate chain description
      type: object
      required:
        - id
        - subject
        - issuer
        - validity
      properties:
        id:
          $ref: '#/components/schemas/ChainID'
        subject:
          $ref: '#/components/schemas/IsdAs'
        issuer:
          $ref: '#/components/schemas/IsdAs'
        validity:
          $ref: '#/components/schemas/Validity'
    Certificate:
      title: Certificate description
      type: object
      required:
        - distinguished_name
        - isd_as
        - validity
        - subject_key_algo
        - subject_key_id
      properties:
        distinguished_name:
          type: string
        isd_as:
          $ref: '#/components/schemas/IsdAs'
        validity:
          $ref: '#/components/schemas/Validity'
        subject_key_algo:
          type: string
          example: ECDSA
        subject_key_id:
          $ref: '#/components/schemas/SubjectKeyID'
    Validity:
      title: Validity period
      type: object
      required:
        - not_before
        - not_after
      properties:
        not_before:
          type: string
          format: date-time
          example: '2021-01-04T09:59:33Z'
        not_after:
          type: string
          format: date-time
          example: '2022-01-04T09:59:33Z'
    Chain:
      title: Certificate chain description
      type: object
      required:
        - subject
        - issuer
      properties:
        subject:
          $ref: '#/components/schemas/Certificate'
        issuer:
          $ref: '#/components/schemas/Certificate'
    SubjectKeyID:
      type: string
      format: spaced-hex-string
      example: 89 B9 49 C2 2F 2F 9C DD 0D 2A 57 A9 DE 8E 2F 95 F3 09 10 D1
    Subject:
      type: object
      required:
        - isd_as
      properties:
        isd_as:
          $ref: '#/components/schemas/IsdAs'
    Policy:
      type: object
      required:
        - chain_lifetime
      properties:
        chain_lifetime:
          type: string
          example: 72h0m0s
    StandardError:
      type: object
      properties:
        error:
          type: string
          description: Error message
      required:
        - error
    IsdAs:
      title: ISD-AS Identifier
      type: string
      pattern: ^\d+-([a-f0-9]{1,4}:){2}([a-f0-9]{1,4})|\d+$
      example: 1-ff00:0:110
    Problem:
      type: object
      required:
        - status
        - title
      properties:
        type:
          type: string
          format: uri-reference
          description: >-
            A URI reference that uniquely identifies the problem type only in
            the context of the provided API. Opposed to the specification in
            RFC-7807, it is neither recommended to be dereferencable and point
            to a human-readable documentation nor globally unique for the
            problem type.
          default: about:blank
          example: /problem/connection-error
        title:
          type: string
          description: >-
            A short summary of the problem type. Written in English and readable
            for engineers, usually not suited for non technical stakeholders and
            not localized.
          example: Service Unavailable
        status:
          type: integer
          description: >-
            The HTTP status code generated by the origin server for this
            occurrence of the problem.
          minimum: 100
          maximum: 599
          example: 503
        detail:
          type: string
          description: >-
            A human readable explanation specific to this occurrence of the
            problem that is helpful to locate the problem and give advice on how
            to proceed. Written in English and readable for engineers, usually
            not suited for non technical stakeholders and not localized.
          example: Connection to database timed out
        instance:
          type: string
          format: uri-reference
          description: >-
            A URI reference that identifies the specific occurrence of the
            problem, e.g. by adding a fragment identifier or sub-path to the
            problem type. May be used to locate the root of this problem in the
            source code.
          example: /problem/connection-error#token-info-read-timed-out
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StandardError'