DSS offers REST and SOAP web services.
The different webservices are :
-
Signature webservices (
dss-signature-soap/dss-signature-rest) and their clients: expose methods to allow signing and augmenting or counter-signing a signature from a client. -
Server-signing webservice (
dss-server-signing-soap/dss-server-signing-rest) and their clients: expose methods to retrieve keys from a server (PKCS#11, PKCS#12, HSM, etc.) and to sign the digest on the server side. -
Signature validation webservices (
dss-validation-soap/dss-validation-rest) and their clients: expose methods to allow signature validation, with an optional detached file and an optional validation policy. -
Certificate validation webservices (
dss-certificate-validation-soap/dss-certificate-validation-rest) and their clients: expose methods to allow certificate validation, with an optional provided certificate chain and custom validation time. -
Timestamp webservices (
dss-timestamp-remote-soap/dss-timestamp-remote-rest) and their clients: expose methods to allow remote timestamp creation, by providing digest value to be timestamped and a digest algorithm, used for the digest calculation.
The data structure in webservices is similar in both REST and SOAP modules.
The documentation will cover the REST calls. All the REST services present in DSS are compliant with OpenAPI Specification.
Additionally, we also provide a SOAP-UI and Postman samples in the dss-cookbook module for simplicity.
This service is composed by two modules:
-
dss-signature-service-client- provides client interfaces for the REST webservices; -
dss-signature-service- contains REST webservices for signature creation, augmentation and document timestamping.
This service exposes several methods taking as input one or more document and having as output a signed data object (possibly a timestamped document):
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/ws/rest/RestSignatureServiceSnippet.java[role=include]A document signing assumes a signature creation in three (or four) consecutive steps (see [SignatureCreationInDSS] for more information). Two of the steps, namely "get data to sign" and "sign document" are available within the current module.
Below you can find examples for processing these steps when signing a single document.
The method allows retrieving the data to be signed. The user sends the document to be signed, the parameters (signature level, etc.) and the certificate chain.
|
Warning
|
The parameters in getDataToSign and signDocument MUST be the same (especially the signing date). |
Samples:
The method allows generation of the signed document with the received signature value.
|
Warning
|
The parameters in getDataToSign and signDocument MUST be the same (especially the signing date). |
Samples:
Similarly to Single document signing, the service exposes methods which allow signing of multiple documents with one signature (format dependent).
The method allows retrieving the data to be signed. The user sends the documents to be signed, the parameters (signature level, etc.) and the certificate chain.
|
Warning
|
The parameters in getDataToSign and signDocument MUST be the same (especially the signing date). |
Samples:
The method allows generation of the signed document with the received signature value.
|
Warning
|
The parameters in getDataToSign and signDocument MUST be the same (especially the signing date). |
Samples:
The method allows augmentation of an existing signature to a higher level.
Samples:
The method allows timestamping of a provided document. Available for PDF, ASiC-E and ASiC-S container formats.
Samples:
Similarly to Single document signing, the counter-signature creation requires execution of three (or four) consecutive steps, with the difference requiring a signed document to be provided as an input and Id of the signature to be counter-signed.
This method returns the data to be signed in order to create a counter signature. The user should provide a document containing a signature to be counter-signed, id of the signature, and other parameters similarly to the method 'getDataToSign()'.
|
Warning
|
The parameters in getDataToBeCounterSigned and counterSignSignature MUST be the same (especially the signing date). |
Samples:
This method incorporates a created counter signature to unsigned properties of the master signature with this specified id.
|
Warning
|
The parameters in getDataToBeCounterSigned and counterSignSignature MUST be the same (especially the signing date). |
Samples:
Special methods have been exposed (since DSS 5.10) allowing to sign a Trusted List (TL) or a List of Trusted Lists (LOTL) using a simplified interface with a pre-configured set of parameters.
The key difference with Single document signing methods is the use of the RemoteTrustedListSignatureParameters object, containing a limited set of important parameters for TL-signature creation, instead of RemoteSignatureParameters object, containing a wide set of various parameters.
The method allows retrieving the data to be signed. The user sends the Trusted List to be signed and the parameters (signing certificate, signing date, etc.).
|
Warning
|
The parameters in getDataToSign and signDocument MUST be the same (especially the signing date). |
Samples:
The method allows generation of the signed Trusted List with the received signature value.
|
Warning
|
The parameters in getDataToSign and signDocument MUST be the same (especially the signing date). |
Samples:
Since version 5.12, DSS provides functionality for a PAdES signature creation using an external CMS signature provider (see [PAdESWithExternalCMS] for more details).
Those services are also exposed in the corresponding REST/SOAP interfaces (see below).
This method prepares a PDF signature revision and calculates message-digest based on its byte range.
Samples:
The method generates a signed PDF document using the CMS signature obtained from an external signature provider.
|
Warning
|
The parameters in getMessageDigest and signDocument MUST be the same (especially the signing date). |
Samples:
For remote-signing solution, creating a CMS signature suitable for a PAdES-BASELINE format of a PDF signature creation, the webservice with the following methods may be exposed (see [PAdESWithExternalCMS] for more details):
This method generates signed attributes using a message-digest of a PDF signature’s byte range computed externally and created a DTBS.
Samples:
Creates a CMS signature signing provided message-digest suitable for a PAdES-BASELINE signature creation.
|
Warning
|
The parameters in getDataToSign and signMessageDigest MUST be the same. |
Samples:
This service also exposes some methods for server signing operations:
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/ws/rest/RestServerSigningServiceSnippet.java[role=include]This method allows retrieving of all available keys on the server side (PKCS#11, PKCS#12, HSM, etc.). All keys will have an alias, a signing certificate and its chain. The alias will be used in following steps.
Samples:
This method allows retrieving a key information for a given alias.
Samples:
This method allows signing of given data with a server side certificate.
Samples:
This method allows signing of given data with a server side certificate by providing a mask function (i.e. MGF1).
Samples:
This method allows signing of given data with a server side certificate by enforcing the target Signature Algorithm.
Samples:
This method allows signing of given digests with a server side certificate.
Samples:
This method allows signing of given digests with a server side certificate by providing a mask function (i.e. MGF1).
Samples:
DSS provides also a module for documents validation.
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/ws/rest/RestValidationServiceSnippet.java[role=include]This service allows a signature validation (all formats/types) against a validation policy.
Samples:
The certificate validation service is used for validation of a certificate with the respective certificate chain.
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/ws/rest/RestCertificateValidationServiceSnippet.java[role=include]This service implements a timestamp creation.
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/ws/rest/RestTimestampServiceSnippet.java[role=include]This service allows a remote timestamp creation. The method takes as an input the digest to be timestamped and digest algorithm that has been used for the digest value computation. The output of the method is the generated timestamp’s binaries.
Samples:
The use of SOAP webServices is very similar to the REST implementation explained above. The main difference is the used implementation of the service. All methods, used parameters and output objects are aligned between both REST and SOAP implementations.
SOAP signature service’s client is initialized using SoapDocumentSignatureService class.
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/ws/soap/SoapSignatureServiceSnippet.java[role=include]The use of the client is similar to REST signature service.
SOAP server signing service’s client is initialized using SoapSignatureTokenConnection class.
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/ws/soap/SoapServerSigningServiceSnippet.java[role=include]The use of the client is similar to REST server signing service.
SOAP validation service’s client is initialized using SoapDocumentValidationService class.
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/ws/soap/SoapValidationServiceSnippet.java[role=include]The use of the client is similar to REST validation service.
SOAP validation service’s client is initialized using SoapCertificateValidationService class.
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/ws/soap/SoapCertificateValidationServiceSnippet.java[role=include]The use of the client is similar to REST certificate validation service.
SOAP validation service’s client is initialized using SoapTimestampService class.
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/ws/soap/SoapTimestampServiceSnippet.java[role=include]The use of the client is similar to REST timestamp service.