Viafirma.NET Desktop Client

Transcripción

1 Viafirma.NET Desktop Client Manual de Integración v1.2

2 ÍNDICE 1. INTRODUCCIÓN REQUISITOS INTEGRACIÓN Obtener la librería y el proyecto de ejemplo Introducir viafirma-client-net-desktop.dll en el proyecto java de escritorio Usando Visual Studio Instanciar el cliente.net de viafirma para escritorio Definición de Proxy Usar el API Obtención de Certificados de usuario Uso de Firma Simple Uso de la Firma en Bucle Uso de la Firma en Lote en Cliente Uso de la Firma en Lote en Servidor Recuperar documentos originales de una firma en Lote Uso de la Multifirma MultiFirma con Objeto policy DESCRIPCIÓN DEL API Principales Métodos del API Lista de Certificados Métodos de Firma Documento Firmado Firma en Bucle Firma en Lote Documento original Multifirma Objeto Certificate TypeFormatSign Objeto Document Objeto signeddocument Objeto genericuserviafirma ÍNDICE

3 4.7. Objeto Policy, PolicyUtil Clase PolicyParams Manejo de Errores ÍNDICE

4 CONTROL DE DOCUMENTO Título: Viafirma.NET Desktop Client Asunto: Manual de Integración Versión: v1.2 Fecha: Código: Revisión anterior: Idioma: Núm. Páginas: 30 CONTROL DE CAMBIOS Y VERSIONES Fecha Versión Motivo del Cambio v.1.0 Primera versión Revisión de nuevas funcionalidades incorporadas en la v1.2 del cliente.net Desktop. Los cambios fueron: Punto 2 Requisitos Punto Definición de Proxy v.1.2 Punto 3.4 Documentación del API en formato HTML Punto Multifirma con Policy Punto 4 Uso del API Puntos 4.4 al 4.9 CONTROL DE DOCUMENTO

5 1. INTRODUCCIÓN Desde la versión 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 Página 5 de 30

6 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: 2. Solicitar credenciales para la configuración del cliente (API KEY) 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 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 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 Página 6 de 30

7 referencias típicas de.net Framework, se puede consultar el proyecto de ejemplo para comprobarlas 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; //Se inicia con la URL de VIAFIRMA y el api_key/api_pass ViafirmaClientDesktop.Init(" "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. Página 7 de 30

8 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(" "<apikey>", "<apipass>", " null, null); Configuración proxy con autenticación: //Inicialización con Proxy CON autenticación ViafirmaClientDesktop.Init(" "<apikey>", "<apipass>", " "<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. Página 8 de 30

9 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 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: Página 9 de 30

10 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 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; Página 10 de 30

11 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; //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. Página 11 de 30

12 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; 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. Página 12 de 30

13 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; 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) { //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()); Página 13 de 30

14 El método SignWithPolicy para realizar una firma en bucle 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. 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 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; 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 signeddocument signeddoc = client.getsigneddocument(id); Página 14 de 30

15 //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.message); El método SignBatchWithPolicy para realizar una firma en lote en el lado cliente 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. List<FileVO>: especifica los documentos a firmar. 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) 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; 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) { Página 15 de 30

16 System.Console.WriteLine("Error en CLIENTE realizando la firma en LOTE en SERVIDOR: " + e1.messageerror + " " + e1.tostring()); //Recuperamos el documento signeddocument signeddoc = client.getsigneddocument(idserver); //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 SignBatchByServerWithPolicy para realizar una firma en lote en el lado servidor recibe los siguientes parámetros: 1. Policy: política de firma de viafirma para especificar la configuración de firmado. 2. List<FileVO>: especifica los documentos a firmar. 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) 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: 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. Página 16 de 30

17 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; 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; 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"; Página 17 de 30

18 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; 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; signeddocument2 = client.getsigneddocument(id2); //Procesamos el documento firmado Código de procesado del documento: custodia, envío a WS... catch (InternalException e2) { System.Console.WriteLine("Error obteniendo el fichero con las dos firmas: " + e2.messageerror); 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; //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 Página 18 de 30

19 //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 //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 //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; Página 19 de 30

20 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 Principales Métodos del API 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 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 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. Página 20 de 30

21 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 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 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. Página 21 de 30