X-Road (NIIS) Certificate Authorities API

openapi: 3.2.0
info:
  title: X Road Global Certificate Authorities API
  version: 2.1.0
  contact:
    name: Nordic Institute for Interoperability Solutions (NIIS)
    url: https://github.com/nordic-institute/X-Road-development/#enhancement-requests-and-error-reports
    email: info@niis.org
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  description: 'Operations tagged certificate-authorities across 2 of this provider''s published API definitions: security-server-admin-openapi.yaml, x-road-global-security-server-admin-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: /api/v1
  description: basepath for API v1
security:
- ApiKeyAuth: []
tags:
- name: certificate-authorities
  description: CA endpoints
paths:
  /certificate-authorities:
    get:
      tags:
      - certificate-authorities
      summary: view the approved certificate authorities
      operationId: getApprovedCertificateAuthorities
      description: Administrator views the approved certificate authorities.
      parameters:
      - in: query
        name: key_usage_type
        description: return only CAs suitable for this type of key usage
        required: false
        schema:
          $ref: '#/components/schemas/KeyUsageType'
      - in: query
        name: include_intermediate_cas
        description: if true, include also intermediate CAs. Otherwise only top CAs are included. Default value is "false".
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: list of approved certificate authorities
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                description: array of certificate authority objects
                items:
                  $ref: '#/components/schemas/CertificateAuthority'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    servers:
    - url: /api/v1
      description: basepath for API v1
  /certificate-authorities/{ca_name}/csr-subject-fields:
    get:
      tags:
      - certificate-authorities
      summary: get description of subject DN fields for CSR
      operationId: getSubjectFieldDescriptions
      description: List DN field descriptions to collect CSR parameters
      parameters:
      - in: path
        name: ca_name
        description: common name of the CA
        example: X-Road Test CA CN
        required: true
        schema:
          type: string
          format: text
          minLength: 1
          maxLength: 255
      - in: query
        name: key_id
        description: id of the key. If provided, used only for validating correct key usage
        required: false
        schema:
          type: string
          format: text
          minLength: 1
      - in: query
        name: key_usage_type
        description: which usage type this CSR is for
        required: true
        schema:
          $ref: '#/components/schemas/KeyUsageType'
      - in: query
        name: member_id
        description: member client id for signing CSRs. <instance_id>:<member_class>:<member_code>
        example: FI:GOV:123
        required: false
        schema:
          type: string
          format: text
          minLength: 1
          maxLength: 767
      - in: query
        name: is_new_member
        description: whether or not the member in the member_id parameter is a new member
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: csr subject field objects
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                description: array of CsrSubjectFieldDescription objects
                items:
                  $ref: '#/components/schemas/CsrSubjectFieldDescription'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    servers:
    - url: /api/v1
      description: basepath for API v1
  /certificate-authorities/{ca_name}/has-acme-eab-credentials:
    get:
      tags:
      - certificate-authorities
      summary: Does the member have external CA account credentials for its ACME server in the…
      operationId: hasAcmeExternalAccountBindingCredentials
      description: 'Check whether given member has external CA account credentials for its ACME server.


        Determines whether the administrator can order the certificate from ACME server with the generated CSR. The credentials are stored in the acme.yml configuration file'
      parameters:
      - in: path
        name: ca_name
        description: common name of the CA
        example: X-Road Test CA CN
        required: true
        schema:
          type: string
          format: text
          minLength: 1
          maxLength: 255
      - in: query
        name: key_usage_type
        description: which usage type this CSR is for
        example: SIGNING
        required: true
        schema:
          $ref: '#/components/schemas/KeyUsageType'
      - in: query
        name: member_id
        description: <instance_id>:<member_class>:<member_code>
        example: FI:GOV:123
        required: false
        schema:
          type: string
          format: text
          minLength: 1
          maxLength: 255
      responses:
        '200':
          description: acme eab credentials status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcmeEabCredentialsStatus'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    servers:
    - url: /api/v1
      description: basepath for API v1
  /certificate-authorities/{ca_name}/acme-order:
    post:
      tags:
      - certificate-authorities
      summary: order certificate from CA hosted ACME server with the given CSR
      operationId: orderAcmeCertificate
      description: Administrator orders the certificate with previously generated CSR whose certificate profile matches chosen CA-s configured profile.
      parameters:
      - in: path
        name: ca_name
        description: common name of the CA
        example: X-Road Test CA CN
        required: true
        schema:
          type: string
          format: text
          minLength: 1
          maxLength: 255
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcmeOrder'
      responses:
        '200':
          description: acme certificate order was successful
        '400':
          description: request was invalid
        '403':
          description: request has been refused
        '409':
          description: an existing item already exists, outdated global conf or token not logged in
        '500':
          description: internal server error
    servers:
    - url: /api/v1
      description: basepath for API v1
  /certificate-authorities/ocsp-prioritization-strategy:
    get:
      tags:
      - certificate-authorities
      summary: get OCSP responders prioritization strategy
      operationId: getOcspPrioritizationStrategy
      description: Administrator views the OCSP prioritization strategy.
      responses:
        '200':
          description: OCSP prioritization strategy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServicePrioritizationStrategy'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '500':
          description: internal server error
    servers:
    - url: /api/v1
      description: basepath for API v1
components:
  schemas:
    KeyUsageType:
      type: string
      description: intended usage for the key (signing or authentication)
      example: AUTHENTICATION
      enum:
      - AUTHENTICATION
      - SIGNING
    AcmeEabCredentialsStatus:
      type: object
      description: Whether there are credentials in the configuration for the given Member and CA. Used for binding the CA external account with the ACME server's account.
      required:
      - has_acme_external_account_credentials
      - acme_eab_required
      properties:
        acme_eab_required:
          type: boolean
          description: if certificate authority required external account binding for ACME
        has_acme_external_account_credentials:
          type: boolean
          description: whether there are credentials present in the configuration.
          example: true
          readOnly: true
    ServicePrioritizationStrategy:
      type: string
      description: service prioritization strategy
      example: FREE_FIRST
      enum:
      - ONLY_FREE
      - ONLY_PAID
      - FREE_FIRST
      - PAID_FIRST
      - NONE
    CertificateAuthorityOcspResponse:
      type: string
      description: certificate authority OCSP status
      example: IN_USE
      enum:
      - NOT_AVAILABLE
      - OCSP_RESPONSE_UNKNOWN
      - OCSP_RESPONSE_GOOD
      - OCSP_RESPONSE_SUSPENDED
      - OCSP_RESPONSE_REVOKED
    CsrSubjectFieldDescription:
      type: object
      description: object describing input fields for CSR subject DN info
      required:
      - id
      - localized
      - read_only
      - required
      properties:
        id:
          type: string
          format: text
          description: the identifier of the field (such as 'O', 'OU' etc)
          example: O
          minLength: 1
          readOnly: true
        label:
          type: string
          format: text
          description: label of the field, used to display the field in the user interface
          example: ORGANIZATION_NAME
          minLength: 1
          readOnly: true
        label_key:
          type: string
          format: text
          description: localization key for label of the field, used to display the field in the user interface
          example: Organization name (O)
          minLength: 1
          readOnly: true
        default_value:
          type: string
          format: text
          description: the default value of the field. Can be empty.
          example: 1234
          minLength: 0
          readOnly: true
        read_only:
          type: boolean
          description: if this field is read-only
          example: true
          readOnly: true
        required:
          type: boolean
          description: if this field is required to be filled
          example: true
          readOnly: true
        localized:
          type: boolean
          description: if true, label key is in property "label_key". If false, actual label is in property "label"
          example: true
          readOnly: true
    OcspResponder:
      type: object
      description: OCSP responder
      required:
      - url
      - cost_type
      properties:
        url:
          type: string
          format: url
          description: url of the OCSP responder
          example: http://dev.xroad.rocks:123
          minLength: 1
          maxLength: 255
          readOnly: true
        cost_type:
          $ref: '#/components/schemas/CostType'
    CostType:
      description: cost type for services like TSP-s and OCSP responders
      enum:
      - FREE
      - PAID
      - UNDEFINED
      example: FREE
      type: string
    CsrFormat:
      type: string
      description: format of the certificate signing request (PEM or DER)
      example: PEM
      default: PEM
      enum:
      - PEM
      - DER
    AcmeOrder:
      type: object
      description: request to order certificate with the given CSR for the given usage type
      required:
      - csr_id
      - key_usage_type
      properties:
        csr_id:
          type: string
          format: text
          description: id of the CSR
          minLength: 1
          maxLength: 40
        key_usage_type:
          $ref: '#/components/schemas/KeyUsageType'
    CertificateAuthority:
      type: object
      description: approved certificate authority information. Only for top CAs.
      required:
      - name
      - subject_distinguished_name
      - issuer_distinguished_name
      - ocsp_response
      - not_after
      - top_ca
      - path
      - authentication_only
      properties:
        name:
          type: string
          format: text
          description: name of the CA, as defined in global conf. Used also as an identifier
          example: X-Road Test CA CN
          minLength: 1
          maxLength: 255
        subject_distinguished_name:
          type: string
          format: text
          description: subject distinguished name
          example: C=FI, O=X-Road Test, OU=X-Road Test CA OU, CN=X-Road Test CA CN
          minLength: 1
          maxLength: 1024
        issuer_distinguished_name:
          type: string
          format: text
          description: issuer distinguished name
          example: C=FI, O=X-Road Test, OU=X-Road Test CA OU, CN=X-Road Test CA CN
          minLength: 1
          maxLength: 1024
        ocsp_response:
          $ref: '#/components/schemas/CertificateAuthorityOcspResponse'
        not_after:
          type: string
          format: date-time
          description: certificate authority expires at
          example: '2099-12-15T00:00:00.001Z'
          minLength: 24
          maxLength: 24
        top_ca:
          type: boolean
          description: if the certificate authority is top CA (instead of intermediate)
          example: true
        path:
          type: string
          format: text
          description: encoded path string from this CA to top CA
          example: C=FI, O=X-Road Test Intermediate, OU=X-Road Test CA OU, CN=X-Road Test CA CN Intermediate:C=FI, O=X-Road Test, OU=X-Road Test CA OU, CN=X-Road Test CA CN
          minLength: 1
        authentication_only:
          type: boolean
          description: if certificate authority is limited for authentication use only
        certificate_profile_info:
          type: string
          format: text
          description: Fully qualified class name that was used to create the CSR. Implements the ee.ria.xroad.common.certificateprofile.CertificateProfileInfoProvider interface.
          example: org.example.TestCertificateInfoProvider
          minLength: 1
          maxLength: 1024
        default_csr_format:
          $ref: '#/components/schemas/CsrFormat'
        acme_capable:
          type: boolean
          description: if certificate authority supports ACME
        acme_server_ip_addresses:
          type: array
          description: ACME server IP address(es) that can be helpful in configuring the firewall rules.
          example:
          - 12.34.5.6
          - AB:cd:67::89
          items:
            type: string
            format: text
        ocsp_responders:
          type: array
          description: list of ocsp responders for this CA
          items:
            $ref: '#/components/schemas/OcspResponder'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: X-Road-ApiKey token=<api key>
x-refined-from:
- security-server-admin-openapi.yaml
- x-road-global-security-server-admin-openapi.yml