SealSign BSS Integration Guide for iOS Applications

[email protected]

elevenpaths.com

SealSign BSS (Biometric Signature Services)

Integration Guide for iOS Applications

ElevenPaths, radical and disruptive innovation in security solutions

SealSign BSS (Biometric Signature Services) Integration Guide for iOS Applications

V.3.2 – October 2016

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

TABLE OF CONTENT

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

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

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

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

2.3 Biometric Signature .................................................................................................................. 5

2.3.1 Including the Signature Panel ..................................................................................................... 5

2.3.2 Events Registration ..................................................................................................................... 5

2.3.3 Establishing a Transparent Signature Background ..................................................................... 6

2.3.4 Enabling the Use of Pressure Pencils .......................................................................................... 6

2.3.5 Starting the Capture ................................................................................................................... 6

2.3.6 Deleting the Capture .................................................................................................................. 6

2.3.7 Beginning the Signature ............................................................................................................. 6

2.3.8 Client Cryptography .................................................................................................................... 7

2.3.9 Ending the Signature .................................................................................................................. 8

2.4 Verifying Signed Documents ..................................................................................................... 8

2.5 Disconnected Biometric Signature ........................................................................................... 9

2.5.1 Disconnected Capture ................................................................................................................ 9

2.5.2 Synchronizing the Signature with the Server ............................................................................. 9

2.6 Biometric Signature with Document Provider (Document on Server) ................................... 10

2.6.1 Beginning the Signature ........................................................................................................... 10

2.6.2 Client Cryptography .................................................................................................................. 10

2.6.3 Ending the Signature ................................................................................................................ 10

2.7 Integrating BioSigner for iOS .................................................................................................. 11

3 Resources .................................................................................................................. 12




1 Introduction

SealSign BSS (Biometric Signature Services) is a product developed entirely by ElevenPaths, 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 iOS 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 iOS 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 SealSignDSSClientLibrary Client

To include biometric capture and cryptography functions in the client platform, you need to add to the project both the SealSignBSSClientLibrary.a capture static library and the SealSignBSSClient Library.h header file:

Figure 01: Appearance of the project.

Once included, you must declare the header file import:

#import "SealSignBSSClientLibrary.h"

To support the functionality of the panel, the addition of the Coremotion.framework framework is required.

Figure 02: Choosing the CoreMotion framework.

Additionally, to include all symbols and avoid the problem of “Unknown class SealSignBSSPanelView in Interface Builder file” in runtime due to a customized view, you can add the -all_load and -ObjC options to the “Other Linker Flags” section.

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





Figure 03: Adding the -all_load and -ObjC options to the “Other Linker Flags” section.

2.3 Biometric Signature

2.3.1 Including the Signature Panel The signature panel is an inherited class from UIView. To include it, you need to add a normal view and specify the SealSignBSSPanelView class in the class type.

Figure 04: Specifying the SealSignBSSPanelView class in the view.

2.3.2 Events Registration You can receive panel events by implementing the SealSignBSSPanelViewDelegate delegate. Events included in the interface are:

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

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

[_panelView setDelegate:self];




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

[_panelView setTransparentSignature:YES];

2.3.4 Enabling the Use of Pressure Pencils The capture of the biometric pattern with IOS devices (iPhone and iPad) does not include the pressure parameter by default. The capture SDK supports the use of pressure capture devices via Bluetooth. Supported devices are the following:

2.3.4.1 Pogo Connect You can use the following sentence to enable support of the Pogo pencil:

[_panelView enablePogoHardware];

The SDK version of Pogo integrated in this SealSign version is v1.4.3 (49), Sep. 10, 2015. For more information on supported devices, see Pogo’s website https://tenonedesign.com/ t1pogomanager.php.

2.3.4.2 Wacom You can use the following sentence to enable support of the Wacom pencil:

[_panelView enableWacomHardware];

The SDK version of Wacom integrated in this SealSign version is iOS SDK 2.0.15 RC2 Release. For more information on supported devices, see Wacom website http://us.wacom.com/en/developerrelations/ ios/.

2.3.4.3 Jot Touch You can use the following sentence to enable support of the Jot Touch pencil:

[_panelView enableJotHardware];

The SDK version of Jot Touch integrated in this SealSign version is V2.7. For more information on supported devices, see Jot Touch website https://github.com/Adonit/JotTouchSDK.

2.3.5 Starting the Capture The panel starts to register the capture with the first detected point. It is not necessary to call any additional method.

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

capturePanel.cleanSignature();

2.3.7 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).

https://tenonedesign.com/%20t1pogomanager.php

https://tenonedesign.com/%20t1pogomanager.php

http://us.wacom.com/en/developerrelations/%20ios/

http://us.wacom.com/en/developerrelations/%20ios/

https://github.com/Adonit/JotTouchSDK




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

NSString *documentPath = [[NSBundle mainBundle] pathForResource:@"sample" ofType:@"pdf"]; NSData *documentData = [NSData dataWithContentsOfFile:documentPath]; NSError *serviceError = nil; BSBBasicHttpBinding_IBiometricSignatureServiceBasic* service = [[BSBBasicHttpBinding_IBiometricSignatureServiceBasic alloc] init]; [service setUrl:@"https://master.sealsignonline.com/sealsignbssservice/biometricsignatureservicebasic.svc/B"]; NSMutableSet *biometricOptions = [[NSMutableSet alloc] initWithObjects:[BSBBiometricSignatureFlags Default], nil]; NSMutableSet *options = [[NSMutableSet alloc] initWithObjects:[BSBSignatureFlags Default], nil]; BSBBiometricImageParameters *biometricImageParameters = [[BSBBiometricImageParameters alloc] init]; [biometricImageParameters setSignatureVisible:YES]; [biometricImageParameters setOnAllPages:YES]; [biometricImageParameters setAutoSize:NO]; [biometricImageParameters setHeight:100]; [biometricImageParameters setWidth:120]; [biometricImageParameters setOffsetX:300]; [biometricImageParameters setOffsetY:100]; BSBArrayOfBiometricImageParameters *arrayBiometricImageParameters = [[BSBArrayOfBiometricImageParameters alloc] initWithObjects: biometricImageParameters, nil]; BSBBiometricSignatureParameters *biometricParameters = [[BSBBiometricSignatureParameters alloc] init]; [biometricParameters setAdvancedImageParameters:arrayBiometricImageParameters]; BSBBiometricSignatureBeginResponseBasic *beginResponse = [service BeginSignature:[BSBSignatureProfile PDF] biometricSignatureType:[BSBBiometricSignatureType Default] _id:nil account:nil biometricOptions:biometricOptions biometricParameters:biometricParameters options:options parameters:nil detachedSignature:nil signingDocument:documentData __error:&serviceError];

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

NSString *finalBiometricStateBase64 = [_panelView getSignature:[beginResponse getInstance] biometricState:[beginResponse getBiometricState]]; NSData *finalBiometricState = [[NSData alloc] initWithBase64EncodedString:finalBiometricStateBase64 options:NSDataBase64DecodingIgnoreUnknownCharacters];






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

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

NSData *signedDocument = [service EndSignature:[beginResponse getInstance] biometricState:finalBiometricState __error:&serviceError]; NSArray *paths = NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES); NSString *documentsDirectory = [paths objectAtIndex:0]; NSString *filePath = [NSString stringWithFormat:@"%@/%@", documentsDirectory, @"sample.pdf.signed.pdf"]; [signedDocument writeToFile:filePath atomically:YES];

2.4 Verifying Signed Documents

You can verify a captured signature against the signatures within a document. 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.

NSArray *paths = NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES); NSString *documentsDirectory = [paths objectAtIndex:0]; NSString *filePath = [NSString stringWithFormat:@"%@/%@", documentsDirectory, @"sample.pdf.signed.pdf"]; NSData *documentData = [NSData dataWithContentsOfFile:filePath]; NSError *serviceError = nil; BSBBasicHttpBinding_IBiometricSignatureServiceBasic* service = [[BSBBasicHttpBinding_IBiometricSignatureServiceBasic alloc] init]; [service setUrl:@"https://master.sealsignonline.com/sealsignbssservice/biometricsignatureservicebasic.svc/B"]; NSString *finalBiometricStateBase64 = [_panelView getSignature:@"00000000-0000-0000-0000-000000000000" biometricState:nil]; NSData *finalBiometricState = [[NSData alloc] initWithBase64EncodedString:finalBiometricStateBase64 options:NSDataBase64DecodingIgnoreUnknownCharacters]; NSMutableSet *biometricOptions = [[NSMutableSet alloc] initWithObjects:[BSBBiometricVerificationFlags Default], nil]; BSBBiometricSignatureVerification *signatureVerification = [service Verify:[BSBSignatureProfile PDF] biometricSignatureType:[BSBBiometricSignatureType Default] _id:nil account:nil biometricOptions:biometricOptions biometricParameters:nil biometricState:finalBiometricState detachedSignature:nil document:documentData __error:&serviceError]; NSLog(@"%@", [signatureVerification getResult]);







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

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

NSString *documentPath = [[NSBundle mainBundle] pathForResource:@"sample" ofType:@"pdf"]; NSData *documentData = [NSData dataWithContentsOfFile:documentPath]; NSDictionary *offlineDict = [_panelView getOfflineSignature:documentData];

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

BSBBasicHttpBinding_IBiometricSignatureServiceBasic* service = [[BSBBasicHttpBinding_IBiometricSignatureServiceBasic alloc] init]; [service setUrl:@"https://master.sealsignonline.com/sealsignbssservice/biometricsignatureservicebasic.svc/B"]; NSMutableSet *biometricOptions = [[NSMutableSet alloc] initWithObjects:[BSBBiometricSignatureFlags Default], nil]; NSMutableSet *options = [[NSMutableSet alloc] initWithObjects:[BSBSignatureFlags Default], nil]; NSData *finalBiometricState = [[NSData alloc] initWithBase64EncodedString:[offlineDict valueForKey:@"biometricState"] options:NSDataBase64DecodingIgnoreUnknownCharacters]; BSBOfflineBiometricSignature *offlineSignature = [[BSBOfflineBiometricSignature alloc] init]; [offlineSignature set_id:@""]; [offlineSignature setAccount:@""]; [offlineSignature setBiometricOptions:biometricOptions]; [offlineSignature setOptions:options]; [offlineSignature setInstance:[offlineDict valueForKey:@"instance"]]; [offlineSignature setOfflineBiometricState:finalBiometricState]; BSBArrayOfOfflineBiometricSignature *offlineSignatures = [[BSBArrayOfOfflineBiometricSignature alloc] initWithObjects:offlineSignature, nil]; NSData *signedDocument = [service SyncOfflineSignatures:[BSBSignatureProfile PDF] offlineSignatures:offlineSignatures detachedSignature:nil signingDocument:documentData __error:&serviceError]; NSArray *paths = NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES); NSString *documentsDirectory = [paths objectAtIndex:0];




NSString *filePath = [NSString stringWithFormat:@"%@/%@", documentsDirectory, @"sample.pdf.signed.pdf"]; [signedDocument writeToFile:filePath atomically:YES];

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

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


NSError *serviceError = nil; BSBBasicHttpBinding_IBiometricSignatureServiceBasic* service = [[BSBBasicHttpBinding_IBiometricSignatureServiceBasic alloc] init]; [service setUrl:@"https://master.sealsignonline.com/sealsignbssservice/biometricsignatureservicebasic.svc/B"]; BSBBiometricSignatureBeginResponseBasic *beginResponse = [service BeginSignatureProvider:nil account:nil uri:@"demo:\\y:\\proyectos\\sealsign\\samples\\sample.pdf" providerParameter:nil document:nil __error:&serviceError];

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

NSString *finalBiometricStateBase64 = [_panelView getSignature:[beginResponse getInstance] biometricState:[beginResponse getBiometricState]]; NSData *finalBiometricState = [[NSData alloc] initWithBase64EncodedString:finalBiometricStateBase64 options:NSDataBase64DecodingIgnoreUnknownCharacters];

2.6.3 Ending the Signature The ending of the signature is notified to the platform. The used service is /SealSignBSSService/ BiometricSignatureServiceBasic.svc.


[service EndSignatureProvider:[beginResponse getInstance] biometricState:finalBiometricState uri:@"demo:\\y:\\proyectos\\sealsign\\samples\\sample.pdf" providerParameter:nil returnSignedDocument:[NSNumber numberWithInt:0] __error:&serviceError];








2.7 Integrating BioSigner for iOS

ElevenPaths’ BioSigner app for iPad/iPhone 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 Safari 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 App Store, locate and install the “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:

mobilebssfe://?parametro1=valor&parametro2=valor&…

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:

mobilebssfe://?viewerurl=http://www.smartaccess.es&uri=demo://1-2-z.pdf&providerParameter=myProviderParameter&serviceUrl=http://demo.smartaccess.es/sealsigndssfrontend&serviceUsername=usuario&servicePassword=pwd&exitUrl=http://www.google.es




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

Technology

SealSign BSS Integration Guide for iOS Applications