Swisscom All-in Signing Service (AIS) API

openapi: 3.0.1
info:
  title: All-in Signing Service REST Application
  description: All-in Signing Service
  contact: {}
  license:
    name: Commercial
    url: ''
  version: '3'
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:
    ErrorResponse:
      required:
        - error
      type: object
      properties:
        error:
          type: string
          description: |-
            Error code. Common codes are:

            * `invalid_request`: The request is missing a required parameter, includes an invalid
              parameter value, includes a parameter more than once, or is otherwise malformed.
            * `unauthorized_client`: The client is not authorized to call the API method.
            * `access_denied`: The user, authorization server, or remote service denied the request.
            * `unsupported_response_type`: The authorization server does not support obtaining an
              authorization code using this method.
            * `invalid_scope`: The requested scope is invalid, unknown, or malformed.
            * `server_error`: The authorization server encountered an unexpected condition that
              prevented it from fulfilling the request.
            * `temporarily_unavailable`: The authorization server is currently unable to handle the
              request due to a temporary overloading or maintenance of the server.
            * `expired_token`: The access or refresh token is expired or has been revoked.
            * `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
    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
    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)