sealsign bss integration guide for .net applications

[email protected]

elevenpaths.com

SealSign BSS (Biometric Signature Services)

Integration Guide for .NET Applications

ElevenPaths, radical and disruptive innovation in security solutions

SealSign BSS (Biometric Signature Services) Integration Guide for .NET Applications

V.3.2 – October 2016

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

TABLE OF CONTENT

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

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

2.1 Including Web Service References ........................................................................................... 4

2.2 Including the SealSignBSSClientLibrary Client .......................................................................... 6

2.3 Authentication of Calls to Web Services .................................................................................. 6

2.3.1 Credentials Transfer for Basic Authentication............................................................................ 6

2.3.2 Credentials Transfer for Windows Authentication ..................................................................... 7

3 Use Cases .................................................................................................................... 8

3.1 Remarks .................................................................................................................................... 8

3.2 Biometric Signature .................................................................................................................. 8

3.2.1 Including the handwritten signature capture panel ................................................................... 8

3.2.2 Event Log .................................................................................................................................... 8

3.2.3 Capture Background Image on the Tablet (only for Wacom tablets) ......................................... 8

3.2.4 Defining Buttons on the tablet (Wacom tablets only)................................................................ 9

3.2.5 Establishing a Transparent Signature Background ..................................................................... 9

3.2.6 Starting the Capture ................................................................................................................... 9

3.2.7 Stopping the Capture ................................................................................................................. 9

3.2.8 Deleting the Capture .................................................................................................................. 9

3.2.9 Beginning the Signature ............................................................................................................. 9

3.2.10 Client Cryptography .................................................................................................................. 10

3.2.11 Ending the Signature ................................................................................................................ 10

3.3 Verifying Signed Documents ................................................................................................... 11

3.4 Disconnected Biometric Signature ......................................................................................... 11

3.4.1 Disconnected Capture .............................................................................................................. 11

3.4.2 Synchronizing the Signature with the Server ........................................................................... 12

3.5 Biometric Signature with Document Provider (Document on Server) ................................... 12

3.5.1 Beginning the Signature ........................................................................................................... 13

3.5.2 Cryptography in Client .............................................................................................................. 13

3.5.3 Ending the Signature ................................................................................................................ 13

3.6 Document Providers Development ........................................................................................ 13

3.6.1 Including SealSignBSSTypes and SealSignDSSTypes ................................................................. 14

3.6.2 Interface Implementation ........................................................................................................ 14

3.6.3 Getting the Document and the Signature Parameters ............................................................. 14

3.6.4 Storing the Signed Document ................................................................................................... 15

4 Resources .................................................................................................................. 16




1 Introduction

SealSign BSS 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.

The SDK of SealSign BSS also provides several panels for the capture of handwritten signatures, available depending on the technology used by the client application.

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 .NET Applications.




2 Common Tasks

2.1 Including Web Service References

The Web services layer is used to interact with the server platform. The “SealSign BSS - Web Services Reference” document details each service and its parameters. In this section you will learn, as an example, how to include the reference to a platform web service using Visual Studio 2013, but you can use any invocation method, such as the generation of proxy classes with utilities like svcutil.exe.

To add a reference to a web service, you just have to right-click on the .NET project button, select the Add option and then Service Reference…

Image 01: Add Service Reference Menu.

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





The following wizard window will be displayed to add the reference to the Web service:

Image 02: Wizard window to add a Service Reference.

In this window you must include the Web service URL and, after clicking on the Go button, enter a name for the Namespace and click on the OK button. The reference is added to the project and displayed in the Solution Explorer panel:

Image 03: Web service reference in Solution Explorer.




Another method for invoking web services is to generate proxy classes with utilities like svcutil.exe, available both with the Microsoft Windows SDK and with the different versions of Microsoft Visual Studio.

svcutil is a command line tool that generates one or more code files (depending on the language stated) and a .config file with the appropriate configuration for the web service invocation.

An example of command line for the generation of SealSign BSS proxy classes would be as follows:

svcutil.exe /out:BiometricSignatureService.cs /config:BiometricSignatureService.config http://localhost/SealSignBSSService/BiometricSignatureService.svc /n:*,SealSignBSSService /n:http://schemas.datacontract.org/2004/07/SealSignDSSTypes,SealSignDSSTypes /n:http://schemas.datacontract.org/2004/07/SealSignBSSTypes,SealSignBSSTypes

In this example, svcutil.exe will generate two files: BiometricSignatureService.cs and Biometric SignatureService.config. The BiometricSignatureService.cs file will be incorporated to the .net project as just one more code file, and the contents of the BiometricSignatureService.conf file will be added to the app.config file of the .net project.

2.2 Including the SealSignBSSClientLibrary Client

The signature panel distinguishes between two types of devices, Wacom tablets and stylus-compatible devices. In order to add the signature panel, you must create a variable that implements the ISealSignBSSPanel interface, and create an instance by calling the GetSealSignBSSPanel method of the SealSignBSSPanelFactory class.

ISealSignBSSPanel _signaturePanel = SealSignBSSPanelFactory.GetSealSignBSSPanel();

That control is added to the UI, for example to a Grid:

RootGrid.Children.Add((UIElement)_signaturePanel);

2.3 Authentication of Calls to Web Services

Depending on the configuration and operations you wish to conduct, requests to the platform web services will be conducted with authentication. For example, a certificate enumeration operation must be performed with authentication from the client, so that the use of allowed certificates is secure.

For .Net applications, depending on the scenario in which they run, it may not be necessary to provide the credentials programmatically, since they can use the integrated authentication of the Windows platform.

2.3.1 Credentials Transfer for Basic Authentication The following example shows the connection to a SealSign web service, configured with basic authentication and providing credentials through .Net code:

SignatureServiceBasicClient service = new SignatureServiceBasicClient(); service.ClientCredentials.UserName.UserName = "SealSignTest"; service.ClientCredentials.UserName.Password = "Passw0rd"; CertificateReference[] certs = service.GetCertificateReferences(null, false); service.Close();




2.3.2 Credentials Transfer for Windows Authentication The following example shows the connection to a SealSign web service, configured with Windows authentication and providing credentials through .Net code:

SignatureServiceClient service = new SignatureServiceClient(); service.ClientCredentials.Windows.ClientCredential.Domain = "localhost"; service.ClientCredentials.Windows.ClientCredential.UserName = "SealSignTest"; service.ClientCredentials.Windows.ClientCredential.Password = "Passw0rd"; CertificateReference[] certificates = service.GetCertificateReferences(null, false); service.Close();




3 Use Cases

3.1 Remarks

To unify both the component used by Wacom tablets and the one used by inking, all functionality has been located in the same public interface, but there are some methods that the inking component will ignore, as its nature is different from the component for Wacom tablets. The guide will describe which functions are only valid for the component for Wacom tablets.

3.2 Biometric Signature

3.2.1 Including the handwritten signature capture panel Once the SealSignBSSClientLibrary.dll library has been added to Visual Studio, the next step is to add the capture panel. In order to do so, you need to have an instance of an object that implements the ISealSignBSSPanel interface:

ISealSignBSSPanel _signaturePanel;

You should also get an instance of the panel that you will be using. The component will detect if there is a Wacom tablet connected; in case there isn’t any, it will detect if the system supports input with stylus.

ISealSignBSSPanel _signaturePanel = SealSignBSSPanelFactory.GetSealSignBSSPanel();

If no valid input device is detected, the DeviceNotConnected event will be launched.

3.2.2 Event Log You may receive panel events adding delegates that implement the callback method of the event in question. Events included in these panels are:

ErrorCapture: There was an error during the tablet capture process.

ErrorDeviceNotConnected: There was an error indicating that there is no tablet connected.

private void sealSignBSSWacomSTUPanel1_ErrorCapture (object sender, EventArgs e) { } private void sealSignBSSWacomSTUPanel1_DeviceNotConnected (object sender, EventArgs e) { } …

_signaturePanel.ErrorCapture += sealSignBSSWacomSTUPanel1_OkButtonClickEvent; _signaturePanel.DeviceNotConnected += SealSignBSSWacomSTUPanel1_DeviceNotConnected;

3.2.3 Capture Background Image on the Tablet (only for Wacom tablets) The signature panel allows you to set a background BMP image on the tablet during the signature capture with the SetBackgroundImage method.




System.Drawing.Image image = System.Drawing.Image.FromFile(@"FILE PATH"); _signaturePanel.SetBackgroundImage(image);

3.2.4 Defining Buttons on the tablet (Wacom tablets only) Buttons on the tablet must be displayed in the image used as a background. With the next function, the number of buttons and their position are defined. That way, when you click with the pencil on those areas, the button is detected and the event is launched. The following snippet shows how to add two button definitions to the tablet:

_signaturePanel.ClearButtonArea(); _signaturePanel.SetButtonArea("Firmar", 0, 0, 100, 50); _signaturePanel.SetButtonArea("Borrar", 0, 60, 100, 50); _signaturePanel.AddEventListener(this);

The AddEventListener is a method used to subscribe to events receiving an object that implements the ISealSignBSSEventListener interface. Among the methods that must be implemented, there is ButtonClick, which will be called by clicking on any of the above defined buttons. It receives the clicked button as a parameter.

3.2.5 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 property TransparentSignature can be used:

_signaturePanel.TransparentSignature = true;

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

_signaturePanel.Start();

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

_signaturePanel.Stop();

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

_signaturePanel.CleanSignature();

3.2.9 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/BiometricSignatureService.svc.

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

BiometricSignatureServiceClient service = new BiometricSignatureServiceClient(); byte[] biometricState = null; FileStream stream = new FileStream(@"c:\samples\sample.pdf", FileMode.Open); BiometricSignatureParameters biometricParameters = new BiometricSignatureParameters(); biometricParameters.imageParameters = new BiometricImageParameters(); biometricParameters.imageParameters.signatureVisible = true; biometricParameters.imageParameters.onAllPages = true; biometricParameters.imageParameters.offsetX = 370; biometricParameters.imageParameters.offsetY = 220; biometricParameters.imageParameters.height = 80; biometricParameters.imageParameters.width = 100; string instance = service.BeginSignature(SignatureProfile.PDF, BiometricSignatureType.Default, "", "", BiometricSignatureFlags.Default, biometricParameters, SignatureFlags.Default, null, null, stream, out biometricState);

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

// Client encryption with SealSignBSSClientLibrary byte[] biometricFinalState = _signaturePanel.GetSignature(new Guid(instance), biometricState);

3.2.11 Ending the Signature The ending of the signature is notified to the platform and the final document is obtained. The used service is /SealSignBSSService/BiometricSignatureService.svc.

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

// EndSignature

Stream signedStream = service.EndSignature(instance, biometricFinalState); FileStream outputStream = new FileStream(@"c:\samples\sample.pdf.bio.signed.pdf", FileMode.Create, FileAccess.ReadWrite); byte[] buffer = new byte[16 * 1024]; int read; while ((read = signedStream.Read(buffer, 0, buffer.Length)) > 0)








{ outputStream.Write(buffer, 0, read);

} outputStream.Flush(); outputStream.Close(); signedStream.Close();

service.Close();

3.3 Verifying Signed Documents

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


BiometricSignatureServiceClient service = new BiometricSignatureServiceClient(); byte[] biometricState = null; FileStream stream = new FileStream(@"c:\samples\sample.pdf.bio.signed.pdf", FileMode.Open); byte[] biometricFinalState = _signaturePanel.GetSignature(new Guid("00000000-0000-0000-0000-000000000000"), biometricState); if (biometricFinalState != null) {

BiometricSignatureVerification verifyResponse = service.Verify( SignatureProfile.PDF, BiometricSignatureType.Default, "", "", BiometricVerificationFlags.Default, null, biometricFinalState, null, stream);

stream.Close(); } service.Close();

3.4 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.4.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[] document = File.ReadAllBytes(@"c:\samples\sample.pdf");






Guid instance = new Guid(); // Client encryption with SealSignBSSClientLibrary byte[] biometricFinalState = sealSignBSSWacomSTUPanel1.getOfflineSignature(document, out instance);

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

OfflineBiometricSignature[] offlineSignature = new OfflineBiometricSignature[1]; BiometricSignatureParameters biometricParameters = new BiometricSignatureParameters(); biometricParameters.imageParameters = new BiometricImageParameters(); biometricParameters.imageParameters.signatureVisible = true; biometricParameters.imageParameters.onAllPages = true; biometricParameters.imageParameters.offsetX = 370; biometricParameters.imageParameters.offsetY = 220; biometricParameters.imageParameters.height = 80; biometricParameters.imageParameters.width = 100; offlineSignature[0] = new OfflineBiometricSignature(); offlineSignature[0].id = ""; offlineSignature[0].account = ""; offlineSignature[0].biometricOptions = BiometricSignatureFlags.Default; offlineSignature[0].biometricParameters = biometricParameters; offlineSignature[0].options = SignatureFlags.Default; offlineSignature[0].instance = instance.ToString(); offlineSignature[0].offlineBiometricState = biometricFinalState; BiometricSignatureServiceClient service = new BiometricSignatureServiceClient(); MemoryStream stream = new MemoryStream(document); Stream signedStream = service.SyncOfflineSignatures(SignatureProfile.PDF, offlineSignature, null, stream); FileStream outputStream = new FileStream(@"c:\samples\sample.pdf.bio.signed.pdf", FileMode.Create, FileAccess.ReadWrite); byte[] buffer = new byte[16 * 1024]; int read; while ((read = signedStream.Read(buffer, 0, buffer.Length)) > 0) {

outputStream.Write(buffer, 0, read); } outputStream.Flush(); outputStream.Close(); signedStream.Close(); service.Close();

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


BiometricSignatureServiceBasicClient service = new BiometricSignatureServiceBasicClient(); BiometricSignatureBeginResponseBasic response = service.BeginSignatureProvider( "", "", @"demo://c:\samples\sample.pdf", null, null);

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

// Client encryption with SealSignBSSClientLibrary byte[] biometricFinalState = sealSignBSSWacomSTUPanel1.GetSignature(response.instance, response.biometricState);

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

if (biometricFinalState != null) {

service.EndSignatureProvider(response.instance, biometricFinalState, @"demo://c:\samples\sample.pdf", null, false); } service.Close();

3.6 Document Providers Development

As mentioned in the previous section, there is a possibility of signing documents that are not located on the client but on a documentary Backend on the server part. To use this feature, you need to develop and register a type of add-ins, called document providers, which will manage the access to the document repository of the server part.

A document provider is an assembly developed in any .Net language and that implements the SealSignBSSFrontend.IDocumentProvider interface. The description of the interface and the document providers registration on the platform can be found in the “SealSign BSS - Web Services Reference” document.

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








3.6.1 Including SealSignBSSTypes and SealSignDSSTypes The definition of the SealSignBSSFrontend.IDocumentProvider interface is located within the SealSignBSSTypes.dll assembly. Therefore, you will need to include the reference to SealSignBSSTypes.dll in the .Net project of the new document provider.

In addition, some of the classes used in this interface are defined in the library of electronic signature types definition (SealSignDSSTypes.dll). The inclusion of a reference to this assembly in the project will also be required.

3.6.2 Interface Implementation Once the reference has been added to the SealSignBSSTypes.dll and SealSignDSSTypes.dll, you must create a class with public access that implements the SealSignBSSFrontend.IDocumentProvider interface. using SealSignBSSFrontend; public class PDFTestProvider : IDocumentProvider { . . .

3.6.3 Getting the Document and the Signature Parameters The first IDocumentProvider interface method is the method to get the document and signature parameters that will be applied in the operation (GetSigningDocument). With the input parameters specified from the signature client (uri and providerParameter), the document provider must access the document repository, obtain the document to be signed and return both the document and the signature parameters that will be applied.

The following example shows the code of a document provider that accesses the server file system and gets the document specified in the uri that was specified from the client application:

public Stream GetSigningDocument(string uri,

string providerParameter,

out SignatureProfile signatureProfile,

out BiometricSignatureType biometricSignatureType,

out BiometricSignatureFlags biometricOptions,

out BiometricSignatureParameters biometricParameters,

out SignatureFlags options,

out SignatureParameters parameters,

out byte[] detachedSignature)

{

// Signature parameters specification

signatureProfile = SignatureProfile.PDF;

biometricSignatureType = BiometricSignatureType.Default;

biometricOptions = BiometricSignatureFlags.Default;

biometricParameters = null;

options = SignatureFlags.Default;

parameters = null;

detachedSignature = null;

biometricParameters = new BiometricSignatureParameters();

biometricParameters.imageParameters = new BiometricImageParameters();

biometricParameters.imageParameters.signatureVisible = true;




biometricParameters.imageParameters.onAllPages = true;

biometricParameters.imageParameters.offsetX = 370;

biometricParameters.imageParameters.offsetY = 220;

biometricParameters.imageParameters.height = 80;

biometricParameters.imageParameters.width = 100;

// Getting document using uri parameter

Uri documentUri = new Uri(uri);

return new FileStream(documentUri.LocalPath, FileMode.Open, FileAccess.Read);

}

3.6.4 Storing the Signed Document The second IDocumentProvider interface method is the method for storing the document once the signature operation has been performed (SetSignedDocument). With the input parameters specified from the signature client (uri and providerParameter), the document provider will be able to access the document repository to store the document once it has been signed.

The following example shows the code of a document provider that accesses the server file system and stores the document from the uri that was specified from the client application:

public void SetSignedDocument(string uri, string providerParameter, Stream document) { // Storing signed document using uri parameter

Uri documentUri = new Uri(uri); FileStream outputStream = new FileStream(documentUri.LocalPath+".bio.signed.pdf",

FileMode.Create, FileAccess.ReadWrite); byte[] buffer = new byte[16 * 1024];

int read; while ((read = document.Read(buffer, 0, buffer.Length)) > 0) {

outputStream.Write(buffer, 0, read); } outputStream.Flush(); outputStream.Close();

document.Close();

}




4 Resources

For information about the different SealSign services available, please go to this address:

https://www.elevenpaths.com/technology/sealsign/index.html

Also, on the ElevenPaths blog you can find interesting articles and innovations regarding this product.

You can find more information about Eleven Paths products on YouTube, on Vimeo and on Slideshare.

https://www.elevenpaths.com/technology/sealsign/index.html

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 .net applications

Technology