SealSign DSS Integration Guide for iOS Applications

[email protected]

elevenpaths.com

SealSign DSS (Digital Signature Services)

Integration Guide for iOS Applications

ElevenPaths, radical and disruptive innovation in security solutions

SealSign DSS (Digital Signature Services) Integration Guide for iOS 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 Enumeration of Certificates ....................................................................................................... 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 Ending the Signature .................................................................................................................. 8

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

4 Integration with Mobile Signer for IOS ....................................................................... 10

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




1 Introduction

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

This document is not intended as a manual for the specific aspects of the electronic signature, but a technical reference guide, developer-oriented, on integrating SealSign DSS in 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 DSS - 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 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

To include cryptographic functions in the client platform, you need to add to the project both the SealSignDSSClientLibrary.a cryptography static library and the SealSignDSSClientLibrary.h header file:

Once included, you must declare the header file import:

#import "SealSignDSSClientLibrary.h"

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 and the obtaining of a CertificateReference array. Each object contains information related to each certificate that can be used by the user. The returned values and syntax of the method can be found in the “SealSign DSS - Web Services Reference” document.

NSError *serviceError = nil; NSString *documentPath = [[NSBundle mainBundle] pathForResource:@"sample" ofType:@"pdf"]; NSData *documentData = [NSData dataWithContentsOfFile:documentPath]; SSBBasicHttpBinding_ISignatureServiceBasic* service = [[SSBBasicHttpBinding_ISignatureServiceBasic alloc] init]; [service setUrl:@"https://master.sealsignonline.com/sealsigndssservice/signatureservicebasic.svc/BB"]; // Credenciales basicas de acceso NSString *authHeader = [[NSString alloc] initWithFormat:@"Basic %@", [[@"usuario:password" dataUsingEncoding:NSUTF8StringEncoding] base64EncodedStringWithOptions:0]]; [service setHeaders:@{@"Authorization": authHeader}]; SSBArrayOfCertificateReference *references = [service GetCertificateReferences:nil includeEncoded:[NSNumber numberWithUnsignedInt:0] __error:&serviceError]; for (id reference in references) {

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:

NSError *serviceError = nil; NSString *certificatePath = [[NSBundle mainBundle] pathForResource:@"certificate" ofType:@"pfx"]; NSData *certificateData = [NSData dataWithContentsOfFile:certificatePath]; SealSignDSSPKCS12Provider *provider = [[SealSignDSSPKCS12Provider alloc] initWithCertificateData:certificateData certificatePassword:@"1234"]; NSData *certificateEncodedData = [[NSData alloc] initWithBase64EncodedString:[provider certificateBase64] options:0]; CSBBasicHttpBinding_ICertificateServiceBasic* service = [[CSBBasicHttpBinding_ICertificateServiceBasic alloc] init]; [service setUrl:@"https://master.sealsignonline.com/SealSignDSSService/CertificateServiceBasic.svc/B"];







NSNumber *reason = [[NSNumber alloc] initWithInt:0]; CSBValidateResponse *validateResponse = [service Validate:certificateEncodedData timeToUse:nil reason:reason __error:&serviceError]; NSLog(@"%@ %@", [validateResponse getValidateResult], reason);

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.

NSMutableSet *signOptions = [[NSMutableSet alloc] initWithObjects:[SSBSignatureFlags Default], nil]; NSData *signedDocument = [service Sign:[(SSBCertificateReference *)reference get_id] signatureProfile:[SSBSignatureProfile PDF] signatureType:[SSBSignatureType Default] hashAlgorithm:[SSBHashAlgorithm Default] options:signOptions parameters:nil password:nil passwordSealSign:nil detachedSignature:nil signingDocument:documentData __error:&serviceError]; NSArray *paths = NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES); NSString *documentsDirectory = [paths objectAtIndex:0]; NSString *signedDocumentFile = [documentsDirectory stringByAppendingPathComponent:@"sample.pdf.signed.pdf"]; [signedDocument writeToFile:signedDocumentFile atomically:YES];

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 Enumeration of Certificates To get the signature certificate you can use the IOS SDK for key management, or the SealSignDSSPKCS12Provider class for certificate management in PKCS#12files:

NSString *certificatePath = [[NSBundle mainBundle] pathForResource:@"certificate" ofType:@"pfx"]; NSData *certificateData = [NSData dataWithContentsOfFile:certificatePath];






SealSignDSSPKCS12Provider *provider = [[SealSignDSSPKCS12Provider alloc] initWithCertificateData:certificateData certificatePassword:@"password"];

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.

NSData *certificateEncodedData = [[NSData alloc] initWithBase64EncodedString:[provider certificateBase64] options:0]; NSString *documentPath = [[NSBundle mainBundle] pathForResource:@"sample" ofType:@"pdf"]; NSData *documentData = [NSData dataWithContentsOfFile:documentPath]; DSBBasicHttpBinding_IDistributedSignatureServiceBasic *service = [[DSBBasicHttpBinding_IDistributedSignatureServiceBasic alloc] init]; [service setUrl:@"https://master.sealsignonline.com/SealSignDSSService/DistributedSignatureServiceBasic.svc/B"]; NSMutableSet *signOptions = [[NSMutableSet alloc] initWithObjects:[DSBSignatureFlags Default], nil]; DSBDistributedSignatureBeginResponseBasic *beginResponse = [service BeginSignature:certificateEncodedData signatureProfile:[DSBSignatureProfile PDF] signatureType:[DSBSignatureType Default] hashAlgorithm:[DSBHashAlgorithm Default] options:signOptions parameters:nil detachedSignature:nil signingDocument:documentData __error:&serviceError];

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

SealSignDSSAsyncStateManager *manager = [[SealSignDSSAsyncStateManager alloc] initWithAsyncStateBytes:[beginResponse getAsyncState]]; NSString *asynStateBase64 = [manager doFinal:[provider privateKey]];

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:

NSData *asynStateData = [[NSData alloc] initWithBase64EncodedString:asynStateBase64 options:0];

NSData *signedDocument = [service EndSignature:[beginResponse getInstance] asyncState:asynStateData __error:&serviceError]; NSArray *paths = NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES); NSString *documentsDirectory = [paths objectAtIndex:0]; NSString *signedDocumentFile = [documentsDirectory stringByAppendingPathComponent:@"sample.pdf.signed.pdf"]; [signedDocument writeToFile:signedDocumentFile atomically:YES];







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 To get the signature certificate you can use the IOS SDK for key management, or the SealSignDSSPKCS12Provider class for certificate management in PKCS#12files:

NSString *certificatePath = [[NSBundle mainBundle] pathForResource:@"certificate" ofType:@"pfx"]; NSData *certificateData = [NSData dataWithContentsOfFile:certificatePath]; SealSignDSSPKCS12Provider *provider = [[SealSignDSSPKCS12Provider alloc] initWithCertificateData:certificateData certificatePassword:@"password"];

3.5.2 Beginning the Signature The beginning of the signature is notified to the server platform by calling the BeginSignatureProvider 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/ DistributedSignatureServiceBasic.svc.

NSData *certificateEncodedData = [[NSData alloc] initWithBase64EncodedString:[provider certificateBase64] options:0]; DSBBasicHttpBinding_IDistributedSignatureServiceBasic *service = [[DSBBasicHttpBinding_IDistributedSignatureServiceBasic alloc] init]; [service setUrl:@"https://master.sealsignonline.com/SealSignDSSService/DistributedSignatureServiceBasic.svc/B"]; DSBDistributedSignatureBeginResponseBasic *beginResponse = [service BeginSignatureProvider:certificateEncodedData uri:@"demo://c:\\samples\\sample.pdf" providerParameter:nil document:nil __error:&serviceError];

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

SealSignDSSAsyncStateManager *manager = [[SealSignDSSAsyncStateManager alloc] initWithAsyncStateBytes:[beginResponse getAsyncState]]; NSString *asynStateBase64 = [manager doFinal:[provider privateKey]];

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

NSData *asynStateData = [[NSData alloc] initWithBase64EncodedString:asynStateBase64 options:0]; NSData *signedDocument = [service EndSignatureProvider:[beginResponse getInstance] asyncState:asynStateData uri:@"demo://c:\\samples\\sample.pdf" providerParameter:nil returnSignedDocument:[NSNumber numberWithInt:0] __error:&serviceError];






NSArray *paths = NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES); NSString *documentsDirectory = [paths objectAtIndex:0]; NSString *signedDocumentFile = [documentsDirectory stringByAppendingPathComponent:@"sample.pdf.signed.pdf"]; [signedDocument writeToFile:signedDocumentFile atomically:YES];

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 returned values and syntax of the method can be found in the “SealSign DSS - Web Services Reference” document. The used service is / SealSignDSSService/SignatureServiceBasic.svc:

NSError *serviceError = nil; NSArray *paths = NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES); NSString *documentsDirectory = [paths objectAtIndex:0]; NSString *signedDocumentFile = [documentsDirectory stringByAppendingPathComponent:@"sample.pdf.signed.pdf"]; NSData *signedDocument = [NSData dataWithContentsOfFile:signedDocumentFile]; SSBBasicHttpBinding_ISignatureServiceBasic* service = [[SSBBasicHttpBinding_ISignatureServiceBasic alloc] init]; [service setUrl:@"https://master.sealsignonline.com/sealsigndssservice/signatureservicebasic.svc/B"]; NSMutableSet *verifyOptions = [[NSMutableSet alloc] initWithObjects:[SSBVerificationFlags Default], nil]; SSBSignatureVerification *verifyResponse = [service Verify:[SSBSignatureProfile PDF] options:verifyOptions parameters:nil detachedSignature:nil document:signedDocument __error:&serviceError]; NSLog(@"%@", [verifyResponse getResult]);






4 Integration with Mobile Signer for IOS

ElevenPaths’s Mobile Signer App for iPad/iPhone can digitally sign documents by using an electronic certificate stored in the device or in a smartcard.

This App can be initiated as a component from a Web Page viewed inside Safari Browser. The signing document must be accessible by the SealSign server and the logic will be implemented in the document provider.

1. Install Mobile Signer. In the App Store search and install ElevenPaths’s “Mobile Signer”.

2. Call the Mobile Signer component from a Web page passing the necessary parameters. A specific URL must be used in order to invoke the App. The syntax is: mobilesignerfe://?parameter1=value&parameter2=value&…

The parameters are:

a. viewerurl: This URL will be open in a Browser behind the signature panel to visualize the sigining document.

b. uri: Is the first value passed to the document provider to identify the signing document.

c. providerParameter: Is an optional parameter passed to the document provider containing additional info about the signing document.

d. serviceUrl: URL of the SealSign Engine server.

e. serviceUsername: Is specified, the username used in the connection with the SealSign engine server. If not, an anonymous connection will be established.

f. servicePassword: Password used in the connection with the SealSign engine server if serviceUsername is specified.

g. exitUrl: URL that will be shown if the signature process ends successfully. In the query string will be passed the final status of the process.

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

mobilesignerfe://?viewerurl=http://www.smartaccess.es&uri=demo://1-2-

z.pdf&providerParameter=myProviderParameter&serviceUrl=http://demo.smartaccess.es/s

ealsigndssfrontend&serviceUsername=user&servicePassword=pwd&exitUrl=http://www.goog

le.es




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 iOS Applications

Technology

Transcript of SealSign DSS Integration Guide for iOS Applications