SealSign BSS Integration Guide for Android Applications

[email protected]

elevenpaths.com

SealSign BSS (Biometric Signature Services)

Integration Guide for Android Applications

ElevenPaths, radical and disruptive innovation in security solutions

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

TABLE OF CONTENT

1 Introduction ................................................................................................................ 4

2 Common Tasks ............................................................................................................ 5

2.1 Including Web Service Proxies .................................................................................................. 5

2.2 Including the SealSignBSSClientLibrary Client .......................................................................... 5

3 SealSignBSSPanel Activity ........................................................................................... 6

3.1 Biometric Signature .................................................................................................................. 6

3.1.1 Including the Signature Panel ..................................................................................................... 6

3.1.2 Access Permissions to the SealSign Web Service ....................................................................... 6

3.1.3 Configuration Options of the Signature Panel............................................................................ 6

3.1.4 Beginning the Signature ............................................................................................................. 7

3.1.5 Ending the Signature .................................................................................................................. 8

3.2 Signed Documents Verification ................................................................................................ 9

3.2.1 Signature Capture ....................................................................................................................... 9

3.2.2 Signature Verification ............................................................................................................... 10

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

3.3.1 Disconnected Capture Transferring the Document as Extra .................................................... 11

3.3.2 Disconnected Capture Transferring the Document through File Provider............................... 12

3.3.3 Synchronizing the Signature with the Server ........................................................................... 13

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

3.4.1 Beginning the Signature ........................................................................................................... 14

4 SealSignBSSView Customized View ............................................................................ 16

4.1 Biometric Signature ................................................................................................................ 16

4.1.1 Including the Signature Panel ................................................................................................... 16

4.1.2 Access Permissions to the SealSign Web Service ..................................................................... 16

4.1.3 Event Registration .................................................................................................................... 17

4.1.4 Establishing a Transparent Signature Background ................................................................... 17

4.1.5 Deleting the Capture ................................................................................................................ 17


4.1.7 Client Cryptography .................................................................................................................. 18

4.1.8 Ending the Signature ................................................................................................................ 18

4.2 Verifying Signed Documents ................................................................................................... 18

4.2.1 Signature Capture ..................................................................................................................... 18

4.2.2 Signature Verification ............................................................................................................... 19

4.3 Disconnected Biometric Signature ......................................................................................... 19

4.3.1 Disconnected Capture .............................................................................................................. 20

4.3.2 Synchronizing the Signature with the Server ........................................................................... 20




4.4 Biometric Signature with Document Provider (Document on Server) ................................... 21


4.4.2 Client Cryptography .................................................................................................................. 21

4.4.3 Ending the Signature ................................................................................................................ 21

5 Integrating BioSigner for Android ............................................................................... 22

6 Resources .................................................................................................................. 23




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 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 BSS - Web Services References” 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 SealSignBSS 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 SealSignBSSClientLibrary Client

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

Image 01: Adding the SealSignBSSClientLibrary.jar library.

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

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

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




3 SealSignBSSPanel Activity

3.1 Biometric Signature

There are two ways of invoking the signature component: by calling to an activity or by incorporating a customized view. This section details how to integrate calls to the SealSignBSSPanel activity. The activity will manage the signature user interface and the cryptography, thus simplifying integration in the development.

3.1.1 Including the Signature Panel The signature panel is an activity included in the client library. To use it, you need to define the activity in the AndroidManifest.xml:

<activity android:name="es.smartaccess.sealsignbss.SealSignBSSPanel" android:theme="@style/Theme.Transparent"> </activity>

In this example, a transparent background for the activity is set in order not to interfere with the user experience, as the default background is opaque. This is optional, and can be achieved with a theme (@style/Theme.Transparent in the above example). You will need to add the style to the styles.xml file. For example:

<style name="Theme.Transparent" parent="android:Theme">

<item name="android:windowIsTranslucent">true</item>

<item name="android:windowBackground">@android:color/transparent</item>

<item name="android:windowContentOverlay">@null</item>

<item name="android:windowNoTitle">true</item>

<item name="android:windowIsFloating">true</item>

<item name="android:backgroundDimEnabled">false</item>

</style>

3.1.2 Access Permissions to the SealSign Web Service To access the platform Web services, the Android app needs to have permissions to access to the network:

<uses-permission android:name="android.permission.INTERNET" />

It is important to note that calls to Web services, or any connection, cannot be conducted within the user interface main thread, so you will have to conduct them from another thread or within an asynchronous task.

3.1.3 Configuration Options of the Signature Panel The following is a list of the signature panel configuration options that can be set through the properties of the activity Intent are shown below:

WIDTH_PORT: Width of the signature area in normal mode (Portrait). It will take up the entire screen by default.

HEIGHT_PORT: Height of the signature area in normal mode (Portrait). It will take up the entire screen by default.




WIDTH_LAND: Width of the signature area in landscape mode (Landscape). It will take up the entire screen by default.

HEIGHT_LAND: Height of the signature area in landscape mode (Landscape). It will take up the entire screen by default.

BUTTON_UPPER_MARGIN: Upper margin of the buttons with the edge of the signature region. The default value is 6 pixels.

BUTTON_SIDE_MARGIN: Side margin of the buttons with the edge of the signature region. The default value is 4 pixels.

BOTTOM_MARGIN: Botom margin of the buttons with the edge of the signature region. The default value is 5 pixels.

BUTTON_M_SAVE_TEXT: Text displayed on the save signature button. The default value is “Salvar”.

BUTTON_M_CLEAR_TEXT: Text displayed on the clear signature button. The default value is “Borrar”.

DIALOG_TITLE_TEXT: Text displayed in the title bar of the dialog box that opens while the signature is being saved. The default value is “Saving signature”.

DIALOG_MSG_TEXT: Text displayed in the message of the dialog box that opens while the signature is being saved. The default value is "Por favor, espere...”.

DATE_TEXT: Text displayed at the bottom of the signature area. It is calculated by default from the system time.

ETIQUETA_TEXT: Text displayed above the signature area. It does not have a default value, so it is not displayed.

ETIQUETA_BOTTOM_PADDING: Bottom margin of the tag. The default value is 5 pixels.

ETIQUETA_SIDE_PADDING: Side margin of the tag. The default value is 4 pixels.

ETIQUETA_UPPER_PADDING: Upper margin of the tag. The default value is 6 pixels.

ETIQUETA_SIZE_TEXT: Size of the tag text. The default value is 16 pixels.

TRANSPARENT_SIGNATURE: Transparent background in the image of the resulting signature. The default value is false.

3.1.4 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”:

byte[] documentBytes = null;

http://es.slideshare.net/elevenpaths/98-seal-sign-bss-referencia-de-servicios-web

http://es.slideshare.net/elevenpaths/98-seal-sign-bss-referencia-de-servicios-web




InputStream fileStream = getAssets().open("sample.pdf"); int size = fileStream.available(); documentBytes = new byte[size]; fileStream.read(documentBytes); fileStream.close(); BSBBiometricSignatureParameters biometricParameters = new BSBBiometricSignatureParameters(); biometricParameters.imageParameters = new BSBBiometricImageParameters(); biometricParameters.imageParameters.autoSize = false; biometricParameters.imageParameters.height = 180; biometricParameters.imageParameters.width = 250; biometricParameters.imageParameters.offsetX = 100; biometricParameters.imageParameters.offsetY = 100; biometricParameters.imageParameters.onAllPages = true; biometricParameters.imageParameters.signatureVisible = true; BSBBiometricSignatureBeginResponseBasic beginResponse = service.BeginSignature(SignatureProfile.PDF, BiometricSignatureType.Default, "", "", es.sealsign.bss.BSBEnums.BiometricSignatureFlags.getStatusFlags("Default"), biometricParameters, es.sealsign.bss.BSBEnums.SignatureFlags.getStatusFlags("Default"), null, null, documentBytes); Intent myIntent = new Intent(MainPanelActivity.this, SealSignBSSPanel.class); myIntent.putExtra(SealSignBSSConstants.WIDTH_PORT, 500); // Default and max. value = 640 myIntent.putExtra(SealSignBSSConstants.HEIGHT_PORT, 400); // Default and max. value = 480 myIntent.putExtra(SealSignBSSConstants.WIDTH_LAND, 800); // Default and max. value = 640 myIntent.putExtra(SealSignBSSConstants.HEIGHT_LAND, 500); // Default and max. value = 480 myIntent.putExtra(SealSignBSSConstants.BUTTON_UPPER_MARGIN, 10); // Default value = 6 myIntent.putExtra(SealSignBSSConstants.BUTTON_SIDE_MARGIN, 10); // Default value = 4 myIntent.putExtra(SealSignBSSConstants.BOTTOM_MARGIN, 15); // Default value = 5 myIntent.putExtra(SealSignBSSConstants.BUTTON_M_SAVE_TEXT, "Save"); // Default value = "Salvar" myIntent.putExtra(SealSignBSSConstants.BUTTON_M_CLEAR_TEXT, "Clear"); // Default value = "Borrar" myIntent.putExtra(SealSignBSSConstants.DIALOG_TITLE_TEXT, "Saving signature"); // Default value = "Salvando firma" myIntent.putExtra(SealSignBSSConstants.DIALOG_MSG_TEXT, "Please wait..."); // Default value = "Por favor, espere..." myIntent.putExtra(SealSignBSSConstants.DATE_TEXT, new java.util.Date().toString()); myIntent.putExtra(SealSignBSSConstants.BIOMETRIC_INSTANCE, beginResponse.instance.toString()); myIntent.putExtra(SealSignBSSConstants.BIOMETRIC_STATE, beginResponse.biometricState); startActivityForResult(myIntent, 0);

3.1.5 Ending the Signature The result of the signature is captured in the onActivityResult event obtaining, in case of success, the biometric context that must be transferred back to the server by the EndSignature method. The end 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”:

super.onActivityResult(requestCode, resultCode, data); switch(requestCode) { case (0): if (resultCode == Activity.RESULT_OK) { final byte[] biometricState = data.getByteArrayExtra(SealSignBSSConstants.BIOMETRIC_STATE); final String instance = data.getStringExtra(SealSignBSSConstants.BIOMETRIC_INSTANCE); Thread t = new Thread() { public void run() { try { byte[] signedDocument = service.EndSignature(UUID.fromString(instance), biometricState); File signedFile = new File(MainPanelActivity.this.getFilesDir(), "sample.pdf.signed.pdf"); FileOutputStream signedStream = new FileOutputStream(signedFile.getPath()); signedStream.write(signedDocument); signedStream.close(); } catch (Exception e) { e.printStackTrace(); } } }; t.start(); }

break;

3.2 Signed Documents Verification

3.2.1 Signature Capture In order to biometrically verify a signature, you need to follow these three steps:

1. Getting biometric data and the temporary instance through the SealSignBSSClientLibrary client library.

2. Notifying the platform of the operation result in order to perform the verification operation and form the final document.

The obtaining of the temporary biometric data for the verification operation is performed similarly to the start of the signature, although without a biometric token or a server instance. In such case, you will need to transfer the empty instance “00000000-0000-0000-0000-000000000000” and a null biometric state:

Intent myIntent = new Intent(MainPanelActivity.this, SealSignBSSPanel.class); myIntent.putExtra(SealSignBSSConstants.WIDTH_PORT, 500); // Default and max. value = 640 myIntent.putExtra(SealSignBSSConstants.HEIGHT_PORT, 400); // Default and max. value = 480






myIntent.putExtra(SealSignBSSConstants.WIDTH_LAND, 800); // Default and max. value = 640 myIntent.putExtra(SealSignBSSConstants.HEIGHT_LAND, 500); // Default and max. value = 480 myIntent.putExtra(SealSignBSSConstants.BUTTON_UPPER_MARGIN, 10); // Default value = 6 myIntent.putExtra(SealSignBSSConstants.BUTTON_SIDE_MARGIN, 10); // Default value = 4 myIntent.putExtra(SealSignBSSConstants.BOTTOM_MARGIN, 15); // Default value = 5 myIntent.putExtra(SealSignBSSConstants.BUTTON_M_SAVE_TEXT, "Save"); // Default value = "Salvar" myIntent.putExtra(SealSignBSSConstants.BUTTON_M_CLEAR_TEXT, "Clear"); // Default value = "Borrar" myIntent.putExtra(SealSignBSSConstants.DIALOG_TITLE_TEXT, "Saving signature"); // Default value = "Salvando firma" myIntent.putExtra(SealSignBSSConstants.DIALOG_MSG_TEXT, "Please wait..."); // Default value = "Por favor, espere..." myIntent.putExtra(SealSignBSSConstants.DATE_TEXT, new java.util.Date().toString()); myIntent.putExtra(SealSignBSSConstants.BIOMETRIC_INSTANCE, "00000000-0000-0000-0000-000000000000"); myIntent.putExtra(SealSignBSSConstants.BIOMETRIC_STATE, (String)null); startActivityForResult(myIntent, 2);

3.2.2 Signature Verification To verify a signature, 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.

case (2): if (resultCode == Activity.RESULT_OK) { final byte[] biometricState = data.getByteArrayExtra(SealSignBSSConstants.BIOMETRIC_STATE); Thread t = new Thread() { public void run() { try { File signedFile = new File(MainPanelActivity.this.getFilesDir(), "sample.pdf.signed.pdf"); FileInputStream documentStream = new FileInputStream(signedFile); byte[] documentBytes = new byte[documentStream.available()]; documentStream.read(documentBytes); documentStream.close(); BSBBiometricSignatureVerification verificationRespone = service.Verify(SignatureProfile.PDF, BiometricSignatureType.Default, "", "", es.sealsign.bss.BSBEnums.BiometricVerificationFlags.getStatusFlags("Default"), null, biometricState, null, documentBytes); Log.i("SealSignBSSBackendSample", verificationRespone.result.toString()); }






catch (Exception e) { e.printStackTrace(); } } }; t.start(); } break;

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 Transferring the Document as Extra 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:

byte[] documentBytes = null; InputStream fileStream = getAssets().open("sample.pdf"); int size = fileStream.available(); documentBytes = new byte[size]; fileStream.read(documentBytes); fileStream.close(); Intent myIntent = new Intent(MainPanelActivity.this, SealSignBSSPanel.class); myIntent.putExtra(SealSignBSSConstants.WIDTH_PORT, 500); // Default and max. value = 640 myIntent.putExtra(SealSignBSSConstants.HEIGHT_PORT, 400); // Default and max. value = 480 myIntent.putExtra(SealSignBSSConstants.WIDTH_LAND, 800); // Default and max. value = 640 myIntent.putExtra(SealSignBSSConstants.HEIGHT_LAND, 500); // Default and max. value = 480 myIntent.putExtra(SealSignBSSConstants.BUTTON_UPPER_MARGIN, 10); // Default value = 6 myIntent.putExtra(SealSignBSSConstants.BUTTON_SIDE_MARGIN, 10); // Default value = 4 myIntent.putExtra(SealSignBSSConstants.BOTTOM_MARGIN, 15); // Default value = 5 myIntent.putExtra(SealSignBSSConstants.BUTTON_M_SAVE_TEXT, "Save"); // Default value = "Salvar" myIntent.putExtra(SealSignBSSConstants.BUTTON_M_CLEAR_TEXT, "Clear"); // Default value = "Borrar" myIntent.putExtra(SealSignBSSConstants.DIALOG_TITLE_TEXT, "Saving signature"); // Default value = "Salvando firma" myIntent.putExtra(SealSignBSSConstants.DIALOG_MSG_TEXT, "Please wait..."); // Default value = "Por favor, espere..." myIntent.putExtra(SealSignBSSConstants.DATE_TEXT, new java.util.Date().toString()); myIntent.putExtra(SealSignBSSConstants.BIOMETRIC_INSTANCE, "00000000-0000-0000-0000-000000000000"); myIntent.putExtra(SealSignBSSConstants.BIOMETRIC_STATE, (String)null); myIntent.putExtra(SealSignBSSConstants.BIOMETRIC_OFFLINE_DOCUMENT, documentBytes); startActivityForResult(myIntent, 3);




3.3.2 Disconnected Capture Transferring the Document through File Provider Some documents may exceed the maximum size allowed to be transferred through extras. In this case, you can use a FileProvider to transfer the document to be signed to the activity.

You must register the provider in the AndroidManifest.xml file:

<provider android:name="android.support.v4.content.FileProvider" android:authorities="es.elevenpaths.fileprovider" android:grantUriPermissions="true" android:exported="false"> <meta-data android:name="android.support.FILE_PROVIDER_PATHS" android:resource="@xml/filepaths" /> </provider>

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 as a parameter the document to be signed. Subsequently, the temporary instance generated on client is also obtained:

byte[] documentBytes = null; InputStream fileStream = getAssets().open("big-sample.pdf"); int size = fileStream.available(); documentBytes = new byte[size]; fileStream.read(documentBytes); fileStream.close(); Intent myIntent = new Intent(MainPanelActivity.this, SealSignBSSPanel.class); myIntent.putExtra(SealSignBSSConstants.WIDTH_PORT, 500); // Default and max. value = 640 myIntent.putExtra(SealSignBSSConstants.HEIGHT_PORT, 400); // Default and max. value = 480 myIntent.putExtra(SealSignBSSConstants.WIDTH_LAND, 800); // Default and max. value = 640 myIntent.putExtra(SealSignBSSConstants.HEIGHT_LAND, 500); // Default and max. value = 480 myIntent.putExtra(SealSignBSSConstants.BUTTON_UPPER_MARGIN, 10); // Default value = 6 myIntent.putExtra(SealSignBSSConstants.BUTTON_SIDE_MARGIN, 10); // Default value = 4 myIntent.putExtra(SealSignBSSConstants.BOTTOM_MARGIN, 15); // Default value = 5 myIntent.putExtra(SealSignBSSConstants.BUTTON_M_SAVE_TEXT, "Save"); // Default value = "Salvar" myIntent.putExtra(SealSignBSSConstants.BUTTON_M_CLEAR_TEXT, "Clear"); // Default value = "Borrar" myIntent.putExtra(SealSignBSSConstants.DIALOG_TITLE_TEXT, "Saving signature"); // Default value = "Salvando firma" myIntent.putExtra(SealSignBSSConstants.DIALOG_MSG_TEXT, "Please wait..."); // Default value = "Por favor, espere..." myIntent.putExtra(SealSignBSSConstants.DATE_TEXT, new java.util.Date().toString()); myIntent.putExtra(SealSignBSSConstants.BIOMETRIC_INSTANCE, "00000000-0000-0000-0000-000000000000"); myIntent.putExtra(SealSignBSSConstants.BIOMETRIC_STATE, (String)null); File fileToShare = new File(getFilesDir() + File.separator + "export", "signingDocument.pdf"); fileToShare.delete(); fileToShare.getParentFile().mkdirs();




fileToShare.createNewFile(); FileOutputStream fos = new FileOutputStream(fileToShare.getPath()); fos.write(documentBytes); fos.close(); Uri fileUri = FileProvider.getUriForFile(MainPanelActivity.this, "es.elevenpaths.fileprovider", fileToShare); myIntent.addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION); myIntent.setDataAndType(fileUri, getContentResolver().getType(fileUri));

startActivityForResult(myIntent, 4);

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

if (resultCode == Activity.RESULT_OK) { final byte[] biometricState = data.getByteArrayExtra(SealSignBSSConstants.BIOMETRIC_STATE); final String instance = data.getStringExtra(SealSignBSSConstants.BIOMETRIC_INSTANCE); Thread t = new Thread() { public void run() { try { byte[] documentBytes = null; InputStream fileStream = getAssets().open("sample.pdf"); int size = fileStream.available(); documentBytes = new byte[size]; fileStream.read(documentBytes); fileStream.close(); BSBOfflineBiometricSignature offlineSignature = new BSBOfflineBiometricSignature(); offlineSignature.biometricSignatureType = BiometricSignatureType.Default; offlineSignature.id = ""; offlineSignature.account = ""; offlineSignature.biometricOptions = es.sealsign.bss.BSBEnums.BiometricSignatureFlags.getStatusFlags("Default"); offlineSignature.biometricParameters = null; offlineSignature.options = es.sealsign.bss.BSBEnums.SignatureFlags.getStatusFlags("Default"); offlineSignature.parameters = null; offlineSignature.instance = UUID.fromString(instance); offlineSignature.offlineBiometricState = biometricState; BSBArrayOfOfflineBiometricSignature offlineSignatures = new BSBArrayOfOfflineBiometricSignature(); offlineSignatures.add(offlineSignature); byte[] signedDocument = service.SyncOfflineSignatures(SignatureProfile.PDF, offlineSignatures, null, documentBytes);




File signedFile = new File(MainPanelActivity.this.getFilesDir(), "sample.pdf.signed.pdf"); FileOutputStream signedStream = new FileOutputStream(signedFile.getPath()); signedStream.write(signedDocument); signedStream.close(); } catch (Exception e) { e.printStackTrace(); } } }; t.start();

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:

BSBBiometricSignatureBeginResponseBasic beginResponse = service.BeginSignatureProvider("", "", demoURI, null, null); Intent myIntent = new Intent(MainPanelActivity.this, SealSignBSSPanel.class); myIntent.putExtra(SealSignBSSConstants.WIDTH_PORT, 500); // Default and max. value = 640 myIntent.putExtra(SealSignBSSConstants.HEIGHT_PORT, 400); // Default and max. value = 480 myIntent.putExtra(SealSignBSSConstants.WIDTH_LAND, 800); // Default and max. value = 640 myIntent.putExtra(SealSignBSSConstants.HEIGHT_LAND, 500); // Default and max. value = 480 myIntent.putExtra(SealSignBSSConstants.BUTTON_UPPER_MARGIN, 10); // Default value = 6 myIntent.putExtra(SealSignBSSConstants.BUTTON_SIDE_MARGIN, 10); // Default value = 4 myIntent.putExtra(SealSignBSSConstants.BOTTOM_MARGIN, 15); // Default value = 5 myIntent.putExtra(SealSignBSSConstants.BUTTON_M_SAVE_TEXT, "Save"); // Default value = "Salvar" myIntent.putExtra(SealSignBSSConstants.BUTTON_M_CLEAR_TEXT, "Clear"); // Default value = "Borrar" myIntent.putExtra(SealSignBSSConstants.DIALOG_TITLE_TEXT, "Saving signature"); // Default value = "Salvando firma" myIntent.putExtra(SealSignBSSConstants.DIALOG_MSG_TEXT, "Please wait..."); // Default value = "Por favor, espere..." myIntent.putExtra(SealSignBSSConstants.DATE_TEXT, new java.util.Date().toString()); myIntent.putExtra(SealSignBSSConstants.BIOMETRIC_INSTANCE, beginResponse.instance.toString());






myIntent.putExtra(SealSignBSSConstants.BIOMETRIC_STATE, beginResponse.biometricState); startActivityForResult(myIntent, 1);

3.4.1.1 Ending the Signature The end of the signature is notified to the platform. The used service is /SealSignBSSService/Biometric SignatureServiceBasic.svc.


if (resultCode == Activity.RESULT_OK) { final byte[] biometricState = data.getByteArrayExtra(SealSignBSSConstants.BIOMETRIC_STATE); final String instance = data.getStringExtra(SealSignBSSConstants.BIOMETRIC_INSTANCE); Thread t = new Thread() { public void run() { try { service.EndSignatureProvider(UUID.fromString(instance), biometricState, demoURI, null, false); } catch (Exception e) { e.printStackTrace(); } } }; t.start(); } break;






4 SealSignBSSView Customized View

4.1 Biometric Signature

The integration of signature processes in the application using the SealSignBSSView customized view increases flexibility in the processing of the user interface and information flow. However, it requires the completion of the interface with the necessary buttons to perform actions on the capture (cleaning the panel, signing, etc.).

4.1.1 Including the Signature Panel To include the signature panel in an application, you need to follow the steps of any view. In this example, the signature panel is added as part of a LinearLayout:

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" xmlns:tools="http://schemas.android.com/tools" android:layout_width="fill_parent" android:layout_height="fill_parent" android:orientation="vertical" tools:context="es.elevenpaths.sealsignbssbackendsample.MainPanelActivity" >

<Button android:id="@+id/signButton" android:layout_width="wrap_content" android:layout_height="wrap_content" android:layout_gravity="center" android:layout_marginTop="5dp" android:onClick="sign" android:text="Sign" /> <Button android:id="@+id/clearButton" android:layout_width="wrap_content" android:layout_height="wrap_content" android:layout_gravity="center" android:layout_marginTop="5dp" android:onClick="clear" android:text="Clear" /> <es.smartaccess.sealsignbss.SealSignBSSView android:id="@+id/signatureView" android:layout_width="fill_parent" android:layout_height="fill_parent" android:layout_marginBottom="5dp" android:layout_marginLeft="5dp" android:layout_marginRight="5dp" android:layout_marginTop="5dp" />

</LinearLayout>

4.1.2 Access Permissions to the SealSign Web Service To access the platform Web services, the Android app needs to have permissions to access to the network:

<uses-permission android:name="android.permission.INTERNET" />




It is important to note that calls to Web services, or any connection, cannot be conducted within the user interface main thread, so you will have to conduct them from another thread or within an asynchronous task.

4.1.3 Event Registration You can receive panel events by implementing the SealSignBSSEventListener interface. Events included in the interface are:

void onSignatureCleared():The signature has been cleared from the tablet.

void onSignatureStarted(): The signature capture has started and the first sample has been taken.

void onSignatureCanceled(): The capture has been canceled.

SealSignBSSView signatureView = (SealSignBSSView)findViewById(R.id.signatureView); signatureView.setOnSealSignBSSEventListener(this)

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

SealSignBSSView signatureView = (SealSignBSSView)findViewById(R.id.signatureView); signatureView.setTransparentSignature(true);

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

SealSignBSSView signatureView = (SealSignBSSView)findViewById(R.id.signatureView); signatureView.cleanSignature();

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


byte[] documentBytes = null; InputStream fileStream = getAssets().open("sample.pdf"); int size = fileStream.available(); documentBytes = new byte[size]; fileStream.read(documentBytes); fileStream.close();






BSBBiometricSignatureParameters biometricParameters = new BSBBiometricSignatureParameters(); biometricParameters.imageParameters = new BSBBiometricImageParameters(); biometricParameters.imageParameters.autoSize = false; biometricParameters.imageParameters.height = 180; biometricParameters.imageParameters.width = 250; biometricParameters.imageParameters.offsetX = 100; biometricParameters.imageParameters.offsetY = 100; biometricParameters.imageParameters.onAllPages = true; biometricParameters.imageParameters.signatureVisible = true; BSBBiometricSignatureBeginResponseBasic beginResponse = service.BeginSignature(SignatureProfile.PDF, BiometricSignatureType.Default, "", "", es.sealsign.bss.BSBEnums.BiometricSignatureFlags.getStatusFlags("Default"), biometricParameters, es.sealsign.bss.BSBEnums.SignatureFlags.getStatusFlags("Default"), null, null, documentBytes);

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

byte[] finalBiometricState = signatureView.getSignature(beginResponse.instance.toString(), beginResponse.biometricState);

4.1.8 Ending the Signature The ending of the signature is notified to the platform and the final document is obtained using the EndSignature method. The used service is /SealSignBSSService/BiometricSignatureServiceBasic.svc.


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

4.2 Verifying Signed Documents

4.2.1 Signature Capture In order to biometrically verify a signature, you need to follow these three steps:

1. Getting biometric data and the temporary instance through the SealSignBSSClientLibrary client library.

2. Notifying the platform of the operation result in order to perform the verification operation and form the final document.

The obtaining of the temporary biometric data for the verification operation is performed similarly to the start of the signature, although without a biometric token or a server instance. In such case, you will need to transfer the empty instance “00000000-0000-0000-0000-000000000000” and a null biometric state:






Intent myIntent = new Intent(MainPanelActivity.this, SealSignBSSPanel.class); myIntent.putExtra(SealSignBSSConstants.WIDTH_PORT, 500); // Default and max. value = 640 myIntent.putExtra(SealSignBSSConstants.HEIGHT_PORT, 400); // Default and max. value = 480 myIntent.putExtra(SealSignBSSConstants.WIDTH_LAND, 800); // Default and max. value = 640 myIntent.putExtra(SealSignBSSConstants.HEIGHT_LAND, 500); // Default and max. value = 480 myIntent.putExtra(SealSignBSSConstants.BUTTON_UPPER_MARGIN, 10); // Default value = 6 myIntent.putExtra(SealSignBSSConstants.BUTTON_SIDE_MARGIN, 10); // Default value = 4 myIntent.putExtra(SealSignBSSConstants.BOTTOM_MARGIN, 15); // Default value = 5 myIntent.putExtra(SealSignBSSConstants.BUTTON_M_SAVE_TEXT, "Save"); // Default value = "Salvar" myIntent.putExtra(SealSignBSSConstants.BUTTON_M_CLEAR_TEXT, "Clear"); // Default value = "Borrar" myIntent.putExtra(SealSignBSSConstants.DIALOG_TITLE_TEXT, "Saving signature"); // Default value = "Salvando firma" myIntent.putExtra(SealSignBSSConstants.DIALOG_MSG_TEXT, "Please wait..."); // Default value = "Por favor, espere..." myIntent.putExtra(SealSignBSSConstants.DATE_TEXT, new java.util.Date().toString()); myIntent.putExtra(SealSignBSSConstants.BIOMETRIC_INSTANCE, "00000000-0000-0000-0000-000000000000"); myIntent.putExtra(SealSignBSSConstants.BIOMETRIC_STATE, (String)null); startActivityForResult(myIntent, 2);

4.2.2 Signature Verification A single call is made to the Verify method of the server platform. The used service is /SealSignBSSService/BiometricSignatureServiceBasic.svc.


File signedFile = new File(MainViewActivity.this.getFilesDir(), "sample.pdf.signed.pdf"); FileInputStream documentStream = new FileInputStream(signedFile); byte[] documentBytes = new byte[documentStream.available()]; documentStream.read(documentBytes); documentStream.close(); byte[] finalBiometricState = signatureView.getSignature("00000000-0000-0000-0000-000000000000", null); BSBBiometricSignatureVerification verificationRespone = service.Verify(SignatureProfile.PDF, BiometricSignatureType.Default, "", "", es.sealsign.bss.BSBEnums.BiometricVerificationFlags.getStatusFlags("Default"), null, finalBiometricState, null, documentBytes); Log.i("SealSignBSSBackendSample", verificationRespone.result.toString());

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

4.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:

byte[] documentBytes = null; InputStream fileStream = getAssets().open("sample.pdf"); int size = fileStream.available(); documentBytes = new byte[size]; fileStream.read(documentBytes); fileStream.close(); byte[] finalBiometricState = signatureView.getOfflineSignature(documentBytes); String instance = signatureView.getBiometricInstance();

4.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:

BSBOfflineBiometricSignature offlineSignature = new BSBOfflineBiometricSignature(); offlineSignature.biometricSignatureType = BiometricSignatureType.Default; offlineSignature.id = ""; offlineSignature.account = ""; offlineSignature.biometricOptions = es.sealsign.bss.BSBEnums.BiometricSignatureFlags.getStatusFlags("Default"); offlineSignature.biometricParameters = null; offlineSignature.options = es.sealsign.bss.BSBEnums.SignatureFlags.getStatusFlags("Default"); offlineSignature.parameters = null; offlineSignature.instance = UUID.fromString(instance); offlineSignature.offlineBiometricState = finalBiometricState; BSBArrayOfOfflineBiometricSignature offlineSignatures = new BSBArrayOfOfflineBiometricSignature(); offlineSignatures.add(offlineSignature); byte[] signedDocument = service.SyncOfflineSignatures(SignatureProfile.PDF, offlineSignatures, null, documentBytes); File signedFile = new File(MainViewActivity.this.getFilesDir(), "sample.pdf.signed.pdf"); FileOutputStream signedStream = new FileOutputStream(signedFile.getPath()); signedStream.write(signedDocument); signedStream.close();




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

4.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/BiometricSignatureServiceBasic.svc.


BSBBiometricSignatureBeginResponseBasic beginResponse = service.BeginSignatureProvider("", "", demoURI, null, null);

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

byte[] finalBiometricState = signatureView.getSignature(beginResponse.instance.toString(), beginResponse.biometricState);

4.4.3 Ending the Signature The ending of the signature is notified to the platform and the final document is obtained using the EndSignature method. The used service is /SealSignBSSService/BiometricSignatureServiceBasic.svc.


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








5 Integrating BioSigner for Android

ElevenPaths’ BioSigner app for Android allows the biometric signature of electronic 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 BioSigner application on the device. Through Google Play, locate and install the ElevenPaths’ “Mobile BioSigner” application.

2. Create a web page that invokes the BioSigner signature component by indicating the required parameters. The invocation of BioSigner 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.mobilebiosigner.SIGNFE;launchFlags=0x

10000000;component=es.smartaccess.mobilebiosigner/.MobileBioSignerFE;S.par

ametro1=valor;S.parametro2=valor;…;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 BioSigner:

intent:#Intent;action=es.smartaccess.mobilebiosigner.SIGNFE;launchFlags=0x

10000000;component=es.smartaccess.mobilebiosigner/.MobileBioSignerFE;S.vie

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

http://www.google.es;end




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

Technology

Transcript of SealSign BSS Integration Guide for Android Applications