sealsign bss integration guide for java applications

[email protected]

elevenpaths.com

SealSign BSS (Biometric Signature Services)

Integration Guide for Java Applications

ElevenPaths, radical and disruptive innovation in security solutions

SealSign BSS (Biometric 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 15

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 Biometric Signature .................................................................................................................. 7

3.1.1 Including the Signature Panel ..................................................................................................... 7

3.1.2 Event Registration ...................................................................................................................... 7

3.1.3 Background Image During the Capture on the Tablet ................................................................ 8

3.1.4 Default Background Image on the Tablet ................................................................................... 8

3.1.5 Defining Buttons on the Tablet .................................................................................................. 8

3.1.6 Establishing a Transparent Signature Background ..................................................................... 8

3.1.7 Showing the Watermark of the Document Hash ....................................................................... 8

3.1.8 Starting the Capture ................................................................................................................... 9

3.1.9 Stopping the Capture ................................................................................................................. 9

3.1.10 Deleting the Capture .................................................................................................................. 9

3.1.11 Beginning the Signature ............................................................................................................. 9

3.1.12 Client Cryptography .................................................................................................................. 10

3.1.13 Ending the Signature ................................................................................................................ 10

3.2 Verifying Signed Documents ................................................................................................... 11

3.3 Disconnected Biometric Signature ......................................................................................... 11

3.3.1 Disconnected Capture .............................................................................................................. 11

3.3.2 Synchronizing the Signature with the Server ........................................................................... 12

3.4 Biometric Signature with Document Provider (Document on Server) ................................... 13

3.4.1 Beginning the Signature ........................................................................................................... 13

3.4.2 Cryptography in Client .............................................................................................................. 13

3.4.3 Ending the Signature ................................................................................................................ 13

4 Resources .................................................................................................................. 14




1 Introduction

SealSign BSS (Digital Signature Services) is a product designed to facilitate the integration of the electronic signature with corporate applications. SealSign BSS 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 BSS 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 BSS - 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.

Image 01: Project properties in Eclipse.

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

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

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


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:

Image 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:

Image 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.

The wgssSTU.dll library corresponding to the executable architecture (x86 or x64) must be available in the path of native libraries, either in the system path or through the native libraries path, in order to use the SDK of Wacom STU tablets. These libraries are distributed with the SealSign BSS SDK.




3 Use Cases

3.1 Biometric Signature

3.1.1 Including the Signature Panel The SealSign BSS signature panel is an inherited class from JPanel. Therefore, its inclusion in a form and its handling are conducted in the same way:

private static SealSignBSSPanel capturePanel = new SealSignBSSPanel(); … JFrame mainFrame = new JFrame(); mainFrame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE); … capturePanel.setPreferredSize(new Dimension(400, 200)); … mainFrame.add(capturePanel, BorderLayout.CENTER); mainFrame.pack(); mainFrame.setVisible(true);

3.1.2 Event Registration You can receive panel events by adding a listener that implements the SealSignBSSPanelEventListener interface. Events included in the interface are:

ButtonClick: You have clicked on a button on the tablet. In a subsequent section we will explain how to add buttons.

SignatureCleared: The signature has been cleared from the tablet.

SignatureStarted: The signature capture has started and the first sample has been taken.

public class TestBSSSignature implements SealSignBSSPanelEventListener { … @Override public void ButtonClick(SealSignBSSPanelButtonEvent arg0) { } @Override public void SignatureCleared() { } @Override public void SignatureStarted() { } …

capturePanel.addEventListener(this);




3.1.3 Background Image During the Capture on the Tablet With the signature panel you can set a background BMP image on the tablet during the signature capture with the setBackgroundImage method:

try {

RandomAccessFile backgroundImageFile = new RandomAccessFile("C:\\samples\\PantallaFirma.bmp", "r");

byte[] backgroundImageBytes = new byte[(int)backgroundImageFile.length()];

backgroundImageFile.read(backgroundImageBytes);

backgroundImageFile.close();

backgroundBufferedImage = ImageIO.read(new ByteArrayInputStream(backgroundImageBytes));

}

catch (Exception ex)

{

ex.printStackTrace();

}

capturePanel.setBackgroundImage(backgroundBufferedImage);

3.1.4 Default Background Image on the Tablet With the setClearImage method of the signature panel, you can set a background BMP image on the tablet that is displayed once the capture ends:

capturePanel.setClearImage(backgroundBufferedImage);

3.1.5 Defining Buttons on the Tablet Over the background image set on the tablet, you can define areas that will act as buttons when you click on them. The scales and limits are set by the tablet resolution. For example, the STU-520A has a resolution of 800 x 480 pixels:

capturePanel.setButtonArea("Accept", 2, 131, 75, 26);

capturePanel.setButtonArea("Cancel", 2, 166, 75, 26);

3.1.6 Establishing a Transparent Signature Background The default signature is shown in the image on a white background. If a transparent background is required for the graphic representation, the method setTransparentSignature can be used:

capturePanel.setTransparentSignature(true);

3.1.7 Showing the Watermark of the Document Hash The default signature shows a watermark with the document hash in the image. You can control the appearance of the watermark with the setDocumentHashInImage method:

capturePanel.setDocumentHashInImage(false);




3.1.8 Starting the Capture Once the panel is integrated in the development, the biometric capture starts by calling the start method of the panel:

try {

capturePanel.start(); } catch (Exception ex) { ex.printStackTrace(); }

3.1.9 Stopping the Capture The stop method of the panel stops the capture of biometric data. It is convenient to stop the capture once it has been recognized and before beginning the signature process with the server platform:

try {

capturePanel.stop(); } catch (Exception ex) { ex.printStackTrace(); }

3.1.10 Deleting the Capture To reset and delete the capture, you can call the cleanSignature method of the signature panel:

capturePanel.cleanSignature();

3.1.11 Beginning the Signature In order to biometrically sign, you need to follow these steps:

1. Notifying to the platform the document that will be signed.

2. Performing the biometric data fusion and cryptography operations through the SealSignBSSClientLibrary client library using data from the server (i.e., instance and signature token).

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

The beginning of the signature is notified to the server platform by calling the BeginSignature method. The used service is /SealSignBSSService/BiometricSignatureServiceBasic.svc.

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

// BeginSignature using Axis2 stub BiometricSignatureServiceBasicStub service = new BiometricSignatureServiceBasicStub(); BiometricSignatureFlags biometricSignatureFlags = new BiometricSignatureFlags();






biometricSignatureFlags.setBiometricSignatureFlags_type0(new BiometricSignatureFlags_type0[] { BiometricSignatureFlags_type0.Default }); SignatureFlags signatureFlags = new SignatureFlags(); signatureFlags.setSignatureFlags_type0(new SignatureFlags_type0[] { SignatureFlags_type0.Default }); DataHandler signingDocumentDH = new javax.activation.DataHandler(new FileDataSource("C:\\samples\\sample.pdf")); BeginSignature beginParameters = new BeginSignature(); beginParameters.setSignatureProfile(SignatureProfile.PDF); beginParameters.setBiometricSignatureType(BiometricSignatureType.Default); beginParameters.setId(""); beginParameters.setAccount(""); beginParameters.setBiometricOptions(biometricSignatureFlags); beginParameters.setOptions(signatureFlags); beginParameters.setSigningDocument(signingDocumentDH); BeginSignatureResponse beginResponse = service.beginSignature(beginParameters); BiometricSignatureBeginResponseBasic beginResult = beginResponse.getBeginSignatureResult();

3.1.12 Client Cryptography Calling the signature panel results in the obtaining of biometric data and the cryptographic operation:

ByteArrayOutputStream asyncStateStream = new ByteArrayOutputStream(); beginResult.getBiometricState().writeTo(asyncStateStream); // Client encryption with SealSignBSSClientLibrary byte[] biometricState = capturePanel.getSignature(beginResult.getInstance().toString(), asyncStateStream.toByteArray()); javax.activation.DataHandler finalBiometricStateDH = new javax.activation.DataHandler(new ByteArrayDataSource(biometricState));

3.1.13 Ending the Signature The ending of the signature is notified to the platform and the final document is obtained. The used service is /SealSignBSSService/BiometricSignatureServiceBasic.svc. The returned values and syntax of the method can be found in the “SealSign BSS - Web Services Reference” document:

// EndSignature using axis2 stub and signed document return EndSignature endParameters = new EndSignature(); endParameters.setBiometricState(finalBiometricStateDH); endParameters.setInstance(beginResult.getInstance()); EndSignatureResponse endResponse = service.endSignature(endParameters); DataHandler signedDocument = endResponse.getEndSignatureResult(); File graphFile = new File("C:\\samples\\sample.pdf.signed.pdf"); FileOutputStream outputStream = new FileOutputStream(graphFile); signedDocument.writeTo(outputStream); service.cleanup();





3.2 Verifying Signed Documents

It is possible to verify a signature captured against the signatures located within a document. To do so, a single call is made to the Verify method of the server platform. The used service is /SealSignBSSService/BiometricSignatureServiceBasic.svc.

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

// BeginSignature using Axis2 stub BiometricSignatureServiceBasicStub service = new BiometricSignatureServiceBasicStub(); DataHandler signedDocumentDH = new javax.activation.DataHandler(new FileDataSource("C:\\samples\\sample.pdf.signed.pdf")); BiometricVerificationFlags BiometricVerificationFlags = new BiometricVerificationFlags(); BiometricVerificationFlags.setBiometricVerificationFlags_type0(new BiometricVerificationFlags_type0[] { BiometricVerificationFlags_type0.Default }); byte[] biometricState = capturePanel.getSignature("00000000-0000-0000-0000-000000000000", null); javax.activation.DataHandler finalBiometricStateDH = new javax.activation.DataHandler(new ByteArrayDataSource(biometricState)); Verify verifyParameters = new Verify(); verifyParameters.setSignatureProfile(SignatureProfile.PDF); verifyParameters.setBiometricSignatureType(BiometricSignatureType.Default); verifyParameters.setBiometricOptions(BiometricVerificationFlags); verifyParameters.setBiometricState(finalBiometricStateDH); verifyParameters.setDocument(signedDocumentDH); VerifyResponse verifyResponse = service.verify(verifyParameters); BiometricSignatureVerification biometricVerification = verifyResponse.getVerifyResult(); service.cleanup();

3.3 Disconnected Biometric Signature

In some scenarios, there may be no connection to the biometric signature server. SealSign can create a preliminary signature to synchronize with the service when the client is connected again. The document must be located on the client in order to uniquely associate the signature captured with the same.

3.3.1 Disconnected Capture Calling the signature panel results in the obtaining of biometric data and the cryptographic operation. Instead of the data obtained from the service on a normal call, the biometric token is obtained by transferring the document to be signed as a parameter. Subsequently, the temporary instance generated on client is also obtained:

DataHandler signedDocumentDH = new javax.activation.DataHandler(new FileDataSource("C:\\samples\\sample.pdf"));






InputStream signedDocumentStream = signedDocumentDH.getInputStream(); byte[] signedDocumentBytes = IOUtils.toByteArray(signedDocumentStream); // Client encryption with SealSignBSSClientLibrary byte[] biometricState = capturePanel.getOfflineSignature(signedDocumentBytes); Guid biometricInstance = new Guid(); biometricInstance.setGuid(capturePanel.getBiometricInstance()); javax.activation.DataHandler finalBiometricStateDH = new javax.activation.DataHandler(new ByteArrayDataSource(biometricState));

3.3.2 Synchronizing the Signature with the Server Once the communication with the service is restored, you will need to synchronize the signature or signatures generated without connection in order to obtain the final document including all the necessary elements by calling the SyncOfflineSignatures method. The used service is /SealSignBSSService/BiometricSignatureServiceBasic.svc:

// BeginSignature using Axis2 stub BiometricSignatureServiceBasicStub service = new BiometricSignatureServiceBasicStub(); BiometricSignatureFlags biometricSignatureFlags = new BiometricSignatureFlags(); biometricSignatureFlags.setBiometricSignatureFlags_type0(new BiometricSignatureFlags_type0[] { BiometricSignatureFlags_type0.Default }); SignatureFlags signatureFlags = new SignatureFlags(); signatureFlags.setSignatureFlags_type0(new SignatureFlags_type0[] { SignatureFlags_type0.Default }); OfflineBiometricSignature offlineSignature = new OfflineBiometricSignature(); offlineSignature.setId(""); offlineSignature.setAccount(""); offlineSignature.setBiometricOptions(biometricSignatureFlags); offlineSignature.setOptions(signatureFlags); offlineSignature.setInstance(biometricInstance); offlineSignature.setOfflineBiometricState(finalBiometricStateDH); ArrayOfOfflineBiometricSignature offlineSignatures = new ArrayOfOfflineBiometricSignature(); offlineSignatures.addOfflineBiometricSignature(offlineSignature); SyncOfflineSignatures offlineParameters = new SyncOfflineSignatures(); offlineParameters.setSignatureProfile(SignatureProfile.PDF); offlineParameters.setOfflineSignatures(offlineSignatures); offlineParameters.setSigningDocument(signedDocumentDH); SyncOfflineSignaturesResponse offlineResponse = service.syncOfflineSignatures(offlineParameters); DataHandler signedDocument = offlineResponse.getSyncOfflineSignaturesResult(); File graphFile = new File("C:\\samples\\sample.pdf.signed.pdf"); FileOutputStream outputStream = new FileOutputStream(graphFile); signedDocument.writeTo(outputStream); service.cleanup();




3.4 Biometric Signature with Document Provider (Document on Server)

The signature procedure against the platform using a document provider is similar to that of the biometric signature, 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.4.1 Beginning the Signature The beginning of the signature is notified to the server platform by calling the BeginSignatureProvider method. The used service is /SealSignBSSService/BiometricSignatureService Basic.svc. The returned values and syntax of the method can be found in the “SealSign BSS - Web Services Reference” document:

// BeginSignature using Axis2 stub BiometricSignatureServiceBasicStub service = new BiometricSignatureServiceBasicStub(); BeginSignatureProvider beginProviderParameters = new BeginSignatureProvider(); beginProviderParameters.setId(""); beginProviderParameters.setAccount(""); beginProviderParameters.setUri("demo://C:\\samples\\sample.pdf"); BeginSignatureProviderResponse beginProviderResponse = service.beginSignatureProvider(beginProviderParameters); BiometricSignatureBeginResponseBasic beginResult = beginProviderResponse.getBeginSignatureProviderResult(); ByteArrayOutputStream asyncStateStream = new ByteArrayOutputStream(); beginResult.getBiometricState().writeTo(asyncStateStream);

3.4.2 Cryptography in Client Calling the signature panel performs the obtaining of biometric data and the cryptographic operation:

// Client encryption with SealSignBSSClientLibrary byte[] biometricState = capturePanel.getSignature(beginResult.getInstance().toString(), asyncStateStream.toByteArray()); javax.activation.DataHandler finalBiometricStateDH = new javax.activation.DataHandler(new ByteArrayDataSource(biometricState));

3.4.3 Ending the Signature The end of the signature is notified to the platform. The used service is /SealSignBSSService/ BiometricSignatureServiceBasic.svc. The returned values and syntax of the method can be found in the “SealSign BSS - Web Services Reference” document:

// EndSignature using axis2 stub and signed document return EndSignatureProvider endProviderParameters = new EndSignatureProvider(); endProviderParameters.setUri("demo://C:\\samples\\sample.pdf"); endProviderParameters.setBiometricState(finalBiometricStateDH); endProviderParameters.setInstance(beginResult.getInstance()); EndSignatureProviderResponse endProviderResponse = service.endSignatureProvider(endProviderParameters); service.cleanup();







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 bss integration guide for java applications

Technology