Viafirma .NET Desktop Client · Viafirma .NET Desktop Client : Manual de Integración Página 7 de 30 referencias típicas de .Net Framework, se puede consultar el proyecto de ejemplo

Viafirma .NET Desktop Client

Manual de Integración

v1.2

ÍNDICE

ÍNDICE

1. INTRODUCCIÓN ................................................................................ 5

2. REQUISITOS .................................................................................... 5

3. INTEGRACIÓN .................................................................................. 5 3.1. Obtener la librería y el proyecto de ejemplo ........................................................... 6 3.2. Introducir viafirma-client-net-desktop.dll en el proyecto java de escritorio ..................... 6

3.2.1. Usando Visual Studio 2010 ........................................................................ 6 3.3. Instanciar el cliente .NET de viafirma para escritorio ................................................. 7

3.3.1. Definición de Proxy ................................................................................ 8 3.4. Usar el API .................................................................................................... 9

3.4.1. Obtención de Certificados de usuario ........................................................... 9 3.4.2. Uso de Firma Simple ............................................................................. 10 3.4.3. Uso de la Firma en Bucle ........................................................................ 13 3.4.4. Uso de la Firma en Lote en Cliente ........................................................... 14 3.4.5. Uso de la Firma en Lote en Servidor .......................................................... 15 3.4.6. Recuperar documentos originales de una firma en Lote ................................... 16 3.4.7. Uso de la Multifirma ............................................................................. 17

3.4.7.1. MultiFirma con Objeto policy ............................................................ 18

4. DESCRIPCIÓN DEL API ...................................................................... 20 4.1. Principales Métodos del API .............................................................................. 20

4.1.1. Lista de Certificados ............................................................................. 20 4.1.2. Métodos de Firma ................................................................................ 20 4.1.3. Documento Firmado ............................................................................. 20 4.1.4. Firma en Bucle .................................................................................... 21 4.1.5. Firma en Lote ..................................................................................... 21 4.1.6. Documento original .............................................................................. 21 4.1.7. Multifirma ......................................................................................... 22

4.2. Objeto Certificate ......................................................................................... 22 4.3. TypeFormatSign ............................................................................................ 24 4.4. Objeto Document .......................................................................................... 25 4.5. Objeto signedDocument .................................................................................. 25 4.6. Objeto genericUserViafirma ............................................................................. 26

ÍNDICE

4.7. Objeto Policy, PolicyUtil ................................................................................. 27 4.8. Clase PolicyParams ........................................................................................ 27 4.9. Manejo de Errores ......................................................................................... 28

CONTROL DE DOCUMENTO

CONTROL DE DOCUMENTO

Título: Viafirma .NET Desktop Client

Asunto: Manual de Integración

Versión: v1.2 Fecha: 14-06-2013

Código: Revisión anterior: 14-12-2012

Idioma: Núm. Páginas: 30

CONTROL DE CAMBIOS Y VERSIONES

Fecha Versión Motivo del Cambio

14-12-12 v.1.0 Primera versión

14-06-13 v.1.2

Revisión de nuevas funcionalidades incorporadas en la v1.2 del cliente .NET Desktop. Los cambios fueron:

• Punto 2 Requisitos

• Punto 3.3.1 Definición de Proxy

• Punto 3.4 Documentación del API en formato HTML

• Punto 3.4.7.1 Multifirma con Policy

• Punto 4 Uso del API

• Puntos 4.4 al 4.9

Página 5 de 30 Viafirma .NET Desktop Client : Manual de Integración

1. INTRODUCCIÓN

Desde la versión 3.5.3 de viafirma platform existe la posibilidad de hacer uso del API de

la plataforma desde aplicaciones .NET de escritorio, para este propósito existe un cliente

específico llamado ViafirmaClientNETDesktop, que aporta las herramientas necesarias

para realizar firmas de todos los formatos compatibles con viafirma platform.

La intención de este manual es proporcionar el conocimiento adecuado sobre cómo hacer

uso del cliente .NET de escritorio para viafirma platform desde una tercera aplicación.

2. REQUISITOS

Para la utilización de este cliente serán necesarios los requisitos que se describen en la siguiente tabla:

Requisitos

Sistema Operativo Windows XP, Vista o Seven

Viafirma Platform v3.5.5 y superior

Aplicación .NET de escritorio que necesite consumir el servicio de firma

3. INTEGRACIÓN

En los próximos puntos se explican los pasos necesarios para, desde cero, implementar la firma electrónica en cualquier proyecto .NET de escritorio, en resumen los pasos a dar serán:

1. Obtener las DLLs y el proyecto de ejemplo

2. Introducir la librería en el proyecto

3. Instanciar el cliente

4. Usar el API


3.1. Obtener la librería y el proyecto de ejemplo

El primer paso necesario para la integración de la firma electrónica con viafirma en una aplicación .NET de escritorio será obtener la librería necesaria que da acceso al API específico (llamada viafirma-client-net-desktop.dll) y el proyecto de ejemplo de ese API, estos recursos los podrás obtener de dos modos distintos:

1. Descargando el kit de desarrollo .Net para escritorio desde la pagina de desarrolladores de viafirma: http://developers.viafirma.com

2. Solicitar credenciales para la configuración del cliente (API KEY).

3.2. Introducir viafirma-client-net-desktop.dll en el proyecto java de escritorio

A continuación se describe cómo importar la librería en el IDE de desarrollo visual studio.

3.2.1. Usando Visual Studio 2010

Para poder utilizar viafirma en cualquier aplicación .Net de escritorio que necesite hacer uso de capacidades de firma, no hay más que obtener la librería viafirma-client-net-desktop.dll, en la forma indicada en el punto anterior (a través del portal de developers de viafirma), y añadirla al proyecto de Visual Studio 10 como se haría con cualquier otra ‘Referencia’.

Para agregar una Referencia hay que seguir los siguientes pasos, extraídos de la documentación web de Microsoft - http://msdn.microsoft.com/es-es/library/7314433t(v=vs.90).aspx

1. En el Explorador de soluciones, seleccione el proyecto.

2. En el menú Proyecto, haga clic en Agregar referencia.

3. Se abrirá el cuadro de diálogo Agregar referencia.

4. Seleccione la ficha que indique el tipo de componente al que desee hacer referencia.

5. En el panel superior, seleccione el componente al que desea hacer referencia y, a continuación, haga clic en el botón Aceptar. Presione CTRL haciendo clic para seleccionar varios componentes.

Nota: También será necesaria incluir la librería BouncyCastle.Crypto.dll la cual se podrá encontrar en el directorio /lib del proyecto de ejemplo. Además serán necesarias otras


referencias típicas de .Net Framework, se puede consultar el proyecto de ejemplo para comprobarlas.

3.3. Instanciar el cliente .NET de viafirma para escritorio

Una vez que tengas la librería viafirma-client-net-desktop.dll disponible en tu proyecto podrás comenzar a usar el API y lo primero que deberás hacer es instanciar el objeto que te permitirá usar el API de firma. Para ello no hay más que implementar el siguiente código (todo el código incluido en este manual ha sido extraído de la aplicación de ejemplo del cliente .Net de Viafirma para escritorio distribuido gratuitamente por viafirma):

//*******************************************// /* INICIALIZACIÓN CLIENTE */ //*******************************************// //Iniciamos el ViafirmaClientDesktop ViafirmaClientNetDesktop.ViafirmaClientDesktop client; try {

//Se inicia con la URL de VIAFIRMA y el api_key/api_pass ViafirmaClientDesktop.Init("http://testservices.viafirma.com/viafirma",

"xnoccio", "12345");

//Obtenemos la instancia del cliente client = ViafirmaClientDesktop.GetInstance();

} catch (InternalException e) { System.Console.WriteLine("Error iniciando cliente: " + e.MessageError + "

" + e.ToString()); }

Básicamente debes realizar una llamada a ViafirmaClientDesktop.Init(…) pasando los siguientes parámetros:

1. String URLViafirma: en este parámetro es necesario pasar la dirección URL donde se encuentra el servidor viafirma platform.

2. String apiKey: nombre de las credenciales proporcionadas por el equipo de Viafirma.

3. String passKey: pass de las credenciales proporcionadas por el equipo de viafirma.

Y una vez inicializado, simplemente hay que llamar al ViafirmaClientDesktop.GetInstance() para obtener la instancia de ViafirmaClientDesktop que contiene los métodos necesarios para realizar firmas electrónicas.


3.3.1. Definición de Proxy

Desde la versión 1.2 del SDK se habilita la posibilidad de inicializar el cliente indicándole la configuración del WebProxy a utilizar, la inicialización con proxy sin autenticación se haría del siguiente modo:

//Inicialización con Proxy SIN autenticación ViafirmaClientDesktop.Init("http://testservices.viafirma.com/viafirma", "<apiKey>", "<apiPass>", "http://<proxyHost>:<proxyPort>/", null, null);

Configuración proxy con autenticación:

//Inicialización con Proxy CON autenticación ViafirmaClientDesktop.Init("http://testservices.viafirma.com/viafirma", "<apiKey>", "<apiPass>", "http://<proxyHost>:<proxyPort>/", "<proxyUser>", "<proxyPass>");

También es posible inicializar el cliente sin indicar proxy y configurar el proxy en la aplicación cliente, esta configuración se haría del siguiente modo:

//Otro modo de definir un proxy System.Net.ServicePointManager.Expect100Continue = false; WebProxy proxy = new WebProxy(); proxy.Address = new System.Uri(@"<proxyHost>:<proxyPort>/"); proxy.UseDefaultCredentials = false; proxy.Credentials = new NetworkCredential("<proxyUser>", "<proxyPass>"); WebRequest.DefaultWebProxy = proxy;

De la configuración anterior cabe destacar la primera línea de código:

System.Net.ServicePointManager.Expect100Continue = false;

Esa línea puede no ser necesaria para todos los entornos, en algunos casos se ha comprobado que con esta propiedad a true el servidor proxy no respondía a las peticiones que se realizaban desde el cliente .Net.


3.4. Usar el API

Para explicar el uso del API se utilizará el código del proyecto ejemplo. Además se podrá ver la explicación de cada método.

3.4.1. Obtención de Certificados de usuario

En este punto se explica el código necesario para recuperar los Certificados disponibles para el usuario que se encuentren instalados en el Sistema.

Suponiendo que ya has inicializado el cliente y que, por tanto, disponemos de una instancia de la clase ViafirmaClientDesktop (en adelante el cliente de viafirma o, simplemente, el cliente) podrás comenzar a utilizar el API de viafirma. En el siguiente ejemplo de código se hace uso de este API para obtener los certificados de usuario disponibles en el sistema:

//Obtenemos la lista de certificados disponibles List<Certificate> certificates = client.GetClientCertificates(); Como se observa, únicamente es necesario llamar al método del cliente GetClientCertifficates() sin ningún parámetro, el propio cliente se encargará de acceder al almacén de certificados de usuario para recuperar todos los certificados disponibles y retornarlos como una lista de objetos ViafirmaClientNetDesktop.DesktopVO.Certificate.

La clase ViafirmaClientNetDesktop.DesktopVO.Certificate da acceso a una amplia información sobre el certificado, esta información podría servir además de para mostrar información al usuario sobre su certificado, para poder filtrarlos según los requerimientos que deseemos y tengamos disponibles. Un método de ejemplo de filtrado de certificados es el siguiente, el que se filtran según la Autoridad de certificación que lo expide:


public static List<Certificate> filterCerts(List<Certificate> certificates){

//Controlo que no esté vacía if(certificates==null){ System.Console.WriteLine("No se ha encontrado ningún certificado instalado"); return null; } List<Certificate> certsFNMT = new List<Certificate>(); //Filtro el cetificado (por ejemplo para quedarme solo los de FNMT) foreach (Certificate cert in certificates){ //Etiqueta para usar con certificados System.Console.WriteLine(cert.Label); if (cert.CA.Contains("FNMT"))

{ certsFNMT.Add(cert); }

} return certsFNMT; }

Este método recibe la lista de Certificate anteriormente recuperada.

Una vez obtenidos los certificados disponibles y filtrados, debería ser la aplicación la encargada de mostrarlos al usuario para que seleccione el que corresponda.

3.4.2. Uso de Firma Simple

En este punto se presupone que ya se ha inicializado el cliente y se ha seleccionado un certificado para realizar la firma. Una vez que se alcance este punto se puede proceder a ejecutar los métodos necesarios que realizarán el firmado. Para lo cual será necesario crear los objetos FileVO y Policy que definirán el modo en que debe realizarse el proceso de firma. Ejemplo de creación del FileVO y el Policy:

//Creamos FileVO FileVO documento = new FileVO(); documento.name = "test" + extension; documento.typeFile = typeFile; documento.typeFormatSign = typeFormatSign; documento.bytes = datosAFirmar; //Creamos Policy Policy policy = new Policy(); policy.typeFormatSign = typeFormatSign; policy.typeSign = TypeSign.ENVELOPED;


Los campos necesarios que debemos rellenar para obtener el FileVO válido son:

1. name: nombre del documento resultante.

2. typeFile: formato del fichero a firmar. Existe el enumerado TypeFile que incluye el listado de formatos de fichero disponibles.

3. typeFormatSign: formato de firma que se desea realizar. Existe el enumerado TypeFormatSign que incluye el listado de formatos de firma disponibles.

4. bytes: Byte array de los datos a firmar.

Y lo necesario para definir un Policy básico será:

1. Crear el objeto usando el constructor por defecto.

2. Asignarle el formato de firma (typeFormatSign) que se desee usando el método set correspondiente.

3. Y, por último, asignar el tipo de firma que se desea realizar mediante el enumerado TypeSign. Actualmente es recomendable usar el tipo Enveloped, para otros tipos es recomendable consultar su disponibilidad con el equipo de viafirma.

El objeto Policy permite definir otros parámetros útiles haciendo uso de OptionalRequest y/o PolicyParams, para estas operaciones recomendamos contactar con el soporte de viafirma para que puedan orientarle en su uso para el caso específico que se necesite.

Una vez definidos FileVO y Policy se puede llamar al método de firma que nos devolverá el idFirma en la plataforma.

String idFirma = null; try { //Pasamos el certificado elegido, la politica de firma y el documento idFirma = client.SignWithPolicy(cert, policy, documento); } catch (InternalException e) {

System.Console.WriteLine("Internal Server Exception" + e.MessageError + " " + e.ToString()); }catch (ViafirmaClientException e) {

System.Console.WriteLine("Client Side Exception: " + e.ToString()); } El método SignWithPolicy para realizar una firma simple recibe los siguientes parámetros:

1. Certificate: certificado con el que firmar.

2. Policy: política de firma de viafirma para especificar la configuración de firmado.

3. FileVO: especifica el documento a firmar y algo de metainformación propia y de la firma.

Este método podrá lanzar dos tipos de excepciones:

1. InternalException: Indica que se ha producido un error en el lado del servidor, además contiene información básica sobre el error producido.


2. ViafirmaClientException: Indica que la excepción se ha producido en el lado Cliente.

Si la firma ha funcionado correctamente devuelve el IdFirma por el que se reconoce esa operación en el servidor, ese IdFirma es el que se utiliza para obtener el documento firmado mediante el método GetSignedDocument(string idFirma). Ejemplo:

byte[] signedDocumentBytes; try { signedDocumentBytes = client.GetSignedDocument(idFirma).data; } catch (InternalException e) {

System.Console.WriteLine("Error al obtener el documento:" + e.ToString()); } El método devuelve un objeto SignedDocument que, además del documento firmado (data), contiene información útil sobre la firma realizada. Este método sirve para recuperar información dado cualquier idFirma de cualquier tipo de firma, solo en el caso de la firma en bucle debe tratarse con más cuidado ya que el método de firmado devuelve más de un idFirma en el mismo string, esto se explica en el siguiente punto.


3.4.3. Uso de la Firma en Bucle

La firma en bucle consiste en realizar una serie de firmas independientes en una sola operación, dando como resultado los ficheros firmados por separado. Básicamente, este modo de firma, permite realizar tareas de firma masiva con una única intervención del usuario. A continuación un ejemplo del uso de la firma en Bucle en el que se supone que disponemos de cliente correctamente inicializado y de certificado de suario seleccionado:

//Creamos Ficheros List<FileVO> documents = new List<FileVO>(); FileVO f1 = new FileVO(); f1.name ="test.pdf"; f1.bytes =datosPdf; f1.typeFile=TypeFile.PDF; documents.Add(f1); FileVO f2 = new FileVO(); f2.name = "test2.xml"; f2.bytes = datosXml; f2.typeFile = TypeFile.XML; documents.Add(f2); //Definimos Policy Policy policy = new Policy(); policy.typeFormatSign =TypeFormatSign.XADES_EPES_ENVELOPED; policy.typeSign = TypeSign.ENVELOPED; //Firmamos (el idFirma de una firma en bucle devuelve un string con varios ids separados por ;) String resultId; try { resultId = client.SignWithPolicy(cert, policy, documents); } catch (InternalException e1) {

System.Console.WriteLine("Error en SERVIDOR realizando la firma en BUCLE. Message: " + e1.MessageError + " " + e1.ToString()); } catch (ViafirmaClientException e1) {

System.Console.WriteLine("Error en CLIENTE realizando la firma en BUCLE: " + e1.MessageError + " " + e1.ToString()); } //Separamos los distintos ids de firma recuperados String[] individualsIds = resultId.Split(";".ToCharArray()); //Recorremos los ids foreach (String id in individualsIds) {

try { //Recuperamos cada documento signedDocument signedDocument = client.GetSignedDocument(id);

//Procesamos el documento firmado … Código de procesado del documento: custodia, envío a WS...

} catch (InternalException e) { System.Console.WriteLine("Error al obtener el documento: " + e.MessageError + " " + e.ToString()); } }


El método SignWithPolicy para realizar una firma en bucle recibe los siguientes parámetros:



3. List<FileVO>: especifica los documentos a firmar.

Este método devuelve un string que contiene varios idFirma separados el carácter de punto y coma (;). Si se desease recuperar los documentos firmados se deberá llamar al método GetSignedDocument(idFirma) una vez por cada id de firma recuperado, por ejemplo, para tres documentos, tres llamadas.

3.4.4. Uso de la Firma en Lote en Cliente

La firma en Lote permite firmar varios documentos con una sola operación, para ello se genera un ‘lote’ con todos los documentos enviados y se realiza una única firma de ese ‘lote’. Con este método se genera una sola firma para un número elevado de documentos. En este ejemplo la firma se realiza en el lado cliente usando el certificado que seleccionase el usuario.

//Creamos Ficheros List<FileVO> documents = new List<FileVO>(); FileVO f1 = new FileVO(); f1.name = "test.pdf"; f1.bytes=datosPdf; f1.typeFile=TypeFile.PDF; documents.Add(f1); FileVO f2 = new FileVO(); f2.name = "test2.xml"; f2.bytes = datosXml; f2.typeFile = TypeFile.XML; documents.Add(f2); //Definimos Policy Policy policy = new Policy(); policy.typeFormatSign = TypeFormatSign.XADES_EPES_ENVELOPED; policy.typeSign = TypeSign.ENVELOPED; //Firmamos String id; try { id = client.SignBatchWithPolicy(cert, policy, documents); } catch (InternalException e1) { System.Console.WriteLine("Error en SERVIDOR realizando la firma en LOTE en CLIENTE: " + e1.MessageError + " " + e1.ToString()); } catch (ViafirmaClientException e1) {

System.Console.WriteLine("Error en CLIENTE realizando la firma en LOTE en CLIENTE: " + e1.MessageError + " " + e1.ToString()); } //Recuperamos el documento try { signedDocument signedDoc = client.GetSignedDocument(id);



} catch (InternalException e) { System.Console.WriteLine("Error al obtener el documento: " + e.Message); }

El método SignBatchWithPolicy para realizar una firma en lote en el lado cliente recibe los siguientes parámetros:




Este método devuelve un string que contiene el idFirma. Si se desease recuperar el documento firmado resultante se deberá llamar al método GetSignedDocument(idFirma).

3.4.5. Uso de la Firma en Lote en Servidor

Igual que la anterior, pero realizando la firma en el servidor con un certificado previamente instalado en él.

//Creamos Ficheros List<FileVO> documents = new List<FileVO>(); FileVO f1 = new FileVO(); f1.name = "test.pdf"; f1.bytes = datosPdf; f1.typeFile = TypeFile.PDF; documents.Add(f1); FileVO f2 = new FileVO(); f2.name = "test2.xml"; f2.bytes = datosXml; f2.typeFile = TypeFile.XML; documents.Add(f2); //Definimos Policy Policy policy = new Policy(); policy.typeFormatSign=TypeFormatSign.XADES_EPES_ENVELOPED; policy.typeSign=TypeSign.ENVELOPED; //Reutilizamos Policy y documents de la firma anterior para hacer lo mismo pero en servidor String idServer; try { idServer = client.SignBatchByServerWithPolicy(policy, documents,"xnoccio","12345"); } catch (InternalException e1) {

System.Console.WriteLine("Error en SERVIDOR realizando la firma en LOTE en SERVIDOR: " + e1.MessageError + " " + e1.ToString()); } catch (ViafirmaClientException e1) {


System.Console.WriteLine("Error en CLIENTE realizando la firma en LOTE en SERVIDOR: " + e1.MessageError + " " + e1.ToString()); } //Recuperamos el documento try { signedDocument signedDoc = client.GetSignedDocument(idServer);


} catch (InternalException e) {

System.Console.WriteLine("Error al obtener el documento: " + e.MessageError + " " + e.ToString());

}

El método SignBatchByServerWithPolicy para realizar una firma en lote en el lado servidor recibe los siguientes parámetros:



3. String Alias: Alias con el que se ha instalado el certificado en el servidor.

4. String Password: Password con el que se ha instalado el certificado en el servidor.

Este método devuelve un string que contiene el idFirma. Si se desease recuperar el documento firmado resultante se deberá llamar al método GetSignedDocument(idFirma).

3.4.6. Recuperar documentos originales de una firma en Lote

Una vez realizada una firma el Lote puede ser necesario volver a recuperar alguno de los documentos originales que componían el Lote. Para ello será necesario, en primer lugar, pedir a viafirma los identificadores por los que conoce a esos documentos originales (utilizando para ello el identificador de firma obtenido al firmar el Lote), para después recuperar el que nos interese:

try { List<String> originalDocumentsIds= client.GetOriginalDocumentsIds(signId);

foreach (String idOriginal in originalDocumentsIds) { Document originalDocument = client.GetOriginalDocument(idOriginal);

} } catch (InternalException e1) { … }

Nota: El orden en el que devuelve los identificadores es aquel en el que se incluyeron en el lote.

Nota 2: El objeto Document se explica en puntos siguientes de este manual.


3.4.7. Uso de la Multifirma

La multifirma consiste en obtener un documento con múltiples firmantes.

Para este caso de uso viafirma permite realizar el proceso de un modo natural. Para agregar un nuevo firmante a un documento ya firmado, únicamente necesitamos enviar el documento firmado a ese nuevo firmante y que lo firme, será viafirma quien se encargue de introducir la nueva firma en el modo adecuado, independientemente de si estamos trabajando con un XAdES o PAdES o firmas binarias.

El único aspecto que habrá que tener en cuenta es que se mantenga el mismo formato para todas las firmas.

//Creamos Fichero FileVO document = new FileVO(); document.name = "test.pdf"; document.bytes = datosXml; document.typeFile = TypeFile.XML; //Definimos Policy Policy policy = new Policy(); policy.typeFormatSign=TypeFormatSign.XADES_EPES_ENVELOPED; policy.typeSign=TypeSign.ENVELOPED; //Realizamos un firma simple normal String id; try { id = client.SignWithPolicy(cert, policy, document); } catch (InternalException e1) {

System.Console.WriteLine("Error en SERVIDOR realizando la primera firma multifirma: " + e1.MessageError + " " + e1.ToString()); } catch (ViafirmaClientException e1) {

System.Console.WriteLine("Error en CLIENTE realizando la primera firma multifirma: " + e1.MessageError + " " + e1.ToString()); } //MULTIFIRMA: Suponemos que otro usuario con otro certificado quiere realizar una segunda firma en el documento, para lo cual realizamos otra firma simple normal sobre el documento ya firmado previamente //1.-‐ Obtenenmos el fichero previamente firmado signedDocument signedDoc; try {

signedDoc = client.GetSignedDocument(id); } catch (InternalException e2) {

System.Console.WriteLine("Error obteniendo el fichero con la primera firma: " + e2.MessageError); } //2.-‐ Creamos Policy como siempre y FileVO con el fichero recuperado //Creamos Fichero Policy policy2 = new Policy(); policy2.typeFormatSign=TypeFormatSign.XADES_EPES_ENVELOPED; policy2.typeSign=TypeSign.ENVELOPED; FileVO document2 = new FileVO(); document2.name = "test.xml";


document2.bytes = signedDoc.data; document2.typeFile = TypeFile.XML; //3.-‐Realizamos la firma normalmente (en este caso lo normal sería utilizar un certificado diferente, pero en este ejemplo se reutiliza el mismo) String id2; try { id2 = client.SignWithPolicy(cert, policy2, document2); } catch (InternalException e1) {

System.Console.WriteLine("Error en SERVIDOR realizando la segunda firma: " + e1.MessageError + " " + e1.ToString());

} catch (ViafirmaClientException e1) { System.Console.WriteLine("Error en CLIENTE realizando la segunda firma: " + e1.MessageError + " " + e1.ToString());

} //Recuperamos y procesamos el documento multifirmado signedDocument signedDocument2; try { signedDocument2 = client.GetSignedDocument(id2);


} catch (InternalException e2) { System.Console.WriteLine("Error obteniendo el fichero con las dos firmas:

" + e2.MessageError); }

3.4.7.1. MultiFirma con Objeto policy

A partir del cliente v1.2 se incorpora la posibilidad de realizar una multifirma a partir del uso de Políticas de firma, a través del objeto Policy y sus respectivos parámetros. Esta mejora es compatible con versiones de viafirma platform v3.5.5 y superior. A continuación se muestra un ejemplo del uso de la multifirma haciendo uso del Policy;

//Creamos Fichero FileVO document = new FileVO(); document.name = "test.pdf"; document.bytes = datosPdf; document.typeFile = TypeFile.PDF; //Definimos Policy Policy policy = PolicyUtil.newPolicy(TypeFormatSign.XADES_EPES_ENVELOPED, TypeSign.ENVELOPED); String idMultifirma; try {

//Iniciamos la multifirma y obtenemos el id del proceso de multifirma idMultifirma = client.InitMultisign(policy, document); } catch (InternalException e1) { throw e1; }

String idFirma; //El documento puede ser vacio, no se utilizará ya que se establece en el método initMultisign document = new FileVO(); //PRIMERA FIRMA


try { //Policy con datos básicos indicando el idMultifirma en el Policy //Se podría reutilizar el anterior

Policy pol = PolicyUtil.newPolicy(TypeFormatSign.XADES_EPES_ENVELOPED, TypeSign.ENVELOPED); //indicamos el id de multifirma PolicyUtil.AddParameter(pol, PolicyParam.MULTISIGN_ID, idMultifirma); //el id que devuelve será el mismo que en firmas sucesivas que usen el mismo idMultifirma idFirma = client.SignWithPolicy(cert, pol, new FileVO()); //recupero el documento con una firma signedDocument signedDocument = client.GetSignedDocument(idFirma); } catch (Exception e) { throw e; } //SEGUNDA FIRMA try {

//Policy con datos básicos indicando el idMultifirma en el Policy Policy pol = PolicyUtil.newPolicy(TypeFormatSign.XADES_EPES_ENVELOPED, TypeSign.ENVELOPED); //indicamos el id de multifirma PolicyUtil.AddParameter(pol, PolicyParam.MULTISIGN_ID, idMultifirma); //No necesitaría recuperar el idFirma porque es el mismo que antes client.SignWithPolicy(cert, pol, new FileVO()); //Notese que se recupera el documento con el mismo idFirma que antes pero esta vez tendrá dos firmas signedDocument signedDocument = client.GetSignedDocument(idFirma); } catch (Exception e) { throw e; } //TERCERA FIRMA try {

//Policy con datos básicos indicando el idMultifirma en el Policy Policy pol = PolicyUtil.newPolicy(TypeFormatSign.XADES_EPES_ENVELOPED, TypeSign.ENVELOPED); //indicamos el id de multifirma PolicyUtil.AddParameter(pol, PolicyParam.MULTISIGN_ID, idMultifirma);

//No necesitaría recuperar el idFirma porque es el mismo que antes client.SignWithPolicy(cert, pol, new FileVO()); //Notese que se recupera el documento con el mismo idFirma que antes pero esta vez tendrá tres firmas signedDocument signedDocument = client.GetSignedDocument(idFirma); } catch (Exception e) { throw e; }


4. DESCRIPCIÓN DEL API

A partir de la v1.2 se incluye en la SDK la documentación detallada del API en formato html.

4.1. Principales Métodos del API

4.1.1. Lista de Certificados

• public List<Certificate> GetClientCertificates()

Este método devuelve el listado de certificados disponibles en el sistema operativo (Windows) incluyendo las tarjetas criptográficas que Windows sea capaz de reconocer.

4.1.2. Métodos de Firma

• public String SignWithPolicy(Certificate certificate, Policy policy, FileVO document)

Este es el método principal de firma, recibe un Certificate que contiene el certificado con el que firmar, un FileVO que representa al documento a firmar, un Policy que describe el método de firma. Devuelve el identificador de firma en la Plataforma.

Puede lanzar dos excepciones: InternalException si se produce en el lado del servidor o ViafirmaClientDesktop si se produce en el lado cliente.

• public String SignByServerWithPolicy(Policy policy, FileVO document, String alias, String password)

Similar al anterior, pero realiza la firma en el servidor. También recibe Policy y FileVO pero no el Certificate, en su lugar ha de pasarse el alias y password del certificado instalado en servidor. Lanza las mismas excepciones que el método anterior.

4.1.3. Documento Firmado

• public SignedDocument GetSignedDocument(String signId)

Haciendo uso del IdFirma obtenido en alguno de los métodos de firma anteriores, es posible recuperar información de la operación, así como en el documento firmado. Esa información está contenida en el objeto SignedDocument que es devuelto por este método. Puede lanzar la excepción InternalException que indica error o en el lado servidor o en la comunicación WS.


4.1.4. Firma en Bucle

• public String SignWithPolicy(Certificate certificate, Policy policy, List<FileVO> documents)

Es similar al método de firma simple, pero recibe un listado de FileVO en lugar de uno solo. Este método devuelve un String con los ID’s de firma de los documentos firmados separados por ‘;’. Por ejemplo, si mandásemos un listado de tres FileVO, el método devolvería algo como lo siguiente (obsérvese que correspondería a tres ID’s separados por punto y coma):

xxxx-xxxx-xxxx-xxxx-xxxx;xxxx-xxxx-xxxx-xxxx-xxxx;xxxx-xxxx-xxxx-xxxx-xxxx

4.1.5. Firma en Lote

• public String SignBatchWithPolicy(Certificate certificate, Policy policy, List<FileVO> documents)

Realiza la firma de un lote de documentos que se generará con la lista de FileVO pasada, también recibe el Policy de firma y el certificado con el que firmar. Devuelve el ID de firma correspondiente

• public String SignBatchByServerWithPolicy(Policy policy, List<FileVO> documents, String alias, String password)

Igual que la anterior, pero realizando la firma en el servidor, para ello debemos tener previamente instalado el certificado en el servidor. El método recibe el Policy, la lista de FileVO y el alias/pass del certificado del servidor. Devuelve el ID correspondiente.

4.1.6. Documento original

• public Document GetOriginalDocument(String signId)

Recupera el documento original correspondiente al identificador pasado. Devuelve un objeto Document.

• public List<String> GetOriginalDocumentsIds(String batchSignId)

Pasándole un identificador de firma en Lote, devuelve un listado con todos los identificadores de los documentos originales que componen dicho Lote. El orden de los identificadores devueltos es aquel con el que se introdujeron los documentos en el lote.


4.1.7. Multifirma

• public String InitMultisign(Policy policy, FileVO document)

Inicia una operación de multifirma (múltiples firmantes de un documento) y devuelve un identificador del proceso de multifirma (no identificará nunca al fichero firmado).

Una vez se tiene el identificador de multifirma, se debe invocar al método de firma correspondiente (sign...Policy(Policy policy, FileVO document, ...)) pasándole el id de multifirma como un parámetro del objeto Policy con nombre ‘MULTISIGN_ID’.

(Se puede ver un ejemplo en los ejemplo de us del API de este mismo manual)

4.2. Objeto Certificate

Contiene toda la información sobre un X509 con la que el sistema puede trabajar. Es una abstracción de un certificado X509. En él encontraremos los siguientes campos útiles disponibles:

• Dictionary<string, string> Properties

Conjunto de propiedades Oids que contiene el certificado. Aquí se encontrarán todos los oids que no han podido ser importados a campos atributos

• string Country

País de emisión del certificado

• string TypeCertificate

Tipo de certificado

• string CA

Autoridad de registro que emitió el certificado

• string Name

Nombre del usuario

• string Email


Email del usuario (si el certificado lo contiene

• string NumberUserId

Numero identificativo del certificado. En España será el DNI.

• string Surname

Primer apellido indicado en el certificado

• string Lastname

Segundo apellido si existe, si no será null

• string Title

Determina el tipo de cargo. Utilizado para los certificados de Persona con vinculo institucional.

• string Organization

Organización a la que pertenece. Utilizado para los certificados empresariales

• string Cn

Campo CN del certificado.

• string LegalType

Tipo jurídico del certificado

• X509Certificate X509

Devuelve el certificado X509.

• string Alias

Indica el alias del certificado.

• bool SignatureEnabled


Indica si el certificado puede ser usado para firmar según el KeyUsage.

• bool AuthenticationEnabled

Indica si el certificado puede ser usado para autenticar según el KeyUsage.

• string Label

Representación del certificado en una línea de texto.

• bool Expired

Comprueba si el certificado está expirado.

4.3. TypeFormatSign

A la hora de configurar las propiedades de firma dentro del objeto Policy o el FileVO, tenemos que indicar qué formato de firma vamos a utilizar.

Para ello se dispone de un enumerado con todos los formatos permitidos por viafirma platform, sin embargo, no todos ellos estarán soportados en este cliente para java desktop (windows system).

En concreto, los formatos que se podrán utilizar son los siguientes:

• //XAdES

o TypeFormatSign.XADES_EPES_ENVELOPED

o TypeFormatSign.XADES_T_ENVELOPED

o TypeFormatSign.XADES_XL_ENVELOPED //Requiere certificado con OCSP informado

o TypeFormatSign.XADES_A_ENVELOPED //Requiere certificado con OCSP informado

• //PAdES

o TypeFormatSign.PDF_PKCS7

o TypeFormatSign.PDF_PKCS7_T

o TypeFormatSign.PAdES_BASIC

o TypeFormatSign.PAdES_BES

o TypeFormatSign.PAdES_EPES


o TypeFormatSign.PAdES_LTV

4.4. Objeto Document

El objeto Document representa un Documento original para viafirma, es devuelto por el API al invocar al método GetOriginalDocumentsIds(signId).

• String Id

Identificador del documento en viafirma

• TypeFile Type

Tipo indicado para el fichero (XML, PDF, TXT, Binary, etc.)

• byte[] Data

El documento en formato binario

• String Name

Nombre dado al documento.

4.5. Objeto signedDocument

Este objeto representa un documento firmado por viafirma recuperado usando el método GetSignedDocument(String signId). Además incluye información sobre el firmante.

• genericUserViafirma asociatedUser

Información sobre el firmante

• byte[] data

Documento en formato binario

• string id

Identificador del documento en viafirma

• string name


Nombre dado al documento

• object temp

Campo de uso interno

• TypeFile type

Tipo del documento (XML, PDF, TXT, Binary, etc.)

• TypeFormaSign typeFormaSign

Formato en el que se ha realizado la firma

4.6. Objeto genericUserViafirma

Contiene información relativa al certificado del firmante, se obtiene a partir del objeto signedDocument.

• string caName

Nombre de la autoridad de certificación que emitió el certificado

• string email

Email del firmante

• string firstName

Nombre del firmante

• string lastName

Apellido del firmante

• string numbreUserId

Identificador del firmante (puede una id personal como el número de DNI o un email si no hubiera ningún otro identificador en el certificado)

• genericUserViafirmaEntry[] properties


Todas las propiedades que se han podido extraer del certificado

• string typeCertificate

Tipo del certificado reconocido por viafirma

• string typeLegal

Tipo legal del certificado definido por viafirma

4.7. Objeto Policy, PolicyUtil

A partir del cliente v1.2, se incorpora el soporte para Políticas de Firma a través del objeto Policy y PolicyUtil.

Usando la clase PolicyUtil podemos instanciarnos cómodamente objetos Policy con sus propiedades básicas y, después, poder añadirle parámetros fácilmente.

Ejemplo:

//Instanciamos Policy con datos básicos usando PolicyUtil Policy pol = PolicyUtil.newPolicy(TypeFormatSign.XADES_EPES_ENVELOPED, TypeSign.ENVELOPED); //Agregamos un parámetro (MULTISIGN_ID) al policy usando PolicyUtil PolicyUtil.AddParameter(pol, PolicyParam.MULTISIGN_ID, idMultifirma);

4.8. Clase PolicyParams

La clase PolicyParams contiene los nombres para distintos parámetros permitidos para definir la política de firma. En esta versión solo contiene un parámetro:

/// <summary> Id del proceso de multifirma. </summary> /// <value> values: id de multifirma válido</value> /// <remarks>type: String</remarks> /// <remarks>since: 3.5.5</remarks> public static String MULTISIGN_ID = "MULTISIGN_ID";


4.9. Manejo de Errores

A partir del cliente v1.2 se mejora el manejo de errores recuperados desde viafirma platform:

InternalException:

• CodeError codigoError - puede ser null

• int code

• String message

Donde las posibles claves son las siguientes: /// CONNECTION_PROBLEM=100, /// ERROR_AUTHENTICATION_UNAVALIBLE=4000, /// ERROR_PROTOCOL_SIGN = 5000, ///Error interno en el servidor, por favor inténtelo mas tarde. ERROR_INTERNO=1, ///No se ha podido recuperar correctamente el certificado. ERROR_MANEJO_CERTIFICADO=2, ///La aplicación indicada no existe, utilice un código de aplicación valido. ERROR_APLICACION_NO_ENCONTRADA=3, ///La entidad indicada no existe, utilice un identificador valido. ERROR_IDENTIFICADOR_NO_ENCONTRADO=4, ///No se ha podido crear la entidad. ERROR_CREATE=5, ///No se ha podido recuperar el certificado desde el XMLSign ERROR_XMLSIGN_SIN_CERTIFICADO=6, /// El certificado no es valido ERROR_XMLSIGN_CERTIFICADO_NO_VALIDO=7, /// El parámetro requerido no es válido. ERROR_PARAM=8, /// El formato de firma no es reconocido o contiene errores. ERROR_XMLSIGN_FORMAT=9, /// Identificador no válido. ERROR_INVALID_ID=10, /// Operación no implementada. ERROR_NOT_IMPLEMENTED=11, /// Faltan parámetros de configuración en contexto ERROR_BADCONFIGURATION=20, /// El certificado no ha sido enviado por el usuario. WARNING_CERTIFICADO_NO_ENVIADO=50, /// Autoridad de certificación no reconocida por el sistema. ERROR_VALIDACION_AUTORIDAD_NO_RECONOCIDA=101, /// Autoridad de certificación no reconocida por el sistema. ERROR_VALIDACION_AUTORIDAD_NO_RECONOCIDA_SOPORTE_FNMT=111, /// Autoridad de certificación no configurada en el sistema. ERROR_VALIDACION_AUTORIDAD_NO_CONFIGURADA=112, /// La configuración del validador no es correcta, probablemente no existan certificados de confianza configurados. ERROR_VALIDACION_CONFIGURACION_PARAMETRO=102, /// No se han podido recuperar las lista de revocacin de certificados =CRLs). ERROR_VALIDACION_CRL=103, /// Certificado caducado.


ERROR_VALIDACION_CERTIFICADO_CADUCADO=104, /// Certificado caducado o no válido. ERROR_CERTIFICADO_NO_VALIDO=105, /// No se ha podido recuperar el certificado. ERROR_CERTIFICADO_NO_FOUND=106, /// El certificado indicado está revocado ERROR_VALIDACION_CERTIFICADO_REVOCADO=107, /// No se conoce el estado del certificado ERROR_VALIDACION_CERTIFICADO_UNKNOWN=108, /// No se han podido validar el certificado, la plataforma interna de validación no está disponible. ERROR_VALIDACION_PLUGIN_ERROR=109, /// El servicio de validación de certificados OCSP no está disponible en este momento. ERROR_OCSP_NO_DISPONIBLE=130, /// La ruta para la validación OCSP no es correcta. ERROR_OCSP_URL=131, /// No se puede validar el certificado, hay problemas de conexión con el servidor de validación OCSP. ERROR_OCSP_IO=132, /// No se puede validar el certificado, el servicios de validación OCSP parece no estar disponible en este momento. ERROR_OCSP_INTERNAL_ERROR=133, /// El validador de certificados OCSP no esta disponible en estos momentos, inténtelo mas tarde. ERROR_OCSP_TRY_LATER=134, /// La validación OCSP del certificado no ha sido autorizada. ERROR_OCSP_NO_AUTORIZADO=135, /// No se ha podido realizar la validación del certificado. Se requiere que el titular del certificado autorice su validación. ERROR_OCSP_NO_AUTORIZADO_REQUIERE_AUTIRIZACION_USUARIO=136, /// El sistema de custodia no está disponible en este momento. El proceso de firma no se puede completar ERROR_CUSTODIA=9000, /// El fichero enviado tiene un tamaño demasiado grande. ERROR_FILE_SIZE=9001, /// No se ha indicado ningún fichero para su firma, o el fichero esta vacio. ERROR_FILE_EMPTY=9002, /// El código de chequeo de este identificador no es válido, compruebe que el código es correcto. ERROR_CUSTODIA_CHECK_DIGIT=9003, /// No se ha podido verificar el documento custodiado. ERROR_CUSTODIA_NO_VALID=9004, /// El formato de firma no es reconocido. ERROR_TYPE_FORMAT_SIGN=9005, /// No se ha podido localizar el documento en la cache temporal. ERROR_CACHE_DOCUMENT=9006, /// No se ha podido realizar la comprobación del documento. ERROR_VALIDANDO_FIRMA=8000, /// El documento indicado no es un documento XML. ERROR_NOT_XML_DOCUMENT=8001, /// El documento indicado parece estar dañado. ERROR_NOT_HEALTHY_DOCUMENT=8002, /// Incorrect orginal documnent format. ERROR_NOT_CORRECT_FORMAT_DOCUMENT=8003, /// El fichero original es desconocido para esta firma. Por favor utilice el método, checkSignedDetachedDocumentValidity=signedDocument, originalDocument) ERROR_DETACHED_VALIDATION=8004, /// Se esperaba otro formato de firma ERROR_FORMAT_SIGN_UNEXPECTED=8005, /// Error al procesar el PDF.


ERROR_PDF=1001, /// Error al enviar el email. ERROR_SEND_MAIL=1100, /// No se puede actualizar el keystore. ERROR_KEYSTORE_UPDATE_FILE=1200, /// No se ha encontrado ninguna TSA Configurada. ERROR_TSA_NOT_CONFIGURED=6000, /// No se ha podido conectar con ninguna de las TSA configuradas ERROR_TSA_CONNECT_PROBLEM=6001, /// Se ha producido un error al analizar los parámetros de la petición. ERROR_PARSING_PARAMETER=3001, /// Aplicación no registrada, contacte con su proveedor de servicios de firma y autenticación. ERROR_APLICACION_NO_REGISTRADA=4009,