integración de sealsign dss en aplicaciones .net

ElevenPaths, innovación radical y disruptiva en seguridad

2015 © Telefonica Digital Identity & Privacy, S.L.U. All Rights Reserved. Página 2 de 15

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

3.4.1 Enumeración de Certificados ..................................................................................................... 9

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

3.4.3 Criptografía en Cliente.............................................................................................................. 10

3.4.4 Fin de Firma .............................................................................................................................. 10

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

3.5.1 Enumeración de Certificados ................................................................................................... 10

3.5.2 Inicio de la Firma ...................................................................................................................... 11

3.5.3 Criptografía en Cliente.............................................................................................................. 11

3.5.4 Fin de la Firma .......................................................................................................................... 11

3.6 Desarrollo de document providers ......................................................................................... 11

3.6.1 Inclusión de SealSignDSSTypes ................................................................................................. 11

3.6.2 Implementación del interfaz .................................................................................................... 12

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

3.6.4 Almacenamiento del documento firmado ............................................................................... 12

3.7 Verificación de documentos firmados .................................................................................... 13

4 Recursos .................................................................................................................... 14


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


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 2013, 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/SignatureService.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 2013 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(); service.ClientCredentials.UserName.UserName = "SealSignTest"; service.ClientCredentials.UserName.Password = "Passw0rd"; CertificateReference[] certs = service.GetCertificateReferences(null, false); service.Close();

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:

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 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/SignatureService.svc:

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); if (references != null && references.length > 0) { // Server certificate signing CertificateReference reference = references[0]; . . . } service.Close();

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 string certPath = "C:\\Samples\\UserCertificate.cer"; FileStream certStream = new FileStream(certPath, FileMode.Open, FileAccess.Read); certStream.Seek(0, SeekOrigin.Begin); // Verify certificate byte[] certificate = Tools.StreamToByteArray(certStream); int reason = 0; CertificateServiceBasicClient service = new CertificateServiceBasicClient(); X509ChainStatusFlags ret = (X509ChainStatusFlags)service.Validate(certificate,

DateTime.MinValue, ref reason);

// Show result switch (ret) {

case X509ChainStatusFlags.NoError: Console.WriteLine("Certificate is not revoked.");

break; case X509ChainStatusFlags.Revoked:

Console.WriteLine("Certificate is revoked."); break;

case X509ChainStatusFlags.RevocationStatusUnknown: Console.WriteLine("Unable to get revocation status."); break;

case X509ChainStatusFlags.OfflineRevocation: Console.WriteLine("The revocation server is not accesible."); break;

}

service.Close();






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/SignatureService.svc:

// Read source file string sourceDocument = "C:\\Samples\\sample.pdf"; FileStream documentStream = new FileStream(sourceDocument,

FileMode.Open, FileAccess.Read);

SignatureServiceClient service = new SignatureServiceClient(); // Get certificate references array CertificateReference[] certs = service.GetCertificateReferences(null, false); if (certs.GetLength(0) > 0) {

// Sign document using the first certificate Stream signedDocument = service.Sign(certs[0].id,

SignatureProfile.PDF, SignatureType.Enveloped, HashAlgorithm.Default, SignatureFlags.Default, null, null, null, null, documentStream);

// Write signed file Tools.WriteStreamToFile(signedDocument, sourceDocument + ".signed.pdf"); } service.Close();

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/SignatureService.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 X509Certificate2 cert = new X509Certificate2(@"C:\Samples\UserCertificate.pfx", "1234");



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

// Read source file string sourceDocument = "C:\\Samples\\sample.pdf"; FileStream documentStream = new FileStream(sourceDocument, FileMode.Open, FileAccess.Read); // BeginSignature DistributedSignatureServiceClient service = new DistributedSignatureServiceClient(); Byte[] asyncState = null; string instance = service.BeginSignature(cert.RawData,

SignatureProfile.PDF, SignatureType.Enveloped, HashAlgorithm.Default, SignatureFlags.Default, null, null, documentStream, out asyncState);

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 SealSignDSSClientLibrary.AsyncStateManager manager = new SealSignDSSClientLibrary.AsyncStateManager(asyncState); asyncState = manager.doFinal(cert);

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

// EndSignature and get signed document Stream signedStream = service.EndSignature(instance, asyncState); // Write signed file Tools.WriteStreamToFile(signedStream, "C:\\Samples\\sample.pdf.signed.pdf"); documentStream.Close(); service.Close();

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/ SignatureService.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 X509Certificate2 cert = new X509Certificate2(@"C:\Samples\UserCertificate.pfx", "1234");






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 DistributedSignatureServiceBasicClient service = new

DistributedSignatureServiceBasicClient(); DistributedSignatureBeginResponseBasic response =

service.BeginSignatureProvider(certificate.RawData, @"demo://c:\samples\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 SealSignDSSClientLibrary.AsyncStateManager manager = new SealSignDSSClientLibrary.AsyncStateManager(response.asyncState); response.asyncState = manager.doFinal(certificate);

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

// EndSignatureProvider service.EndSignatureProvider(response.instance,

response.asyncState, @"demo://c:\samples\sample.pdf", null, false);

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

}

3.7 Verificación de documentos firmados

Para verificar las firmas contenidas en un documento se realiza una única llamada al método Verify de la plataforma servidora. 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/SignatureService.svc:

// Signature verification string sourceDocument = "C:\\Samples\\sample.pdf.signed.pdf";

FileStream documentStream = new FileStream(sourceDocument, FileMode.Open, FileAccess.Read); SignatureServiceClient service = new SignatureServiceClient(); SignatureVerification docSignature = service.Verify(SignatureProfile.PDF, VerificationFlags.ValidateChain | VerificationFlags.CheckRevocationStatus, null, null, documentStream); // Document signature verification global state switch (docSignature.result) { case VerificationResult.Valid: Console.WriteLine("All document signatures are valid."); break; case VerificationResult.Invalid: Console.WriteLine("At lease one document signature are invalid."); break; case VerificationResult.IncompleteValidation: Console.WriteLine("Some document signatures couldn't be verified."); break; } // State and information of each signature existing on document Console.WriteLine("First level signatures information:"); foreach (SignatureReference signature in docSignature.signatures) { Console.WriteLine("Signature Id: " + signature.signatureID); Console.WriteLine("Signature Status: " + signature.signatureStatus); Console.WriteLine("Signature Profile: " + signature.signatureProfile); X509Certificate2 cert = new X509Certificate2(signature.signatureCertificate); Console.WriteLine("Signer certificate issuer name: " + cert.GetNameInfo(X509NameType.SimpleName, true)); Console.WriteLine("Signer certificate subject name: " + cert.GetNameInfo(X509NameType.SimpleName, false)); Console.WriteLine("Signature Type: " + signature.signatureType); Console.WriteLine("Signature Date: " + signature.signingTime.ToLongDateString()); Console.WriteLine("Signature Time: " + signature.signingTime.ToLongTimeString()); } documentStream.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 Identity & Privacy, S.L.U. (“TDI&P”) y/o de cualquier otra entidad dentro del Grupo Telefónica o sus licenciantes. TDI&P y/o cualquier compañía del Grupo Telefónica o los licenciantes de TDI&P 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 TDI&P.

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.

TDI&P 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.

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

PUBLICACIÓN:

Junio 2015

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

Technology

inicio de firma

fin de firma

enumeracin de certificados

verificacin de certificados

autenticacin de llamadas

autenticacin bsica

autenticacin windows

servicios web