Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Minor

READY TO BE PUBLISHED

This article describes the Certificate Manager REST API (RESTful application programming interface) in Nexus Certificate Manager.

Certificate Manager REST API (RESTful application programming interface) is an HTTP-based service for x.509 and attribute certificates creation, certificate searching, certificate download, certificate revocation, certificate reinstatement, creation of PKCS#12 files and token procedure listing in Certificate Manager. 

The API requires client authentication over TLS using a CM officer certificate. Write operations like revoke, reinstate and certificate issuance requires the request data to be signed by a CM officer. The REST API server can also be configured to use a CM officer for signing the requests on the caller’s behalf, enabling automated services for trusted clients.

See also Example: Certificate Manager (CM) REST API configuration in Protocol Gateway. 

Date-time format

The expected date-time format for time search fields is ISO 8601. Example: 2021-12-20T08:01:30Z.


Note

This article only contains plain documentation of the Certificate Manager REST API. It is not possible to try out the commands. 


This article is valid for Certificate Manager 8.7.0 and later.

Related information

Children Display



Open API Documentation
openapi: 3.0.0
info:
  title: CM REST API
  version: "1.0"
  description: |
    The CM REST API is a HTTP-based service used for interacting with CM.
    It supports ways of performing certificate creation, searching, revocation,
    reinstatement, registrations and procedure listing through HTTP REST calls.

    ## HTTP Client Authentication
    The CM REST API requires TLS client authentication using a CM officer
    certificate, to identify the caller. The client TLS certificate must be
    an officer certificate, and must be issued by one of the CAs that are
    present in the PGWY Tomcat trust store. The officer must have all of the
    roles configured by the `requiredRoRoles` setting in `api.properties`.

    ## Signed requests
    Furthermore, operations that are sent to the CA that write or modify data,
    such as revoking, reinstating and issuing certificates requires the request
    data to be signed by a CM officer when sending the command to the CA.
    This signing can be done either by PGWY itself (VRO), or by PGWY requesting
    a signature from the caller. Signing by caller is the default.

    ### VRO signing
    To make PGWY sign such requests, PGWY must be configured to act as a Virtual
    Registration Officer (VRO) and thereby sign the requests on the caller's
    behalf. This is done by enabling server-side signing in the server
    configuration (`api.properties`).

    1. Example request with VRO signing:
        ```
        POST /certificates/pkcs10
        pkcs10=(binary data)
        ```

    2. Server response:
        ```
        (pkcs#7 data containing DER-encoded certificate)
        ```

    ### Signing by caller
    If PGWY is not configured to act as VRO, then all operations that require a
    signature will return the request data to the caller for signing using the
    CM officer's key. The request to sign is returned as the `dataToSign`
    json field, base64-encoded. The caller is then expected to sign the request
    and re-send the request with the signature in a field named `signature`.

    1. Example request with signature by caller:
        ```
        POST /certificates/pkcs10
        pkcs10=(binary data)
        ```

    2. Server response:
        ```
        Http Status: 200 (OK)
        {
          "error":-19,
          "msg":"Sign request and send again",
          "dataToSign":"MIIC8...Rva2Vu"
        }
        ```

    3. Caller signs request and sends again:
        ```
        POST /certificates/pkcs10
        pkcs10=(binary data)
        signature=(base64 encoded signature)
        ```

    4. Server response:
        ```
        (pkcs#7 data containing DER-encoded certificate)
        ```

    ### Implementation details and example code for caller signature
    Alongside this document are two examples on how to perform the CMS (PKCS#7)
    based signature of the 'dataToSign' blob. The signature requires that the
    original data (the 'dataToSign' blob) is encapsulated and that it is in
    DER-encoded format.

    1. OpenSSL:
        ```
        See accompanied file 'APISigningWithOpenSSL.sh'
        ```

    2. BouncyCastle:
        ```
        See accompanied file 'APISigningWithBouncyCastle.java'
        ```

servers:
  - url: https://{hostname}:{port}/{basePath}
    description: PGWY
    variables:
      hostname:
        default: localhost
      port:
        enum:
          - '8444'
          - '8443'
          - '443'
        default: '8444'
      basePath:
        default: pgwy/api

paths:
  /certificates:
    get:
      operationId: listCertificates
      summary: List certificates
      description: |
        Returns a list of certificates that match the provided search parameters.
      tags:
        - Certificates
      parameters:
        - $ref: '#/components/parameters/searchLimit'
        - $ref: '#/components/parameters/searchOffset'

        - name: cardSerialNumber
          in: query
          description: Serial number of the card the certificate is on.
          schema:
            type: string

        - $ref: '#/components/parameters/certificateSerialNumber'
        - $ref: '#/components/parameters/revocationTimeFrom'
        - $ref: '#/components/parameters/revocationTimeTo'
        - $ref: '#/components/parameters/revocationReason'
        - $ref: '#/components/parameters/isNotRevoked'

        - name: subjectCommonName
          in: query
          description: The common name ( CN ) of the subject of the certificate.
          schema:
            type: string

        - name: subjectGivenName
          in: query
          description: The given name ( GN ) of the subject of the certificate.
          schema:
            type: string

        - name: subjectSurName
          in: query
          description: The surname ( SN ) of the subject of the certificate.
          schema:
            type: string

        - name: subjectOrganisationName
          in: query
          description: The name of the organisation ( O ) of the subject of the certificate.
          schema:
            type: string

        - name: subjectOrganisationUnit
          in: query
          description: The name of the organisational unit ( OU ) of the subject of the certificate.
          schema:
            type: string

        - name: subjectSerialNumber
          in: query
          description: The serial number of the subject of the certificate.
          schema:
            type: string

        - name: subjectCountry
          in: query
          description: The country ( C ) of the subject of the certificate.
          schema:
            type: string

        - $ref: '#/components/parameters/publicationAllowed'
        - $ref: '#/components/parameters/publicationTimeFrom'
        - $ref: '#/components/parameters/publicationTimeTo'
        - $ref: '#/components/parameters/ocspActivationTimeFrom'
        - $ref: '#/components/parameters/ocspActivationTimeTo'
        - $ref: '#/components/parameters/validFromTimeFrom'
        - $ref: '#/components/parameters/validFromTimeTo'
        - $ref: '#/components/parameters/isNotYetValid'
        - $ref: '#/components/parameters/validToTimeFrom'
        - $ref: '#/components/parameters/validToTimeTo'
        - $ref: '#/components/parameters/isExpired'
        - $ref: '#/components/parameters/field1'
        - $ref: '#/components/parameters/field2'
        - $ref: '#/components/parameters/field3'
        - $ref: '#/components/parameters/field4'
        - $ref: '#/components/parameters/field5'
        - $ref: '#/components/parameters/field6'
        - $ref: '#/components/parameters/authorityKeyIdentifier'
        - $ref: '#/components/parameters/subjectKeyIdentifier'
        - $ref: '#/components/parameters/subjectType'

        - name: issuer
          in: query
          description: |
            Only return certificates whose issuer matches the provided DN.
            The value must be a URL encoded RFC1779 string.
            Example: issuer=cn%3DExample%20CM%20issuing%20CA%2Co%3DExample%20CM%2Cc%3DSE
          schema:
            type: string
            format: RFC1779 distinguished name string.

      responses:
        200:
          description: OK - Returns an array of certificates.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: "#/components/schemas/ApiResponse_Error"
                  msg:
                    $ref: "#/components/schemas/ApiResponse_Msg"
                  searchHits:
                    description: |
                      The total number of search hits that the given search
                      parameters would yield without pagination.
                    type: integer
                  certificates:
                    description: Array of certificates
                    type: array
                    items:
                      $ref: "#/components/schemas/JsonCertificate"
              example:
                error: 0
                msg:  "Fetched certificates"
                searchHits: 476
                certificates: [
                  {
                    subject:  "Super Officer 1, System, SE",
                    validfrom: 1475849262000,
                    certid:  "10003",
                    certificateserialnumber:  "31e96265e40b809cffa3862b073ae98b",
                    subjectType: EE,
                    validto: 1633615659000,
                    status:  "active"
                  }
                ]
        500:
          description: Internal server error - An unexpected error occurred.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
              example:
                error: -14
                msg: Too many hits

  /certificates/issuers:
    get:
      deprecated: true
      operationId: listIssuers
      summary: List available issuers
      description: |
        Returns a list of distinguished names of issuer CAs that match the provided search parameters.
      tags:
        - Certificates
      parameters:
        - $ref: '#/components/parameters/searchLimit'
        - $ref: '#/components/parameters/searchOffset'
        - $ref: '#/components/parameters/certificateSerialNumber'
        - $ref: '#/components/parameters/revocationTimeFrom'
        - $ref: '#/components/parameters/revocationTimeTo'
        - $ref: '#/components/parameters/revocationReason'
        - $ref: '#/components/parameters/publicationAllowed'
        - $ref: '#/components/parameters/publicationTimeFrom'
        - $ref: '#/components/parameters/publicationTimeTo'
        - $ref: '#/components/parameters/ocspActivationTimeFrom'
        - $ref: '#/components/parameters/ocspActivationTimeTo'
        - $ref: '#/components/parameters/validFromTimeFrom'
        - $ref: '#/components/parameters/validFromTimeTo'
        - $ref: '#/components/parameters/isNotYetValid'
        - $ref: '#/components/parameters/validToTimeFrom'
        - $ref: '#/components/parameters/validToTimeTo'
        - $ref: '#/components/parameters/isExpired'

      responses:
        200:
          description: OK - Returns an array of issuer subjects.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: "#/components/schemas/ApiResponse_Error"
                  msg:
                    $ref: "#/components/schemas/ApiResponse_Msg"
                  searchHits:
                    description: |
                      The total number of search hits that the given search
                      parameters would yield without pagination.
                    type: integer
                  subjects:
                    description: Array of certificate issuer DNs.
                    type: array
                    items:
                      $ref: "#/components/schemas/JsonIssuer"
              example:
                error: 0
                msg: "Fetched issuers"
                searchHits: 476
                issuers: [
                  {
                    subjectDn: "cn=Example CM CA,o=Example CM,c=SE",
                    subject: {
                      cn: "Example CM CA",
                      o: "Example CM",
                      c: "SE"
                    }
                  }
                ]
        500:
          description: Internal server error - An unexpected error occurred.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
              example:
                error: -14
                msg: Too many hits

  /certificates/{certid}/details:
    get:
      operationId: getCertificateDetails
      summary: Certificate details
      description: |
        Returns information about the certificate with the provided id.
      tags:
        - Certificates
      parameters:
        - name: certid
          in: path
          description: Certificate id
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK - Returns details about the requested certificate.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: "#/components/schemas/ApiResponse_Error"
                  msg:
                    $ref: "#/components/schemas/ApiResponse_Msg"
                  certificate:
                    $ref: "#/components/schemas/JsonCertificate"
              example:
                error: 0
                msg:  "Fetched certificate"
                certificate:
                  subject:  "Super Officer 2, System, SE"
                  validfrom: 1475849262000
                  certid:  "10003"
                  certificateserialnumber:  "31e96265e40b809cffa3862b073ae98b"
                  subjectType: EE
                  validto: 1633615659000
                  status:  "active"
        500:
          description: Internal server error - An unexpected error occurred.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
              example:
                error: -14
                msg: "No certificate found"

  /certificates/{certid}/download:
    get:
      operationId: downloadCertificate
      summary: Download certificate
      description: |
        Returns a certificate in binary form. For X.509 certificates, the
        returned certificate encoding may be DER, PEM or MIME (pkcs#7),
        depending on the media type in the provided Accept header.
      tags:
        - Certificates
      parameters:
        - name: certid
          in: path
          description: Certificate ID.
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK - Returns the requested certificate.
          content:
            application/pkix-cert:
              schema:
                type: string
                format: binary
            application/pkcs7-mime:
              schema:
                type: string
                format: binary
            application/pem-certificate-chain:
              schema:
                description: Returns full chain including <br> certificate specified by certid.
                type: string
                format: binary
            application/pem-certificate-chain;depth=<value>:
              schema:
                description: ;depth=0<br>Returns full chain including <br> certificate specified by certid. <br><br> ;depth=1<br>Returns certificate specified by certid. <br><br> ;depth=value bigger than 1<br>Returns part of the chain <br> up to the given depth value, if the depth value is <br> bigger than the number of certificates in the chain <br> it returns the full chain.
                type: string
                format: binary
        500:
          description: Internal server error - An unexpected error occurred.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
              example:
                error: -14
                msg: "No certificate found"

  /certificates/revoke:
    post:
      operationId: revokeCertificate
      summary: Revoke certificate
      description: Revokes the certificate(s) with the matching certificate id(s).
      tags:
        - Certificates
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                certid:
                  description: Certificate id(s) to revoke.
                  type: array
                  items:
                    type: string
                reason:
                  $ref: "#/components/schemas/ApiRequest_RevocationReason"
                signature:
                  $ref: "#/components/schemas/ApiRequest_Signature"
              required:
                - certid
                - reason

      responses:
        200:
          description: OK - Requested certificates were revoked.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: "#/components/schemas/ApiResponse_Error"
                  msg:
                    $ref: "#/components/schemas/ApiResponse_Msg"
              example:
                error: 0
                msg: "1 certificate(s) has been revoked"
        500:
          description: Internal server error - An unexpected error occurred.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponseWithCertIds"
              example:
                error: -1
                msg: "Error(s) occurred during the revocation"
                errors: [
                  {
                    certid: "1",
                    errorcode: 907,
                    errormessage: "The certificate was not found",
                    servererrormessage: "Certificate with certSerNr: 1 is not found."
                  }
                ]

  /certificates/reinstate:
    post:
      operationId: reinstateCertificate
      summary: Reinstate certificate
      description: Reinstates the certificate(s) with the matching certificate id(s).
      tags:
        - Certificates
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                certid:
                  description: Certificate id(s) to reinstate
                  type: array
                  items:
                    type: string
                signature:
                  $ref: "#/components/schemas/ApiRequest_Signature"
              required:
                - certid
      responses:
        200:
          description: OK - Requested certificates were reinstated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: "#/components/schemas/ApiResponse_Error"
                  msg:
                    $ref: "#/components/schemas/ApiResponse_Msg"
              example:
                error: 0
                msg: "1 certificate(s) has been reinstated"
        500:
          description: Internal server error - An unexpected error occurred.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponseWithCertIds"
              example:
                error: -1
                msg: "Error(s) occurred during the reinstatement"
                errors: [
                  {
                    certid: "1",
                    errorcode: 907,
                    errormessage: "The certificate was not found",
                    servererrormessage: "Certificate with certSerNr: 1 is not found."
                  }
                ]

  /certificates/pkcs10:
    post:
      operationId: issueCertificatePkcs10
      summary: Create certificate from PKCS10 request
      description: |
        Creates a certificate from a PKCS10 request and returns the result as either
        PKCS7 or X.509 DER or PEM encoded depending on the Accept HTTP header.
        The PKCS#7 and PEM results will contain the chain if the token procedure
        had store all. Otherwise, will return only the end certificate.
      tags:
        - Certificates
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                pkcs10:
                  description: PKCS10 request (Base64 encoded)
                  type: string
                  format: byte
                validfrom:
                  description: |
                    X.509 "not before" point in time. Format 'ISO 8601'.
                    Example: 2007-03-01T13:00:00Z
                  type: string
                  format: date-time
                validto:
                  description: |
                    X.509 "not after" point in time. Format 'ISO 8601'.
                    Example: 2008-05-11T15:30:00Z
                  type: string
                  format: date-time
                procname:
                  description: |
                    Name of token procedure that should be used to issue the
                    certificate. If this parameter is not given, a default value
                    set in the server side configuration will be used
                    (`handler.(n).tokenprocedure` in `api.properties`).
                  type: string
                signature:
                  $ref: "#/components/schemas/ApiRequest_Signature"
              required:
                - pkcs10
            encoding:
              pkcs10:
                contentType: application/pkcs10
      responses:
        200:
          description: OK - Returns a PKCS7 message or X509 the issued certificate.
          content:
            application/pkcs7-mime:
              schema:
                type: string
                format: binary
            application/pkix-cert:
              schema:
                type: string
                format: binary
            application/pem-certificate-chain:
              schema:
                type: string
                format: binary
        500:
          description: Internal server error - An unexpected error occurred.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"

  /certificates/pkcs10-to-pkcs12:
    post:
      operationId: issueCertificatePkcs10ToPkcs12
      summary: Issue certificate to PKCS#12 from PKCS#10 request
      description: |
        Issues a certificate from a PKCS#10 request and returns the result as
        PKCS#12.

        This endpoint is used to issue certificates for keys that are generated
        server-side by CM. For these cases, this endpoint is by default
        configured to accept unsigned PKCS#10 requests that only contain the TBS
        parts, and by default configured to discard the public key part
        specified in the PKCS#10 request. To generate the key on the
        server-side, the token procedure should specify an applicable key
        procedure.
      tags:
        - Certificates
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                pkcs10:
                  description: PKCS10 request (Base64 encoded).
                  type: string
                  format: byte
                validfrom:
                  description: |
                    X.509 "not before" point in time. Format 'ISO 8601'.
                    Example: 2007-03-01T13:00:00Z
                  type: string
                  format: date-time
                validto:
                  description: |
                    X.509 "not after" point in time. Format 'ISO 8601'.
                    Example: 2008-05-11T15:30:00Z
                  type: string
                  format: date-time
                password:
                  description: |
                    Password to be used to protect the resulting PKCS12 archive.
                    If this parameter is not given, the password will be
                    generated by the server.
                  type: string
                  format: password
                procname:
                  description: |
                    Name of token procedure that should be used to issue the
                    certificate. If this parameter is not given, a default value
                    set in the server side configuration will be used
                    (`handler.(n).tokenprocedure` in `api.properties`).
                  type: string
                signature:
                  $ref: "#/components/schemas/ApiRequest_Signature"
              required:
                - pkcs10
            encoding:
              pkcs10:
                contentType: application/pkcs10
      responses:
        200:
          description: OK - Returns a PKCS12 archive with the issued certificate and key.
          content:
            application/x-pkcs12:
              schema:
                type: string
                format: binary
        500:
          description: Internal server error - An unexpected error occurred.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"

  /certificates/{certid}/pkcs10-to-attr-cert:
    post:
      operationId: issueCertificatePkcs10ToAttrCert
      summary: Issue certificate to PKCS#7 or X.509 containing attribute certificate
               from PKCS#10 request
      description: |
        Issues an attribute certificate from a PKCS#10 request and returns the result as
        PKCS#7 or X.509 DER or PEM encoded depending on the Accept HTTP header.
        The PKCS#7 and PEM results will contain the chain if the token procedure
        had store all. Otherwise, will return only the end certificate.

        This endpoint is used to issue attribute certificates that are generated for
        a base certificate on server-side by CM. For these cases, this endpoint is by default
        configured to accept unsigned PKCS#10 requests that only contain the TBS
        parts. A public key is required by PKCS#10, while it is not required for issuing the
        attribute certificate. Therefore, by default the endpoint is configured to discard
        the public key part specified in the PKCS#10 request as it is not required.
      tags:
        - Certificates
      parameters:
        - $ref: '#/components/parameters/certid'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                pkcs10:
                  description: PKCS10 request (Base64 encoded).
                  type: string
                  format: byte
                validfrom:
                  description: |
                    X.509 "not before" point in time. Format 'ISO 8601'.
                    Example: 2007-03-01T13:00:00Z
                  type: string
                  format: date-time
                validto:
                  description: |
                    X.509 "not after" point in time. Format 'ISO 8601'.
                    Example: 2008-05-11T15:30:00Z
                  type: string
                  format: date-time
                procname:
                  description: |
                    Name of token procedure that should be used to issue the
                    attribute certificate. If this parameter is not given, a default
                    value set in the server side configuration will be used
                    (`handler.(n).tokenprocedure` in `api.properties`).
                  type: string
                signature:
                  $ref: "#/components/schemas/ApiRequest_Signature"
              required:
                - pkcs10
            encoding:
              pkcs10:
                contentType: application/pkcs10
      responses:
        200:
          description: OK - Returns a PKCS7 archive with the issued attribute certificate.
          content:
            application/pkcs7-mime:
              schema:
                type: string
                format: binary
            application/pkix-cert:
              schema:
                type: string
                format: binary
            application/pem-certificate-chain:
              schema:
                type: string
                format: binary
        500:
          description: Internal server error - An unexpected error occurred.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"

  /certificates/skip:
    post:
      operationId: secureKeyInjectionPackage
      summary: Create a secure key injection package from a PKCS10 request
      description: |
        Creates a secure key package for IoT devices from a PKCS10 request
        and return the result as PKCS7.

        The PKCS10 request only need to include the public key and subject
        information and no other request data.
        The PKCS7 response content is an ASN.1 encoded list of the generated
        device keypairs, KeyPairContainers, where the public key is an encoded
        SubjectPublicKeyInfo (RFC 5280), and the private key is an encoded
        EncryptedPrivateKeyInfo (RFC 5958).

            KeyPairContainers ::= SEQUENCE OF KeyPairContainer
            KeyPairContainer ::= SEQUENCE {
                public SubjectPublicKeyInfo,
                encryptedPrivate EncryptedPrivateKeyInfo
            }
      tags:
        - Certificates
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                pkcs10:
                  description: |
                    PKCS10 request (Base64 encoded) containing the initial
                    public key and subject information.
                  type: string
                  format: byte
                validfrom:
                  description: |
                    X.509 "not before" point in time. Format 'ISO 8601'.
                    Example: 2007-03-01T13:00:00Z
                  type: string
                  format: date-time
                validto:
                  description: |
                    X.509 "not after" point in time. Format 'ISO 8601'.
                    Example: 2008-05-11T15:30:00Z
                  type: string
                  format: date-time
                procname:
                  description: |
                    Name of token procedure that should be used to issue the
                    certificate. If this parameter is not given, a default value
                    set in the server side configuration will be used
                    (`handler.(n).tokenprocedure` in `api.properties`).
                  type: string
                signature:
                  $ref: "#/components/schemas/ApiRequest_Signature"
              required:
                - pkcs10
            encoding:
              pkcs10:
                contentType: application/pkcs10
      responses:
        200:
          description: OK - Returns a PKCS7 message with the issued certificate.
          content:
            application/pkcs7-mime:
              schema:
                type: string
                format: binary
        500:
          description: Internal server error - An unexpected error occurred.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"

  /certificates/import-pki-x509:
    post:
      operationId: importPKIX509
      summary: Import externally issued X.509 certificates
      description: |
        Imports X.509 certificates from an external PKI.

        This endpoint is used to import certificate(s) to CM issued by an
        external PKI. Each imported certificate may be complemented with
        revocation information, such as reason code and time of revocation.

        The request may specify a token procedure, which must be connected to a
        CA with a SubjectDN matching imported certificates IssuerDN.
        If no Token Procedure is specified, a default is used by the server.
      tags:
        - Certificates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                procname:
                  description: |
                    Name of token procedure that should be used to issue the
                    certificate. If this parameter is not given, a default value
                    set in the server side configuration will be used.
                  type: string
                importdata:
                  description: |
                    Array of certificate(s) to import.
                  type: array
                  items:
                    type: object
                    properties:
                      certificate:
                        description: |
                          Base64 encoded certificate.
                        type: string
                        format: byte
                      reason:
                        $ref: "#/components/schemas/ApiRequest_RevocationReason"
                      revocationtime:
                        description: |
                          Point in time when the certificate was revoked.
                        type: string
                        format: date-time
                    required:
                      - certificate
                signature:
                  $ref: "#/components/schemas/ApiRequest_Signature"
              required:
                - importdata
      responses:
        200:
          description: OK - successfully imported all certificates
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: "#/components/schemas/ApiResponse_Error"
                  msg:
                    $ref: "#/components/schemas/ApiResponse_Msg"
              example:
                error: 0
                msg: "1 certificate(s) has been imported"
        500:
          description: Internal server error - An unexpected error occurred.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponseWithJsonArrayIndex"
              example:
                error: -1
                msg: "Error(s) occurred during the PKI import"
                errors: [
                  {
                    arrayindex: 0,
                    errorcode: -14,
                    errormessage: "Duplicated certificate import entry",
                  },
                  {
                    arrayindex: 1,
                    errorcode: -14,
                    errormessage: "Unable to import certificate",
                    servererrormessage: "Invalid certificate issuer"
                  },
                  {
                    arrayindex: 2,
                    errorcode: -40,
                    errormessage: "Maximum import limit exceeded",
                    limit: 1
                  }
                ]

  /procedures:
    get:
      operationId: listProcedures
      summary: List procedures
      description: |
        Lists all token procedures that are available for the authenticated officer.
      tags:
        - Procedures
      responses:
        200:
          description: OK - Returns the list of available token procedures.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: "#/components/schemas/ApiResponse_Error"
                  msg:
                    $ref: "#/components/schemas/ApiResponse_Msg"
                  procedures:
                    description: Array of token procedures.
                    type: array
                    items:
                      type: object
                      properties:
                        procid:
                          type: string
                          description: Unique ID of the procedure.
                        name:
                          type: string
                          description: Human-readable name of the procedure.
              example:
                error: 0
                msg: "Fetched procedures"
                procedures: [
                  {
                    procid: "t-scep-registr-visible-p10",
                    name: "SCEP Registration Visible Procedure"
                  }
                ]
        500:
          description: Internal server error - An unexpected error occurred.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
              example:
                error: -1
                msg: "No procedures found"

  /registrations/{procid}:
    get:
      operationId: listRegistrations
      summary: List registrations
      description: |
        The registrations endpoint returns a list of registrations done on the
        procedure with the matching token procedure id and, if given, the other
        optional parameters.
      tags:
        - Registrations
      parameters:
        - $ref: '#/components/parameters/procid'
        - $ref: '#/components/parameters/regid'
        - $ref: '#/components/parameters/fqdn'
        - $ref: '#/components/parameters/status'
        - $ref: '#/components/parameters/validity'
        - $ref: '#/components/parameters/officer'
        - $ref: '#/components/parameters/regtype'
      responses:
        200:
          description: OK - Returns all registrations matching the given query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistrationResponseGet'
              example:
                registrations:
                  - regid: akZShn8u3qcOetstcL7eyfD05Tk=
                    fqdn: 'test-1-170645'
                    creationdate: 1565096805000
                    status: closed
                    regtype: cmp
                    validity: 7
                error: 0
                msg: Fetched registrations
        500:
          $ref: '#/components/responses/ServerError'

    post:
      operationId: createRegistration
      summary: Creates registration
      description: |
        Either body OR file must be set.
      tags:
        - Registrations
      parameters:
        - $ref: '#/components/parameters/procid'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRegistration'
            example:
              fqdn: "Device Test"
              regtype: "cmp"
              status: "open"
              validity: "7"
              signature: "MIIFuwYJK..."
      responses:
        200:
          $ref: '#/components/responses/RegistrationPost200'
        500:
          $ref: '#/components/responses/RegistrationPost500'

    put:
      operationId: updateRegistration
      summary: Update registration
      description: |
        Updates a registration with the given data.
      tags:
        - Registrations
      parameters:
        - $ref: '#/components/parameters/procid'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRegistration'
            example:
              regid: "regid-1234"
              status: "open"
              validity: "always"
              signature: "MIIFuwYJK..."
      responses:
        200:
          $ref: '#/components/responses/RegistrationUpdate200'
        500:
          $ref: '#/components/responses/RegistrationUpdate500'

  /registrations/certificate/{certid}:
    get:
      operationId: getRegistrationsCertId
      summary: Retrieves the registration that issued the certificate.
      description: Retrieves the registration that issued the certificate.
      tags:
        - Registrations
      responses:
        200:
          description: OK - Returns the registration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistrationCertId'
        500:
          $ref: '#/components/responses/ServerError'
      parameters:
        - $ref: '#/components/parameters/certid'

  /registrations/{procid}/scep:
    get:
      operationId: listRegistrationsScep
      summary: List registrations under SCEP
      description: |
        The SCEP registrations endpoint returns a list of registrations done on the
        procedure with the matching token procedure id and, if given, the other
        optional parameters.
      tags:
        - Registrations/{procid}/SCEP
      responses:
        200:
          description: OK - Returns all registrations matching the given query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistrationResponseGet'
              example:
                registrations:
                  - regid: CGEMNL39wUEB/srVptVCKYyD2nA=
                    fqdn: 'test-*.example.com'
                    creationdate: 1572490820000
                    officer: Super Officer 2
                    status: open
                    regtype: scep
                    validity: always
                    encryptedpassword: MIIB...3yv6
                error: 0
                msg: Fetched registrations
        500:
          $ref: '#/components/responses/ServerError'
      parameters:
        - $ref: '#/components/parameters/procid'
        - $ref: '#/components/parameters/regid'
        - $ref: '#/components/parameters/fqdn'
        - $ref: '#/components/parameters/status'
        - $ref: '#/components/parameters/validity'
        - $ref: '#/components/parameters/officer'

    post:
      operationId: createRegistrationScep
      summary: Creates registration for SCEP
      description: |
        Either body OR file must be set.
      tags:
        - Registrations/{procid}/SCEP
      parameters:
        - $ref: '#/components/parameters/procid'
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/RegistrationScep'
              required:
                - fqdn
                - password
            example:
              fqdn: "SCEP-1234"
              password: "1234"
              status: "open"
              validity: "always"
              signature: "MIIFuwYJK..."
      responses:
        200:
          $ref: '#/components/responses/RegistrationPost200'
        500:
          $ref: '#/components/responses/RegistrationPost500'

    put:
      operationId: updateRegistrationScep
      summary: Updates registration for SCEP
      description: |
        Updates a registration with the given data for SCEP protocol.
      tags:
        - Registrations/{procid}/SCEP
      parameters:
        - $ref: '#/components/parameters/procid'
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/RegistrationScep'
              required:
                - regid
            example:
              regid: "regid-1234"
              status: "open"
              validity: "7"
              signature: "MIIFuwYJK..."
      responses:
        200:
          $ref: '#/components/responses/RegistrationUpdate200'
        500:
          $ref: '#/components/responses/RegistrationUpdate500'

  /registrations/{procid}/est:
    get:
      operationId: listRegistrationsEst
      summary: List registrations for EST
      description: |
        The EST registrations endpoint returns a list of registrations done on the
        procedure with the matching token procedure id, and if given, the other
        optional parameters.
      tags:
        - Registrations/{procid}/EST
      responses:
        200:
          description: OK - Returns all registrations matching the given query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistrationResponseGet'
              example:
                registrations:
                  - regid: 2YLD25xzE9BW84WdhRSsNFyNTvk=
                    fqdn: 'APIClientTest_-1835737403'
                    creationdate: 1572490406000
                    officer: Super Officer 1
                    status: open
                    regtype: est
                    validity: always
                    encryptedpassword: MIIB...IX9m
                error: 0
                msg: Fetched registrations

        500:
          $ref: '#/components/responses/ServerError'
      parameters:
        - $ref: '#/components/parameters/procid'
        - $ref: '#/components/parameters/regid'
        - $ref: '#/components/parameters/fqdn'
        - $ref: '#/components/parameters/status'
        - $ref: '#/components/parameters/validity'
        - $ref: '#/components/parameters/officer'

    post:
      operationId: createRegistrationEst
      summary: Creates registration for EST
      description: |
        Either body OR file must be set.
      tags:
        - Registrations/{procid}/EST
      parameters:
        - $ref: '#/components/parameters/procid'
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
                - $ref: '#/components/schemas/RegistrationEstHttpAuth'
                - $ref: '#/components/schemas/RegistrationEstCertAuth'
              required:
                - fqdn
            examples:
              http-authentication:
                value:
                  fqdn: "*.ad.example.com"
                  password: "1234"
                  status: "open"
                  validity: "7"
                  signature: "MIIFuwYJK..."
              certificate-authentication:
                value:
                  fqdn: "my.authentication.certificate"
                  subject-commonname: "my.commonname.in.csr"
                  status: "open"
                  validity: "7"
                  signature: "MIIFuwYJK..."
      responses:
        200:
          $ref: '#/components/responses/RegistrationPost200'
        500:
          $ref: '#/components/responses/RegistrationPost500'

    put:
      operationId: updateRegistrationEst
      summary: Updates registration for EST
      description: |
        Updates a registration with the given data for EST protocol.
      tags:
        - Registrations/{procid}/EST
      parameters:
        - $ref: '#/components/parameters/procid'
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
                - $ref: '#/components/schemas/RegistrationEstHttpAuth'
                - $ref: '#/components/schemas/RegistrationEstCertAuth'
              required:
                - regid
            examples:
              http-authentication:
                value:
                  regid: "regid-1234"
                  fqdn: "*.ad.example.com"
                  status: "closed"
                  validity: "7"
                  signature: "MIIFuwYJK..."
              certificate-authentication:
                value:
                  regid: "regid-1234"
                  fqdn: "my.authentication.certificate"
                  subject-commonname: "my.new.commonname.in.csr"
                  status: "open"
                  validity: "3"
                  signature: "MIIFuwYJK..."

      responses:
        200:
          $ref: '#/components/responses/RegistrationUpdate200'
        500:
          $ref: '#/components/responses/RegistrationUpdate500'

  /registrations/{procid}/cmp:
    get:
      operationId: listRegistrationsCmp
      summary: List registrations for CMP
      description: |
        The CMP registrations endpoint returns a list of registrations done on the
        procedure with the matching token procedure id, and if given, the other
        optional parameters.
      tags:
        - Registrations/{procid}/CMP
      responses:
        200:
          description: OK - Returns all registrations matching the given query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistrationResponseGet'
              example:
                registrations:
                  - regid: JS2rc9cTa1jlAXxHdANTg7YEvu4=
                    fqdn: '*.vendor.com'
                    creationdate: 1572490601000
                    officer: Super Officer 2
                    status: open
                    regtype: cmp
                    validity: always
                    encryptedpassword: MIIB...fJ8D
                error: 0
                msg: Fetched registrations
        500:
          $ref: '#/components/responses/ServerError'
      parameters:
        - $ref: '#/components/parameters/procid'
        - $ref: '#/components/parameters/regid'
        - $ref: '#/components/parameters/fqdn'
        - $ref: '#/components/parameters/status'
        - $ref: '#/components/parameters/validity'
        - $ref: '#/components/parameters/officer'

    post:
      operationId: createRegistrationCmp
      summary: Creates registration for CMP
      description: |
        Either body OR file must be set.
      tags:
        - Registrations/{procid}/CMP
      parameters:
        - $ref: '#/components/parameters/procid'
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/RegistrationCmp'
              required:
                - fqdn
            example:
              fqdn: "*.ad.example.com"
              status: "open"
              validity: "7"
              signature: "MIIFuwYJK..."
      responses:
        200:
          $ref: '#/components/responses/RegistrationPost200'
        500:
          $ref: '#/components/responses/RegistrationPost500'

    put:
      operationId: updateRegistrationCmp
      summary: Updates registration for CMP
      description: |
        Updates a registration with the given data for CMP protocol.
      tags:
        - Registrations/{procid}/CMP
      parameters:
        - $ref: '#/components/parameters/procid'
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/RegistrationCmp'
              required:
                - regid
            example:
              regid: "regid-1234"
              fqdn: "*.ad.example.com"
              status: "open"
              validity: "7"
              signature: "MIIFuwYJK..."
      responses:
        200:
          $ref: '#/components/responses/RegistrationUpdate200'
        500:
          $ref: '#/components/responses/RegistrationUpdate500'

  /registrations/{procid}/acme:
    get:
      operationId: listRegistrationsAcme
      summary: List registrations for ACME
      description: |
        The ACME registrations endpoint returns a list of registrations done on the
        procedure with the matching token procedure id, and if given, the other
        optional parameters.
      tags:
        - Registrations/{procid}/ACME
      responses:
        200:
          description: OK - Returns all registrations matching the given query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistrationResponseAcmeGet'
              example:
                registrations:
                  - regid: 4Lvs8mYrqi73CcZjt5UFfiIa4kc=
                    fqdn: 'keyId-63453491'
                    creationdate: 1572490404000
                    officer: Super Officer 1
                    status: open
                    regtype: acme
                    validity: always
                error: 0
                msg: Fetched registrations
        500:
          $ref: '#/components/responses/ServerError'
      parameters:
        - $ref: '#/components/parameters/procid'
        - $ref: '#/components/parameters/regid'
        - $ref: '#/components/parameters/fqdn'
        - $ref: '#/components/parameters/status'
        - $ref: '#/components/parameters/validity'
        - $ref: '#/components/parameters/officer'

    post:
      operationId: createRegistrationAcme
      summary: Creates registration for ACME
      description: |
        Either body OR file must be set.
      tags:
        - Registrations/{procid}/ACME
      parameters:
        - $ref: '#/components/parameters/procid'
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/RegistrationAcme'
              required:
                - fqdn
                - hmacKey
            example:
              fqdn: "*.ad.example.com"
              hmacKey: "PSuC...Zoi8"
              status: "open"
              validity: "7"
              signature: "MIIFuwYJK..."
      responses:
        200:
          $ref: '#/components/responses/RegistrationPost200'
        500:
          $ref: '#/components/responses/RegistrationPost500'

    put:
      operationId: updateRegistrationAcme
      summary: Updates registration for ACME
      description: |
        Updates a registration with the given data for ACME protocol.
      tags:
        - Registrations/{procid}/ACME
      parameters:
        - $ref: '#/components/parameters/procid'
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/RegistrationAcme'
              required:
                - regid
            example:
              regid: "regid-1234"
              fqdn: "*.ad.example.com"
              status: "open"
              validity: "7"
              signature: "MIIFuwYJK..."
      responses:
        200:
          $ref: '#/components/responses/RegistrationUpdate200'
        500:
          $ref: '#/components/responses/RegistrationUpdate500'

  /registrations/{procid}/acme/accounts:
    get:
      operationId: listAcmeAccounts
      summary: Lists ACME accounts.
      description: |
        Lists all ACME accounts from a registration. Search can be limited
        by using the query parameter 'accountid'.
      tags:
        - Registrations/{procid}/ACME
      parameters:
        - $ref: '#/components/parameters/procid'
        - $ref: '#/components/parameters/accountid'
      responses:
        200:
          description: OK - Account(s) successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
              example:
                registrations:
                  - regid: 4Lvs8mYrqi73CcZjt5UFfiIa4kc=
                    fqdn: 'CnY9c9OuvSEHGT3cfRkBlQ'
                    creationdate: 1575278296000
                    officer: Super Officer 1
                    status: Active
                    keyid: 'keyId-644251404'
                    email: acme@example.com
                    regType: 'acme/account'
                    certIds: [10050, 10051, 11302]
                error: 0
                msg: Fetched registrations
        500:
          description: Error - Failed to retrieve accounts
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
              example:
                error: -14
                msg: "Code -14, invalid procedure id"

components:
  schemas:
    ApiResponse_Error:
      type: integer
      description: |
        Non-zero error code if the request could not be processed, or zero
        if there was no error.
        Possible values:

        *   0 = Ok
        *  -1 = General error
        *  -7 = Missing field
        *  -8 = Encoding error
        * -12 = Not initialized
        * -14 = Bad field value
        * -15 = Privilige error
        * -17 = Bad signature
        * -18 = Connection error
        * -19 = Signature required
        * -40 = Too many requests
    ApiResponse_Msg:
      type: string
      description: Developer message describing the outcome of the request.

    ApiRequest_Signature:
      type: string
      description: |
        Signed request (Base64 encoded).
        Only used when CM REST API is configured to not use VRO signing.
      format: byte
      writeOnly: true

    ApiRequest_RevocationReason:
      type: integer
      minimum: 0
      maximum: 10
      description: |
        Revocation reason code mapping
        * 0: Unspecified
        * 1: Key Compromise
        * 3: Affiliation Changed
        * 4: Superseded
        * 5: Cessation Of Operation
        * 6: Certificate Hold
        * 9: Privilege Withdrawn

    ApiErrorResponse:
      type: object
      properties:
        error:
          $ref: "#/components/schemas/ApiResponse_Error"
        msg:
          $ref: "#/components/schemas/ApiResponse_Msg"

    ApiErrorResponseWithCertIds:
      type: object
      properties:
        error:
          $ref: "#/components/schemas/ApiResponse_Error"
        msg:
          $ref: "#/components/schemas/ApiResponse_Msg"
        errors:
          type: array
          items:
            type: object
            properties:
              certid:
                description: Certificate ID.
                type: string
              errorcode:
                description: |
                  Integer code of the problem that prevented this
                  certificate ID from being processed.
                  Possible values:

                  * 901 = Already Revoked
                  * 902 = Access Denied
                  * 903 = Incorrect Password
                  * 904 = Free text (non specific errorcode)
                  * 906 = Already on hold
                  * 907 = Certificate missing
                  * 908 = Request not signed
                  * 909 = Not visible from domain
                  * 910 = Not on hold
                  * 911 = Revocation not available extension
                  *  -1 = General error
                type: integer
              errormessage:
                description: |
                  Developer message describing the problem that
                  prevented this certificate ID from being
                  processed.
                type: string
              servererrormessage:
                description: |
                  Developer message given by the server.
                type: string

    ApiErrorResponseWithJsonArrayIndex:
      type: object
      properties:
        error:
          $ref: "#/components/schemas/ApiResponse_Error"
        msg:
          $ref: "#/components/schemas/ApiResponse_Msg"
        errors:
          type: array
          items:
            type: object
            properties:
              arrayindex:
                description: |
                  Indicates the index position of the failed certificate import.
                type: integer
              errorcode:
                description: |
                  Integer code of the problem that prevented this
                  certificate ID from being processed.
                type: integer
              errormessage:
                description: |
                  Developer message describing the problem that
                  prevented this certificate from being processed.
                type: string
              servererrormessage:
                description: |
                  Developer message given by the server.
                type: string
              limit:
                description: |
                  Integer indicating the maximum allowed size of
                  the JsonArray in the request. The limit is added to
                  clarify if the error is due to the limit being exceeded.
                type: integer

    JsonIssuer:
      type: object
      description: CA details.
      properties:
        subject:
          type: array
          description: Subject
          items:
            type: object
            description: |
              Relative DN of directory attributes as per RFC1779
              (for example {"cn":"somecommonname"}.)
        subjectDn:
          type: string
          description: Full subject DN string

    JsonCertificate:
      type: object
      description: Certificate details.
      properties:
        certid:
          type: string
          description: Unique ID of the certificate.

        status:
          type: string
          description: Human-readable status of the certificate, revoked/active.

        reason:
          type: string
          description: Revocation reason.

        revocationtime:
          type: string
          format: date-time
          description: Point in time when the certificate was revoked.

        validto:
          type: string
          format: date-time
          description: X.509 "not after" point in time.

        validfrom:
          type: string
          format: date-time
          description: X.509 "not before" point in time.

        certificateserialnumber:
          type: string
          description: Certificate serial number in hex format.

        subject:
          type: string
          description: Subject distinguished name.

        issuer:
          type: string
          description: Issuer distinguished name.

        keyusage:
          type: array
          items:
            type: string
          description: |
            List of key usage names, including those from ExtendedKeyUsage
            extension.

        subjectType:
          type: string
          description: |
            Identifies the subject tpye of the certificate, either an
            End Entity (EE) or a Certificate Authority (CA)

        extendedcertsearch:
          type: object
          properties:
            field1:
              type: string
            field2:
              type: string
            field3:
              type: string
            field4:
              type: string
            field5:
              type: string
            field6:
              type: string
          description: |
            List of extended certificate search criteria field values

        authorityKeyIdentifier:
          type: string
          description: AuthorityKeyIdentifier in hex format

        subjectKeyIdentifier:
          type: string
          description: SubjectKeyIdentifier in hex format
      required:
        - certid
        - status

    Regid:
      type: string
      description: The registration id. Created on the server side.
      readOnly: true

    Fqdn:
      type: string
      description: Fully qualified domain name.

    Validity:
      type: string
      description: |
        Determines for how long the registration will be open. Set in either
        days or 'always' to be open forever.

    Officer:
      type: string
      description: Officer who signed the request. Created on the server side.
      readOnly: true

    Creationdate:
      type: string
      description: Creation date of the registration. Created on the server side.
      readOnly: true

    Regtype:
      type: string
      enum:
        - est
        - cmp
        - scep
        - device
        - acme
        - acme/account
      description: |
        Determines which type the registration can be used with.

    Status:
      type: string
      enum:
        - open
        - closed
      description: |
        Either 'open' or 'closed'. Determines if that registration can be
        used for certificate creation.

    AccountStatus:
      type: string
      enum:
        - active
        - deactivated
        - revoked
      description: |
        Either 'active', 'deactivate' or 'revoked'. Determines if the
        account registration can be used for certificate creation.

    Email:
      type: string
      description: Email address used with the registration.

    Keyid:
      type: string
      description: Keyid of the connected pre-registration.

    Certids:
      type: array
      description: Array of certificate ids.
      items:
        type: string
      readOnly: true

    Accountids:
      type: array
      description: Array of ACME account ids.
      items:
        type: string

    # Contains base parameters common for all types of registrations
    RegistrationBase:
      properties:
        regid:
          $ref: '#/components/schemas/Regid'
        fqdn:
          $ref: '#/components/schemas/Fqdn'
        validity:
          $ref: '#/components/schemas/Validity'
        status:
          $ref: '#/components/schemas/Status'
        signature:
          $ref: "#/components/schemas/ApiRequest_Signature"

    Registration:
      type: object
      allOf:
        - $ref: '#/components/schemas/RegistrationBase'
        - properties:
            regtype:
              $ref: '#/components/schemas/Regtype'
            officer:
              $ref: '#/components/schemas/Officer'
            creationdate:
              $ref: '#/components/schemas/Creationdate'
            certids:
              $ref: '#/components/schemas/Certids'

    PreRegistrationAcme:
      type: object
      allOf:
        - $ref: '#/components/schemas/RegistrationBase'
        - properties:
            regtype:
              $ref: '#/components/schemas/Regtype'
            officer:
              $ref: '#/components/schemas/Officer'
            creationdate:
              $ref: '#/components/schemas/Creationdate'
            accountids:
              $ref: '#/components/schemas/Accountids'

    RegistrationScep:
      type: object
      allOf:
        - $ref: '#/components/schemas/RegistrationBase'
        - properties:
            ipaddress:
              type: string
              description: |
                IP address of the device using the registration.
            email:
              $ref: '#/components/schemas/Email'
            serialnumber:
              type: string
              description: |
                Serial number of the device using the registration.
            password:
              type: string
              description: |
                The password used to register.

    RegistrationEstHttpAuth:
      type: object
      allOf:
        - $ref: '#/components/schemas/RegistrationBase'
        - properties:
            username:
              type: string
              description: |
                Username used with HTTP based authentication.
            realm:
              type: string
              description: |
                Realm used with HTTP based authentication.
            password:
              type: string
              description: |
                The password used to register.

    RegistrationEstCertAuth:
      type: object
      allOf:
        - $ref: '#/components/schemas/RegistrationBase'
        - properties:
            subject-commonname:
              type: string
              description: |
                Commonname of the subject in the CSR to enroll for
            authentication-certificate-ca:
              type: string
              description: |
                AWB name of the CA of the device authentication certificate.

    RegistrationCmp:
      type: object
      allOf:
        - $ref: '#/components/schemas/RegistrationBase'
        - properties:
            password:
              type: string
              description: |
                The password used to register.

    RegistrationAcme:
      type: object
      allOf:
        - $ref: '#/components/schemas/RegistrationBase'
        - properties:
            hmacKey:
              type: string
              format: byte
              description: |
                HMAC key for ACME pre-registration (32 bytes in base64 url-safe encoding).
            allowedDomains:
              type: string
              description: |
                Comma separated string of allowed domains for ACME pre-registration.

    RegistrationCertId:
      type: object
      properties:
        registration:
          $ref: '#/components/schemas/Registration'
        error:
          $ref: '#/components/schemas/ApiResponse_Error'
        msg:
          $ref: '#/components/schemas/ApiResponse_Msg'

    Account:
      type: object
      allOf:
        - properties:
            regid:
              $ref: '#/components/schemas/Regid'
            fqdn:
              $ref: '#/components/schemas/Fqdn'
            creationdate:
              $ref: '#/components/schemas/Creationdate'
            officer:
              $ref: '#/components/schemas/Officer'
            status:
              $ref: '#/components/schemas/AccountStatus'
            keyid:
              $ref: '#/components/schemas/Keyid'
            email:
              $ref: '#/components/schemas/Email'
            certids:
              $ref: '#/components/schemas/Certids'


    CreateRegistration:
      allOf:
        - $ref: '#/components/schemas/RegistrationBase'
        - properties:
            regtype:
              $ref: '#/components/schemas/Regtype'
      required:
        - fqdn
        - regtype

    UpdateRegistration:
      allOf:
        - $ref: '#/components/schemas/Registration'
        - properties:
            regid:
              readOnly: false
            regtype:
              readOnly: true
      required:
        - regid

    RegistrationResponseGet:
      type: object
      properties:
        registrations:
          type: array
          description: Array of registrations connected to the given procid.
          items:
            $ref: '#/components/schemas/Registration'
        error:
          $ref: '#/components/schemas/ApiResponse_Error'
        msg:
          $ref: '#/components/schemas/ApiResponse_Msg'

    RegistrationResponseAcmeGet:
      type: object
      properties:
        registrations:
          type: array
          description: Array of registrations connected to the given procid.
          items:
            $ref: '#/components/schemas/PreRegistrationAcme'
        error:
          $ref: '#/components/schemas/ApiResponse_Error'
        msg:
          $ref: '#/components/schemas/ApiResponse_Msg'

    RegistrationResponsePostOrPut:
      type: object
      properties:
        registration:
          type: object
          properties:
            regid:
              $ref: '#/components/schemas/Regid'
        error:
          $ref: "#/components/schemas/ApiResponse_Error"
        msg:
          $ref: "#/components/schemas/ApiResponse_Msg"

  # Defines common parameters used by multiple GET operations
  parameters:
    procid:
      name: procid
      in: path
      description: Token procedure id
      required: true
      schema:
        type: string
    regid:
      name: regid
      in: query
      description: Registration id
      schema:
        type: string
    certid:
      name: certid
      in: path
      description: Certificate id
      required: true
      schema:
        type: string
    accountid:
      name: accountid
      in: query
      description: Account id, allows wildcard(*)
      schema:
        type: string
    fqdn:
      name: fqdn
      in: query
      description: Fully qualified domain name.
      schema:
        type: string
    status:
      name: status
      in: query
      description: Registration status
      schema:
        enum:
          - open
          - closed
        type: string
    validity:
      name: validity
      in: query
      description: Number of days the registration will be open or 'always'.
      schema:
        type: string
    regtype:
      name: regtype
      in: query
      description: Registration type of the registration.
      schema:
        $ref: '#/components/schemas/Regtype'
    email:
      name: email
      in: query
      description: Email address
      schema:
        type: string
    ipaddress:
      name: ipaddress
      in: query
      description: IP address
      schema:
        type: string
    serialnumber:
      name: serialnumber
      in: query
      description: Certificate serialnumber as hex.
      schema:
        type: string
    password:
      name: password
      in: query
      description: The password used to register.
      schema:
        type: string
    username:
      name: username
      in: query
      description: The username used to register.
      schema:
        type: string
    realm:
      name: realm
      in: query
      description: The realm the user should be connected with.
      schema:
        type: string
    subject-commonname:
      name: subject-commonname
      in: query
      description: The commonname of the subject to be enrolled
      schema:
        type: string
    hmacKey:
      name: hmacKey
      in: query
      description: |
        HMAC key for ACME pre-registration (32 bytes in base64 url-safe encoding).
        The HMAC Key Id must also be specified in the fqdn field.
      schema:
        type: string
    allowedDomains:
      name: allowedDomains
      in: query
      description: Comma separated string of allowed domains.
      schema:
        type: string
    creationdate:
      name: creationdate
      in: query
      description: Creation date of the registration.
      schema:
        type: string
    officer:
      name: officer
      in: query
      description: Officer who signed the request.
      schema:
        type: string
    searchLimit:
      name: searchLimit
      in: query
      description: |
        The maximum number of certificates that should be returned.
        Please note that the highest possible value is still limited by
        server-side configuration (`certsearch.maxhits` in
        `cm.conf`).
      schema:
        type: integer
    searchOffset:
      name: searchOffset
      in: query
      description: |
        The starting offset of the first certificate that should be
        returned. This may be used for pagination of the results, together
        with the searchLimit parameter.
      schema:
        type: integer
    certificateSerialNumber:
      name: certificateSerialNumber
      in: query
      description: Serial number of the certificate.
      schema:
        type: string
    revocationTimeFrom:
      name: revocationTimeFrom
      in: query
      description: |
        Only return certificates whose revocation time is after
        the provided time.
      schema:
        type: string
        format: date-time
    revocationTimeTo:
      name: revocationTimeTo
      in: query
      description: |
        Only return certificates whose revocation time is before
        the provided time.
      schema:
        type: string
        format: date-time
    revocationReason:
      name: revocationReason
      in: query
      description: |
        Only return certificates with specified revocation reasons.

        Takes an array of integers in the format e.g. `1,2,3,4`.

        Reason code mapping:
        * 0: Unspecified
        * 1: Key Compromise
        * 2: Ca Compromise
        * 3: Affiliation Changed
        * 4: Superseded
        * 5: Cessation Of Operation
        * 6: Certificate Hold
        * 8: Remove From CRL
        * 9: Privilege Withdrawn
        * 10: AACompromise
      schema:
        type: array
        items:
          type: integer
          minimum: 0
          maximum: 10
    isNotRevoked:
      name: isNotRevoked
      in: query
      description: |
        If `true`, only certificates that are not revoked will be
        returned.
      schema:
        type: boolean
    publicationAllowed:
      name: publicationAllowed
      in: query
      description: |
        If `true`, only certificates where publication is allowed
        will be returned.
      schema:
        type: boolean
    publicationTimeFrom:
      name: publicationTimeFrom
      in: query
      description: |
        Only return certificates whose publication time is after
        the provided time.
      schema:
        type: string
        format: date-time
    publicationTimeTo:
      name: publicationTimeTo
      in: query
      description: |
        Only return certificates whose publication time is before
        the provided time.
      schema:
        type: string
        format: date-time
    ocspActivationTimeFrom:
      name: ocspActivationTimeFrom
      in: query
      description: |
        Only return certificates whose OCSP-activation time is after
        the provided time.
      schema:
        type: string
        format: date-time
    ocspActivationTimeTo:
      name: ocspActivationTimeTo
      in: query
      description: |
        Only return certificates whose OCSP-activation time is before
        the provided time.
      schema:
        type: string
        format: date-time
    validFromTimeFrom:
      name: validFromTimeFrom
      in: query
      description: |
        Only return certificates whose "valid from" (also named
        "not before") is after the provided time.
      schema:
        type: string
        format: date-time
    validFromTimeTo:
      name: validFromTimeTo
      in: query
      description: |
        Only return certificates whose "valid from" (also named
        "not before") is before the provided time.
      schema:
        type: string
        format: date-time
    isNotYetValid:
      name: isNotYetValid
      in: query
      description: |
        If `true`, only certificates whose "valid from" (also named
        "not before") is in the future will be returned.
      schema:
        type: boolean
    validToTimeFrom:
      name: validToTimeFrom
      in: query
      description: |
        Only return certificates whose "valid to (also named
        "not after") is after the provided time.
      schema:
        type: string
        format: date-time
    validToTimeTo:
      name: validToTimeTo
      in: query
      description: |
        Only return certificates whose "valid to" (also named
        "not after") is before the provided time.
      schema:
        type: string
        format: date-time
    isExpired:
      name: isExpired
      in: query
      description: |
        If `true`, only certificates that have already expired will
        be returned. This implies that the certificate's "valid to"
        (also named "not after") has passed.
      schema:
        type: boolean
    field1:
      name: field1
      in: query
      description: |
        Only return certificates with the specified extended
        certificate search field set
      schema:
        type: string
    field2:
      name: field2
      in: query
      description: |
        Only return certificates with the specified extended
        certificate search field set
      schema:
        type: string
    field3:
      name: field3
      in: query
      description: |
        Only return certificates with the specified extended
        certificate search field set
      schema:
        type: string
    field4:
      name: field4
      in: query
      description: |
        Only return certificates with the specified extended
        certificate search field set
      schema:
        type: string
    field5:
      name: field5
      in: query
      description: |
        Only return certificates with the specified extended
        certificate search field set
      schema:
        type: string
    field6:
      name: field6
      in: query
      description: |
        Only return certificates with the specified extended
        certificate search field set
      schema:
        type: string
    authorityKeyIdentifier:
      name: authorityKeyIdentifier
      in: query
      description: |
        AKI to filter results on. Must be in hexadecimal format.
        Example: 4A3A887184A13B28
      schema:
        type: string
    subjectKeyIdentifier:
      name: subjectKeyIdentifier
      in: query
      description: |
        SKI to filter results on. Must be in hexadecimal format.
        Example: 4A3A887184A13B28
      schema:
        type: string
    subjectType:
      name: subjectType
      in: query
      description: |
        Allows for filtering on subject type. By default only End Entity (EE)
        certificates are returned. Available values are:
        * EE
        * CA

        Takes an array of string in the format e.g. 'EE,CA`.

        Enum mapping:
        * EE: End Entity
        * CA: Certificate Authority
      schema:
        type: array
        items:
          type: string

  # Defines common responses used by multiple PATHS
  responses:
    RegistrationPost200:
      description: OK - Registration was successful
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/RegistrationResponsePostOrPut"
          example:
            registration: {'regid':'kplclzbq4KeoaS86KimttAUlXKw='}
            error: 0
            msg: "Registration has been successful"
    RegistrationPost500:
      description: Error - Registration failed, invalid input parameters
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiErrorResponse"
          example:
            error: -14
            msg: "Code -14, Registration type not supported"
    RegistrationUpdate200:
      description: OK - The updated registration
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/RegistrationResponsePostOrPut"
          example:
            registration: {'regid':'kplclzbq4KeoaS86KimttAUlXKw='}
            error: 0
            msg: "Registration has been successful"
    RegistrationUpdate500:
      description: Error - Registration update failed, no such registration
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiErrorResponse"
          example:
            error: -14
            msg: "Code -14, Registration type not supported"
    ServerError:
      description: Internal server error - An unexpected error occurred.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiErrorResponse"
          example:
            error: -14
            msg: "Code -14, Internal bad request"