Swisscom Signatures API

openapi: 3.2.0
info:
  title: All-in Signing Service REST Application Signatures API
  description: All-in Signing Service
  contact: {}
  license:
    name: Commercial
    url: ''
  version: '3'
servers:
- url: https://ais.swisscom.com/AIS-Server/rs/v1.0
  description: Base URL declared by the provider in apis.yml (roadmap#122).
tags:
- name: signatures
paths:
  /signatures/signDoc:
    post:
      tags:
      - signatures
      summary: Request creation of AdES signatures
      operationId: signDoc
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignDocRequest'
            example:
              SAD: eyJh...Mmw
              requestID: fdf41e6a-382a-4512-afe9-fd2a9bab30d7
              credentialID: OnDemand-Qualified
              profile: http://uri.etsi.org/19432/v1.1.1#/creationprofile#
              signatureFormat: P
              conformanceLevel: AdES-B-LT
              documentDigests:
                hashAlgorithmOID: 2.16.840.1.101.3.4.2.1
                hashes:
                - HLNTuE2+zWOo+p1VfQdjdEjDC9xcLfVdqdHYX2gwTFM=
                - sHS3ei9wNyR/rGu5ghto/v0+h22wmdlD3TGxRyO/sgM=
      responses:
        '200':
          description: Result of the signature creation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignDocResponse'
              example:
                validationInfo:
                  ocsp:
                  - MII...AGk=
                  crl:
                  - MII...sNrI=
                responseID: fdf41e6a-382a-4512-afe9-fd2a9bab30d7
                SignatureObject:
                - MII2...23w4=
                - MII2...m5c=
        4XX:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        5XX:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    DocumentDigests:
      required:
      - hashAlgorithmOID
      - hashes
      type: object
      properties:
        hashes:
          type: array
          description: Hashes to be signed
          items:
            type: string
            format: Base64
        hashAlgorithmOID:
          type: string
          description: Hash algorithm OID used to calculate the hashes to be signed
          example: 2.16.840.1.101.3.4.2.1
      description: Hashes to be signed and the algorithm OID used to calculate those hashes.
    SignDocRequest:
      required:
      - SAD
      - credentialID
      - signatureFormat
      - profile
      - documentDigests
      type: object
      properties:
        profile:
          type: string
          description: 'Identifies the protocol being used by the client application to communicate with the

            SCS.'
          example: http://uri.etsi.org/19432/v1.1.1#/creationprofile#
        signatureFormat:
          type: string
          description: 'Signature format. One of the following values:


            * `C`: CAdES

            * `P`: PAdES'
          enum:
          - C
          - P
        conformanceLevel:
          type: string
          description: 'Signature conformance level. One of the following values:


            * `AdES-B-B`: 191x2 level B

            * `AdES-B-T`: 191x2 level T

            * `AdES-B-LT`: 191x2 level LT'
          enum:
          - AdES-B-B
          - AdES-B-T
          - AdES-B-LT
          default: AdES-B-B
        documentDigests:
          $ref: '#/components/schemas/DocumentDigests'
        requestID:
          type: string
          description: 'Data from the client application generally used to handle a signature transaction

            identifier'
        SAD:
          type: string
          description: Authentication data used to authorize the use of the signing key
        credentialID:
          type: string
          description: Identifier associated to the private key and corresponding certificate
      description: AdES signature creation request to the signature creation service (SCS)
    SignDocResponse:
      type: object
      properties:
        SignatureObject:
          type: array
          description: Signatures detached from the documents
          items:
            type: string
            format: Base64
        responseID:
          type: string
          description: 'Arbitrary value generated by the SCS uniquely identifying the response originated from

            the SCS itself. This value is mainly used in asynchronous operation mode where the

            client application shall provide the `responseID` value received with the initial

            response as `requestID` of any subsequent request polling the pending signature results.'
        validationData:
          $ref: '#/components/schemas/ValidationInfo'
      description: AdES signature creation response from signature creation service (SCS)
    ValidationInfo:
      type: object
      description: 'Validation information to be embedded into the resulting signed document in order to achieve

        AdES-B-LT level.  Only returned when signatureFormat is `P` and conformanceLevel is

        `AdES-B-LT`.  This structure is derived from CSC specification v2.'
      properties:
        ocsp:
          type: array
          description: OCSP response objects
          items:
            type: string
            format: Base64
        crl:
          type: array
          description: CRL objects
          items:
            type: string
            format: Base64
    ErrorResponse:
      required:
      - error
      type: object
      properties:
        error:
          type: string
          description: "Error code. Common codes are:\n\n* `invalid_request`: The request is missing a required parameter, includes an invalid\n  parameter value, includes a parameter more than once, or is otherwise malformed.\n* `unauthorized_client`: The client is not authorized to call the API method.\n* `access_denied`: The user, authorization server, or remote service denied the request.\n* `unsupported_response_type`: The authorization server does not support obtaining an\n  authorization code using this method.\n* `invalid_scope`: The requested scope is invalid, unknown, or malformed.\n* `server_error`: The authorization server encountered an unexpected condition that\n  prevented it from fulfilling the request.\n* `temporarily_unavailable`: The authorization server is currently unable to handle the\n  request due to a temporary overloading or maintenance of the server.\n* `expired_token`: The access or refresh token is expired or has been revoked.\n* `invalid_token`: The token provided is not a valid OAuth access or refresh token."
          example: invalid_request
        error_description:
          type: string
          description: 'Human readable description, written in a language that considers the requested language,

            which provides additional information on the error.'
          example: Required parameter `SAD` is missing
      description: Outcome of operations with an HTTP status different from 200 OK