SealSign DSS Integration Guide for Android Applications

[email protected]

elevenpaths.com

SealSign DSS (Digital Signature Services)

Integration Guide for Android Applications

ElevenPaths, radical and disruptive innovation in security solutions

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

V.3.2 – October 2016

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

Table of content

Table of content ............................................................................................................. 2

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

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

2.1 Including Web Service Proxies .................................................................................................. 4

2.2 Including the SealSignDSSClientLibrary Client .......................................................................... 4

3 Use Cases .................................................................................................................... 5

3.1 User Certificate Enumeration ................................................................................................... 5

3.2 Certificate Verification .............................................................................................................. 5

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

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

3.4.1 Certificate Enumeration ............................................................................................................. 6

3.4.2 Beginning the Signature ............................................................................................................. 7

3.4.3 Cryptography in Client ................................................................................................................ 7

3.4.4 Ending the Signature .................................................................................................................. 7

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

3.5.1 Certificate Enumeration ............................................................................................................. 8

3.5.2 Beginning the Signature ............................................................................................................. 8

3.5.3 Cryptography in Client ................................................................................................................ 8

3.5.4 End Signature ............................................................................................................................. 8

3.6 Signed Documents Verification ................................................................................................ 9

4 Integrating BioSigner for Android ............................................................................... 10

5 Resources .................................................................................................................. 11




1 Introduction

SealSign DSS (Digital Signature Services) is a product 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 Android Applications.




2 Common Tasks

2.1 Including Web Service Proxies

The Web services layer is used to interact with the server platform. The “SealSign DSS - Web Services Reference” document details each service and its parameters. The required proxy classes generated with the www.easywsdl.com tool are included in the Android SDK. These classes are provided as an integration facilitator, but are not part of the SealSignDSS SDK and, therefore, not supported.

In order to include these classes in the project, you must follow the steps detailed in the included readme.txt file. For more information on the integration of proxies, see http://easywsdl.com/Home/ Faq.

2.2 Including the SealSignDSSClientLibrary Client

In order to include cryptographic functions in the platform client, you need to add the reference to the SealSignDSSClientLibrary library in the project.

Image 01: Adding the SealSignDSSClientLibrary.jar library.

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

http://easywsdl.com/Home/%20Faq

http://easywsdl.com/Home/%20Faq




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 through the proxy classes generated with www.easywsdl.com, and a CertificateReference array is obtained. 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.

SSBBasicHttpBinding_ISignatureServiceBasic service = new SSBBasicHttpBinding_ISignatureServiceBasic(null, baseURL + "/SealSignDSSService/SignatureServiceBasic.svc/BB"); if (service.httpHeaders == null) {

service.httpHeaders = new ArrayList<HeaderProperty>(); } service.httpHeaders.add(new HeaderProperty("Authorization", "Basic " + Base64.encodeToString(basicAuth.getBytes(), 0))); SSBArrayOfCertificateReference certificateReferences = service.GetCertificateReferences(null, false); for (SSBCertificateReference reference : certificateReferences) {

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:

InputStream certificateStream = getAssets().open("certificate.pfx"); KeyStore certificateStore = KeyStore.getInstance("PKCS12", "BC"); certificateStore.load(certificateStream, "1234".toCharArray()); Enumeration<String> aliases = certificateStore.aliases(); for (; aliases.hasMoreElements(); ) {

String alias = (String)aliases.nextElement(); if (certificateStore.isKeyEntry(alias) == true) {

Integer reason = Integer.valueOf(0); CSBBasicHttpBinding_ICertificateServiceBasic service = new CSBBasicHttpBinding_ICertificateServiceBasic(null, baseURL + "/SealSignDSSService/CertificateServiceBasic.svc/B"); CSBValidateResponse validateResponse = service.Validate(certificate.getEncoded(), null, reason); Log.i("SealSignDSSBackendSample", validateResponse.ValidateResult.toString());






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/SignatureServiceBasic.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.

InputStream documentStream = getAssets().open("sample.pdf"); byte[] documentBytes = new byte[documentStream.available()]; documentStream.read(documentBytes); documentStream.close(); byte[] signedDocument = service.Sign(reference.id, es.sealsign.dss.SSBEnums.SignatureProfile.PDF, es.sealsign.dss.SSBEnums.SignatureType.Default, es.sealsign.dss.SSBEnums.HashAlgorithm.Default, es.sealsign.dss.SSBEnums.SignatureFlags.getStatusFlags("Default"), null, null, null, null, documentBytes); File signedFile = new File(MainActivity.this.getFilesDir(), "sample.pdf.signed.pdf"); FileOutputStream signedStream = new FileOutputStream(signedFile.getPath()); signedStream.write(signedDocument); signedStream.close();

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:

InputStream certificateStream = getAssets().open("certificate.pfx"); KeyStore certificateStore = KeyStore.getInstance("PKCS12", "BC"); certificateStore.load(certificateStream, "1234".toCharArray()); Enumeration<String> aliases = certificateStore.aliases(); for (; aliases.hasMoreElements(); ) {






String alias = (String)aliases.nextElement();

if (certificateStore.isKeyEntry(alias) == true) { X509Certificate certificate = (X509Certificate)certificateStore.getCertificate(alias); PrivateKey key = (PrivateKey)certificateStore.getKey(alias, "1234".toCharArray());

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:

InputStream documentStream = getAssets().open("sample.pdf"); byte[] documentBytes = new byte[documentStream.available()]; documentStream.read(documentBytes); documentStream.close(); DSBBasicHttpBinding_IDistributedSignatureServiceBasic service = new DSBBasicHttpBinding_IDistributedSignatureServiceBasic(null, baseURL + "/SealSignDSSService/DistributedSignatureServiceBasic.svc/B"); DSBDistributedSignatureBeginResponseBasic beginResponse = service.BeginSignature(certificate.getEncoded(), es.sealsign.dss.DSBEnums.SignatureProfile.PDF, es.sealsign.dss.DSBEnums.SignatureType.Default, es.sealsign.dss.DSBEnums.HashAlgorithm.Default, es.sealsign.dss.DSBEnums.SignatureFlags.getStatusFlags("Default"),

null, null, documentBytes);

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:

AsyncStateManager manager = new AsyncStateManager(beginResponse.asyncState); 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:

byte[] signedDocument = service.EndSignature(beginResponse.instance, finalAsyncState); File signedFile = new File(MainActivity.this.getFilesDir(), "sample.pdf.signed.pdf"); FileOutputStream signedStream = new FileOutputStream(signedFile.getPath()); signedStream.write(signedDocument); signedStream.close();







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:

InputStream certificateStream = getAssets().open("certificate.pfx"); KeyStore certificateStore = KeyStore.getInstance("PKCS12", "BC"); certificateStore.load(certificateStream, "1234".toCharArray()); Enumeration<String> aliases = certificateStore.aliases(); for (; aliases.hasMoreElements(); ) { String alias = (String)aliases.nextElement();

if (certificateStore.isKeyEntry(alias) == true) { X509Certificate certificate = (X509Certificate)certificateStore.getCertificate(alias); PrivateKey key = (PrivateKey)certificateStore.getKey(alias, "1234".toCharArray());

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:

DSBBasicHttpBinding_IDistributedSignatureServiceBasic service = new DSBBasicHttpBinding_IDistributedSignatureServiceBasic(null, baseURL + "/SealSignDSSService/DistributedSignatureServiceBasic.svc/B"); DSBDistributedSignatureBeginResponseBasic beginResponse = service.BeginSignatureProvider(certificate.getEncoded(), demoURI, null, null);

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:

AsyncStateManager manager = new AsyncStateManager(beginResponse.asyncState); 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:

service.EndSignatureProvider(beginResponse.instance, finalAsyncState, demoURI, null, false);






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.

File signedFile = new File(MainActivity.this.getFilesDir(), "sample.pdf.signed.pdf"); FileInputStream documentStream = new FileInputStream(signedFile); byte[] documentBytes = new byte[documentStream.available()]; documentStream.read(documentBytes); documentStream.close(); SSBBasicHttpBinding_ISignatureServiceBasic service = new SSBBasicHttpBinding_ISignatureServiceBasic(null, baseURL + "/SealSignDSSService/SignatureServiceBasic.svc/B"); SSBSignatureVerification signatureVerification = service.Verify(es.sealsign.dss.SSBEnums.SignatureProfile.PDF, es.sealsign.dss.SSBEnums.VerificationFlags.getStatusFlags("Default"), null, null, documentBytes); Log.i("SealSignDSSBackendSample", signatureVerification.result.toString());





4 Integrating BioSigner for Android

ElevenPaths’ Mobile Signer app for Android allows the electronic signature of documents of different formats (PDF, Office, XML).

This application may be invoked as a component that performs the signature operation from a website that is displayed in the browser of the mobile device. The document to be signed in this way must be accessible by the SealSign server. The logic required to retrieve the document is implemented in the documents providers.

The required steps for this integration are:

1. Install the Mobile Signer application on the device. Through Google Play, locate and install the ElevenPaths’ “Mobile Signer” application.

2. Create a web page that invokes the Mobile Signer signature component by indicating the required parameters. The invocation of Mobile Signer from a website is performed invoking a special URL that has been registered in the device when installing the application. The URL has the following syntax:

intent:#Intent;action=es.smartaccess.mobilesigner.SIGNFE;launchFlags=0x100

00000;component=es.smartaccess.mobilesigner/.MobileSignerFE;S.parameter=va

lue;S.parameter2=value;…;end

The parameters are:

a. viewerurl: Said URL will open in a web viewer behind the signature fields.

b. uri: It is the first value. It will be transferred to the server document provider in order to identify the document.

c. providerParameter: It is an optional value that is transferred to the server document provider with additional information about the document (e.g., metadata associated with the document).

d. serviceUrl: It identifies the URL of the SealSign Engine server that will be used.

e. serviceUsername: If this parameter is specified, the connection to the signature server will be conducted with this user. If it is not specified, an anonymous connection will be performed.

f. servicePassword: It indicates the password that will be used to connect to the SealSign signature server if a username is specified.

g. exitUrl: It specifies the exit URL that will be browsed after the signature operation.

The following is a complete example of integration with Mobile Signer:

intent:#Intent;action=es.smartaccess.mobilesigner.SIGNFE;launchFlags=0x100

00000;component=es.smartaccess.mobilesigner/.MobileSignerFE;S.viewerurl=

http://www.smartaccess.es;S.uri= demo://1-2-z.pdf;S.exitUrl=

http://www.google.es;end




5 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 Android Applications

Technology

Transcript of SealSign DSS Integration Guide for Android Applications