SealSign DSS Integration Guide for Windows 8.1 Applications

[email protected]

elevenpaths.com

SealSign DSS (Digital Signature Services) Integration Guide for Windows 8.1 Applications

ElevenPaths, radical and disruptive innovation in security solutions


V.3.2 – October 2016

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

Table of content

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

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

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

2.2 Including the SealSignDSSClientLibrary Client .......................................................................... 5

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

2.3.1 Credentials Transfer for Basic Authentication............................................................................ 7

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

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

3.1 User Certificate Enumeration ................................................................................................... 8

3.2 Certificate Verification .............................................................................................................. 8

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

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

3.4.1 Certificate Enumeration ........................................................................................................... 10

3.4.2 Beginning the Signature ........................................................................................................... 10

3.4.3 Cryptography in Client .............................................................................................................. 11

3.4.4 Ending the Signature ................................................................................................................ 11

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

3.5.1 Certificate Enumeration ........................................................................................................... 12

3.5.2 Beginning the Signature ........................................................................................................... 12

3.5.3 Cryptography in Client .............................................................................................................. 12

3.5.4 End Signature ........................................................................................................................... 12

3.6 Document Providers Development ........................................................................................ 12

3.6.1 Including SealSignDSSTypes ..................................................................................................... 13

3.6.2 Interface Implementation ........................................................................................................ 13

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

3.6.4 Storing the Signed Document ................................................................................................... 14

4 Resources .................................................................................................................. 15




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 Windows 8.1 Applications.




2 Common Tasks

2.1 Including Web Service References

The Web services layer is used to interact with the server platform. The “SealSign DSS - Web Services Reference” document details each service and its parameters. 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…

Figure 01: Add Service Reference Menu

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

Figure 02: Wizard window to add a Service Reference

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





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

Figure 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 DSS proxy classes would be as follows:

svcutil.exe /out:SignatureService.cs /config:SignatureService.config http://localhost:8731/SealSignDSSService/SignatureServiceBasic.svc /n:*,SealSignDSSService /n:http://schemas.datacontract.org/2004/07/SealSignDSSTypes,SealSignDSSTypes

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

2.2 Including the SealSignDSSClientLibrary Client

In order to include cryptographic functions in the platform client, you need to add the reference to the SealSignDSSClientLibrary library in the project. To do so, just right-click on the .NET project, select the Add option and then Reference...




Figure 04: Adding the SealSignDSSClientLibrary.dll library.

Once you have done this, the reference manager window that will allow the selection of the SealSignDSSClientLibrary.dll library will be displayed:

Figure 05: Visual Studio 2013 Reference Manager.

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 = await service.GetCertificateReferencesAsync(null, false); await service.CloseAsync();

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[] certs = await service.GetCertificateReferencesAsync(null, false); await service.CloseAsync();




3 Use Cases

3.1 User Certificate Enumeration

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. The used service is /SealSignDSSService/SignatureServiceBasic.svc:

SignatureServiceBasicClient service = new SignatureServiceBasicClient( SignatureServiceBasicClient.EndpointConfiguration.BasicHttpBinding_ISignatureServiceBasic2);

var references = await service.GetCertificateReferencesAsync(null, false); foreach (CertificateReference reference in references) { ... } await service.CloseAsync();

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:

// Load certificate StorageFolder assetsFolder = await Package.Current.InstalledLocation.GetFolderAsync("Assets"); StorageFile certificateFile = await assetsFolder.GetFileAsync("certificate.pfx"); IRandomAccessStream certificateStream = await certificateFile.OpenAsync(FileAccessMode.Read); Pkcs12Store certificateStore = new Pkcs12Store(

certificateStream.GetInputStreamAt(0).AsStreamForRead(), "1234".ToCharArray());

// Verify certificate CertificateServiceBasicClient service = new CertificateServiceBasicClient(

CertificateServiceBasicClient.EndpointConfiguration.BasicHttpBinding_ICertificateServiceBasic2

); foreach (string alias in certificateStore.Aliases) {

X509CertificateEntry certificate = certificateStore.GetCertificate(alias); var validation = await service.ValidateAsync(

new ValidateRequest( certificate.Certificate.GetEncoded(), DateTime.MinValue, 0));

// Show result switch (validation.ValidateResult) {

case 0: //X509ChainStatusFlags.NoError



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




Result.Text = "Certificate is not revoked."; break;

case 4: //X509ChainStatusFlags.Revoked Result.Text = "Certificate is revoked."; break;

case 64: //X509ChainStatusFlags.RevocationStatusUnknown Result.Text = "Unable to get revocation status."; break;

case 16777216: //X509ChainStatusFlags.OfflineRevocation Result.Text = "The revocation server is not accesible."; break;

} } await service.CloseAsync();

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 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. The used service is /SealSignDSSService/SignatureServiceBasic.svc:

// Read source file StorageFolder assetsFolder = await Package.Current.InstalledLocation.GetFolderAsync("Assets"); StorageFile documentFile = await assetsFolder.GetFileAsync("sample.pdf"); IRandomAccessStream documentStream = await documentFile.OpenAsync(FileAccessMode.Read); DataReader reader = new DataReader(documentStream.GetInputStreamAt(0)); await reader.LoadAsync((uint)documentStream.Size); byte[] documentBytes = new byte[documentStream.Size]; reader.ReadBytes(documentBytes); // Get certificate references array SignatureServiceBasicClient service = new SignatureServiceBasicClient(

SignatureServiceBasicClient.EndpointConfiguration.BasicHttpBinding_ISignatureServiceBasic2); var references = await service.GetCertificateReferencesAsync(null, false); foreach (CertificateReference reference in references) {

var signedBytes = await service.SignAsync(reference.id, SealSignDSSClientLibrary.SignatureServiceBasic.SignatureProfile.PDF, SealSignDSSClientLibrary.SignatureServiceBasic.SignatureType.Default, SealSignDSSClientLibrary.SignatureServiceBasic.HashAlgorithm.Default, SealSignDSSClientLibrary.SignatureServiceBasic.SignatureFlags.Default, null, null, null, null, documentBytes);

StorageFolder localFolder = ApplicationData.Current.LocalFolder;

StorageFile signedDocument = await localFolder.CreateFileAsync(

"sample.signed.pdf",






CreationCollisionOption.ReplaceExisting);

using (Stream signedStream = await signedDocument.OpenStreamForWriteAsync()) {

signedStream.Write(signedBytes, 0, signedBytes.Length); }

} await service.CloseAsync();

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.

The used service is /SealSignDSSService/SignatureServiceBasic.svc.

3.4.1 Certificate Enumeration Regular resources of the environment are used to enumerate the certificates available, independently of the SealSign platform:

// Load certificate from PFX X509Certificate2 cert = new X509Certificate2(@"C:\Samples\UserCertificate.pfx", "1234");

3.4.2 Beginning the Signature The beginning of the signature is notified to the server platform by calling the BeginSignature method. The returned values and syntax of the method can be found in the “SealSign DSS - Web Services Reference” document:

// Read source file var assetsFolder = await Package.Current.InstalledLocation.GetFolderAsync("Assets"); var certificateFile = await assetsFolder.GetFileAsync("certificate.pfx"); var certificateStream = await certificateFile.OpenReadAsync(); Pkcs12Store certificateStore = new Pkcs12Store(


StorageFile documentFile = await assetsFolder.GetFileAsync("sample.pdf"); IRandomAccessStream documentStream = await documentFile.OpenAsync(FileAccessMode.Read); DataReader reader = new DataReader(documentStream.GetInputStreamAt(0)); await reader.LoadAsync((uint)documentStream.Size); byte[] documentBytes = new byte[documentStream.Size]; reader.ReadBytes(documentBytes); DistributedSignatureServiceBasicClient service = new DistributedSignatureServiceBasicClient(






DistributedSignatureServiceBasicClient.EndpointConfiguration.BasicHttpBinding_IDistributedSignatureServiceBasic2); foreach (string alias in certificateStore.Aliases) {

if (certificateStore.IsKeyEntry(alias)) {

X509CertificateEntry certificate = certificateStore.GetCertificate(alias); AsymmetricKeyEntry key = certificateStore.GetKey(alias);

// BeginSignature

var beginSignatureResult = await service.BeginSignatureAsync( certificate.Certificate.GetEncoded(), SealSignDSSClientLibrary.DistributedSignatureServiceBasic.SignatureProfile.PDF, SealSignDSSClientLibrary.DistributedSignatureServiceBasic.SignatureType.Default, SealSignDSSClientLibrary.DistributedSignatureServiceBasic.HashAlgorithm.Default, SealSignDSSClientLibrary.DistributedSignatureServiceBasic.SignatureFlags.Default, null, null, documentBytes);

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

// Client encryption with SealSignDSSClientLibrary AsyncStateManager manager = new AsyncStateManager(beginSignatureResult.asyncState); var asyncState = manager.doFinal(key.Key);

3.4.4 Ending the Signature The end of the signature is notified to the platform and the final document is obtained. The returned values and syntax of the method can be found in the “SealSign DSS - Web Services Reference” document:

// EndSignature and get signed document var signedBytes = await service.EndSignatureAsync(beginSignatureResult.instance, asyncState); // Write signed file StorageFolder localFolder = ApplicationData.Current.LocalFolder; StorageFile signedDocument = await localFolder.CreateFileAsync(

"sample.signed.pdf", CreationCollisionOption.ReplaceExisting);

using (Stream signedStream = await signedDocument.OpenStreamForWriteAsync()) {

signedStream.Write(signedBytes, 0, signedBytes.Length); } } await service.CloseAsync();

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. The used service is /SealSignDSSService/SignatureServiceBasic.svc

3.5.1 Certificate Enumeration Regular resources of the environment are used to enumerate the certificates available, independently of the SealSign platform:

var assetsFolder = await Package.Current.InstalledLocation.GetFolderAsync("Assets"); // Load certificate from PFX var certificateFile = await assetsFolder.GetFileAsync("certificate.pfx"); var certificateStream = await certificateFile.OpenReadAsync(); Pkcs12Store certificateStore = new kcs12Store(


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:

DistributedSignatureServiceBasicClient service = new DistributedSignatureServiceBasicClient(

DistributedSignatureServiceBasicClient.EndpointConfiguration.BasicHttpBinding_IDistributedSignatureServiceBasic2); // BeginSignatureProvider var beginSignatureResponse = await service.BeginSignatureProviderAsync(

certificate.Certificate.GetEncoded(), "demo://d:\\test\\sample.pdf", null, null);

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

// Client encryption with SealSignDSSClientLibrary AsyncStateManager manager = new AsyncStateManager(beginSignatureResponse.asyncState); beginSignatureResponse.asyncState = manager.doFinal(key.Key);

3.5.4 End Signature It is used to notify the ending of the signature to the platform. The returned values and syntax of the method can be found in the “SealSign DSS - Web Services Reference” document:

// EndSignatureProvider

var signedBytes = await service.EndSignatureProviderAsync( beginSignatureResponse.instance, beginSignatureResponse.asyncState, "demo://d:\\test\\sample.pdf", null, true);

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 IDocumentProvider interface. The description of the interface and the document providers registration on the platform can be found in the “SealSign DSS - Web Services Reference” document.

3.6.1 Including SealSignDSSTypes The definition of the IDocumentProvider interface is located within the SealSignDSSTypes.dll assembly. Therefore, you will need to include the reference to SealSignDSSTypes.dll in the .NET project of the new document provider. In order to add the reference to this library, you can follow the same steps explained in the Including the SealSignDSSClientLibrary Client section of this document.

3.6.2 Interface Implementation Once the reference has been added to the SealSignDSSTypes.dll, you must create a class with public access that implements the IDocumentProvider interface.

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 SignatureType signatureType, out HashAlgorithm hashAlgorithm, out SignatureFlags options, out SignatureParameters parameters, out byte[] detachedSignature)

{ // Signature parameters specification signatureProfile = SignatureProfile.PDF; signatureType = SignatureType.Default; hashAlgorithm = HashAlgorithm.Default; options = SignatureFlags.Default; parameters = null; detachedSignature = null;

// Getting document using uri parameter

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

}

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




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 + ".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.

Technology

SealSign DSS Integration Guide for Windows 8.1 Applications