integración de sealsign dss en aplicaciones windows 10

[email protected]

elevenpaths.com

Guía de Integración de SealSign DSS (Digital Signature Services) en Aplicaciones Windows 10

ElevenPaths, innovación radical y disruptiva en seguridad

Guía de integración de SealSign DSS (Digital Signature Services) en Aplicaciones Windows 10

V.3.2 – Octubre 2016

2016 © Telefónica Digital España, S.L.U. Todos los derechos reservados. Página 2 de 16

Contenidos

1 Introducción ............................................................................................................... 3

2 Tareas comunes .......................................................................................................... 4

2.1 Inclusión de Referencias de Servicios Web .............................................................................. 4

2.2 Inclusión del Cliente SealSignDSSClientLibrary ......................................................................... 5

2.3 Autenticación de llamadas a servicios web .............................................................................. 6

2.3.1 Paso de credenciales para una autenticación básica ................................................................. 7

2.3.2 Paso de credenciales para una autenticación Windows ............................................................ 7

3 Casos de uso ............................................................................................................... 8

3.1 Enumeración de Certificados del Usuario ................................................................................ 8

3.2 Verificación de Certificados ...................................................................................................... 8

3.3 Firma con Certificado en el Servidor ........................................................................................ 9

3.4 Firma con Certificado en el Cliente......................................................................................... 10

3.4.1 Enumeración de Certificados ................................................................................................... 10

3.4.2 Inicio de Firma .......................................................................................................................... 10

3.4.3 Criptografía en Cliente.............................................................................................................. 11

3.4.4 Fin de Firma .............................................................................................................................. 11

3.5 Firma con document provider (Documento en el Servidor) .................................................. 11

3.5.1 Enumeración de Certificados ................................................................................................... 11

3.5.2 Inicio de la Firma ...................................................................................................................... 12

3.5.3 Criptografía en Cliente.............................................................................................................. 12

3.5.4 Fin de la Firma .......................................................................................................................... 12

3.6 Desarrollo de document providers ......................................................................................... 12

3.6.1 Inclusión de SealSignDSSTypes ................................................................................................. 12

3.6.2 Implementación del interfaz .................................................................................................... 13

3.6.3 Obtención del documento y de los parámetros de firma ........................................................ 13

3.6.4 Almacenamiento del documento firmado ............................................................................... 13

4 Recursos .................................................................................................................... 15




1 Introducción

SealSign DSS es un producto desarrollado por ElevenPaths, dirigido a facilitar la integración de la firma electrónica en las aplicaciones corporativas. SealSign DSS expone su funcionalidad a través de Servicios Web basados en la tecnología WCF (Windows Communication Framework). Estos servicios pueden ser invocados por aplicaciones implementadas sobre la mayoría de las tecnologías del mercado.

Este documento no pretende ser un manual sobre los aspectos concretos de la firma electrónica sino un manual de referencia técnica, orientado al desarrollador, sobre cómo integrar SealSign DSS en Aplicaciones para Windows 10.




2 Tareas comunes

2.1 Inclusión de Referencias de Servicios Web

Para interactuar con la plataforma servidora se hace uso de la capa de servicios Web. El documento “SealSign DSS - Referencia de Servicios Web” detalla cada servicio y sus parámetros. En este apartado se muestra, a modo de ejemplo, cómo incluir la referencia a un servicio web de la plataforma usando Visual Studio 2015, pero es posible utilizar cualquier otro método de invocación como la generación de clases proxy con utilidades como svcutil.exe.

Para añadir la referencia a un servicio web es necesario pulsar con el botón derecho del ratón sobre el proyecto .NET, seleccionar la opción Add y después Service Reference…

Imagen 01: Menú añadir referencia de servicio.

Aparecerá la ventana asistente para añadir la referencia del servicio web:

Imagen 02: Ventana asistente para añadir referencia de servicio.

http://es.slideshare.net/elevenpaths/referencia-de-servicios-web-en-sealsign-dss




En esta ventana hay que incluir la URL del servicio web, y, tras pulsar el botón Go, escribir un nombre para el Namespace (SignatureServiceReference en este caso) y pulsar el botón OK. La referencia se añadirá al proyecto y se mostrará en el panel Solution Explorer:

Imagen 03: Referencia de servicio web en Solution Explorer.

Otro método para la invocación de servicios web es la generación de clases proxy con utilidades como svcutil.exe, disponible tanto con el SDK de Microsoft Windows como con las diferentes versiones de Microsoft Visual Studio.

svcutil es una herramienta de línea de comandos que generará uno o varios ficheros de código (según el lenguaje indicado) y un fichero .config con la configuración adecuada para la invocación del web service.

Un ejemplo de línea de comandos para la generación de clases proxy de SealSign DSS sería el siguiente:

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

En este ejemplo, svcutil.exe generará dos ficheros: SignatureService.cs y SignatureService.config. El fichero SignatureService.cs se incorporará al proyecto .NET como un fichero de código más y el contenido del fichero SignatureService.conf se deberá añadir dentro del fichero app.config del proyecto .NET.

2.2 Inclusión del Cliente SealSignDSSClientLibrary

Para incluir las funciones de criptografía en el cliente de la plataforma, es necesario añadir la referencia a la librería SealSignDSSClientLibrary en el proyecto. Para ello hay que pulsar con el botón derecho del ratón sobre el proyecto .NET, seleccionar la opción Add y después Reference…




Imagen 04: Adición de la librería SealSignDSSClientLibrary.dll.

Tras esto aparecerá la ventana del administrador de referencia que permitirá seleccionar la librería SealSignDSSClientLibrary.dll:

Imagen 05: Visual Studio 2015 Reference Manager.

2.3 Autenticación de llamadas a servicios web

Dependiendo de la configuración y según las operaciones que se deseen realizar, las peticiones a los servicios web de la plataforma deberán realizarse de manera autenticada. Por ejemplo, una operación de enumeración de certificados debe realizarse de manera autenticada desde el cliente, de forma que se asegure el uso de certificados permitidos.

En el caso de aplicaciones .NET, según el escenario en el que estas se ejecuten, es posible que no sea necesario suministrar las credenciales programáticamente puesto que pueden hacer uso de la autenticación integrada de la propia plataforma Windows.




2.3.1 Paso de credenciales para una autenticación básica En el siguiente ejemplo se muestra la conexión a un servicio web de SealSign, configurado con autenticación básica y suministrando las credenciales mediante código .NET:

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

service.ClientCredentials.UserName.UserName = "SealSignTest";

service.ClientCredentials.UserName.Password = "Passw0rd";

var references = await service.GetCertificateReferencesAsync(null, false);

await service.CloseAsync();

2.3.2 Paso de credenciales para una autenticación Windows En el siguiente ejemplo se muestra la conexión a un servicio web de SealSign, configurado con autenticación Windows y suministrando las credenciales mediante código .NET:


service.ClientCredentials.Windows.ClientCredential.UserName = "SealSignTest";

service.ClientCredentials.Windows.ClientCredential.Password = "Passw0rd";


await service.CloseAsync();




3 Casos de uso

3.1 Enumeración de Certificados del Usuario

En el siguiente ejemplo se realiza la conexión al servicio y se obtiene un array de CertificateReference. Cada objeto contiene información relativa a cada certificado que el usuario puede utilizar. Los valores retornados y la sintaxis del método se pueden consultar en el documento “SealSign DSS - Referencia de Servicios Web”. El servicio consumido es el /SealSignDSSService/SignatureServiceBasic.svc:





foreach (CertificateReference reference in references)

{ ... } await service.CloseAsync();

3.2 Verificación de Certificados

Para comprobar la validez de un certificado se realiza una única llamada al método Validate. Los valores retornados y la sintaxis del método se pueden consultar en el documento “SealSign DSS - Referencia de Servicios Web”. El servicio usado es el /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);

CertificateServiceBasicClient service = new CertificateServiceBasicClient(CertificateServiceBasicClient.EndpointConfiguration.BasicHttpBinding_ICertificateServiceBasic2);

Pkcs12Store certificateStore = new Pkcs12Store(certificateStream.GetInputStreamAt(0).AsStreamForRead(), "1234".ToCharArray());

foreach (string alias in certificateStore.Aliases)

{ X509CertificateEntry certificate = certificateStore.GetCertificate(alias);

//Verify certificate

var validation = await service.ValidateAsync(new ValidateRequest(certificate.Certificate.GetEncoded(), DateTime.MinValue, 0));

// Show result

switch (validation.ValidateResult)

{ case 0: //X509ChainStatusFlags.NoError

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 Firma con Certificado en el Servidor

La firma con certificado y clave privada en el servidor (HSM, BBDD) se realiza con una sola llamada al servicio Web de firma, pasando el documento a firmar y los parámetros necesarios. El certificado con el que se firma se especifica mediante su ID en la plataforma. Los valores retornados y la sintaxis del método se pueden consultar en el documento “SealSign DSS - Referencia de Servicios Web”. El servicio consumido es el /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 certificates SignatureServiceBasicClient service = new SignatureServiceBasicClient(SignatureServiceBasicClient.EndpointConfiguration.BasicHttpBinding_ISignatureServiceBasic);




foreach (CertificateReference reference in references)

{ //Sign the document

var signedBytes = await service.SignAsync(reference.id,

SignatureServiceBasic.SignatureProfile.PDF,

SignatureServiceBasic.SignatureType.Default,

SignatureServiceBasic.HashAlgorithm.Default,

SignatureServiceBasic.SignatureFlags.Default,

null,

null,

null,

null,

documentBytes); //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.4 Firma con Certificado en el Cliente

Para firmar con un certificado cuya clave privada reside en el cliente, se realizan tres pasos:

1. Se notifica a la plataforma la parte pública del certificado que se va a utilizar y el documento a firmar.

2. Con los datos obtenidos del servidor (instancia y token de firma) se realiza la operación criptográfica mediante la librería cliente SealSignDSSClientLibrary.

3. Se notifica el resultado de la operación criptográfica a la plataforma para finalizar la operación de firma y componer el documento final.

El servicio consumido es el /SealSignDSSService/SignatureServiceBasic.svc.

3.4.1 Enumeración de Certificados Para enumerar los certificados disponibles se utilizan los recursos habituales del entorno, de forma independiente a la plataforma SealSign:

//Load certificate from PFX var certificateFile = await assetsFolder.GetFileAsync("certificate.pfx");

var certificateStream = await certificateFile.OpenReadAsync();


3.4.2 Inicio de Firma Se notifica el inicio de firma a la plataforma servidora mediante la llamada al método BeginSignature. Los valores retornados y la sintaxis del método se pueden consultar en el documento “SealSign DSS - Referencia de Servicios Web”:

foreach (string alias in certificateStore.Aliases)

{ if (certificateStore.IsKeyEntry(alias))

{ X509CertificateEntry certificate = certificateStore.GetCertificate(alias);

AsymmetricKeyEntry key = certificateStore.GetKey(alias);

//Read source file

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); //Begin signature

DistributedSignatureServiceBasicClient service = new DistributedSignatureServiceBasicClient(DistributedSignatureServiceBasicClient.EndpointConfiguration.BasicHttpBinding_IDistributedSignatureServiceBasic2);






var beginSignatureResult = await service.BeginSignatureAsync(

certificate.Certificate.GetEncoded(), DistributedSignatureServiceBasic.SignatureProfile.PDF,

DistributedSignatureServiceBasic.SignatureType.Default,

DistributedSignatureServiceBasic.HashAlgorithm.Default,

DistributedSignatureServiceBasic.SignatureFlags.Default,

null,

null,

documentBytes);

3.4.3 Criptografía en Cliente Mediante la llamada al componente AsyncStateManager se realiza la operación criptográfica con la clave privada del certificado elegido previamente:

//Client encryption with SealSignDSSClientLibrary AsyncStateManager manager = new AsyncStateManager(beginSignatureResult.asyncState);

beginSignatureResult.asyncState = manager.doFinal(key.Key);

3.4.4 Fin de Firma Se notifica a la plataforma el fin de la firma y se obtiene el documento final. Los valores retornados y la sintaxis del método se pueden consultar en el documento “SealSign DSS - Referencia de Servicios Web”:

//End signature and get signed bytes var signedBytes = await service.EndSignatureAsync(beginSignatureResult.instance, beginSignatureResult.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 Firma con document provider (Documento en el Servidor)

El procedimiento de firma contra la plataforma usando un document provider es similar al de firma con certificado en el cliente, con la diferencia de que el documento no tiene por qué estar en el cliente. En su lugar, se especifica una URI que el document provider utilizará para obtener el documento de un Backend documental en la parte servidora. El servicio web consumido es el /SealSignDSSService/ SignatureServiceBasic.svc

3.5.1 Enumeración de Certificados Para enumerar los certificados disponibles se utilizan los recursos habituales del entorno, de forma independiente a la plataforma SealSign:

//Load certificate from PFX var certificateFile = await assetsFolder.GetFileAsync("certificate.pfx");

var certificateStream = await certificateFile.OpenReadAsync();







3.5.2 Inicio de la Firma Se notifica el inicio de firma a la plataforma servidora mediante la llamada al método BeginSignatureProvider. Los valores retornados y la sintaxis del método se pueden consultar en el documento “SealSign DSS - Referencia de Servicios Web”:

//BeginSignature var beginSignatureResponse = await service.BeginSignatureProviderAsync(

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

null,

null);

3.5.3 Criptografía en Cliente Mediante la llamada al componente AsyncStateManager se realiza la operación criptográfica con la clave privada del certificado elegido previamente:

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

beginSignatureResponse.asyncState = manager.doFinal(key.Key);

3.5.4 Fin de la Firma Se utiliza para notificar a la plataforma el fin de la firma. Los valores retornados y la sintaxis del método se pueden consultar en el documento “SealSign DSS - Referencia de Servicios Web”:

// End Signature var signedBytes = await service.EndSignatureProviderAsync(

beginSignatureResponse.instance, beginSignatureResponse.asyncState, "demo://d:\\test\\sample.pdf",

null,

true);

3.6 Desarrollo de document providers

Tal y como se comentaba en el apartado anterior, existe la posibilidad de realizar la firma de documentos que no residan en el cliente sino en un Backend documental en la parte servidora. Para el uso de esta funcionalidad, es necesario desarrollar y registrar un tipo de add-ins, denominados document providers, que serán los encargados del acceso al repositorio documental de la parte servidora.

Un document provider es un ensamblado (assembly) desarrollado en cualquier lenguaje .NET y que implementa el interfaz IDocumentProvider. La descripción del interfaz y el registro de document providers en la plataforma se pueden consultar en el documento “SealSign DSS - Referencia de Servicios Web”.

3.6.1 Inclusión de SealSignDSSTypes La definición del interface IDocumentProvider se encuentra dentro del ensamblado SealSignDSSTypes.dll. Es, por tanto, necesario incluir la referencia a SealSignDSSTypes.dll en el proyecto .NET del nuevo document provider. Para añadir la referencia a esta librería, se pueden seguir los mismos pasos indicados en el apartado Inclusión del cliente SealSignDSSClientLibrary de este mismo documento.








3.6.2 Implementación del interfaz Una vez añadida la referencia a SealSignDSSTypes.dll, se deberá crear una clase con acceso público que implemente el interfaz IDocumentProvider.

public class PDFTestProvider : IDocumentProvider { . . .

3.6.3 Obtención del documento y de los parámetros de firma El primer método del interfaz IDocumentProvider es el método de obtención del documento y los parámetros de firma que se aplicarán en la operación (GetSigningDocument). Con los parámetros de entrada especificados desde el cliente de firma (uri y providerParameter), el document provider deberá acceder al repositorio documental, obtener el documento que va a ser firmado y retornar tanto el documento como los parámetros de firma que se aplicarán.

El siguiente ejemplo muestra el código de un document provider que accede al sistema de ficheros del servidor y obtiene el documento especificado en la uri que se indicó desde la aplicación cliente:

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);

}

3.6.4 Almacenamiento del documento firmado El segundo método del interfaz IDocumentProvider es el método de almacenamiento del documento, una vez realizada la operación de firma (SetSignedDocument). Con los parámetros de entrada especificados desde el cliente de firma (uri y providerParameter), el document provider podrá acceder al repositorio documental para almacenar el documento tras haber sido firmado.

El siguiente ejemplo muestra el código de un document provider que accede al sistema de ficheros del servidor y almacena el documento a partir de la uri que se especificó desde la aplicación cliente:

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 Recursos

Para información acerca de los distintos servicios de SealSign puede accederse a esta dirección: https://www.elevenpaths.com/es/tecnologia/sealsign/index.html

Además en el blog de ElevenPaths es posible encontrar artículos interesantes y novedades acerca de este producto.

Puede encontrarse más información acerca de los productos de Eleven Paths en YouTube, en Vimeo y en Slideshare.

https://www.elevenpaths.com/es/tecnologia/sealsign/index.html

http://blog.elevenpaths.com/

https://www.youtube.com/user/ElevenPaths

http://vimeo.com/elevenpaths

http://www.slideshare.net/elevenpaths/




La información contenida en el presente documento es propiedad de Telefónica Digital España, S.L.U. (“TDE”) y/o de cualquier otra entidad dentro del Grupo Telefónica o sus licenciantes. TDE y/o cualquier compañía del Grupo Telefónica o los licenciantes de TDE se reservan todos los derechos de propiedad industrial e intelectual (incluida cualquier patente o copyright) que se deriven o recaigan sobre este documento, incluidos los derechos de diseño, producción, reproducción, uso y venta del mismo, salvo en el supuesto de que dichos derechos sean expresamente conferidos a terceros por escrito. La información contenida en el presente documento podrá ser objeto de modificación en cualquier momento sin necesidad de previo aviso.

La información contenida en el presente documento no podrá ser ni parcial ni totalmente copiada, distribuida, adaptada o reproducida en ningún soporte sin que medie el previo consentimiento por escrito por parte de TDE.

El presente documento tiene como único objetivo servir de soporte a su lector en el uso del producto o servicio descrito en el mismo. El lector se compromete y queda obligado a usar la información contenida en el mismo para su propio uso y no para ningún otro.

TDE no será responsable de ninguna pérdida o daño que se derive del uso de la información contenida en el presente documento o de cualquier error u omisión del documento o por el uso incorrecto del servicio o producto. El uso del producto o servicio descrito en el presente documento se regulará de acuerdo con lo establecido en los términos y condiciones aceptados por el usuario del mismo para su uso.

TDE y sus marcas (así como cualquier marca perteneciente al Grupo Telefónica) son marcas registradas. TDE y sus filiales se reservan todo los derechos sobre las mismas.

PUBLICACIÓN:

Octubre 2016

En ElevenPaths pensamos de forma diferente cuando hablamos de seguridad. Liderados por Chema Alonso, somos un equipo de expertos con inquietud para replantearnos la industria y gran experiencia y conocimiento en el sector de la seguridad. Dedicamos toda nuestra experiencia y esfuerzos en crear productos innovadores para que la vida digital sea más segura para todos.

La evolución de las amenazas de seguridad en la tecnología es cada vez más rápida y constante. Por eso, desde junio de 2013, nos hemos constituido como una start-up dentro de Telefónica para trabajar de forma ágil y dinámica, y ser capaces de transformar el concepto de seguridad anticipándonos a los futuros problemas que afecten a nuestra identidad, privacidad y disponibilidad online.

Con sede en Madrid, estamos presentes también en Londres, EE.UU, Brasil, Argentina, y Colombia.

TIENES ALGO QUE CONTARNOS, PUEDES HACERLO EN:

elevenpaths.com Blog.elevenpaths.com @ElevenPaths Facebook.com/ElevenPaths YouTube.com/ElevenPaths

integración de sealsign dss en aplicaciones windows 10

Technology