dev.trustservices.swisscom.com Open in urlscan Pro
194.209.222.161  Public Scan

Form analysis
0 forms found in the DOM

Text Content

Contact experts

 * Introduction
 * Get Started
 * Documentation
 * GitHub Repositories
 * Learn & Use the APIs
   * APIs Overview
   * Postman Samples
   * Client Libraries
 * Types of Signatures
   * On-Demand Signatures
   * Static Signatures
   * Trusted Timestamps
 * AIS API Definition
   * postrequestSignature
   * postpollSignatureStatus

API docs by Redocly





SWISSCOM TRUST SERVICES DEV HUB (V1.1)

Download OpenAPI specification:Download

E-mail: paul.muntean@swisscom.com License: Swisscom License Terms of Service




INTRODUCTION

Welcome to the Development Hub for the Swisscom Trust Services APIs. This
website provides the resources we have available to help you get started in
using the APIs that Swisscom provide for:

 * Smart Registration Service
 * Registration Authority Service
 * All-In Signing (AIS) Service.

On this site you can find:

 * links to main reference guides and API definitions
 * useful Github repositories that we develop as open source libraries to help
   users integrate our services
 * Postman samples/collections to quickly test our APIs and get a feeling of how
   they work
 * Complete API documentation of the All-In Signing Service (Redocly
   documentation)


GET STARTED

Here are the steps to help you get started using our services:

 1. Have a look at the Service Overview Guide (PDF) to understand how our
    services work together and what API you need to use
 2. Check the All-In Signing Service Reference Guide (PDF) to familiarize
    yourself with our main signing API. This API allows you to create user
    signatures around digital documents and create qualified electronic
    signatures
 3. Check the Github repositories from the Swisscom Trust Services space. While
    you can use any library you like for accessing our APIs, we provide
    production-level client libraries to help with the integration in your
    projects.


DOCUMENTATION

We provide the following materials for reference:

 * Main collection of documents for Swisscom Trust Services
 * Service Overview Guide (PDF)
 * All-In Signing Service API Reference Guide (PDF)
 * Smart Registration Service Integration Guide (PDF)
 * iFrame integration guide for the Password/OTP application
 * How to implement the PAdES standard and Long Term Validation signatures
 * Smart Registration Service API (Swagger definition)
 * Registration Authority Service API (Swagger definition)


GITHUB REPOSITORIES

We provide several open source libraries and projects to help you get stated
quickly using the All-In Signing Service. Here is a list of repositories on
GitHub that could come handy when using the service:

 * pdfbox-ais - All-In Signing Service client library for Java, implemented
   using the Apache PDFBox library. Both this client and PDFBox are licensed
   with Apache License 2.0, so you can use them commercially in your project
   free of charge.

 * itext7-ais - Service client library for Java, implemented using the iText 7
   library. The client is Apache License 2.0 but, in order to use it
   commercially, you need an iText license.

 * itext-dotnet-ais - Service client library for .NET, implemented using the
   iText for .NET library. Similar to itext7-ais above, the client is Apache
   License 2.0 but, to use it commercially, you need an iText license.

 * AIS-postman-samples - A collection of Postman samples ready to import in the
   tool and call against the All-In Signing Service API. Please see the section
   Postman Samples down below for more information on how to use them.


LEARN & USE THE APIS


APIS OVERVIEW


SWISSCOM REGISTRATION AUTHORITY SERVICE API (RA SERVICE)

The Registration Authority Service (RA Service) has implemented the following
business functions:

 * Encrypted storage of ID document metadata (according to legal regulation on
   electronic signatures), ID document images, and linked authenticator
   identifiers (MSISDN, Mobile ID Serial Number or PWD/OTP Serial Number) of the
   ID document holder
 * Encrypted storage of the evidences of the ID registration process (vetter's
   data and signature, ID document, signed user consent)
 * User Consent flow in the ID registration process
 * RESTful API for verifying user metadata, the linked MSISDN, and the
   compliance level of ID registration process for digital signature purpose
 * RESTful API for authentication of privileged users with Mobile ID
 * RESTful API for importing ID document metadata, ID document images, MSISDN
   and ID registration evidences for digital signature in the banking context


SMART REGISTRATION SERVICE (SRS)

Our Smart Registration Service (SRS) offers various identification procedures.

If you would like to sign documents with a qualified electronic signature, you
need to identify yourself. Currently, we offer various identification methods,
which are valid according to EU and Swiss law. As a Service Provider you need to
offer to the end user the ability to identify themselves for the All-in Signing
Service. This API provides the ability to choose an identification method for
end users if they are not already able to sign. After the successful
identification process the user is able to sign.

Please note that, in order to get access to this API in Production, you have to
use the OAuth 2.0 Client Credentials Grant See Client Credentials Grant in RFC
6479. The Client Credentials grant type is used by clients to obtain an access
token outside of the context of a user.


ALL-IN SIGNING SERVICE (AIS)

The All-In Signing Service (AIS) is a server-based remote signature service. It
enables signatories to electronically sign digital files and thus ensure the
integrity and authenticity of a file. The qualified trust service of Swisscom
creates and manages the signature certificate for the signatories as a fiduciary
and makes it available to the remote signature service via an encrypted channel.
Apart from a subscriber application for the sending and receipt of the signed
document, the signatory does not require any other operating equipment, such as
tokens or signature cards.


POSTMAN SAMPLES

Before integrating the Trust Services APIs in your project, you can have a look
at the APIs and test them a bit, to get a feeling of how they work what a
request-response roundtrip looks like. For this we provide a set of Postman
collections that you can download, import in your installation of Postman and
then call the Trust Services APIs.

The Postman collections are available on Github:
https://github.com/SwisscomTrustServices/AIS-Postman-Samples

For setting up Postman and importing the collections, here is a video with
detailed step by step instructions:


CLIENT LIBRARIES

All the APIs that we provide are REST-based APIs that can be accessed/consumed
using the available tools and client libraries that you have for the language
and platform of your choice. To help with the integration of our APIs in client
projects, we also provide custom libraries that ease up the accessing of the
interface by creating an additional layer over the interface and providing
customized functions for the main scenarios that can run on the interface.

All our libraries are open source, available on Github and licensed under Apache
License 2.0.

For the All-In Signing Service API we provide the following libraries:

 * Java client library using Apache PDFBox
   
   * This library helps with creating digital signatures for PDF documents and
     embedding the signature and the additional CRL and OCSP data (for long term
     validation) in the document. It uses the Apache PDFBox library, which is
     licensed under Apache License 2.0.
   * Learn how to use in code or as a tool
   * Download now
   * Use in Maven or Gradle

 * Java client library using iText 7
   
   * This library helps with creating digital signatures for PDF documents and
     embedding the signature and the additional CRL and OCSP data (for long term
     validation) in the document. It uses the iText library, version 7, which is
     licensed under GPL for open source client projects or with a custom paid
     license for commercial use.
   * Learn how to use in code or as a tool
   * Download now
   * Use in Maven or Gradle

 * .NET client library using iText 7
   
   * This library helps with creating digital signatures for PDF documents and
     embedding the signature and the additional CRL and OCSP data (for long term
     validation) in the document. It uses the .NET version of the iText library,
     version 7, which is licensed under GPL for open source client projects or
     with a custom paid license for commercial use.
   * Learn how to use in code or as a tool
   * Download now
   * Use in Maven or Gradle


TYPES OF SIGNATURES

The All-In Signing Service allows the acquisition of digital signatures around
hashes of documents. There are 3 types of signatures available, explained and
exemplified in the next sections.


ON-DEMAND SIGNATURES

On-Demand signatures are performed with certificates that are context-based
issued and that contain the end user information collected at the customer’s
service side itself. The collected information can be set as attributes in the
Distinguished Name (DN) of the short-lived certificate. Before issuing the
certificate and using it only for one request, a declaration of will by the
signer is enforced. On-Demand certificates and signatures are well suited for
signing documents interactively/online such as contracts, medical assessments,
construction permits, tax declarations, etc.

Here is a REST exchange for performing an On-Demand signature:

{
    "SignRequest": {
        "@Profile": "http://ais.swisscom.ch/1.1",
        "@RequestID": "ID-b0b35bee-2694-46d8-bc60-45d2a807a598",
        "InputDocuments": {
            "DocumentHash": [
                {
                    "@ID": "DOC-38b97ff6-7b32-4150-9813-a5fb33a57299",
                    "dsig.DigestMethod": {
                        "@Algorithm": "http://www.w3.org/2001/04/xmlenc#sha512"
                    },
                    "dsig.DigestValue": "Ack78UyNjqUBdNhFhiAa3dkxrL6h7KYGFwh+L3WAILbsMWdr13PI1nF3H2mA7U7Wgk+4dRbOUpZOBxg6rBnjoQ=="
                }
            ]
        },
        "OptionalInputs": {
            "AddTimestamp": {
                "@Type": "urn:ietf:rfc:3161"
            },
            "AdditionalProfile": [
                "http://ais.swisscom.ch/1.0/profiles/ondemandcertificate",
                "http://ais.swisscom.ch/1.1/profiles/redirect",
                "urn:oasis:names:tc:dss:1.0:profiles:asynchronousprocessing"
            ],
            "ClaimedIdentity": {
                "Name": "ais-90days-trial:OnDemand-Advanced"
            },
            "SignatureType": "urn:ietf:rfc:3369",
            "sc.AddRevocationInformation": {
                "@Type": "PAdES-Baseline"
            },
            "sc.SignatureStandard": "PAdES-baseline",
            "sc.CertificateRequest": {
                "sc.DistinguishedName": "cn=TEST User, givenname=User, surname=FamilyName, c=CH, serialnumber=afe1ccfa4aa229a960c25da8271b210f7c8670f2",
                "sc.StepUpAuthorisation": {
                    "sc.Phone": {
                        "sc.Language": "en",
                        "sc.MSISDN": "40712345678",
                        "sc.Message": "Please confirm the signing of the document"
                    }
                }
            }
        }
    }
}


and, after a few pollings:

{
    "SignResponse": {
        "@Profile": "http://ais.swisscom.ch/1.1",
        "@RequestID": "ID-b0b35bee-2694-46d8-bc60-45d2a807a598",
        "OptionalOutputs": {
            "sc.APTransID": "ID-694815be-ad7a-4c51-bed3-a121dcefc0fb",
            "sc.RevocationInformation": {
                "sc.CRLs": {
                    "sc.CRL": [
                        "MIIEUjC...",
                        "MIIGwzC..."
                    ]
                },
                "sc.OCSPs": {
                    "sc.OCSP": [
                        "MIIJMgo...",
                        "MIIInQo..."
                    ]
                }
            },
            "sc.StepUpAuthorisationInfo": {
                "sc.Result": {
                    "sc.SerialNumber": "SAS0118bupd4ffzyk"
                }
            }
        },
        "Result": {
            "ResultMajor": "urn:oasis:names:tc:dss:1.0:resultmajor:Success"
        },
        "SignatureObject": {
            "Base64Signature": {
                "$": "MII2yQ...",
                "@Type": "urn:ietf:rfc:3369"
            }
        }
    }
}


The resulting signature needs to be embedded in the original PDF, to get the
signed document. Here is a sample document signed with an on-demand signature
(best viewed in Adobe Acrobat Reader or other local PDF viewer that can display
the signatures of the document).

View sample document


STATIC SIGNATURES

Static signatures are performed using certificates that are standard ones
proposed and issued by any official Certificate Authority (CA) for the customer
and are securely hosted at the AIS on its Hardware Security Module (HSM). After
the certificate’s registration process, the corresponding customer can address
and use it in a secure and exclusive manner. Static certificates and signatures
are well suited for any organization planning to sign many documents in its name
in an automated manner, for example invoices, account listings, archives of
documents.

Here is a REST exchange for performing an Static signature:

{
    "SignRequest": {
        "@Profile": "http://ais.swisscom.ch/1.1",
        "@RequestID": "ID-0ca48d0e-41bb-4025-83f7-a09952bf7647",
        "InputDocuments": {
            "DocumentHash": [
                {
                    "@ID": "DOC-f76b3717-1511-4cfa-8446-ebe2a5b6eabd",
                    "dsig.DigestMethod": {
                        "@Algorithm": "http://www.w3.org/2001/04/xmlenc#sha512"
                    },
                    "dsig.DigestValue": "IMwxKxjAR+Jun6A9tT1vuk0BPeP6YfNoDm+ETenjqjnDQj0v9x4K+DHPkeV8GfpaxFO4uxfoJziVDND9H5g/gw=="
                }
            ]
        },
        "OptionalInputs": {
            "AddTimestamp": {
                "@Type": "urn:ietf:rfc:3161"
            },
            "AdditionalProfile": [],
            "ClaimedIdentity": {
                "Name": "ais-90days-trial:static-saphir4-eu"
            },
            "SignatureType": "urn:ietf:rfc:3369",
            "sc.AddRevocationInformation": {
                "@Type": "PAdES-Baseline"
            },
            "sc.SignatureStandard": "PAdES-baseline"
        }
    }
}


and the response:

{
    "SignResponse": {
        "@Profile": "http://ais.swisscom.ch/1.1",
        "@RequestID": "ID-0ca48d0e-41bb-4025-83f7-a09952bf7647",
        "OptionalOutputs": {
            "sc.RevocationInformation": {
                "sc.CRLs": {
                    "sc.CRL": [
                        "MIIEUjC...",
                        "MIIGwzC..."
                    ]
                },
                "sc.OCSPs": {
                    "sc.OCSP": [
                        "MIIJMgo...",
                        "MIIInQo..."
                    ]
                }
            }
        },
        "Result": {
            "ResultMajor": "urn:oasis:names:tc:dss:1.0:resultmajor:Success"
        },
        "SignatureObject": {
            "Base64Signature": {
                "$": "MII2CAY...",
                "@Type": "urn:ietf:rfc:3369"
            }
        }
    }
}


The resulting signature needs to be embedded in the original PDF, to get the
signed document. Here is a sample document signed with a static signature (best
viewed in Adobe Acrobat Reader or other local PDF viewer that can display the
signatures of the document).

View sample document


TRUSTED TIMESTAMPS

Trusted Timestamps applied to the hash values as signatures by AIS are qualified
timestamps provided by a trusted third party Time Stamp Authority ( TSA),
according to the RFC3161 standard. Timestamp signatures are used to prove the
existence of certain data at a certain point in time without a person or an
organization behind them. This kind of signature is well suited for system
transactions and log files.

Here is a REST exchange for performing an timestamp signature:

{
    "SignRequest": {
        "@Profile": "http://ais.swisscom.ch/1.1",
        "@RequestID": "ID-67dd19db-e5bd-4c96-9812-f4d18d885b8d",
        "InputDocuments": {
            "DocumentHash": [
                {
                    "@ID": "DOC-d4ec42b5-e03a-4837-b9fa-25a60776ac06",
                    "dsig.DigestMethod": {
                        "@Algorithm": "http://www.w3.org/2001/04/xmlenc#sha512"
                    },
                    "dsig.DigestValue": "kgF9dCQ/lnUgStceTVhSYHjFSNehpQfrGJLZEepUS15WVZ09/h5vE39Mgg7DY6qRIC9LPZXsHwECjxcWvnYrSQ=="
                }
            ]
        },
        "OptionalInputs": {
            "AddTimestamp": {
                "@Type": "urn:ietf:rfc:3161"
            },
            "AdditionalProfile": [
                "urn:oasis:names:tc:dss:1.0:profiles:timestamping"
            ],
            "ClaimedIdentity": {
                "Name": "ais-90days-trial"
            },
            "SignatureType": "urn:ietf:rfc:3161",
            "sc.AddRevocationInformation": {
                "@Type": "PAdES-Baseline"
            }
        }
    }
}


and the response:

{
    "SignResponse": {
        "@Profile": "http://ais.swisscom.ch/1.1",
        "@RequestID": "ID-67dd19db-e5bd-4c96-9812-f4d18d885b8d",
        "OptionalOutputs": {
            "sc.RevocationInformation": {
                "sc.CRLs": {
                    "sc.CRL": [
                        "MIIEUjC...",
                        "MIIGwzC..."
                    ]
                },
                "sc.OCSPs": {
                    "sc.OCSP": [
                        "MIIJMgo...",
                        "MIIInQo..."
                    ]
                }
            }
        },
        "Result": {
            "ResultMajor": "urn:oasis:names:tc:dss:1.0:resultmajor:Success"
        },
        "SignatureObject": {
            "Timestamp": {
                "RFC3161TimeStampToken": "MIIhCgYJK..."
            }
        }
    }
}


The resulting signature needs to be embedded in the original PDF, to get the
signed document. Here is a sample document signed with a timestamp signature
(best viewed in Adobe Acrobat Reader or other local PDF viewer that can display
the signatures of the document).

View sample document


AIS API DEFINITION


REQUESTSIGNATURE

REQUEST BODY SCHEMA: APPLICATION/JSON
REQUIRED



SignRequest
object (SignRequest)

A request to send to AIS for creating a digital signature around one or more
provided hashes


RESPONSES

200

OK

post/rs/v1.0/sign

Public AIS service

https://ais.swisscom.com/AIS-Server/rs/v1.0/sign


REQUEST SAMPLES

 * Payload
 * On-Demand
 * Static
 * Trusted Timestamp

Content type
application/json
Copy
Expand all Collapse all
{
 * "SignRequest": {
    * "@Profile": "string",
    * "@RequestID": "string",
    * "InputDocuments": {
       * "DocumentHash": [
          * {
             * "@ID": "string",
             * "dsig.DigestMethod": {
                * "@Algorithm": "http://www.w3.org/2001/04/xmlenc#sha256"
               
               },
             * "dsig.DigestValue": "string"
            
            }
         
         ]
      
      },
    * "OptionalInputs": {
       * "AddTimestamp": {
          * "@Type": "string"
         
         },
       * "AdditionalProfile": [
          * "string"
         
         ],
       * "ClaimedIdentity": {
          * "Name": "string"
         
         },
       * "SignatureType": "string",
       * "sc.AddRevocationInformation": {
          * "@Type": "string"
         
         },
       * "sc.SignatureStandard": "string",
       * "sc.CertificateRequest": {
          * "sc.DistinguishedName": "string",
          * "sc.StepUpAuthorisation": {
             * "sc.Phone": {
                * "sc.Language": "string",
                * "sc.MSISDN": "string",
                * "sc.Message": "string",
                * "sc.SerialNumber": "string"
               
               }
            
            }
         
         }
      
      }
   
   }

}





POLLSIGNATURESTATUS

REQUEST BODY SCHEMA: APPLICATION/JSON
REQUIRED



async.PendingRequest
object (AsyncPendingRequest)



RESPONSES

200

OK

post/rs/v1.0/pending

Public AIS service

https://ais.swisscom.com/AIS-Server/rs/v1.0/pending


REQUEST SAMPLES

 * Payload

Content type
application/json
Copy
Expand all Collapse all
{
 * "async.PendingRequest": {
    * "@Profile": "string",
    * "OptionalInputs": {
       * "AddTimestamp": {
          * "@Type": "string"
         
         },
       * "AdditionalProfile": [
          * "string"
         
         ],
       * "ClaimedIdentity": {
          * "Name": "string"
         
         },
       * "SignatureType": "string",
       * "sc.AddRevocationInformation": {
          * "@Type": "string"
         
         },
       * "sc.SignatureStandard": "string",
       * "sc.CertificateRequest": {
          * "sc.DistinguishedName": "string",
          * "sc.StepUpAuthorisation": {
             * "sc.Phone": {
                * "sc.Language": "string",
                * "sc.MSISDN": "string",
                * "sc.Message": "string",
                * "sc.SerialNumber": "string"
               
               }
            
            }
         
         }
      
      }
   
   }

}


--------------------------------------------------------------------------------


 * Facebook
 * Twitter
 * Instagram
 * YouTube
 * LinkedIn
 * TikTok
 * Xing

 * Legal aspects
 * Imprint
 * Contact
 * Data protection