sealsign dss integration guide for java applications

[email protected]

elevenpaths.com

SealSign DSS (Digital Signature Services)

Integration Guide for Java Applications

ElevenPaths, radical and disruptive innovation in security solutions

SealSign DSS (Digital Signature Services) Integration Guide for Java Applications

V.3.2 – October 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. of 13

Table of content

1 Introduction ................................................................................................................ 3

2 Common Tasks ............................................................................................................ 4

2.1 Generating Web Service Proxies .............................................................................................. 4

2.2 Including the SealSignDSSClientLibrary Client .......................................................................... 6

3 Use Cases .................................................................................................................... 7

3.1 User Certificate Enumeration ................................................................................................... 7

3.2 Certificate Verification .............................................................................................................. 7

3.3 Signature with Certificate on the Server .................................................................................. 8

3.4 Signature with Certificate on the Client ................................................................................... 8

3.4.1 Certificate Enumeration ............................................................................................................. 8

3.4.2 Beginning the Signature ............................................................................................................. 9

3.4.3 Cryptography in Client ................................................................................................................ 9

3.4.4 Ending the Signature ................................................................................................................ 10

3.5 Signature with Document Provider (Document on the Server) ............................................. 10

3.5.1 Certificate Enumeration ........................................................................................................... 10

3.5.2 Beginning the Signature ........................................................................................................... 10

3.5.3 Cryptography in Client .............................................................................................................. 11

3.5.4 End Signature ........................................................................................................................... 11

3.6 Signed Documents Verification .............................................................................................. 11

4 Resources .................................................................................................................. 12




1 Introduction

SealSign DSS (Digital Signature Services) is a product developed entirely by ElevenPaths, designed to facilitate the integration of the electronic signature with corporate applications. SealSign DSS exposes its functionality through Web services based on WCF (Windows Comunication Framework) technology. These services can be invoked by applications implemented on most technologies on the market.

This document is not intended as a manual for the specific aspects of the electronic signature, but a technical reference guide, developer-oriented, on integrating SealSign DSS in Java Applications.




2 Common Tasks

2.1 Generating Web Service Proxies

The Web services layer is used to interact with the server platform. The “SealSign DSS - Web Services References” document details each service and its parameters. In this section you will learn, as an example, how to include in a client project the required classes to invoke those services. For this purpose, you will use the Axis2 engine, but you can use any other invocation method (KSOAP, raw, etc.). For references to this engine, see http://axis.apache.org/axis2/java/core/,

You need to add the Axis2 support to the project properties in order to access the autogeneration.

Figure 01: Project properties in Eclipse.

Then you start the generation wizard of the Web service client:

Figure 02: Wizard to create the Web Service client in Eclipse.

http://es.slideshare.net/elevenpaths/web-services-reference-sealsign-dss

http://axis.apache.org/axis2/java/core/




We recommend using Axis2 as Web services runtime, as it solves many integration problems with WCF services used by the SealSign platform:

Figure 03: Using Axis2 as runtime.

Finally, the confirmation window is displayed. If the service publishes multiple endpoints (Basic, WS, etc.), it is important to select the appropriate one according to the required authentication and also to the required connection parameters:

Figure 04: Configuring the Web Service client.




2.2 Including the SealSignDSSClientLibrary Client

To include cryptographic functions in the client platform, you need to add to the project the SealSignDSSClientLibrary:

Image 05: Add SealSignDSSClientLibrary.jar.




3 Use Cases

3.1 User Certificate Enumeration

To enumerate certificates, requests to the service must be authenticated from the client, so that the use of allowed certificates is ensured. The used service is /SealSignDSSService/SignatureService Basic.svc.

The following example shows the connection to the service using Axis2 and the obtaining of a CertificateReference array. Each object contains information related to each certificate that can be used by the user. The returned values and syntax of the method can be found in the “SealSign DSS – Web Services Reference” document:

SignatureServiceBasicStub service = new SignatureServiceBasicStub(); HttpTransportProperties.Authenticator basicAuthentication = new HttpTransportProperties.Authenticator(); basicAuthentication.setUsername("SealSignTest"); basicAuthentication.setPassword("Passw0rd"); basicAuthentication.setPreemptiveAuthentication(true); service._getServiceClient().getOptions().setProperty(org.apache.axis2.transport.http.HTTPConstants.AUTHENTICATE, basicAuthentication); GetCertificateReferences getParameters = new GetCertificateReferences(); GetCertificateReferencesResponse getResponse = service.getCertificateReferences(getParameters); ArrayOfCertificateReference referencesResult = getResponse.getGetCertificateReferencesResult(); CertificateReference[] references = referencesResult.getCertificateReference(); if (references != null && references.length > 0) { // Server certificate signing CertificateReference reference = references[0];

3.2 Certificate Verification

To verify a certificate, a single call is made to the Validate method. The returned values and syntax of the method can be found in the “SealSign DSS - Web Services Reference” document. The used service is /SealSignDSSService/CertificateServiceBasic.svc:

// BeginSignature using Axis2 stub CertificateServiceBasicStub service = new CertificateServiceBasicStub(); java.security.cert.Certificate certificate = ks.getCertificate(alias); DataHandler certificateDH = new DataHandler(new ByteArrayDataSource(certificate.getEncoded())); Validate validateParameters = new Validate(); validateParameters.setValidatingCertificate(certificateDH); ValidateResponse validateResponse = service.validate(validateParameters);







3.3 Signature with Certificate on the Server

The signature with certificate and private key on the server (HSM, BBDD) is performed with a single call to the signature Web service, transferring the document to be signed and the required parameters. The used service is /SealSignDSSService/SignatureService.svc

The certificate with which the signature is performed, is specified by its ID on the platform. The returned values and syntax of the method can be found in the “SealSign DSS - Web Services Reference” document.

// Server certificate signing CertificateReference reference = references[0]; Sign signParameters = new Sign(); signParameters.setSignatureProfile(SignatureProfile.PDF); signParameters.setSignatureType(SignatureType.Default); signParameters.setHashAlgorithm(HashAlgorithm.Default); signParameters.setIdCertificate(reference.getId()); SignatureFlags signatureFlags = new SignatureFlags(); signatureFlags.setSignatureFlags_type0(new SignatureFlags_type0[] { SignatureFlags_type0.Default }); signParameters.setOptions(signatureFlags); DataHandler signingDocumentDH = new javax.activation.DataHandler(new FileDataSource("y:\\proyectos\\sealsign\\samples\\sample.pdf")); signParameters.setSigningDocument(signingDocumentDH); SignResponse signResponse = service.sign(signParameters); DataHandler signedDocument = signResponse.getSignResult(); File graphFile = new File("y:\\proyectos\\sealsign\\samples\\sample.pdf.signed.pdf"); FileOutputStream outputStream = new FileOutputStream(graphFile); signedDocument.writeTo(outputStream);

3.4 Signature with Certificate on the Client

In order to sign a certificate the private key of which is located on the client, you need to follow these three steps:

1. Notifying the platform of the public part of the certificate that will be used and the document to be signed.

2. Performing the cryptographic operation through the SealSignDSSClientLibrary client library using data from the server (instance and signature token).

3. Notifying the platform of the cryptographic operation result in order to complete the signature operation and form the final document.

3.4.1 Certificate Enumeration Regular resources of the environment are used to enumerate the certificates available, independently of the SealSign platform:

// Certificate enumeration from PFX

Security.addProvider(new org.bouncycastle.jce.provider.BouncyCastleProvider());

KeyStore ks = KeyStore.getInstance("pkcs12");






ks.load(new FileInputStream(new File("C:\\Temp\\FNMT.pfx")), "1234".toCharArray());

for (Enumeration<String> e = ks.aliases(); e.hasMoreElements();)

{

String alias = e.nextElement();

// Certificate selection based on private key

if (ks.isKeyEntry(alias))

{

3.4.2 Beginning the Signature The beginning of the signature is notified to the server platform by calling the BeginSignature method. The used service is /SealSignDSSService/DistributedSignatureServiceBasic.svc.

The returned values and syntax of the method can be found in the “SealSign DSS - Web Services Reference” document:

// BeginSignature using Axis2 stub

DistributedSignatureServiceBasicStub service = new

DistributedSignatureServiceBasicStub();

java.security.cert.Certificate certificate = ks.getCertificate(alias);

DataHandler certificateDH = new DataHandler(new

ByteArrayDataSource(certificate.getEncoded()));

SignatureFlags signatureFlags = new SignatureFlags();

signatureFlags.setSignatureFlags_type0(new SignatureFlags_type0[] {

SignatureFlags_type0.Default });

DataHandler signingDocumentDH = new javax.activation.DataHandler(new

FileDataSource("y:\\proyectos\\sealsign\\samples\\sample.pdf"));

BeginSignature beginParameters = new BeginSignature();

beginParameters.setCertificate(certificateDH);

beginParameters.setSignatureProfile(SignatureProfile.PDF);

beginParameters.setSignatureType(SignatureType.Default);

beginParameters.setHashAlgorithm(HashAlgorithm.Default);

beginParameters.setOptions(signatureFlags);

beginParameters.setSigningDocument(signingDocumentDH);

BeginSignatureResponse beginResponse = service.beginSignature(beginParameters);

DistributedSignatureBeginResponseBasic beginResult =

beginResponse.getBeginSignatureResult();

3.4.3 Cryptography in Client The cryptographic operation is performed by calling the AsyncStateManager component, with the private key of the previously chosen certificate:

ByteArrayOutputStream asyncStateStream = new ByteArrayOutputStream(); beginResult.getAsyncState().writeTo(asyncStateStream); PrivateKey key = (PrivateKey)ks.getKey(alias, "1234".toCharArray()); // Client encryption with SealSignDSSClientLibrary AsyncStateManager manager = new AsyncStateManager(asyncStateStream.toByteArray()); byte[] finalAsyncState = manager.doFinal(key);






3.4.4 Ending the Signature The end of the signature is notified to the platform and the final document is obtained. The used service is /SealSignDSSService/DistributedSignatureServiceBasic.svc. The returned values and syntax of the method can be found in the “SealSign DSS - Web Services Reference” document:

javax.activation.DataHandler finalAsyncStateDH = new javax.activation.DataHandler(new ByteArrayDataSource(finalAsyncState)); EndSignature endParameters = new EndSignature(); endParameters.setInstance(beginResult.getInstance()); endParameters.setAsyncState(finalAsyncStateDH); // EndSignature using axis2 stub and signed document return EndSignatureResponse endResponse = service.endSignature(endParameters); DataHandler signedDocument = endResponse.getEndSignatureResult(); File graphFile = new File("y:\\proyectos\\sealsign\\samples\\sample.pdf.signed.pdf"); FileOutputStream outputStream = new FileOutputStream(graphFile); signedDocument.writeTo(outputStream);

3.5 Signature with Document Provider (Document on the Server)

The signature procedure against the platform using a document provider is similar to that of the signature with certificate on the client, but the document does not have to be on the client. Instead, a URI that the document provider will use to get the document from a documentary Backend on the server part is specified.

3.5.1 Certificate Enumeration Regular resources of the environment are used to enumerate the certificates available, independently of the SealSign platform:

// Certificate enumeration from PFX

Security.addProvider(new org.bouncycastle.jce.provider.BouncyCastleProvider());

KeyStore ks = KeyStore.getInstance("pkcs12");

ks.load(new FileInputStream(new File("C:\\Temp\\FNMT.pfx")), "1234".toCharArray());

for (Enumeration<String> e = ks.aliases(); e.hasMoreElements();)

{

String alias = e.nextElement();

// Certificate selection based on private key

if (ks.isKeyEntry(alias))

{

3.5.2 Beginning the Signature The beginning of the signature is notified to the server platform by calling the BeginSignatureProvider method. The used service is /SealSignDSSService/DistributedSignatureService Basic.svc. The returned values and syntax of the method can be found in the “SealSign DSS - Web Services Reference” document:

// BeginSignatureProvider using Axis2 stub

DistributedSignatureServiceBasicStub service = new DistributedSignatureServiceBasicStub(); java.security.cert.Certificate certificate = ks.getCertificate(alias); DataHandler certificateDH = new DataHandler(new ByteArrayDataSource(certificate.getEncoded()));







BeginSignatureProvider beginProviderParameters = new BeginSignatureProvider(); beginProviderParameters.setCertificate(certificateDH); beginProviderParameters.setUri("demo://y:\\proyectos\\sealsign\\samples\\sample.pdf"); BeginSignatureProviderResponse beginProviderResponse = service.beginSignatureProvider(beginProviderParameters); DistributedSignatureBeginResponseBasic context = beginProviderResponse.getBeginSignatureProviderResult();

3.5.3 Cryptography in Client The cryptographic operation is performed by calling the AsyncStateManager component, with the private key of the previously chosen certificate:

ByteArrayOutputStream asyncStateStream = new ByteArrayOutputStream(); context.getAsyncState().writeTo(asyncStateStream); PrivateKey key = (PrivateKey)ks.getKey(alias, "1234".toCharArray()); // Client encryption with SealSignDSSClientLibrary AsyncStateManager manager = new AsyncStateManager(asyncStateStream.toByteArray()); byte[] finalAsyncState = manager.doFinal(key);

3.5.4 End Signature It is used to notify the ending of the signature to the platform. The used service is /SealSignDSSService/DistributedSignatureServiceBasic.svc . The returned values and syntax of the method can be found in the “SealSign DSS - Web Services Reference” document:

javax.activation.DataHandler finalAsyncStateDH = new javax.activation.DataHandler(new ByteArrayDataSource(finalAsyncState)); EndSignatureProvider endProviderParameters = new EndSignatureProvider(); endProviderParameters.setInstance(context.getInstance()); endProviderParameters.setUri("demo://y:\\proyectos\\sealsign\\samples\\sample.pdf"); endProviderParameters.setAsyncState(finalAsyncStateDH); // EndSignatureProvider using axis2 stub and signed document return EndSignatureProviderResponse endResponse = service.endSignatureProvider(endProviderParameters);

3.6 Signed Documents Verification

To verify the signatures within a document, a single call is made to the Verify method of the server platform. The used service is /SealSignDSSService/SignatureServiceBasic.svc: The returned values and syntax of the method can be found in the “SealSign DSS - Web Services Reference” document.

// Signature verification DataHandler signedDocumentDH = new javax.activation.DataHandler(new FileDataSource("y:\\proyectos\\sealsign\\samples\\sample.pdf.signed.pdf")); Verify verifyParameters = new Verify(); verifyParameters.setSignatureProfile(SignatureProfile.PDF); verifyParameters.setDocument(signedDocumentDH); VerifyResponse verifyResponse = service.verify(verifyParameters); SignatureVerification signatureVerification = verifyResponse.getVerifyResult(); VerificationResult verificationResult = signatureVerification.getResult();






4 Resources

For information about the different SealSign services available, please go to this address:

https://www.elevenpaths.com/technology/sealsign/index.html

Also, on the ElevenPaths blog you can find interesting articles and innovations regarding this product.

You can find more information about Eleven Paths products on YouTube, on Vimeo and on Slideshare.

http://blog.elevenpaths.com/

https://www.youtube.com/user/ElevenPaths

http://vimeo.com/elevenpaths

http://www.slideshare.net/elevenpaths/




PUBLICATION

October 2016

At ElevenPaths we have our own way of thinking when we talk about security. Led by Chema Alonso, we are a team of experts who are passionate about their work, who are eager to redefine the industry and have great experience and knowledge about the security sector.

Security threats in technology evolve at an increasingly quicker and relentless pace. Thus, since June 2013, we have become a startup company within Telefónica aimed at working in an agile and dynamic way, transforming the concept of security and, consequently, staying a step ahead of our attackers.

Our head office is in Spain, but we can also be found in the UK, the USA, Brazil, Argentina and Colombia.

IF YOU WISH TO KNOW MORE ABOUT US, PLEASE CONTACT US AT:

elevenpaths.com Blog.elevenpaths.com @ElevenPaths Facebook.com/ElevenPaths YouTube.com/ElevenPaths

The information disclosed in this document is the property of Telefónica Digital España, S.L.U. (“TDE”) and/or any other entity within Telefónica Group and/or its licensors. TDE and/or any Telefonica Group entity or TDE’S licensors reserve all patent, copyright and other proprietary rights to this document, including all design, manufacturing, reproduction, use and sales rights thereto, except to the extent said rights are expressly granted to others. The information in this document is subject to change at any time, without notice.

Neither the whole nor any part of the information contained herein may be copied, distributed, adapted or reproduced in any material form except with the prior written consent of TDE.

This document is intended only to assist the reader in the use of the product or service described in the document. In consideration of receipt of this document, the recipient agrees to use such information for its own use and not for other use.

TDE shall not be liable for any loss or damage arising out from the use of the any information in this document or any error or omission in such information or any incorrect use of the product or service. The use of the product or service described in this document are regulated in accordance with the terms and conditions accepted by the reader.

TDE and its trademarks (or any other trademarks owned by Telefonica Group) are registered service marks.

sealsign dss integration guide for java applications

Technology