openapi: "3.1.0"
info:
  title: Cryptera Key Management - Operational/CICD API
  description: |
    <p>This is the CI/CD API for the Cryptera Key Management Server.</p>
    <h2><b>NOTICE: </b>The API presentation is for reference only!</h2>
    <p>"Authorize" and "Try it out" functions are disabled.</p>
    <p>Please contact Cryptera for further information.</p>  
  version: 1.0
paths:
  /api/keys:
    get:
      tags:
      - keys
      summary: Get public keypair information for all keys
      security:
        -  authorizationCodeSecurity: [read]
        -  clientCredentialsSecurity: [read]
      description: Get public keypair information and public certificate for all keys the client has access to
      operationId: getallkeys
      responses:
        '200':
          description: A JSON array of key names
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/key-info'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        default:
          $ref: '#/components/responses/DefaultError'
  /api/keys/{keyid}:
    get:
      tags:
      - keys
      summary: Get public keypair information
      security:
        -  authorizationCodeSecurity: [read]
        -  clientCredentialsSecurity: [read]
      description: Get keypair information and public certificate for a specific key
      operationId: getkeys
      parameters:
        - in: path
          name: keyid
          required: true
          schema:
            type: string
          x-constraints: "@KeysKeyIdValid"
          description: The key-id of the keypair to get information about.  
      responses:
        '200':
          description: A JSON structure with information about the keypair
          content:
            application/json:
              schema:
                $ref:  '#/components/schemas/key-info'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/DefaultError'
  /api/keys/priv/{keyid}:
    get:
      tags:
      - keys
      summary: Get keypair information including private key
      security:
        -  authorizationCodeSecurity: [read]
        -  clientCredentialsSecurity: [read]
      description: For non-HSM keys (keystore keys), get keypair information, private key and public certificate for a specific key
      operationId: getprivkeys
      parameters:
        - in: path
          name: keyid
          required: true
          schema:
            type: string
          x-constraints: "@KeysPrivGetValid"
          description: The key-id of the keypair to get information about.  
      responses:
        '200':
          description: A JSON structure with information about the keypair
          content:
            application/json:
              schema:
                $ref:  '#/components/schemas/key-info'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/DefaultError'
  /api/operations:
    post:
      tags:
      - operations
      summary: Create a new Pipeline
      security:
        -  authorizationCodeSecurity: [write]
        -  clientCredentialsSecurity: [write]
      description: Create a new Pipeline to hold signingorders, key usage and approvals
      operationId: createoperation
      requestBody:
        description: Order an operation by sending keyid and data to be processed
        x-constraints: "@OperationPostValid"
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/new-operation'
        required: true
      responses:
        '201':
          $ref: '#/components/responses/IdResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/DefaultError'
  /api/operations/{operationid}:
    get:
      tags:
      - operations
      summary: Get details about a pipeline operation
      security:
        -  authorizationCodeSecurity: [read]
        -  clientCredentialsSecurity: [read]
      description: Get details about a specific signing operation with contains one or more signing orders. This is relevant for approvers to inspect what is to be approved.
      operationId: getoperation
      parameters:
        - in: path
          name: operationid
          required: true
          schema:
            type: string
          x-constraints: "@OperationsGetValid"
          description: The unique ID (UUID) of the operation to checked. This value is the result returned when the operation was added.  
      responses:
        '200':
          description: A JSON with details about the sign order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/operation-info'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/DefaultError'
  /api/operations/{operationidtocancel}:
    delete:
      tags:
      - operations
      summary: Cancel the pipeline operation with the given operationid
      security:
        -  authorizationCodeSecurity: [write]
        -  clientCredentialsSecurity: [write]
      description: This request cancels an the ordered signing associated with the given operationid
      operationId: canceloperation
      parameters:
        - in: path
          name: operationidtocancel
          required: true
          description: The operationid of the signing order to cancel          
          schema:
            type: string
          x-constraints: "@OperationsDeleteValid"
      responses:
        '200':
          $ref: '#/components/responses/IdResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/DefaultError'
          
  /api/signorders:
    post:
      tags:
      - signorders
      summary: Order a cryptographic operation
      security:
        -  authorizationCodeSecurity: [write]
        -  clientCredentialsSecurity: [write]
      description: Orders a cryptographic operation to be performed on the supplied input data using the keypair identified by keyid. If successful it returns the signature
      operationId: order
      requestBody:
        description: Order an operation by sending keyid and data to be processed 
        x-constraints: "@SignordersPostValid"
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/new-signorder'
        required: true
      responses:
        '201':
          description: A JSON with details about the signorder status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/signorder-info'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '410':
          $ref: '#/components/responses/Gone'
        default:
          $ref: '#/components/responses/DefaultError'
  /api/certificates:
    post:
      tags:
      - certificates
      summary: Sign a CSR
      security:
        -  authorizationCodeSecurity: [write]
        -  clientCredentialsSecurity: [write]
      description: Sign a Certificate Signing Request returning certificate, optionally including entire chain. Only web.
      operationId: createcertificate
      requestBody:
        description: The CSR to be signed
        x-constraints: "@CertificatesPostValid"
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/new-certificate'
        required: true
      responses:
        '200':
          description: The requested certificate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/certificate-info'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/DefaultError'
  /api/datas/{keyid}:
    get:
      tags:
      - datastore
      summary: Get data in datastore associated with key
      security:
        -  authorizationCodeSecurity: [read]
        -  clientCredentialsSecurity: [read]
      description: Get data in datastore associated with key
      operationId: getdata
      parameters:
        - in: path
          name: keyid
          required: true
          schema:
            type: string
          description: The key-id of the data to retrieve from datastore.  
      responses:
        '200':
          description: A JSON structure with information about the keypair
          content:
            application/json:
              schema:
                $ref:  '#/components/schemas/data-info'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/DefaultError'
components:
  responses:
    BadRequest:
      description: The request was illformed (400) - RFC9457 format
      content:
        application/json:
          schema:
            $ref:  '#/components/schemas/problem-detail'
          examples:
            Formstyle:
              value:
                type: about:blank
                status: 400
                title: Form Validation Error
                instance: /api/exampleservice
                properties:
                  - key: examplefield
                    message: examplefield must conform to xxx
            Detailstyle:
              value:
                type: about:blank
                status: 400
                title: Validation Error
                instance: /api/exampleservice
                detail: Failed because xxx only yyy is alowed
    Unauthorized:
      description: The request was Unauthorized access (401) - RFC9457 format
      content:
        application/json:
          schema:
            $ref:  '#/components/schemas/problem-detail'
          examples:
            Formstyle:
              value:
                type: about:blank
                status: 401
                title: Authorization Error
                instance: /api/exampleservice
                properties:
                  - key: examplefield
                    message: examplefield must conform to xxx
            Detailstyle:
              value:
                type: about:blank
                status: 401
                title: Authorization Error
                instance: /api/exampleservice
                detail: Failed because xxx only yyy is alowed
    Forbidden:
      description: The request was forbidden - not the right permissions (403) - RFC9457 format
      content:
        application/json:
          schema:
            $ref:  '#/components/schemas/problem-detail'
          examples:
            Formstyle:
              value:
                type: about:blank
                status: 403
                title: Request was forbidden
                instance: /api/exampleservice
                properties:
                  - key: examplefield
                    message: examplefield must conform to xxx
            Detailstyle:
              value:
                type: about:blank
                status: 403
                title: Request was forbidden
                instance: /api/exampleservice
                detail: Failed because xxx only yyy is alowed
    NotFound:
      description: The specified resource was not found (404) - RFC9457 format
      content:
        application/json:
          schema:
            $ref:  '#/components/schemas/problem-detail'
          examples:
            Formstyle:
              value:
                type: about:blank
                status: 404
                title: Resource not found
                instance: /api/exampleservice
                properties:
                  - key: examplefield
                    message: examplefield must conform to xxx
            Detailstyle:
              value:
                type: about:blank
                status: 404
                title: Resource not found
                instance: /api/exampleservice
                detail: Failed because xxx only yyy is alowed
    Conflict:
      description: The server cannot fullfill the request at the present time (409) - RFC9457 format
      content:
        application/json:
          schema:
            $ref:  '#/components/schemas/problem-detail'
          examples:
            Formstyle:
              value:
                type: about:blank
                status: 409
                title: Server cannot fullfill the request
                instance: /api/exampleservice
                properties:
                  - key: examplefield
                    message: examplefield must conform to xxx
            Detailstyle:
              value:
                type: about:blank
                status: 409
                title: Server cannot fullfill the request
                instance: /api/exampleservice
                detail: Failed because xxx only yyy is alowed
    Gone:
      description: The requested resource is permanently unavailable (410) - RFC9457 format
      content:
        application/json:
          schema:
            $ref:  '#/components/schemas/problem-detail'
          examples:
            Formstyle:
              value:
                type: about:blank
                status: 410
                title: The requested resource is permanently unavailable
                instance: /api/exampleservice
                properties:
                  - key: examplefield
                    message: examplefield must conform to xxx
            Detailstyle:
              value:
                type: about:blank
                status: 409
                title: The requested resource is permanently unavailable
                instance: /api/exampleservice
                detail: Failed because xxx only yyy is alowed
    DefaultError:
      description: Any other error (Anything >300) - RFC9457 format
      content:
        application/json:
          schema:
            $ref:  '#/components/schemas/problem-detail'
          examples:
            Formstyle:
              value:
                type: about:blank
                status: Any other 300+
                title: Some error occured
                instance: /api/exampleservice
                properties:
                  - key: examplefield
                    message: examplefield must conform to xxx
            Detailstyle:
              value:
                type: about:blank
                status: Any other 300+
                title: The requested resource is permanently unavailable
                instance: /api/exampleservice
                detail: Failed because xxx only yyy is alowed
    IdResponse:
      description: Identifier of the object just created, updated or deleted
      content:
        application/json:
          schema:
            $ref:  '#/components/schemas/id-response'
  securitySchemes:
    clientCredentialsSecurity:
      type: oauth2
      description: Client credentials authorization used from trusted clients (build pipelines etc.)
      flows: 
        clientCredentials: 
          tokenUrl: /oauth2/token
          scopes:
            read: Grants read access
            write: Grants write access
    authorizationCodeSecurity:
      type: oauth2
      description: Authorization Code authorization. Used for Web logins
      flows: 
        authorizationCode:
          authorizationUrl: https://keyserver.demo.cryptera.com:8200/oauth2/authorize 
          tokenUrl: /oauth2/token
          scopes:
            read: Grants read access
            write: Grants write access
  schemas:
    new-operation:
      type: object
      required: [validms, description, keyusagerestrictions]
      properties:
        validms:
          type: integer
          minimum: 1
          description: This is the number of milliseconds (measured form its creation) this operation is valid.
          example: 600000
        description:
          type: string
          minLength: 16
          maxLength: 4096
          description: A highlevel description of the purpose af the operation. This is the text the approvers will se when deciding to approve or cancel.
          example: Building of firmware for processor board for Terminator model T-1000
        new-keyusagerestrictions:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/new-keyusagerestriction'
        creatorowns:
          type: boolean
          description: If true, only the creator can use this operation for get, cancel, sign etc.
          example: true
          default: true
    new-keyusagerestriction:
      type: object
      required: [keyid, count]
      properties:
        keyid:
          type: string
          description: keyid of the key to define restrictions for
          example: fw-quickstart
        maxusagecount:
          type: integer
          minimum: 1
          description: Maximum number of times "keyid" can be used in the associated operation
          example: 5
    new-signorder:
      type: object
      required: [operationid, keyid, inputdata, inputformat, signatureformat, info]
      properties:
        operationid:
          type: string
          format: uuid
          description: The operationid (UUID) of the operation this signing order is a part of
          example: 123e4567-e89b-12d3-a456-426655440000
        keyid:
          type: string
          minLength: 4
          maxLength: 64 
          description: This is a reference (name) to the key used for signing
          example: "FW1_IMX_SIGN_KEY"
        inputdata:
          type: string
          minLength: 4
          maxLength: 256 
          description: This the data to be signed - string representing hex-digits
          example: 0a8830b86cd7f03841ef0c477f77429c
        inputformat:
          type: inputformat-type
          description: The format of the input data (simple => 32 bytes hex string)
          example: hex
        inputpadding:
          type: inputpadding-type
          description: Type of padding included in inputdata (if any) 
          example: pkcs1
        signatureformat:
          type: signatureformat-type
          example: asn1 
          description: Desired format of the signature to issue
        cmsincludecert:
          type: boolean
          description: If true, the public certificate of the keypair used for signing will be included in the CMS signature
          example: true
        cmsdirectsignature:
          type: boolean
          description: If true, the signer signature will be based on the data, not a collection of signed attributes, and no signed attributes will be included
          example: true
        cmsencapsulate:
          type: boolean
          description: If true, the generated CMS Signed Data object will have encapsulated data - otherwise it will be carrying a detached CMS signature
          example: true
        description:
          type: string
          minLength: 8
          maxLength: 4096 
          description: Textual description of what is to be signed. Important as it allows approvers to see what they approve
          example: Version 3.4.5 of XYZ controller for the ABC product. International version.
    new-certificate:
      required: [operationid, keyid, fullchain, csrpem]
      type: object
      properties:
        operationid:
          type: string
          format: uuid
          description: The operationid (UUID) of the operation this CSR is a part of
          example: 123e4567-e89b-12d3-a456-426655440000
        keyid:
          type: string
          minLength: 4
          maxLength: 64
          description: Id of the intermediate keypair that should sign the public key within the CSR to produce the certificate
          example: devkey
        serialnumber:
          type: string 
          minLength: 2
          maxLength: 40
          description: If set, this hexadecimal number is used as serial number for the issued certificate. If not set, a random, positive number is used
          example: 0102030405060708090AABBCCDDEEFF 
        fullchain:
          type: boolean
          description: If true, return the entire certificate chain (in the order certificate, intermediate, root)
          example: true
        csrpem:
          type: string
          maxLength: 4096
          description: The certificate signing request in PEM-format. Replace any newline characters (NL, CR) with '\n'
          example: -----BEGIN CERTIFICATE REQUEST----- MIIB.... aQuPK -----END CERTIFICATE REQUEST-----
    operation-info:
      type: object
      properties:
        operationid:
          type: string
          format: uuid
          description: Operation id of this pipeline operation
          example: 123e4567-e89b-12d3-a456-426655440000
        validms:
          type: integer
          description: This is the number of milliseconds (measured form its creation) this operation is valid.
          example: 600000
        description:
          type: string
          description: A highlevel description of the purpose af the operation. This is the text the approvers will se when deciding to approve or cancel.
          example: Building of firmware for processor board for Terminator model T-1000
        keyusagerestrictions:
          type: array
          items:
            type: object
            required: [keyid, count]
            properties:
              keyid:
                type: string
                description: keyid of the key to define restrictions for
                example: fw-quickstart
              usagecount:
                type: integer
                description: Number of times "keyid" has been used in the associated operation
                example: 2
              maxusagecount:
                type: integer
                description: Maximum number of times "keyid" can be used in the associated operation
                example: 5
        approved:
          type: boolean
          description: status on the approval process. True if all signing keys has enough approvers thus marking the pipeline operation ready to use
          example: true 
        approvers:
          type: array
          items:
            description: Approver
            type: string
            example: rel-man1, gitlab-user1
        approvalclaims:
          type: array
          items:
            type: object
            required: [claim]
            properties:
              claim:
                type: string
                description: The JWT claim to be shown to approver
                example: build_branch
              claimvalue:
                type: string
                description: The value of the claim
                example: release_v2_23243434
        createdby:
          type: string
          description: The client/user that created this signorder
          example: orderer-client
        createdms:
          type: long
          description: Creation time of this operation measured in milliseconds since epoch time start
          example: 1739181485554
    key-info:
      type: object
      properties:
        keyid:
          type: string
          description: This is a reference (name) to the key used for signing
          example: "FW1_IMX_SIGN_KEY"
        keyinfo:
          type: string
          description: Description of the key - it's usage etc.'
          example: Firmware signing key for controller model T-101
        required-approvers:
          type: integer
          description: Number of approvers required for signature
          example: 1
        certificate:
          type: string
          description: The certificate containing the public certificate of the keypair in PEM
          example: -----BEGIN CERTIFICATE----- MII... -----END CERTIFICATE-----
        privatekey:
          type: string
          description: The private key of the keypair in PEM, This field is only available for non-HSM keys located in keystore 
          example: -----BEGIN PRIVATE KEY----- MII... -----END PRIVATE KEY-----
        description:
          type: string
          description: This is a structured, human readable description of the certificate
          example: Version V3 Subject O=..
    signorder-info:
      type: object
      properties:
        keyid:
          type: string
          description: The key this signature is produced by
          example: "FW1_IMX_SIGN_KEY"
        inputdata:
          type: string
          description: The original input data
          example: 0a8830b86cd7f03841ef0c477f77429c
        signatureformat:
          type: signatureformat-type
          description: Format of the issued signature
        result:
          type: string
          description: String of hex-digits providing the result of the transaction (signature) if signed
          example: "3704dd9d7a25abc56c4aa04372ed0bcdd18cae8ddd53e1fbf19723a3f0105355"
    certificate-info:
      description: The requested certificate optionally including entire chain in the order certificate, intermediate, root
      type: object
      properties:
        certificates:
          type: string
          description: The certificate or full certificate chain in pem-format
          example: -----BEGIN CERTIFICATE----- MIIB.... aQuPK -----END CERTIFICATE-----
    data-info:
      type: object
      properties:
        keyid:
          type: string
          description: This is the key that identifies the data that should be retrieved
          example: abc_key
        value:
          type: string
          description: The data associated with the key 'keyid'
          example: TheVerySecretSecret
        description:
          type: string
          description: Information about this key/value pair, it's usage and relevance
          example: This is the symmetric key used for XYZ board
    problem-detail:
      description: A RFC 9457 error report
      type: object
      properties:
        type:
          type: string
          description: A URI reference that identifies the problem type
          example: https://problems-registry.smartbear.com/missing-body-property
        status:
          type: integer
          description: The HTTP status code generated by the origin server for this occurrence of the problem
          example: 400
        title:
          type: string
          description: Problem description headline
          example: Field 'info' is insufficient
        detail:
          type: string
          description: Optional Problem description headline
          example: Must contain at least 16 characters
        instance:
          type: string
          description: A URI reference that identifies the specific occurrence of the problem
          example: /signorders/10
        properties:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              message:
                type: string
    id-response:
      type: object
      properties:
        id:
          type: string
          description: Identifier for the object created, modified or deleted
          example: 123
    subject-type:
      enum:
        - client
        - user
      type: string
    subject-types:
      enum:
        - clients
        - users
        - all
      type: string
    role-type:
      enum:
        - all
      type: string
    signingkey-type:
      enum:
        - all
        - initialized
      type: string
    signatureformat-type:
      enum:
        - p1363
        - asn1
        - cms
        - pem
      type: string
    inputformat-type:
      enum:
        - hex
        - base64
        - pem
      type: string
    inputpadding-type:
      enum:
        - none
        - digestinfo
      type: string
    keytype-type:
      enum:
        - FW
        - CA
        - ROOT
      type: string
    keylocation-type:
      enum:
        - HSM
        - KEYSTORE
      type: string
    keyorigin-type:
      enum:
        - HSM
        - IMPORTED
      type: string
    keystatus-type:
      enum:
        - NEW
        - INITIALIZED
        - FAILED
        - RETRY
        - REJECTED
      type: string
    signaturealgorithm-type:
      enum:
        - ECDSA
        - RSA
      type: string
    hashalgorithm-type:
      enum:
        - SHA256
        - SHA384
        - SHA512
      type: string
    keypairgeneratoralgorithm-type:
      enum:
        - EC
        - RSA
      type: string

       
