Digital Signature Service Protocol Client

This Java library provides an implementation of the client side of the Digital Signature Service Protocol.

This Java library can be used to:

Create a signature on a document
Verify signatures on a document.

DSSP SDKs for .NET and PHP are available at Github.

The current DSS supports both PDF and XML documents.

The Java client library is available within the e-contract.be Maven repository. Configure this Maven repository within your pom.xml as follows:

<repositories>
        <repository>
                <id>e-contract.be</id>
                <url>https://www.e-contract.be/maven2/</url>
        </repository>
</repositories>

Add the client library within your pom.xml dependencies element as follows:

<dependency>
        <groupId>be.e_contract.dssp</groupId>
        <artifactId>dssp-client</artifactId>
        <version>1.8.2</version>
</dependency>

Depending on the used application server, you need to include support for WSS4J version 1.x, version 2.1.x, or version 2.2.x. Add support for WSS4J 2.2.x runtimes via:

<dependency>
        <groupId>be.e_contract.dssp</groupId>
        <artifactId>dssp-client-wss4j2</artifactId>
        <version>1.8.2</version>
        <scope>runtime</scope>
</dependency>

Add support for WSS4J 2.1.x runtimes via:

<dependency>
        <groupId>be.e_contract.dssp</groupId>
        <artifactId>dssp-client-wss4j21</artifactId>
        <version>1.8.2</version>
        <scope>runtime</scope>
</dependency>

Add support for WSS4J 1.x runtimes via:

<dependency>
        <groupId>be.e_contract.dssp</groupId>
        <artifactId>dssp-client-wss4j1</artifactId>
        <version>1.8.2</version>
        <scope>runtime</scope>
</dependency>

Creating a signature

The creation of a signature on a document involves several steps.

SameSite=None session cookie

Since the DSS Protocol client stores state within the HTTP session, we need a session cookie that survives the redirection to/from the Digital Signature Service. Since Google Chrome version 80, this requires a session cookie with the SameSite=None flag enabled. The DSSP Protocol client library comes with a Java EE servlet filter to set the appropriate cookie flags. You can activate this filter easily from within your web.xml configuration file. An example below is given for Java EE JSF applications:

<filter>
    <filter-name>SameSite Filter</filter-name>
    <filter-class>
        be.e_contract.dssp.client.samesite.SameSiteNoneFilter
    </filter-class>
</filter>
<filter-mapping>
    <filter-name>SameSite Filter</filter-name>
    <servlet-name>Faces Servlet</servlet-name>
</filter-mapping>

Depending on your runtime environment (non-JSF for example), the filter-mapping might be different. Please be aware of the security implications of using this servlet filter.

Uploading a document

First step is uploading the document you want to get signed to the DSS.

DigitalSignatureServiceClient client = new DigitalSignatureServiceClient("https://www.e-contract.be/dss-ws/dss");
byte[] pdfData = ...;
DigitalSignatureServiceSession session = client.uploadDocument("application/pdf", pdfData);

The session object should be stored inside the HTTP session as you'll need this later on.

HttpSession httpSession = ...;
httpSession.setAttribute("DigitalSignatureServiceSession", session);

If you receive some WS-Security error message like "Invalid timestamp The security semantics of the message have expired", you might want to synchronize your server's clock using NTP.

Browser POST towards DSS

Next you need to perform a browser POST towards the DSS.

String destination = "https://yoursite.be/where-dss-should-land-after-signing";
String pendingRequest = PendingRequestFactory.createPendingRequest(session, destination, "nl");

The pending request should be put inside an HTML form as follows:

<html>
        <head><title>DSS Browser POST</title></head>
        <body>
                <p>Redirecting to the DSS Server...</p>
                <form name="BrowserPostForm" method="post" action="https://www.e-contract.be/dss-ws/start">
                        <input type="hidden" name="PendingRequest" value="..."/>
                </form>
                <script type="text/javascript">
                        window.onload = function() {
                                document.forms["BrowserPostForm"].submit();
                        }
                </script>
        </body>
</html>

Via PendingRequestFactory.createPendingRequest you can also set the PDF signature visualization profile that should be used. Contact us for a company specific signature visualization profile.

DSS landing page

After signing, the DSS will POST back to your given landing page. You should check the incoming SignResponse HTML form parameter as follows:

HttpSession httpSession = ...;
DigitalSignatureServiceSession session = (DigitalSignatureServiceSession) httpSession.getAttribute("DigitalSignatureServiceSession");
SignResponseVerifier.checkSignResponse(signResponse, session);

Downloading the signed document

Final step is downloading the signed document.

HttpSession httpSession = ...;
DigitalSignatureServiceSession session = (DigitalSignatureServiceSession) httpSession.getAttribute("DigitalSignatureServiceSession");
DigitalSignatureServiceClient client = new DigitalSignatureServiceClient("https://www.e-contract.be/dss-ws/dss");
byte[] signedDocument = client.downloadSignedDocument(session);
httpSession.removeAttribute("DigitalSignatureServiceSession");

Verifying document signatures

Signatures on documents can be verified via the DSS web service as follows:

DigitalSignatureServiceClient client = new DigitalSignatureServiceClient("https://www.e-contract.be/dss-ws/dss");
byte[] pdfData = ...;
VerificationResult verificationResult = client.verify("application/pdf", pdfData);

eSeal

The eSeal functionality of DSS requires the registration of an activation certificate at the DSS vendor.

Creating an eSeal on a document

We assume you loaded the activation certificate and corresponding private key.

PrivateKey activationPrivateKey = ...;
X509Certificate activationCertificate = ...;
byte[] pdfData = ...;

DigitalSignatureServiceClient client = new DigitalSignatureServiceClient("https://www.e-contract.be/dss-ws/dss");
client.setCredentials(activationPrivateKey, activationCertificate);
DownloadResult downloadResult = client.eSeal("application/pdf", pdfData);

Verify an eSeal on a document

The eSeal signing certificate might be issued by a different CA than the default trusted CA. Hence application authentication might be required during document signature verification for correct trust domain selection.

PrivateKey activationPrivateKey = ...;
X509Certificate activationCertificate = ...;
byte[] pdfData = ...;

DigitalSignatureServiceClient client = new DigitalSignatureServiceClient("https://www.e-contract.be/dss-ws/dss");
client.setCredentials(activationPrivateKey, activationCertificate);
VerificationResult verificationResult = client.verify("application/pdf", pdfData);

Two-step Approach Local Signatures

Two-step Approach Local Signatures allows desktop software to create advanced electronic signature via the DSS.

During the first step the client sends over the document to be signed, together with the signing certificate chain.

DigitalSignatureServiceClient client = new DigitalSignatureServiceClient("https://www.e-contract.be/dss-ws/dss");
client.setCredentials(...);
byte[] pdfData = ...;
List<X509Certificate> signingCertificateChain = ...;
TwoStepSession session = this.client.prepareSignature("application/pdf", pdfData, null, false, certificateChain);

Next the client signs the received signature digest value. We provide a helper function for this.

PrivateKey signPrivateKey = ...;
byte[] signatureValue = session.sign(signPrivateKey);

Finally the client sends over the signature value and the DSS finalizes the signature.

byte[] signedDocument = client.performSignature(session, signatureValue);

OSGi support

The DSS client libraries support OSGi. The OSGi support has been tested via Apache Felix.