openapi: 3.0.3
info:
  version: 1.0-SNAPSHOT
  title: eIDAS Signature REST API
  description: >-
    The eIDAS Signature REST API allows you to sign objects using X509 / eidas
    compliant signatures.
  contact:
    name: Sphereon
    url: https://sphereon.com
    email: dev@sphereon.com
  license:
    name: GNU Affero General Public License v3
    url: https://www.gnu.org/licenses/agpl-3.0.en.html
servers:
  - url: http://localhost:8080/api
    description: Development
  - url: http://localhost:21764/api
    description: Docker
  - url: https://gw.api.cloud.sphereon.com/eidas-signatures/v1
    description: Sphereon VDX Platform
tags:
  - name: Signing
    description: Signing APIs
  - name: Keys
    description: Certificate and Key Entry management APIs
  - name: SignatureConfig
    description: Signature configuration APIs
  - name: KeyProvider
    description: Key Provider APIs
  - name: EzDocSeal
    description: Eeasy Document Seals and signatures APIs
paths:
  /signatures/input:
    post:
      tags:
        - Signing
      security:
        - openId:
            - sign:vdx_sign_key
        - oauth2:
            - sign:vdx_sign_key
        - bearer: []
      summary: Determine signature input data
      operationId: determineSignInput
      description: Determines the data that needs to be signed from an input
      requestBody:
        $ref: '#/components/requestBodies/DetermineSignInputRequest'
      responses:
        '200':
          description: Signature input data created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetermineSignInputResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /signatures/digest:
    post:
      tags:
        - Signing
      security:
        - openId:
            - sign:vdx_sign_key
        - oauth2:
            - sign:vdx_sign_key
        - bearer: []
      summary: Create digest value
      operationId: digest
      description: Create a hash/digest value
      requestBody:
        $ref: '#/components/requestBodies/DigestRequest'
      responses:
        '200':
          description: Digest value created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Digest'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /signatures/create:
    post:
      tags:
        - Signing
      security:
        - openId:
            - sign:vdx_sign_key
        - oauth2:
            - sign:vdx_sign_key
        - bearer: []
      summary: Create signature
      operationId: createSignature
      description: Create a signature
      requestBody:
        $ref: '#/components/requestBodies/CreateSignatureRequest'
      responses:
        '200':
          description: Signature created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSignatureResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /signatures/merge:
    post:
      tags:
        - Signing
      security:
        - openId:
            - sign:vdx_sign_key
        - oauth2:
            - sign:vdx_sign_key
        - bearer: []
      summary: Merges the original data with the created signature
      operationId: mergeSignature
      requestBody:
        $ref: '#/components/requestBodies/MergeSignatureRequest'
      responses:
        '200':
          description: Data signed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MergeSignatureResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /providers:
    post:
      tags:
        - KeyProvider
      security:
        - openId:
            - admin:vdx_sign_provider
        - oauth2:
            - admin:vdx_sign_provider
        - bearer: []
      summary: Create Key Provider
      operationId: createKeyProvider
      requestBody:
        $ref: '#/components/requestBodies/CreateKeyProviderRequest'
      responses:
        '201':
          description: Key Provider was created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyProviderResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
        - KeyProvider
      security:
        - openId:
            - admin:vdx_sign_provider
        - oauth2:
            - admin:vdx_sign_provider
        - bearer: []
      summary: Get Key Providers
      operationId: listKeyProviders
      responses:
        '200':
          description: List Key Providers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyProvidersResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /providers/{providerId}:
    put:
      tags:
        - KeyProvider
      security:
        - openId:
            - admin:vdx_sign_provider
        - oauth2:
            - admin:vdx_sign_provider
        - bearer: []
      summary: Update Key provider
      operationId: updateKeyProvider
      description: Update the Key Provider Settings
      parameters:
        - $ref: '#/components/parameters/providerId'
      requestBody:
        $ref: '#/components/requestBodies/UpdateKeyProviderRequest'
      responses:
        '200':
          description: Key Provider was updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyProvidersResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
        - KeyProvider
      security:
        - openId:
            - admin:vdx_sign_provider
        - oauth2:
            - admin:vdx_sign_provider
        - bearer: []
      summary: Get Key Provider
      operationId: getKeyProvider
      parameters:
        - $ref: '#/components/parameters/providerId'
      responses:
        '200':
          description: Key Provider was retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyProviderResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
        - KeyProvider
      security:
        - openId:
            - admin:vdx_sign_provider
        - oauth2:
            - admin:vdx_sign_provider
        - bearer: []
      summary: Delete Key Provider
      operationId: deleteKeyProvider
      parameters:
        - $ref: '#/components/parameters/providerId'
      responses:
        '200':
          description: Key Provider was deleted successfully
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /providers/{providerId}/certificates:
    post:
      tags:
        - Keys
      security:
        - openId:
            - admin:vdx_sign_key
        - oauth2:
            - admin:vdx_sign_key
        - bearer: []
      summary: >-
        Import a X509 Certificate as Key Entry. Note not every Key Provider
        supports this method
      operationId: importX509Certificate
      description: Import a X509 certificate
      parameters:
        - $ref: '#/components/parameters/providerId'
      requestBody:
        $ref: '#/components/requestBodies/ImportX509CertificateRequest'
      responses:
        '201':
          description: Key Entry imported successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /providers/{providerId}/keys:
    put:
      tags:
        - Keys
      security:
        - openId:
            - admin:vdx_sign_key
        - oauth2:
            - admin:vdx_sign_key
        - bearer: []
      summary: link Key Entry
      operationId: linkKey
      description: Link a Key Entry kid to a Key/certificate id from the provider
      parameters:
        - $ref: '#/components/parameters/providerId'
      requestBody:
        $ref: '#/components/requestBodies/LinkKeyRequest'
      responses:
        '201':
          description: Key Entry linked successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags:
        - Keys
      security:
        - openId:
            - admin:vdx_sign_key
        - oauth2:
            - admin:vdx_sign_key
        - bearer: []
      summary: Create Key Entry (x509 certificate)
      operationId: createKey
      description: Create a Key Entry (x509 certificate)
      parameters:
        - $ref: '#/components/parameters/providerId'
      requestBody:
        $ref: '#/components/requestBodies/CreateOrUpdateKeyRequest'
      responses:
        '201':
          description: Key Entry created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /providers/{providerId}/keys/{kid}:
    get:
      tags:
        - Keys
      security:
        - openId:
            - read:vdx_sign_key
        - oauth2:
            - read:vdx_sign_key
        - bearer: []
      summary: Get a key Entry (X509 certificate)
      operationId: getKey
      description: Get a Key Entry
      parameters:
        - $ref: '#/components/parameters/providerId'
        - $ref: '#/components/parameters/kid'
      responses:
        '200':
          description: Key Entry retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
        - Keys
      security:
        - openId:
            - admin:vdx_sign_key
        - oauth2:
            - admin:vdx_sign_key
        - bearer: []
      summary: Update Key Entry
      operationId: updateKey
      description: Update a Key Entry (x509 certificate)
      parameters:
        - $ref: '#/components/parameters/providerId'
        - $ref: '#/components/parameters/kid'
      requestBody:
        $ref: '#/components/requestBodies/CreateOrUpdateKeyRequest'
      responses:
        '200':
          description: Key Entry updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
        - Keys
      security:
        - openId:
            - admin:vdx_sign_key
        - oauth2:
            - admin:vdx_sign_key
        - bearer: []
      summary: Delete Key Entry
      operationId: deleteKey
      description: Delete a Key Entry (x509 certificate)
      parameters:
        - $ref: '#/components/parameters/providerId'
        - $ref: '#/components/parameters/kid'
      responses:
        '200':
          description: Key Entry deleted successfully
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /configs:
    post:
      tags:
        - SignatureConfig
      security:
        - openId:
            - admin:vdx_sign_config
        - oauth2:
            - admin:vdx_sign_config
        - bearer: []
      summary: Create configuration
      operationId: createConfig
      requestBody:
        $ref: '#/components/requestBodies/ConfigRequest'
      responses:
        '201':
          description: Config was created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
        - SignatureConfig
      security:
        - openId:
            - read:vdx_sign_config
        - oauth2:
            - read:vdx_sign_config
        - bearer: []
      summary: List configurations
      operationId: listConfigs
      responses:
        '200':
          description: Configurations retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConfigResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /configs/{configId}:
    put:
      tags:
        - SignatureConfig
      security:
        - openId:
            - admin:vdx_sign_config
        - oauth2:
            - admin:vdx_sign_config
        - bearer: []
      summary: Update configuration
      operationId: updateConfig
      parameters:
        - $ref: '#/components/parameters/configId'
      requestBody:
        $ref: '#/components/requestBodies/ConfigRequest'
      responses:
        '200':
          description: Config was updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
        - SignatureConfig
      security:
        - openId:
            - read:vdx_sign_config
        - oauth2:
            - read:vdx_sign_config
        - bearer: []
      summary: Get configuration
      operationId: getConfig
      parameters:
        - $ref: '#/components/parameters/configId'
      responses:
        '200':
          description: Config was retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
        - SignatureConfig
      security:
        - openId:
            - admin:vdx_sign_config
        - oauth2:
            - admin:vdx_sign_config
        - bearer: []
      summary: Delete configuration
      operationId: deleteConfig
      parameters:
        - $ref: '#/components/parameters/configId'
      responses:
        '200':
          description: Config was deleted successfully
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /ezdocseal/sign:
    post:
      tags:
        - EzDocSeal
      summary: Sign a PDF creating a blue bar
      operationId: sign
      requestBody:
        description: Sign request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EzDocJsonSignRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/EzDocMultipartSignRequest'
        required: true
      responses:
        '200':
          description: Signed PDF document
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '422':
          description: Validation error
          content: {}
      x-codegen-request-body-name: body
components:
  securitySchemes:
    openId:
      type: openIdConnect
      openIdConnectUrl: >-
        https://auth-test.sphereon.com/auth/realms/sign-test/.well-known/openid-configuration
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: >-
            https://auth-test.sphereon.com/auth/realms/sign-test/protocol/openid-connect/token
          scopes:
            read:vdx_sign_key: Read/List Keys/Certificates
            admin:vdx_sign_key: Administer Keys/Certificates
            sign:vdx_sign_key: Sign using Keys/Certificates
            read:vdx_sign_config: Read configurations
            admin:vdx_sign_config: Create and update configurations
            admin:vdx_sign_provider: Create and update Key Providers
        authorizationCode:
          tokenUrl: >-
            https://auth-test.sphereon.com/auth/realms/sign-test/protocol/openid-connect/token
          authorizationUrl: >-
            https://auth-test.sphereon.com/auth/realms/sign-test/protocol/openid-connect/auth
          scopes:
            read:vdx_sign_key: Read/List Keys/Certificates
            admin:vdx_sign_key: Administer Keys/Certificates
            sign:vdx_sign_key: Sign using Keys/Certificates
            read:vdx_sign_config: Read configurations
            admin:vdx_sign_config: Create and update configurations
            admin:vdx_sign_provider: Create and update Key Providers
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    DetermineSignInput:
      description: >-
        The input value that needs to be signed from the provided data. For
        example a PDF signature isn't a simple hash of the whole file
      type: object
      required:
        - origData
        - signMode
        - binding
      properties:
        origData:
          $ref: '#/components/schemas/OrigData'
        signMode:
          $ref: '#/components/schemas/SignMode'
        binding:
          $ref: '#/components/schemas/ConfigKeyBinding'
        signatureFormParametersOverride:
          $ref: '#/components/schemas/SignatureFormParameters'
    DetermineSignInputResponse:
      type: object
      description: Determine sign input value response
      required:
        - signInput
      properties:
        signInput:
          $ref: '#/components/schemas/SignInput'
    SignInput:
      required:
        - name
        - input
        - signMode
        - signingDate
        - binding
        - signatureFormParameters
      type: object
      description: >-
        The input value as previously determined that needs to be signed or
        digested
      properties:
        name:
          type: string
          description: The file name
          example: example.pdf
        input:
          type: string
          format: byte
          description: The input value
          example: <base64>
        signMode:
          $ref: '#/components/schemas/SignMode'
        digestAlgorithm:
          $ref: '#/components/schemas/DigestAlgorithm'
        signingDate:
          type: string
          format: date-time
          example: '2022-06-11T22:53:40Z'
          description: >-
            This is the date which comes from the initial configuration signing
            date. We need to keep a record of this, in case a PDF document does
            not have a document Id set. Otherwise in different steps different
            date/times would be used, resulting in different hashes for the PDF
            document. Do not change this value between calls
        binding:
          $ref: '#/components/schemas/ConfigKeyBinding'
        signatureFormParameters:
          $ref: '#/components/schemas/SignatureFormParameters'
        password:
          type: string
          description: The password to open the input file
          example: secret-password
    SignOutput:
      type: object
      description: >-
        The output value, containing the merged original data together with the
        signature
      required:
        - name
        - value
        - digestAlgorithm
        - signature
      properties:
        name:
          type: string
          description: The file name
          example: example.pdf
        mimeType:
          type: string
          description: The mimetype of the file
          example: application/pdf
        value:
          type: string
          format: byte
          description: The signed/merged output value of the document
        digestAlgorithm:
          $ref: '#/components/schemas/DigestAlgorithm'
        signature:
          $ref: '#/components/schemas/Signature'
    Signature:
      type: object
      description: The signature object
      required:
        - value
        - algorithm
        - signMode
        - keyEntry
        - binding
        - date
      properties:
        value:
          description: The actual signature value in base64 form
          type: string
          format: byte
          example: <base64>
        algorithm:
          $ref: '#/components/schemas/SignatureAlgorithm'
        signMode:
          $ref: '#/components/schemas/SignMode'
        keyEntry:
          $ref: '#/components/schemas/KeyEntry'
        binding:
          $ref: '#/components/schemas/ConfigKeyBinding'
        date:
          type: string
          format: date-time
          example: '2022-06-11T22:53:40Z'
          description: >-
            This is the date signature date which comes from the initial
            configuration signing date. We need to keep a record of this, in
            case a PDF document does not have a document Id set. Otherwise in
            different steps different date/times would be used, resulting in
            different hashes for the PDF document. Do not change this value in
            between calls for the same input file/digest
        signatureFormParameters:
          $ref: '#/components/schemas/SignatureFormParameters'
        password:
          type: string
          description: The password to open the input file
          example: secret-password
    MergeSignature:
      type: object
      description: >-
        The merge signature request values. Containing the Original Data and the
        previously created Signature.
      required:
        - origData
        - signature
      properties:
        origData:
          $ref: '#/components/schemas/OrigData'
        signature:
          $ref: '#/components/schemas/Signature'
    MergeSignatureResponse:
      type: object
      description: The merge signature response object
      required:
        - signOutput
      properties:
        signOutput:
          $ref: '#/components/schemas/SignOutput'
    Digest:
      type: object
      description: >-
        The digest object, containing a SignInput object. Used in both digest
        requests and responses
      required:
        - signInput
      properties:
        signInput:
          $ref: '#/components/schemas/SignInput'
    CreateSignature:
      type: object
      description: >-
        Create the signature from the input data. Signature Form Parameters
        provided here, override the config's Signature Form Parameters
      required:
        - signInput
      properties:
        signInput:
          $ref: '#/components/schemas/SignInput'
        maskGenFunction:
          $ref: '#/components/schemas/MaskGenFunction'
        signatureAlgorithm:
          $ref: '#/components/schemas/SignatureAlgorithm'
    MaskGenFunction:
      type: string
      description: Mask Generation Function to create random signatures.
      example: MGF1
      enum:
        - MGF1
    CreateSignatureResponse:
      type: object
      description: The signature response
      required:
        - signature
      properties:
        signature:
          $ref: '#/components/schemas/Signature'
    LinkKey:
      type: object
      required:
        - kid
      properties:
        kid:
          type: string
          description: The key identifier
          example: key1234
        providerKid:
          type: string
          description: The id as used by the provider
          example: 12abds-434223-dfss-432432
        accessRestrictions:
          $ref: '#/components/schemas/AccessRestrictions'
    ImportX509Certificate:
      type: object
      description: Imports a X509 Certificate as a Key Entry
      required:
        - kid
        - certificate
      properties:
        kid:
          type: string
          description: The Key Identifier to create
          example: key1234
        certificate:
          type: string
          format: byte
          description: encoded X509 certificate
          example: <encoded X509 certificate base64>
        certificateChain:
          type: array
          items:
            type: string
            format: byte
            description: encoded X509 certificate chain
            example: <encoded X509 certificate chain base64>
        accessRestrictions:
          $ref: '#/components/schemas/AccessRestrictions'
    CreateUpdateKey:
      type: object
      description: Create or update Key response object
      required:
        - keyEntry
      properties:
        keyEntry:
          $ref: '#/components/schemas/KeyEntry'
        password:
          type: string
          description: Optional password used to access the key
          example: example-password
        accessRestrictions:
          $ref: '#/components/schemas/AccessRestrictions'
    KeyUsageType:
      type: string
      description: The allowed Key usage types for the certificate/key
      example: DIGITAL_SIGNATURE
      enum:
        - DIGITAL_SIGNATURE
        - NON_REPUDIATION
        - KEY_ENCIPHERMENT
        - DATA_ENCIPHERMENT
        - KEY_AGREEMENT
        - KEY_key_SIGN
        - CRL_SIGN
        - ENCIPHER_ONLY
        - DECIPHER_ONLY
    KeyResponse:
      type: object
      description: The key entry response
      required:
        - keyEntry
      properties:
        keyEntry:
          $ref: '#/components/schemas/KeyEntry'
        accessRestrictions:
          $ref: '#/components/schemas/AccessRestrictions'
    Certificate:
      type: object
      description: A X509 Certificate
      required:
        - value
      properties:
        value:
          type: string
          format: byte
          description: The certificate (X509) in base64 encoding
          example: <certificate (X509) in base64 encoding>
        fingerPrint:
          type: string
          description: The fingerprint (hash) of the certificate
          example: 1E:DD:AD:32:C3:54:3F:C3:6F:7F:94:51:8D:5E:F7:ED:7C:DB:5D:A5
        serialNumber:
          type: string
          description: The serial number of the certificate
          example: 00936EACBE07F201DF
        issuerDN:
          type: string
          description: The Distinguished Name of the issuer
          example: >-
            CN=Ensured Document Signing CA, O=Ensured B.V., L=Heerhugowaard,
            ST=Noord-Holland, C=NL
        subjectDN:
          type: string
          description: The Distinguished Name of the subject
          example: >-
            CN=USERTrust RSA Certification Authority, O=The USERTRUST Network,
            L=Jersey City, ST=New Jersey, C=US
        notBefore:
          type: string
          format: date-time
          description: The date/time after which the certificate is valid
          example: '2022-07-25T22:53:40.276+00:00'
        notAfter:
          type: string
          format: date-time
          description: The date/time after which the certificate is not valid anymore
          example: '2032-07-25T22:53:40.276+00:00'
        keyUsage:
          type: array
          items:
            $ref: '#/components/schemas/KeyUsageType'
    KeyEntry:
      type: object
      description: >-
        The Key Entry, which typically is a X509 Certificate. It requires a
        public key
      required:
        - kid
        - providerId
        - publicKey
        - encryptionAlgorithm
      properties:
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/KeyEntryAttribute'
        kid:
          type: string
          description: The Key entry kid
          example: key1234
        providerId:
          type: string
          description: The ID of the Key Provider to which this key belongs
          example: 12abds-434223-dfss-432432
        encryptionAlgorithm:
          $ref: '#/components/schemas/CryptoAlgorithm'
        publicKey:
          $ref: '#/components/schemas/Key'
        certificate:
          $ref: '#/components/schemas/Certificate'
        certificateChain:
          type: array
          items:
            $ref: '#/components/schemas/Certificate'
    KeyEntryAttribute:
      type: object
      description: Key Entry Attribute
      required:
        - name
        - value
      properties:
        name:
          type: string
          description: The name of the attribute
          example: attribute1
        value:
          type: string
          description: The value of the attribute
          example: example value 1
    Key:
      type: object
      description: A public or private key
      required:
        - algorithm
        - value
      properties:
        algorithm:
          $ref: '#/components/schemas/CryptoAlgorithm'
        value:
          type: string
          format: byte
          description: The key in base64 encoding
          example: <base64-key>
        format:
          type: string
          description: The key encoding format if supported
          example: X.509
    AccessRestrictions:
      type: object
      title: Access Restrictions
      description: Access Restrictions
      required:
        - accessLevel
      properties:
        subjectId:
          type: string
          description: The subject/owner id
          example: subject1234
          readOnly: true
        roleRestrictions:
          type: array
          items:
            $ref: '#/components/schemas/RoleRestriction'
        accessLevel:
          $ref: '#/components/schemas/AccessLevel'
    SignatureConfig:
      type: object
      title: Signature Config
      description: A signature configuration object
      required:
        - signatureLevel
        - signatureFormParameters
      properties:
        timestampParameters:
          $ref: '#/components/schemas/TimestampParameters'
        signatureLevel:
          $ref: '#/components/schemas/SignatureLevel'
        digestAlgorithm:
          $ref: '#/components/schemas/DigestAlgorithm'
        signatureFormParameters:
          $ref: '#/components/schemas/SignatureFormParameters'
        accessRestrictions:
          $ref: '#/components/schemas/AccessRestrictions'
    TimestampParameters:
      type: object
      description: Timestamp parameters like url and different baseline settings
      required:
        - tsaUrl
      properties:
        tsaUrl:
          type: string
          description: The Time Stamp Authority URL
          example: http://example-tsa-url.com
        baselineBContentTimestampParameters:
          $ref: '#/components/schemas/TimestampParameterSettings'
        baselineTSignatureTimestampParameters:
          $ref: '#/components/schemas/TimestampParameterSettings'
        baselineLTAArchiveTimestampParameters:
          $ref: '#/components/schemas/TimestampParameterSettings'
    TimestampParameterSettings:
      type: object
      description: Timestamp parameters
      required:
        - timestampContainerForm
        - digestAlgorithm
      properties:
        visualSignatureParameters:
          $ref: '#/components/schemas/VisualSignatureParameters'
        timestampContainerForm:
          $ref: '#/components/schemas/TimestampContainerForm'
        digestAlgorithm:
          $ref: '#/components/schemas/DigestAlgorithm'
        canonicalizationMethod:
          $ref: '#/components/schemas/CanonicalizationMethod'
    TimestampContainerForm:
      type: string
      description: >-
        Choose the correct form. PDFs use PDF. There is also documents which can
        contain ASiC-E or ASiC-S containers
      default: PDF
      example: PDF
      enum:
        - PDF
        - ASiC_E
        - ASiC_S
    CanonicalizationMethod:
      type: string
      default: EXCLUSIVE
      example: EXCLUSIVE
      enum:
        - EXCLUSIVE
    RoleRestriction:
      type: object
      description: >-
        Describes which roles and/or access levels are allowed to perform
        certain actions/permissions
      required:
        - name
        - permission
      properties:
        name:
          type: string
          description: >-
            The role name as defined in an IAM system. A User/Group needs to
            have this role name as part of its JWT claims. Not used in case
            access level is set to SUBJECT or PUBLIC!
          example: HR Department
        permission:
          $ref: '#/components/schemas/RolePermission'
    AccessLevel:
      type: string
      description: >-
        The access level can be used to restrict the access to a tenant, to the
        subject/self or allow public access
      default: TENANT
      example: TENANT
      enum:
        - SUBJECT
        - TENANT
        - PUBLIC
    RolePermission:
      type: string
      description: >-
        The permission. Read: Allows to read an object. Use: Allows to use the
        object, not necessarily read the object. Manage: Allows to perform
        updates/deletes to the object
      example: READ
      enum:
        - READ
        - USE
        - MANAGE
    CreateKeyProvider:
      type: object
      description: Create a new Key Provider
      required:
        - type
      properties:
        cacheEnabled:
          type: boolean
          default: false
          description: Whether to cache Keys or not
          example: false
        cacheTTLInSeconds:
          type: number
          default: 300
          description: The cache TTL in seconds
          example: 300
        type:
          $ref: '#/components/schemas/KeyProviderType'
        azureKeyvaultSettings:
          $ref: '#/components/schemas/AzureKeyvaultSetting'
        accessRestrictions:
          $ref: '#/components/schemas/AccessRestrictions'
    AzureKeyvaultSetting:
      type: object
      description: Azure Keyvault and Managed HSM settings
      required:
        - keyvaultUrl
        - tenantId
        - credentialOpts
      properties:
        keyvaultUrl:
          type: string
          description: The Azure keyvault url
          example: https://example-vault.vault.azure.net/
        tenantId:
          type: string
          description: The azure tenant/directory ID
          example: a3b42c5a-5512-4379-bc27-4682acec459a
        applicationId:
          type: string
          description: An id to identify your application (optional)
          example: your-app-id
        credentialOpts:
          $ref: '#/components/schemas/AzureCredentialOpts'
    AzureCredentialOpts:
      description: The Azure credential options
      type: object
      required:
        - credentialMode
      properties:
        credentialMode:
          type: string
          description: The azure credential mode
          example: SERVICE_CLIENT_SECRET
          enum:
            - SERVICE_CLIENT_SECRET
        secretCredentialOpts:
          $ref: '#/components/schemas/AzureSecretCredentialOpts'
    AzureSecretCredentialOpts:
      type: object
      description: Azure Secret Credential values
      required:
        - clientId
      properties:
        clientId:
          type: string
          description: The azure keyvault client id which has access to the keyvault
          example: cfa45c7f-1212-7a59-ac45-aa82acec4364343
        clientSecret:
          type: string
          description: The azure keyvault client secret/password belonging to the client id
          example: your azure clientsecret as provided by Azure
    KeyProviderType:
      type: string
      description: >-
        The Key Provider type. PKCS11 is an interface to HSM, usb and smart
        cards. PKCS12 are keystores. The Azure keyvault options allows for an
        intergration with Azure Keyvault and Azure Managed HSM
      example: AZURE_KEYVAULT
      enum:
        - PKCS11
        - PKCS12
        - AZURE_KEYVAULT
    UpdateKeyProvider:
      type: object
      description: Update a key provider
      allOf:
        - $ref: '#/components/schemas/CreateKeyProvider'
      properties:
        providerId:
          type: string
          description: The id of the provider
          example: 12abds-434223-dfss-432432
    KeyProviderResponse:
      type: object
      description: Key provider response
      allOf:
        - $ref: '#/components/schemas/CreateKeyProvider'
      properties:
        providerId:
          type: string
          readOnly: true
          description: The provider ID
          example: 12abds-434223-dfss-432432
    KeyProvidersResponse:
      type: object
      description: All Key Providers response
      properties:
        keyProviders:
          type: array
          items:
            $ref: '#/components/schemas/KeyProviderResponse'
    ConfigResponse:
      type: object
      description: The signature configuration response
      required:
        - configId
        - config
      properties:
        configId:
          type: string
          description: The config id
          readOnly: true
          example: 12234-1324343-4344334-3443443
        config:
          $ref: '#/components/schemas/SignatureConfig'
    SignatureFormParameters:
      type: object
      description: The signature form parameters to use for signature creation
      properties:
        padesSignatureFormParameters:
          $ref: '#/components/schemas/PadesSignatureFormParameters'
    PadesSignatureFormParameters:
      type: object
      description: The PAdES signature form parameters to use for signature creation
      required:
        - mode
      properties:
        mode:
          $ref: '#/components/schemas/PdfSignatureMode'
        reason:
          type: string
          description: The reason for the signature
          example: Agreed statement of work
        contactInfo:
          type: string
          description: The contant information that ends up in the signature
          example: john.doe@example.com
        location:
          type: string
          description: The location that ends up in the signature
          example: Maarssen, The Netherlands
        signerName:
          type: string
          description: The name of the signer that ends up in the signature
          example: John Doe
        passwordProtection:
          type: string
          description: Password in case PDF is password protected
          example: secret password here
        signinTimeZone:
          type: string
          description: >-
            The timezone to use for the signature. Uses server timezone by
            default if omitted
          example: GMT+3
        visualSignatureParameters:
          $ref: '#/components/schemas/VisualSignatureParameters'
        certificationPermission:
          $ref: '#/components/schemas/CertificationPermission'
    CertificationPermission:
      type: string
      description: >-
        Determines the permissions allowed on the PDF document after
        certification. Minimal changes means filling in forms, instantiating
        page templates and signing. Other changes invalidate the signature
      enum:
        - NO_CHANGE_PERMITTED
        - MINIMAL_CHANGES_PERMITTED
        - CHANGES_PERMITTED
      example: NO_CHANGE_PERMITTED
    PdfSignatureMode:
      type: string
      description: >-
        The signature mode. Certification typically is used by the author and
        can only be used once. Approval typically is used by recipients and can
        be used multiple times
      example: APPROVAL
      enum:
        - CERTIFICATION
        - APPROVAL
    VisualSignatureParameters:
      type: object
      description: Parameters for visual signatures
      properties:
        image:
          $ref: '#/components/schemas/OrigData'
        zoom:
          type: integer
          description: Zoom level percentage of the image
          default: 100
          example: 120
        backgroundColor:
          type: string
          description: Background color of the visual signature
          default: WHITE
          example: WHITE
        dpi:
          type: integer
          description: The DPI of the image
          example: 96
        rotation:
          $ref: '#/components/schemas/VisualSignatureRotation'
        alignmentHorizontal:
          $ref: '#/components/schemas/VisualSignatureAlignmentHorizontal'
        alignmentVertical:
          $ref: '#/components/schemas/VisualSignatureAlignmentVertical'
        imageScaling:
          $ref: '#/components/schemas/VisualSignatureImageScaling'
        textParameters:
          $ref: '#/components/schemas/VisualSignatureTextParameters'
        fieldParameters:
          $ref: '#/components/schemas/VisualSignatureFieldParameters'
    VisualSignatureFieldParameters:
      type: object
      description: The field location and dimensions for a visual signature
      properties:
        fieldId:
          type: string
          description: The signature field id/name (optional)
          example: Signature1
        page:
          type: integer
          default: 1
          description: The page number where the signature field should be placed
          example: 2
        originX:
          type: number
          format: float
          description: >-
            The X coordinate where the signature field should be placed relative
            to the top-left corner
          example: 100f
        originY:
          type: number
          format: float
          description: >-
            The Y coordinate where the signature field should be placed relative
            to the top-left corner
          example: 400f
        width:
          type: number
          format: float
          description: The signature field width
          example: 150f
        height:
          type: number
          format: float
          description: The signature field height
          example: 75f
    VisualSignatureTextParameters:
      type: object
      description: >-
        Text and it's properties that should be part of the visual signature
        (optional)
      properties:
        signerTextPosition:
          $ref: '#/components/schemas/SignerTextPosition'
        signerTextVerticalAlignment:
          $ref: '#/components/schemas/SignerTextVerticalAlignment'
        signerTextHorizontalAlignment:
          $ref: '#/components/schemas/SignerTextHorizontalAlignment'
        text:
          type: string
          description: The text that shows up inside the signature
          example: "John Doe\r\nCEO Acme"
        font:
          type: string
          description: The font to use
          example: calibri
        textWrapping:
          $ref: '#/components/schemas/TextWrapping'
        padding:
          type: number
          format: float
          default: 5f
          example: 10f
          description: The padding to apply to the text
        textColor:
          type: string
          default: BLACK
          description: The text color
          example: RED
        backgroundColor:
          type: string
          default: WHITE
          description: The background color
          example: GRAY
    TextWrapping:
      type: string
      description: >-
        Defines text wrapping inside a signature field. Fill box, changes the
        font size to fill the box. Fill box and linewrapping, wraps lines to
        fill the box as optimal as possible. Font based uses the provided font
        settings
      enum:
        - FILL_BOX
        - FILL_BOX_AND_LINEBREAK
        - FONT_BASED
    SignerTextPosition:
      type: string
      description: >-
        Defines where the signer text resides relative to an image inside the
        signature field
      example: TOP
      enum:
        - TOP
        - BOTTOM
        - RIGHT
        - LEFT
    SignerTextHorizontalAlignment:
      type: string
      description: How to horizontally align the text
      example: LEFT
      enum:
        - LEFT
        - CENTER
        - RIGHT
    SignerTextVerticalAlignment:
      type: string
      description: How to vertically align the text
      example: MIDDLE
      enum:
        - TOP
        - MIDDLE
        - BOTTOM
    VisualSignatureImageScaling:
      type: string
      description: >-
        How the signature image should scale. Strech, streches the image in both
        directions to fill the signature box. Zoom and center. Zooms to the
        minimal fitting dimension and centers for the other dimension. Center,
        keeps the original size and centers the image in both dimensions
      example: CENTER
      enum:
        - STRETCH
        - ZOOM_AND_CENTER
        - CENTER
    VisualSignatureAlignmentHorizontal:
      type: string
      description: How to horizontally align the signature
      example: CENTER
      enum:
        - NONE
        - LEFT
        - CENTER
        - RIGHT
    VisualSignatureAlignmentVertical:
      type: string
      description: How to vertically align the signature
      example: NONE
      enum:
        - NONE
        - TOP
        - MIDDLE
        - BOTTOM
    VisualSignatureRotation:
      type: string
      description: >-
        The signature rotation. None for none, automatic based upon the input
        document rotation
      example: AUTOMATIC
      enum:
        - NONE
        - AUTOMATIC
        - ROTATE_90
        - ROTATE_180
        - ROTATE_270
    OrigData:
      type: object
      description: >-
        Original data that either needs to be signed, or is an image to use in
        visual signatures
      required:
        - name
        - content
      properties:
        name:
          type: string
          description: The file name
          example: example.pdf
        mimeType:
          type: string
          description: The mimetype of the file
          example: application/pdf
        content:
          type: string
          format: byte
          description: The actual content in base64 form of the file
          example: JyAgICAg...
        password:
          type: string
          description: A password if the orig data is protected by a password
          example: s3cr3tp@ss
    SignatureLevel:
      type: string
      description: The signature level to use
      example: PAdES_BASELINE_B
      enum:
        - PDF_NOT_ETSI
        - PKCS7_B
        - PKCS7_T
        - PKCS7_LT
        - PKCS7_LTA
        - PAdES_BASELINE_B
        - PAdES_BASELINE_T
        - PAdES_BASELINE_LT
        - PAdES_BASELINE_LTA
    SignMode:
      type: string
      description: >-
        Whether the signature should be about a full document, meaning
        internally a hash/digest needs to be created or whether it was already
        digested
      example: DOCUMENT
      enum:
        - DIGEST
        - DOCUMENT
    DigestAlgorithm:
      type: string
      description: The hash/digest algorithm to use
      default: SHA256
      example: SHA256
      enum:
        - NONE
        - SHA256
        - SHA512
        - SHA3_256
        - SHA3_512
    SignatureAlgorithm:
      type: string
      description: The signature algorithm to use
      example: RSA_SSA_PSS_SHA3_256_MGF1
      enum:
        - RSA_RAW
        - RSA_SHA256
        - RSA_SHA512
        - RSA_SHA3_256
        - RSA_SHA3_512
        - DSA_SHA256
        - DSA_SHA512
        - RSA_SSA_PSS_RAW_MGF1
        - RSA_SSA_PSS_SHA256_MGF1
        - RSA_SSA_PSS_SHA512_MGF1
        - RSA_SSA_PSS_SHA3_256_MGF1
        - RSA_SSA_PSS_SHA3_512_MGF1
    CryptoAlgorithm:
      type: string
      description: The encryption/crypot algorithm to use
      example: ECDSA
      enum:
        - RSA
        - ECDSA
        - X25519
        - X448
        - ED25519
        - ED448
        - HMAC
    ErrorResponse:
      type: object
      readOnly: true
      description: The response returned in case of errors
      properties:
        timestamp:
          type: string
          format: date-time
          description: The timestamp of the error
          example: '2022-06-11T22:53:40.276+00:00'
        path:
          type: string
          description: The REST endpoint path
          example: /signatures/create
        status:
          type: integer
          description: The HTTP status code
          example: 500
        error:
          type: string
          description: The error
          example: Internal Server Error
        requestId:
          type: string
          description: The Unique Request Id
          example: 38fd064b
    ProviderBinding:
      type: object
      description: >-
        Provides the Key Provider ID to use. Used in payloads. This is not done
        through path parameters like a normal REST pattern to protect against
        ACCESS log statistics/insights
      required:
        - keyProviderId
      properties:
        keyProviderId:
          type: string
          description: >-
            The Key Provider id, which provides the Key/Certificate denoted by
            kid
          example: a1b3c3....
    ConfigKeyBinding:
      type: object
      description: >-
        Binds the Key Identifier, provider and signature configuration. This is
        not done through path parameters like a normal REST pattern to protect
        against ACCESS log statistics/insights
      allOf:
        - $ref: '#/components/schemas/ProviderBinding'
      required:
        - kid
      properties:
        kid:
          type: string
          description: The Key Identifier
          example: hr-cert
        signatureConfigId:
          type: string
          description: The signature configuration id
          example: 1234....
    SignData:
      type: object
      properties:
        emailAddress:
          type: string
        name:
          type: string
        location:
          type: string
        reason:
          type: string
      example:
        emailAddress: example@example.com
        name: Bob Example
        location: Amsterdam
        reason: Approved
    EzDocJsonSignRequest:
      type: object
      properties:
        signData:
          $ref: '#/components/schemas/SignData'
        content:
          type: string
          format: byte
          example: <content byte>
        binding:
          $ref: '#/components/schemas/ConfigKeyBinding'
    EzDocMultipartSignRequest:
      type: object
      properties:
        signData:
          $ref: '#/components/schemas/SignData'
        content:
          type: string
          format: binary
          example: <content binary>
        binding:
          $ref: '#/components/schemas/ConfigKeyBinding'
  requestBodies:
    LinkKeyRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LinkKey'
    ImportX509CertificateRequest:
      required: true
      description: Import X509 Certificate
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ImportX509Certificate'
    CreateOrUpdateKeyRequest:
      required: true
      description: Create/Update Key Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateUpdateKey'
    CreateKeyProviderRequest:
      required: true
      description: Create key provider request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateKeyProvider'
    UpdateKeyProviderRequest:
      required: true
      description: Update key provider request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UpdateKeyProvider'
    ConfigRequest:
      required: true
      description: Configuration Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SignatureConfig'
    DigestRequest:
      required: true
      description: Determine Digest Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Digest'
    DetermineSignInputRequest:
      required: true
      description: Determine Sign Input Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DetermineSignInput'
    CreateSignatureRequest:
      required: true
      description: Create Signature Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateSignature'
    MergeSignatureRequest:
      required: true
      description: Merge Signature Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MergeSignature'
  parameters:
    kid:
      name: kid
      in: path
      schema:
        type: string
      required: true
      description: Certificate/Key kid
      example: 2ZQpJ3UpbjAYXYGaXEJl8lV0TOI
    configId:
      name: configId
      in: path
      schema:
        type: string
      required: true
      description: Config ID
      example: 5d9f2462-13c8-45b6-8e0e-8971cbe412b5
    providerId:
      name: providerId
      in: path
      schema:
        type: string
      required: true
      description: Key Provider ID
      example: 89fbae00-dbf4-41a3-91ed-15a3fa2b83d5