X-Road (NIIS) Ds Tls Certification Authorities API

openapi: 3.2.0
info:
  title: X Road Global Ds Tls Certification Authorities API
  version: 1.0.0
  contact:
    email: info@niis.org
    name: Nordic Institute for Interoperability Solutions (NIIS)
    url: https://github.com/nordic-institute/X-Road-development/#enhancement-requests-and-error-reports
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  description: 'Operations tagged ds-tls-certification-authorities across 2 of this provider''s published API definitions: central-server-admin-openapi.yaml, x-road-global-central-server-admin-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- description: basepath for API v1
  url: /api/v1
security:
- ApiKeyAuth: []
tags:
- name: ds-tls-certification-authorities
  description: resources related to approved DataSpace TLS certification authorities
paths:
  /ds-tls-certification-authorities:
    get:
      description: CS administrator views the list of approved DataSpace TLS certification authorities.
      operationId: getDsTlsCertificationAuthorities
      responses:
        '200':
          content:
            application/json:
              schema:
                description: array of DS TLS certification authority objects
                items:
                  $ref: '#/components/schemas/ApprovedDsTlsCertificationAuthorityListItem'
                type: array
                uniqueItems: false
          description: list of DS TLS certification authorities
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: get all DS TLS certification authorities
      tags:
      - ds-tls-certification-authorities
    post:
      description: CS administrator adds an approved DataSpace TLS certification authority.
      operationId: addDsTlsCertificationAuthority
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/DsTlsCertificationAuthorityFileAndSettings'
        description: the new DS TLS certification authority with settings
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApprovedDsTlsCertificationAuthority'
          description: created item
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: add a new DS TLS certification authority
      tags:
      - ds-tls-certification-authorities
    servers:
    - description: basepath for API v1
      url: /api/v1
  /ds-tls-certification-authorities/{ds_tls_certification_authority_id}:
    parameters:
    - $ref: '#/components/parameters/DsTlsCertificationAuthorityIdParam'
    delete:
      description: CS administrator deletes a DS TLS certification authority.
      operationId: deleteDsTlsCertificationAuthority
      responses:
        '204':
          description: DS TLS certification authority deletion was successful
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: delete DS TLS certification authority
      tags:
      - ds-tls-certification-authorities
    get:
      description: CS administrator views the details of an approved DS TLS certification authority.
      operationId: getDsTlsCertificationAuthority
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApprovedDsTlsCertificationAuthority'
          description: a DS TLS certification authority
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: get a DS TLS certification authority
      tags:
      - ds-tls-certification-authorities
    patch:
      description: CS administrator edits the settings of a DS TLS certification authority.
      operationId: updateDsTlsCertificationAuthority
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DsTlsCertificationAuthoritySettings'
        description: the updated settings of the DS TLS certification authority
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApprovedDsTlsCertificationAuthority'
          description: the new state of the DS TLS certification authority
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: update the DS TLS certification authority
      tags:
      - ds-tls-certification-authorities
    servers:
    - description: basepath for API v1
      url: /api/v1
  /ds-tls-certification-authorities/{ds_tls_certification_authority_id}/certificate:
    get:
      description: CS administrator views the details of an approved DS TLS certification authority certificate.
      operationId: getDsTlsCertificationAuthorityCertificate
      parameters:
      - $ref: '#/components/parameters/DsTlsCertificationAuthorityIdParam'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateDetails'
          description: a DS TLS certification authority certificate
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: get a DS TLS certification authority certificate
      tags:
      - ds-tls-certification-authorities
    servers:
    - description: basepath for API v1
      url: /api/v1
  /ds-tls-certification-authorities/{ds_tls_certification_authority_id}/intermediate-cas:
    parameters:
    - $ref: '#/components/parameters/DsTlsCertificationAuthorityIdParam'
    get:
      description: CS administrator views the intermediate CAs configured for a DS TLS certification authority.
      operationId: getDsTlsCertificationAuthorityIntermediateCas
      responses:
        '200':
          content:
            application/json:
              schema:
                description: array of DS TLS intermediate certificate authorities
                items:
                  $ref: '#/components/schemas/DsTlsIntermediateCertificateAuthority'
                type: array
                uniqueItems: false
          description: list of intermediate certificate authorities belonging to the DS TLS certification authority
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: get the intermediate certificate authorities of a DS TLS certification authority
      tags:
      - ds-tls-certification-authorities
    post:
      description: CS administrator configures an intermediate CA for a DS TLS certification authority.
      operationId: addDsTlsCertificationAuthorityIntermediateCa
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CertificateFile'
        description: the new intermediate certificate authority certificate file
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DsTlsIntermediateCertificateAuthority'
          description: created item
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: add a new intermediate certificate authority to a DS TLS certification authority
      tags:
      - ds-tls-certification-authorities
    servers:
    - description: basepath for API v1
      url: /api/v1
components:
  responses:
    NotFound:
      description: resource requested does not exists
    Unauthorized:
      description: authentication credentials are missing
    Forbidden:
      description: request has been refused
    InternalServerError:
      description: internal server error
    BadRequest:
      description: request was invalid
  parameters:
    DsTlsCertificationAuthorityIdParam:
      in: path
      name: ds_tls_certification_authority_id
      description: unique identifier of the DS TLS certification authority
      required: true
      schema:
        format: int32
        minimum: 1
        type: integer
  schemas:
    ApprovedDsTlsCertificationAuthority:
      description: approved DS TLS certification authority (globalconf approvedConnectorTlsCA entry). Only the ACME directory URL and the DS TLS certificate profile id are exposed for the ACME server - the shared ACME type's auth/sign profile ids are meaningless for these entries and are never surfaced here.
      properties:
        id:
          description: unique identifier
          example: 123
          format: int32
          readOnly: true
          type: integer
        name:
          description: DS TLS certification authority name
          example: Let's Encrypt
          format: text
          maxLength: 255
          minLength: 1
          type: string
        issuer_distinguished_name:
          description: certificate issuer distinguished name
          example: issuer123
          format: text
          maxLength: 255
          minLength: 1
          type: string
        subject_distinguished_name:
          description: certificate subject distinguished name
          example: subject123
          format: text
          maxLength: 255
          minLength: 1
          type: string
        not_after:
          description: certificate validity not after
          example: '2022-01-17T00:00:00.001Z'
          format: date-time
          maxLength: 24
          minLength: 24
          type: string
        not_before:
          description: certificate validity not before
          example: '2022-01-17T00:00:00.001Z'
          format: date-time
          maxLength: 24
          minLength: 24
          type: string
        acme_server_directory_url:
          description: enables auto-enrollment from this CA's ACME server when set
          type: string
          format: url
          minLength: 1
        ds_tls_certificate_profile_id:
          description: certificate profile id some ACME servers need to know the DS TLS certificate usage type
          format: text
          type: string
          minLength: 1
      required:
      - id
      - name
      type: object
    DsTlsCertificationAuthorityFileAndSettings:
      allOf:
      - $ref: '#/components/schemas/CertificateFile'
      - $ref: '#/components/schemas/DsTlsCertificationAuthoritySettings'
      description: DS TLS certification authority file and settings
      type: object
      required:
      - certificate
      - name
    DsTlsCertificationAuthoritySettings:
      description: DS TLS certification authority settings. Only the ACME directory URL and the DS TLS certificate profile id are settable for the ACME server - the shared ACME type's auth/sign profile ids do not apply here.
      properties:
        name:
          description: DS TLS certification authority name
          example: Let's Encrypt
          format: text
          maxLength: 255
          minLength: 1
          type: string
        acme_server_directory_url:
          description: enables auto-enrollment from this CA's ACME server when set
          format: url
          type: string
        ds_tls_certificate_profile_id:
          description: certificate profile id some ACME servers need to know the DS TLS certificate usage type
          format: text
          type: string
      type: object
    CertificateDetails:
      description: certificate details for any kind of certificate (TLS, auth, sign)
      properties:
        hash:
          description: certificate SHA-256 hash
          example: 1234567890ABCDEF
          format: text
          maxLength: 64
          minLength: 1
          type: string
        issuer_common_name:
          description: certificate issuer common name
          example: domain.com
          format: text
          maxLength: 255
          minLength: 1
          type: string
        issuer_distinguished_name:
          description: certificate issuer distinguished name
          example: issuer123
          format: text
          maxLength: 255
          minLength: 1
          type: string
        key_usages:
          description: certificate key usage array
          items:
            $ref: '#/components/schemas/KeyUsage'
          type: array
          uniqueItems: false
        not_after:
          description: certificate validity not after
          example: '2022-01-17T00:00:00.001Z'
          format: date-time
          maxLength: 24
          minLength: 24
          type: string
        not_before:
          description: certificate validity not before
          example: '2022-01-17T00:00:00.001Z'
          format: date-time
          maxLength: 24
          minLength: 24
          type: string
        public_key_algorithm:
          description: certificate public key algorithm
          example: sha256WithRSAEncryption
          format: sha-256
          maxLength: 255
          minLength: 1
          type: string
        rsa_public_key_exponent:
          description: RSA public key exponent (if RSA key) as an integer
          example: 65537
          format: int32
          type: integer
        rsa_public_key_modulus:
          description: hex encoded RSA public key modulus (if RSA key)
          example: c44421d601...
          format: hex
          maxLength: 1000
          minLength: 1
          type: string
        ec_public_parameters:
          description: EC public key named curve (if EC key)
          example: secp256r1(1.2.840.10045.3.1.7)
          format: text
          maxLength: 255
          minLength: 1
          type: string
        ec_public_key_point:
          description: hex encoded EC public key point (if EC key)
          example: c44421d601...
          format: hex
          maxLength: 1000
          minLength: 1
          type: string
        serial:
          description: serial number
          example: '123456789'
          format: text
          maxLength: 255
          minLength: 1
          type: string
        signature:
          description: hex encoded certificate signature
          example: 30af2fdc1780...
          format: text
          maxLength: 255
          minLength: 1
          type: string
        signature_algorithm:
          description: certificate signature algorithm
          example: sha256WithRSAEncryption
          format: sha-256
          maxLength: 255
          minLength: 1
          type: string
        subject_alternative_names:
          description: certificate subject alternative names
          example: DNS:*.example.org
          format: text
          maxLength: 1000
          minLength: 1
          type: string
        subject_common_name:
          description: certificate subject common name
          example: domain.com
          format: text
          maxLength: 255
          minLength: 1
          type: string
        subject_distinguished_name:
          description: certificate subject distinguished name
          example: subject123
          format: text
          maxLength: 255
          minLength: 1
          type: string
        version:
          description: version
          example: 3
          format: int32
          type: integer
      required:
      - issuer_distinguished_name
      - issuer_common_name
      - subject_distinguished_name
      - subject_common_name
      - not_before
      - not_after
      - serial
      - version
      - signature_algorithm
      - signature
      - public_key_algorithm
      - rsa_public_key_modulus
      - rsa_public_key_exponent
      - hash
      - key_usages
      - subject_alternative_names
      type: object
    KeyUsage:
      description: certificate key usage
      enum:
      - DIGITAL_SIGNATURE
      - NON_REPUDIATION
      - KEY_ENCIPHERMENT
      - DATA_ENCIPHERMENT
      - KEY_AGREEMENT
      - KEY_CERT_SIGN
      - CRL_SIGN
      - ENCIPHER_ONLY
      - DECIPHER_ONLY
      example: NON_REPUDIATION
      type: string
    CertificateFile:
      description: certificate file
      properties:
        certificate:
          description: the certificate file
          format: binary
          type: string
      required:
      - certificate
      type: object
    DsTlsIntermediateCertificateAuthority:
      description: DS TLS intermediate certificate authority information
      properties:
        id:
          description: unique identifier
          example: 123
          format: int32
          readOnly: true
          type: integer
        ds_tls_certification_authority_id:
          description: unique identifier of the owning DS TLS certification authority
          example: 123
          format: int32
          readOnly: true
          type: integer
        ca_certificate:
          $ref: '#/components/schemas/CertificateDetails'
      required:
      - ca_certificate
      type: object
    ApprovedDsTlsCertificationAuthorityListItem:
      description: DS TLS certification authority list item
      properties:
        id:
          description: unique identifier
          example: 123
          format: int32
          readOnly: true
          type: integer
        name:
          description: DS TLS certification authority name
          example: Let's Encrypt
          format: text
          maxLength: 255
          minLength: 1
          type: string
        not_after:
          description: certificate validity not after
          example: '2022-01-17T00:00:00.001Z'
          format: date-time
          maxLength: 24
          minLength: 24
          type: string
        not_before:
          description: certificate validity not before
          example: '2022-01-17T00:00:00.001Z'
          format: date-time
          maxLength: 24
          minLength: 24
          type: string
      required:
      - id
      - name
      - not_before
      - not_after
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: X-Road-ApiKey token=<api key>
      in: header
      name: Authorization
      type: apiKey
x-refined-from:
- central-server-admin-openapi.yaml
- x-road-global-central-server-admin-openapi.yml