X-Road (NIIS) Keys API

openapi: 3.2.0
info:
  title: X Road Global Keys 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 keys 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: Keys
  description: keys endpoints
paths:
  /keys/{id}:
    get:
      tags:
      - Keys
      summary: get information for the selected key in selected token
      operationId: getKey
      description: Administrator views key details.
      parameters:
      - in: path
        name: id
        description: id of the key
        required: true
        schema:
          type: string
          format: text
          minLength: 1
      responses:
        '200':
          description: key object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Key'
        '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
    patch:
      tags:
      - Keys
      summary: update key information
      operationId: updateKey
      description: Administrator updates the key information.
      parameters:
      - in: path
        name: id
        description: id of the key
        required: true
        schema:
          type: string
          format: text
          minLength: 1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KeyName'
      responses:
        '200':
          description: key modified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Key'
        '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
    delete:
      tags:
      - Keys
      summary: delete key
      operationId: deleteKey
      description: 'Administrator deletes the key.


        This endpoint can also return metadata in the error response if sending an auth cert deletion management request fails. The metadata array contains the error details that were generated in core. The message is in plain English.


        Note that with this endpoint it''s possible to delete an authentication key with a registered authentication certificate.


        Attempt to delete an authentication key with a registered authentication certificate and with ignore_warnings = false causes the operation to fail with a warning in response''s ErrorInfo object.


        Attempt to delete an authentication key with a registered authentication certificate and with ignore_warnings = true succeeds. The authentication certificate is first unregistered, and the key and certificate are deleted after that.


        When trying to delete an authentication key with a registered authentication certificate, the warning response has a warning code auth_key_with_registered_cert_warning and the metadata field contains the key id of the key'
      parameters:
      - in: path
        name: id
        description: id of the key
        required: true
        schema:
          type: string
          format: text
          minLength: 1
      - in: query
        name: ignore_warnings
        description: if true, any ignorable warnings are ignored. if false (or missing), any warnings cause request to fail
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '204':
          description: key deletion was successful
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
                warnings_response:
                  $ref: '#/components/examples/DeleteKeyWarningExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '500':
          description: internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
    servers:
    - url: /api/v1
      description: basepath for API v1
  /keys/{id}/csrs:
    post:
      tags:
      - Keys
      summary: generate csr for the selected key
      operationId: generateCsr
      description: Administrator generates csr for the key.
      parameters:
      - in: path
        name: id
        description: id of the key
        required: true
        schema:
          type: string
          format: text
          minLength: 1
      requestBody:
        description: request to generate csr
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CsrGenerate'
            examples:
              sign_csr_example:
                $ref: '#/components/examples/SignCsrGenerateExample'
              auth_csr_example:
                $ref: '#/components/examples/AuthCsrGenerateExample'
      responses:
        '201':
          description: created CSR
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
                description: csr file
        '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
  /keys/{id}/csrs/{csr_id}:
    get:
      tags:
      - Keys
      summary: download a CSR binary
      operationId: downloadCsr
      description: Administrator downloads a csr that has been created earlier.
      parameters:
      - in: path
        name: id
        description: id of the key
        required: true
        schema:
          type: string
          format: text
          minLength: 1
      - in: path
        name: csr_id
        description: id of the csr
        required: true
        schema:
          type: string
          format: text
          minLength: 1
          maxLength: 40
      - in: query
        name: csr_format
        description: format of the certificate signing request (PEM or DER)
        required: false
        schema:
          $ref: '#/components/schemas/CsrFormat'
      responses:
        '201':
          description: CSR binary
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
                description: csr file
        '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
    delete:
      tags:
      - Keys
      summary: delete csr from the selected key
      operationId: deleteCsr
      description: Administrator deletes csr from the key.
      parameters:
      - in: path
        name: id
        description: id of the key
        required: true
        schema:
          type: string
          format: text
          minLength: 1
      - in: path
        name: csr_id
        description: id of the csr
        required: true
        schema:
          type: string
          format: text
          minLength: 1
          maxLength: 40
      responses:
        '204':
          description: csr deletion was successful
        '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
  /keys/{id}/csrs/{csr_id}/possible-actions:
    get:
      tags:
      - Keys
      summary: get possible actions for one csr
      operationId: getPossibleActionsForCsr
      description: UI needs to know which actions can be done on one csr.
      parameters:
      - in: path
        name: id
        description: id of the key
        required: true
        schema:
          type: string
          format: text
          minLength: 1
      - in: path
        name: csr_id
        description: id of the csr
        required: true
        schema:
          type: string
          format: text
          minLength: 1
          maxLength: 40
      responses:
        '200':
          description: possible actions that can be done on the certificate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PossibleActions'
        '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
  /keys/{id}/possible-actions:
    get:
      tags:
      - Keys
      summary: get possible actions for one key
      operationId: getPossibleActionsForKey
      description: UI needs to know which actions can be done on one key.
      parameters:
      - in: path
        name: id
        description: id of the key
        required: true
        schema:
          type: string
          format: text
          minLength: 1
      responses:
        '200':
          description: possible actions that can be done on the certificate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PossibleActions'
        '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
components:
  examples:
    SignCsrGenerateExample:
      summary: Sign CSR generate request body example
      value:
        key_usage_type: SIGNING
        ca_name: Customized Test CA CN
        csr_format: DER
        member_id: CS:NIIS:1234
        subject_field_values:
          CN: something.niis.org
          C: FI
          O: NIIS
          serialNumber: CS/SS1/NIIS
    DeleteKeyWarningExample:
      summary: Warning response when trying to delete an authentication key with a registered authentication certificate
      value:
        status: 400
        error:
          code: warnings_detected
        warnings:
        - code: auth_key_with_registered_cert_warning
          metadata:
          - 0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF
    ErrorWithMetadataExample:
      $ref: ../../../../../../common/common-admin-api/src/main/resources/common-openapi-definition.yaml#/components/examples/ErrorWithMetadataExample
    AuthCsrGenerateExample:
      summary: Auth CSR generate request body example
      value:
        key_usage_type: AUTHENTICATION
        ca_name: Customized Test CA CN
        csr_format: PEM
        subject_field_values:
          CN: something.niis.org
          C: FI
          O: NIIS
          L: Helsinki
          OU: Development
          serialNumber: CS/SS1/NIIS
    ErrorExample:
      $ref: ../../../../../../common/common-admin-api/src/main/resources/common-openapi-definition.yaml#/components/examples/ErrorExample
  schemas:
    KeyAlgorithm:
      description: Key type
      enum:
      - RSA
      - EC
      example: RSA
      type: string
    ErrorInfo:
      $ref: ../../../../../../common/common-admin-api/src/main/resources/common-openapi-definition.yaml#/components/schemas/ErrorInfo
    TokenCertificate:
      type: object
      description: Certificate that is stored in a Token (auth or sign cert). Also includes the possible actions that can be done to this object, e.g DELETE (only for cert related operations and does not consider user authorization).
      required:
      - ocsp_status
      - owner_id
      - active
      - saved_to_configuration
      - certificate_details
      - status
      properties:
        ocsp_status:
          $ref: '#/components/schemas/CertificateOcspStatus'
        owner_id:
          type: string
          format: text
          description: client id of the owner member, <instance_id>:<member_class>:<member_code>
          example: FI:GOV:123
          minLength: 1
          maxLength: 767
          readOnly: true
        active:
          type: boolean
          description: if the certificate is active
          example: true
        saved_to_configuration:
          type: boolean
          description: if the certificate is saved to configuration
          example: true
        renewed_cert_hash:
          type: string
          format: text
          description: hash of the newer version of the certificate that is in the process of registration
          readOnly: true
        renewal_error:
          type: string
          format: text
          description: error message thrown during the certificate automatic renewal process
          readOnly: true
        ocsp_verify_before_activation_error:
          type: string
          format: text
          description: error message thrown when verifying ocsp responses before the certificate activation
          readOnly: true
        next_automatic_renewal_time:
          type: string
          format: date-time
          description: next planned automatic renewal time
          readOnly: true
        certificate_details:
          $ref: '#/components/schemas/CertificateDetails'
        status:
          $ref: '#/components/schemas/CertificateStatus'
        possible_actions:
          $ref: '#/components/schemas/PossibleActions'
    KeyUsage:
      type: string
      description: certificate key usage
      example: NON_REPUDIATION
      enum:
      - DIGITAL_SIGNATURE
      - NON_REPUDIATION
      - KEY_ENCIPHERMENT
      - DATA_ENCIPHERMENT
      - KEY_AGREEMENT
      - KEY_CERT_SIGN
      - CRL_SIGN
      - ENCIPHER_ONLY
      - DECIPHER_ONLY
    PossibleActions:
      type: array
      description: array containing the possible actions that can be done for this item
      items:
        $ref: '#/components/schemas/PossibleAction'
    CertificateStatus:
      type: string
      description: certificate status
      example: IN_USE
      enum:
      - SAVED
      - REGISTRATION_IN_PROGRESS
      - REGISTERED
      - DELETION_IN_PROGRESS
      - GLOBAL_ERROR
    PossibleAction:
      type: string
      description: an action to change state or edit token, key, cert or csr
      example: DELETE
      enum:
      - DELETE
      - ACTIVATE
      - DISABLE
      - LOGIN
      - LOGOUT
      - REGISTER
      - UNREGISTER
      - IMPORT_FROM_TOKEN
      - GENERATE_KEY
      - EDIT_FRIENDLY_NAME
      - GENERATE_AUTH_CSR
      - GENERATE_SIGN_CSR
      - TOKEN_CHANGE_PIN
      - TOKEN_DELETE
    KeyUsageType:
      type: string
      description: intended usage for the key (signing or authentication)
      example: AUTHENTICATION
      enum:
      - AUTHENTICATION
      - SIGNING
    KeyName:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: Friendly name of a key
          format: text
          minLength: 1
          maxLength: 255
      example:
        name: my-key-0
    CertificateOcspStatus:
      type: string
      description: certificate status
      example: IN_USE
      enum:
      - DISABLED
      - EXPIRED
      - OCSP_RESPONSE_UNKNOWN
      - OCSP_RESPONSE_GOOD
      - OCSP_RESPONSE_SUSPENDED
      - OCSP_RESPONSE_REVOKED
    Key:
      type: object
      description: Key for the certificate. Also includes the possible actions that can be done to this object, e.g DELETE (only for key related operations and does not consider user authorization).
      required:
      - id
      - name
      - label
      - certificates
      - certificate_signing_requests
      - key_algorithm
      properties:
        id:
          type: string
          format: text
          description: key id
          example: 0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF
          minLength: 1
          readOnly: true
        name:
          type: string
          format: text
          description: key name
          example: friendly name
          minLength: 1
          maxLength: 255
        label:
          type: string
          format: text
          description: key label
          example: key label
          minLength: 1
          maxLength: 255
        certificates:
          type: array
          description: list of certificates for the key
          items:
            $ref: '#/components/schemas/TokenCertificate'
        certificate_signing_requests:
          type: array
          description: list of CSRs for the key
          items:
            $ref: '#/components/schemas/TokenCertificateSigningRequest'
        usage:
          $ref: '#/components/schemas/KeyUsageType'
        available:
          type: boolean
          description: if the key is available
          example: true
        saved_to_configuration:
          type: boolean
          description: if the key is saved to configuration
          example: true
        possible_actions:
          $ref: '#/components/schemas/PossibleActions'
        key_algorithm:
          $ref: '#/components/schemas/KeyAlgorithm'
    CsrGenerate:
      type: object
      description: request to generate a CSR
      required:
      - key_usage_type
      - ca_name
      - csr_format
      - subject_field_values
      properties:
        key_usage_type:
          $ref: '#/components/schemas/KeyUsageType'
        ca_name:
          type: string
          format: text
          description: common name of the CA
          example: X-Road Test CA CN
          minLength: 1
          maxLength: 255
        csr_format:
          $ref: '#/components/schemas/CsrFormat'
        member_id:
          type: string
          format: text
          description: member client id for signing CSRs. <instance_id>:<member_class>:<member_code>
          example: FI:GOV:123
          minLength: 1
          maxLength: 767
        subject_field_values:
          type: object
          description: user-provided values for subject DN parameters
          additionalProperties:
            type: string
        acme_order:
          type: boolean
          default: false
          description: whether or not order certificate from acme server with the generated csr
    CsrFormat:
      type: string
      description: format of the certificate signing request (PEM or DER)
      example: PEM
      default: PEM
      enum:
      - PEM
      - DER
    TokenCertificateSigningRequest:
      type: object
      description: CSR for certificate that is stored in a Token. Also includes the possible actions that can be done to this object, e.g DELETE (only for csr related operations and does not consider user authorization).
      required:
      - id
      - owner_id
      - possible_actions
      properties:
        id:
          type: string
          format: text
          description: CSR id
          example: 0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF
          readOnly: true
        owner_id:
          type: string
          format: text
          description: client id of the owner member, <instance_id>:<member_class>:<member_code>
          example: FI:GOV:123
          minLength: 1
          maxLength: 767
          readOnly: true
        certificate_profile:
          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
          readOnly: true
        possible_actions:
          $ref: '#/components/schemas/PossibleActions'
    CertificateDetails:
      type: object
      description: certificate details for any kind of certificate (TLS, auth, sign)
      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
      properties:
        issuer_distinguished_name:
          type: string
          format: text
          description: certificate issuer distinguished name
          example: issuer123
          minLength: 1
          maxLength: 255
        issuer_common_name:
          type: string
          format: text
          description: certificate issuer common name
          example: domain.com
          minLength: 1
          maxLength: 255
        subject_distinguished_name:
          type: string
          format: text
          description: certificate subject distinguished name
          example: subject123
          minLength: 1
          maxLength: 255
        subject_common_name:
          type: string
          format: text
          description: certificate subject common name
          example: domain.com
          minLength: 1
          maxLength: 255
        not_before:
          type: string
          format: date-time
          description: certificate validity not before
          example: '2018-12-15T00:00:00.001Z'
          minLength: 24
          maxLength: 24
        not_after:
          type: string
          format: date-time
          description: certificate validity not after
          example: '2018-12-15T00:00:00.001Z'
          minLength: 24
          maxLength: 24
        serial:
          type: string
          format: text
          description: serial number
          example: '123456789'
          minLength: 1
          maxLength: 255
        version:
          type: integer
          format: int32
          example: 3
          description: version
        signature_algorithm:
          type: string
          format: sha-256
          description: certificate signature algorithm
          example: sha256WithRSAEncryption
          minLength: 1
          maxLength: 255
        signature:
          type: string
          format: text
          description: hex encoded certificate signature
          example: 30af2fdc1780...
          minLength: 1
          maxLength: 255
        public_key_algorithm:
          type: string
          format: sha-256
          description: certificate public key algorithm
          example: sha256WithRSAEncryption
          minLength: 1
          maxLength: 255
        rsa_public_key_modulus:
          type: string
          format: hex
          description: hex encoded RSA public key modulus (if RSA key)
          example: c44421d601...
          minLength: 1
          maxLength: 1000
        rsa_public_key_exponent:
          type: integer
          format: int32
          description: RSA public key exponent (if RSA key) as an integer
          example: 65537
        ec_public_parameters:
          description: EC public key 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
        hash:
          type: string
          format: text
          description: certificate SHA-256 hash
          example: 1234567890ABCDEF
          minLength: 1
          maxLength: 64
        key_usages:
          type: array
          description: certificate key usage array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/KeyUsage'
        subject_alternative_names:
          type: string
          format: text
          description: certificate subject alternative names
          example: DNS:*.example.org
          minLength: 1
          maxLength: 1000
  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