X-Road (NIIS) Certification Services API

openapi: 3.2.0
info:
  title: X Road Global Certification Services 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 certification-services 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: certification-services
  description: resources related to Certification Services
paths:
  /certification-services:
    get:
      description: CS administrator views the list of certification services that have been approved and described for this X-Road instance.
      operationId: getCertificationServices
      responses:
        '200':
          content:
            application/json:
              schema:
                description: array of certification service objects
                items:
                  $ref: '#/components/schemas/ApprovedCertificationServiceListItem'
                type: array
                uniqueItems: false
          description: list of certification services
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: get all certification services
      tags:
      - certification-services
    post:
      description: CS administrator adds a certification service to the list of approved certification services.
      operationId: addCertificationService
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CertificationServiceFileAndSettings'
        description: the new certification service with settings
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApprovedCertificationService'
          description: created item
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: add a new certification service
      tags:
      - certification-services
    servers:
    - description: basepath for API v1
      url: /api/v1
  /certification-services/{certification_service_id}:
    parameters:
    - $ref: '#/components/parameters/CertificationServiceIdParam'
    delete:
      description: CS Administrator deletes a certification service.
      operationId: deleteCertificationService
      responses:
        '204':
          description: certification service deletion was successful
        '400':
          content:
            application/json:
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                warnings_response:
                  $ref: '#/components/examples/DeleteKeyWarningExample'
              schema:
                $ref: '#/components/schemas/ErrorInfo'
          description: request was invalid
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: delete certification service
      tags:
      - certification-services
    get:
      description: CS administrator views the details of an approved certification service.
      operationId: getCertificationService
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApprovedCertificationService'
          description: a certification service
        '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 certification service
      tags:
      - certification-services
    patch:
      description: CS administrator edits the settings of a certification service.
      operationId: updateCertificationService
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CertificationServiceSettings'
        description: the updated settings of the certification service
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApprovedCertificationService'
          description: the new state of the certification service
        '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 certification service
      tags:
      - certification-services
    servers:
    - description: basepath for API v1
      url: /api/v1
  /certification-services/{certification_service_id}/certificate:
    get:
      description: CS administrator views the details of an approved certification service cetificate.
      operationId: getCertificationServiceCertificate
      parameters:
      - $ref: '#/components/parameters/CertificationServiceIdParam'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateDetails'
          description: a certification service
        '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 certification service
      tags:
      - certification-services
    servers:
    - description: basepath for API v1
      url: /api/v1
  /certification-services/{certification_service_id}/intermediate-cas:
    parameters:
    - $ref: '#/components/parameters/CertificationServiceIdParam'
    get:
      description: CS administrator views the intermediate CAs configured for a certification service.
      operationId: getCertificationServiceIntermediateCas
      responses:
        '200':
          content:
            application/json:
              schema:
                description: array of certificate authorities
                items:
                  $ref: '#/components/schemas/CertificateAuthority'
                type: array
                uniqueItems: false
          description: list of intermediate certificate authorities belonging to the certification service
        '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 certification service
      tags:
      - certification-services
    post:
      description: CS administrator configures an intermediate CA for a certification service.
      operationId: addCertificationServiceIntermediateCa
      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/CertificateAuthority'
          description: created item
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: add a new intermediate certificate authority to a certification service
      tags:
      - certification-services
    servers:
    - description: basepath for API v1
      url: /api/v1
  /certification-services/{certification_service_id}/ocsp-responders:
    parameters:
    - $ref: '#/components/parameters/CertificationServiceIdParam'
    get:
      description: CS administrator views the OCSP responders configured for a CA.
      operationId: getCertificationServiceOcspResponders
      responses:
        '200':
          content:
            application/json:
              schema:
                description: array of ocsp responders
                items:
                  $ref: '#/components/schemas/OcspResponder'
                type: array
                uniqueItems: false
          description: list of ocsp responders belonging to the certification service
        '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 ocsp responders of a certification service
      tags:
      - certification-services
    post:
      description: CS administrator adds an OCSP responder service information for a CA.
      operationId: addCertificationServiceOcspResponder
      requestBody:
        content:
          multipart/form-data:
            schema:
              allOf:
              - $ref: '#/components/schemas/OcspResponderUrl'
              - $ref: '#/components/schemas/CostTypeProperty'
              - $ref: '#/components/schemas/CertificateFile'
              required:
              - url
              - cost_type
        description: ocsp responder to add
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OcspResponder'
          description: created item
        '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: add an ocsp responder to a certification service
      tags:
      - certification-services
    servers:
    - description: basepath for API v1
      url: /api/v1
components:
  schemas:
    CertificationServiceFileAndSettings:
      allOf:
      - $ref: '#/components/schemas/CertificateFile'
      - $ref: '#/components/schemas/CertificationServiceSettings'
      description: certification service file and settings
      type: object
      required:
      - certificate
      - default_csr_format
    CostType:
      description: cost type for services like TSP-s and OCSP responders
      enum:
      - FREE
      - PAID
      - UNDEFINED
      example: FREE
      type: string
    CostTypeProperty:
      type: object
      description: Object containing cost_type field of CostType enum
      properties:
        cost_type:
          $ref: '#/components/schemas/CostType'
      required:
      - cost_type
    ErrorInfo:
      $ref: ../../../../../common/common-admin-api/src/main/resources/common-openapi-definition.yaml#/components/schemas/ErrorInfo
    ApprovedCertificationServiceListItem:
      description: certification service list item
      properties:
        id:
          description: unique identifier
          example: 123
          format: int32
          readOnly: true
          type: integer
        name:
          description: certification service name
          example: Name
          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
    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
    CertificationServiceSettings:
      description: certification service settings
      properties:
        certificate_profile_info:
          description: fully qualified class name that implements the ee.ria.xroad.common.certificateprofile.CertificateProfileInfoProvider interface
          example: ee.ria.xroad.common.certificateprofile.impl.FiVRKCertificateProfileInfoProvider
          format: text
          type: string
        tls_auth:
          description: can the CA be used for TLS authentication
          type: string
        default_csr_format:
          $ref: '#/components/schemas/CsrFormat'
        acme_server_directory_url:
          format: url
          type: string
        acme_server_ip_address:
          format: text
          type: string
        authentication_certificate_profile_id:
          format: text
          type: string
        signing_certificate_profile_id:
          format: text
          type: string
      type: object
    ApprovedCertificationService:
      description: certification service
      properties:
        id:
          description: unique identifier
          example: 123
          format: int32
          readOnly: true
          type: integer
        name:
          description: certification service name
          example: Name
          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
        certificate_profile_info:
          description: fully qualified class name that implements the ee.ria.xroad.common.certificateprofile.CertificateProfileInfoProvider interface
          example: ee.ria.xroad.common.certificateprofile.impl.FiVRKCertificateProfileInfoProvider
          format: text
          minLength: 1
          type: string
        tls_auth:
          description: can the CA be used for TLS authentication
          type: boolean
        default_csr_format:
          $ref: '#/components/schemas/CsrFormat'
        acme_server_directory_url:
          type: string
          format: url
          minLength: 1
        acme_server_ip_address:
          type: string
          format: text
          minLength: 1
        authentication_certificate_profile_id:
          format: text
          type: string
          minLength: 1
        signing_certificate_profile_id:
          format: text
          type: string
          minLength: 1
      required:
      - id
      - tls_auth
      - certificate_profile_info
      type: object
    OcspResponder:
      allOf:
      - $ref: '#/components/schemas/OcspResponderUrl'
      - $ref: '#/components/schemas/CostTypeProperty'
      description: OCSP responder
      properties:
        id:
          description: unique identifier
          example: 123
          format: int32
          readOnly: true
          type: integer
        has_certificate:
          description: has OCSP responder certificate
          default: false
          type: boolean
      required:
      - id
    OcspResponderUrl:
      description: OCSP responder url
      properties:
        url:
          description: url of the OCSP responder
          example: http://dev.xroad.rocks:123
          format: url
          maxLength: 255
          minLength: 1
          type: string
      required:
      - url
      type: object
    CsrFormat:
      description: CSR format
      enum:
      - PEM
      - DER
      example: PEM
      type: string
    CertificateAuthority:
      description: approved certificate authority information
      properties:
        id:
          description: unique identifier
          example: 123
          format: int32
          readOnly: true
          type: integer
        certification_service_id:
          description: unique identifier
          example: 123
          format: int32
          readOnly: true
          type: integer
        ca_certificate:
          $ref: '#/components/schemas/CertificateDetails'
      required:
      - ca_certificate
      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
  responses:
    BadRequest:
      description: request was invalid
    NotFound:
      description: resource requested does not exists
    Unauthorized:
      description: authentication credentials are missing
    Forbidden:
      description: request has been refused
    InternalServerError:
      description: internal server error
  examples:
    DeleteKeyWarningExample:
      summary: Warning response when trying to delete an authentication key with a registered authentication certificate
      value:
        error:
          code: warnings_detected
        status: 400
        warnings:
        - code: auth_key_with_registered_cert_warning
          metadata:
          - 0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF
    ErrorExample:
      $ref: ../../../../../common/common-admin-api/src/main/resources/common-openapi-definition.yaml#/components/examples/ErrorExample
  parameters:
    CertificationServiceIdParam:
      in: path
      name: certification_service_id
      description: unique identifier of the certification service
      required: true
      schema:
        format: int32
        minimum: 1
        type: integer
  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