Tabla de contenido - Viafirma · ii. Instalación a través de Maven ii. .Net i. Instalación a...

1. Introduccióni. Control de Cambiosii. Histórico de versiones

i. Histórico cambios Javaii. Histórico cambios .Net

2. SDKi. SDK Javaii. SDK .Netiii. SDK .Net MVC

3. Instalación del SDKi. Java

i. Instalación a través de librerías .jarii. Instalación a través de Maven

ii. .Neti. Instalación a través de librerías .dll

4. Inicialización del clientei. Inicialización Javaii. Inicialización .Net

5. Aparienciai. Ocultar opciones de aplicaciones de firma

6. Operaciones de Autenticacióni. Procesar respuesta Javaii. Procesar respuesta .Netiii. Uso Viafirma Desktop por protocolo - autenticacióniv. Autenticación sin applet o clientes ricos: SSL client auth

7. Operaciones de Firmai. Firma con intervención de usuario

i. Procesar respuesta firma Javaii. Procesar respuesta firma .Net

ii. Firma sin intervención de usuarioiii. Obtener información firma

i. Obtener información avanzada de firmaii. Obtener documento custodiado firmadoiii. Obtener documento original

iv. Firma en lotev. Firma en buclevi. Promoción (upgrade) de firmavii. Sellado de tiempoviii. Uso Viafirma Desktop por protocolo - firma

8. Operaciones de verificacióni. Verificación de certificadoii. Verificación de firma

9. Policy

Tabla de contenido

2

i. Parámetrosi. Parámetros para la firma digitalizada

i. DIGITALIZED_LOCATION_STATUSii. DIGITALIZED_PRESSURE_INFOiii. DIGITALIZED_PRESURE_STYLUiv. DIGITALIZED_SIGN_ALIASv. DIGITALIZED_SIGN_BACK_COLORvi. DIGITALIZED_SIGN_BIOMETRIC_ALIASvii. DIGITALIZED_SIGN_BIOMETRIC_CRYPTO_PEMviii. DIGITALIZED_SIGN_BIOMETRIC_PASSix. DIGITALIZED_SIGN_COLOURx. DIGITALIZED_SIGN_HELP_TEXTxi. DIGITALIZED_SIGN_LOGOxii. DIGITALIZED_SIGN_PAGExiii. DIGITALIZED_SIGN_PASSxiv. DIGITALIZED_SIGN_PDF_SIGNATURE_FORMATxv. DIGITALIZED_SIGN_RECTANGLExvi. DIGITALIZED_SIGNATURE_FORMATxvii. DIGITALIZED_SIGNATURE_INFO

ii. Parámetros para sello de firmai. DIGITAL_SIGN_CONTACTii. DIGITAL_SIGN_IMAGE_STAMPERiii. DIGITAL_SIGN_IMAGE_STAMPER_AUTOGENERATEiv. DIGITAL_SIGN_LOCATIONv. DIGITAL_SIGN_PAGEvi. DIGITAL_SIGN_REASONvii. DIGITAL_SIGN_RECTANGLEviii. DIGITAL_SIGN_STAMPER_CSV_CODEix. DIGITAL_SIGN_STAMPER_CSV_URLx. DIGITAL_SIGN_STAMPER_FONT_SIZExi. DIGITAL_SIGN_STAMPER_HIDE_BARCODExii. DIGITAL_SIGN_STAMPER_HIDE_QRCODExiii. DIGITAL_SIGN_STAMPER_HIDE_STATUSxiv. DIGITAL_SIGN_STAMPER_ROTATION_ANGLExv. DIGITAL_SIGN_STAMPER_TEXTxvi. DIGITAL_SIGN_STAMPER_TRANSPARENT_BACKGROUNDxvii. DIGITAL_SIGN_STAMPER_TYPExviii. DIGITAL_SIGN_TIMEZONE

iii. Parámetros configuración de firmai. CUSTOM_CSS_URLii. APPLET_STYLEiii. BINARY_NODE_CONTENT_MIME_TYPEiv. CADES_DO_COUNTERSIGNATUREv. CALLBACK_URLvi. CLIENT_LOCALEvii. CONTINUE_LOOP_WITH_ERRORSviii. CSV_MINIMUM_SIZE

3

ix. CSV_PREFIXx. DETACHED_REFERENCE_URLxi. DETACHED_TYPExii. DIGEST_METHODxiii. DISCARD_EXPIRED_CERTIFICATESxiv. ENVELOPED_TARGET_NODExv. FILTER_CA_NAMExvi. FILTER_CERTIFICATE_BYxvii. FILTER_GENERICxviii. FILTER_NUMBER_USER_IDxix. HIDE_ERROR_PAGExx. HIDE_MOBILE_BUTTONSxxi. NODE_ID_TO_SIGNxxii. ORIGINAL_HASHxxiii. PADES_INCLUDE_TSAxxiv. PDF_ANNOTATION_IMAGExxv. PDF_ANNOTATION_PAGExxvi. PDF_ANNOTATION_RECTANGLExxvii. SIGN_BINARY_NODE_CONTENTxxviii. SIGNATURE_ALGORITHMxxix. SIGNATURE_POLICY_DESCRIPTIONxxx. SIGNATURE_POLICY_HASH_DATAxxxi. SIGNATURE_POLICY_IDxxxii. SIGNATURE_POLICY_TRANSFORMxxxiii. SIGNATURE_POLICY_URIxxxiv. SIGNER_ROLExxxv. XML_CANONICALIZATION_METHODxxxvi. XML_CANONIZATION_TRANSFORM

ii. Optional Requesti. AUTO_SEND

10. Aplicación de ejemploi. Aplicación ejemplo Java

i. Instalaciónii. Configuración

ii. Aplicación ejemplo .Neti. Instalaciónii. Configuración

11. Snippets de utilidadi. Cambiar el tamaño máximo de los documentos a firmarii. Obtener PEM de un certificado después de una autenticación o firmaiii. CAdES

i. Verificar correspondencia de firma CMS con documento firmadoii. Extraer certificado firmante de una firma CMS/CAdES

iv. XAdESi. Upgrade de firma XAdES

v. Invocación a Viafirma Desktop por protocolovi. Invocación a Viafirma Platform para autenticación sin cliente (SSL client auth)

4

Este documento tiene como misión facilitar a usuarios integradores la utilización de las librerías del cliente de viafirmaplatform para dotar a sistemas externos de las funcionalidades de autenticación, firma, verificación y custodia dedocumentos.

Está orientado a un perfil de desarrollador habituado a desarrollos JEE, .net asp, por lo que el nivel de detalles dealgunos aspectos tratados necesitan de un conocimiento previo en estas tecnologías. También se requiere un mínimoconocimiento sobre el tratamiento de certificados digitales (X.509v3).

Este manual de integración hace referencia a distintos recursos que serán necesarios para la puesta en marcha de losejemplos descritos. Todos estos recursos están disponibles de forma gratuita desde el siguiente enlace.

Al mismo tiempo, y para el uso inmeidato de los servicios contra nuestro entorno centralizado serán necesarias unascredenciales para desarrollo, que serán proporcionadas también de forma gratuita desde http://developers.viafirma.com

Si lo desea puede descargar este manual en formato .PDF desde el siguiente enlace.

Introducción

Público Objetivo

Requisitos Previos

Credenciales: API-KEY

Manual en PDF

6Introducción

http://developers.viafirma.com

Esta documentación técnica está sujeta a modificaciones diarias, y alguna información o configuración avanzada podríano estar reflejada. Consulte en cualquier caso con el equipo de soporte técnico.

Descripción Valor

Adaptadas instrucciones de integración en java y .net. 12-febrero-2018

Fecha Cambio

04-oct-18 Actualización a los servicios de Desktop por protocolo de Platform 3.17.1

03-sep-18 Actualización 2.14.7

23-jul-18 Actualización 2.14.5

31-ene-18 Añadidas páginas de descargables de recursos.

18-ene-18 Adaptada instrucciones de integración en java y .net.

11-feb-16 Primera publicación online del uso del SDK Java.

23-mar-16 Añadidos capitulos de instalación Policy params y Snippets de utilidad.

Control de Cambios

Control de documento

Últimos cambios

7ControldeCambios

Histórico de cambios en SDK JavaHistórico de cambios en SDK .Net

Las versiones anteriores de las SDK se publican en el portal de desarrolladores de viafirma. Si necesitas una vesiónanterior a la actual ponte en contacto con nosotros: [email protected]

Histórico de cambios y versiones

8Históricodeversiones

https://developers.viafirma.com/descargas-viafirma-platform

Nuevo parámetro CUSTOM_CSS_URL que permite especificar por policy la URL de la hoja de estilos CSS con el quequiere que Viafirma Platform muestre la página de autenticación/firma.

Nuevo parámetro DIGITAL_SIGN_TIMEZONE. que permite incluir la zona horaria de la aplicación, para representar lafecha y hora si el sello configurado incluye esta información.

Mejora del soporte de proxy - se incluye el reconocimiento de la variable de JVM http.nonProxyHost

Cuando tokenConnector está configurado, y las URLs internas y externas de Platform son diferentes (se usa una URLinterna), todas las llamadas internas se realizan utilizando la URL interna.

Modificada la constante MAX_SIZE_UPLOAD_FILE de 5 Mb a 50 Mb por defecto

Optimización de memoria relacionada con la carga de BouncyCastle

Se agrega la propiedad signatureFormat (de tipo TypeFormatSign) a la clase SignatureVerification con el fin dedevolver el tipo de firma en la llamada al método verifySignature, para la verificación de la validez de firmas.

Se incluye el soporte a mejoras en la llamada a Viafirma Desktop por protocolo: se incluyen nuevos filtros enautenticación y firma (CA Filter, Serial Number Filter)

Se incluye el soporte al nuevo servicio para autenticación del cliente con certificado digital utilizando SSL client auth.

Histórico cambios Java

v2.14.15 / 27-Abril-2020

v2.14.14 / 25-Octubre-2019

v2.14.13 / 06-febrero-2019

v2.14.12 / 19-enero-2019

v2.14.11 / 19-diciembre-2018

v2.14.10 / 17-diciembre-2018

v2.14.9 / 15-noviembre-2018

v2.14.8 / 4-octubre-2018

v2.14.7 / 3-septiembre-2018

9HistóricocambiosJava

El objeto Policy en la invocación por Viafirma Desktop por protocolo pasa a ser un parámetro a nivel de cada ficheroenviado en la llamada, en lugar de ser global para la llamada.

Se incorporan dos servicios que complementan a la invocación por Viafirma Desktop por protocolo, para permitirdescargar desde la aplicación integrada la información de la operación de autenticación con certificado y de firmaelectrónica dado un operationId recibido al preparar la operación.

Corrección de errores

Soporte para invocación a Viafirma Desktop por protocolo, tanto para autenticación como para firma. De esta forma seelimina la página de Viafirma que incluye el applet y el resto de métodos de firma.

Cuando el estado de verificación de un certificado es "Unknown", no se devuelven los datos ni propiedades delcertificado parseadas debido a que el certificado no está soportado por la plataforma. Para identificarlo, si podemosobtener el "Subjet" del certificado, por lo cual lo devolvemos en esta nueva propiedad.

Verificación de certificados.

Nuevo estado llamado UNKNOWN cuando el certificado que estemos validando mediante el método verifyCertificate,no esté reconocido por viafirma platform, es decir, que no se le haya añadido el soporte.

Verificación de certificados.

v2.14.6 / 26-julio-2018

v2.14.5 / 23-julio-2018

v2.14.4.1 / 20 marzo-2018

v2.14.4 / 14-marzo-2018

26364: Soporte para invocación a Viafirma Desktop por protocolo

v2.14.3 / 31-enero-2018

26242: Incorpora nuevo atributo SubjetDN en la verificación de certificados.

v2.14.1 / 15-septiembre-2017

26197: Nuevo estado UNKNOWN para la validación de certificados.

v2.14.0 / 11-agosto-2017

#26068: Nuevo filtro "GenericFilter" para la selección de certificados.


Nuevo filtro para la selección de certificados que filtrará si el valor pasado como parámetro coincide con cualquiera dela propiedades existentes en un certificado.

Filtro genérico.

CSV_PREFIX: Define un prefijo a incorporar en el CSV (signatureId) para una operacion de firma.CSV_MINIMUM_SIZE: Define un tamaño minimo para el CSV (signatureId) para una operacion de firma.

DIGITAL_SIGN_STAMPER_FONT_SIZE: Para los nuevos sellos de tipo 'TEXT' se permite usar este parámetro depolítica de firma donde indicar el tamaño de fuente (en points).

DISCARD_EXPIRED_CERTIFICATES: Descarta los certificados expirados a la hora de mostrarlos en lasaplicaciones de selector de certificados.

CONTINUE_LOOP_WITH_ERRORS: con este parámetro se permite seguir adelante en una firma en bucle conerrores previos en algunas firmas de documentos.

Verificación de certificados.Verificación de firmas

v2.13.6 / 27-junio-2017

#25867: Nuevos parámetros de política de firma para CSV : CSV_PREFIX yCSV_MINIMUM_SIZE.

v2.13.5 / 7-junio-2017

#25865: Nuevo parámetro de política de firma :DIGITAL_SIGN_STAMPER_FONT_SIZE.

v2.13.3 / 1-marzo-2017

#25864: Nuevo parámetro de política de firma :DISCARD_EXPIRED_CERTIFICATES.

v2.13.1 / 15-febrero-2017

#25863: Nuevo parámetro de política de firma : CONTINUE_LOOP_WITH_ERRORS.

v2.12.0 / 30-diciembre-2016

Nuevos metodos de verificacion de firmas y certificados.

Versiones anteriores


Para consultar la lista de cambios en versiones anteriores, diríjase al portal de viafirma developers


https://developers.viafirma.com/sdk-java

Corregido el uso de viafirma desktop por protocolo usando tokenConenctor

Posibilidad de enviar/recuperar el PEM como OptionalRequest en la autenticación y firma

Se incluye el soporte a mejoras en la llamada a Viafirma Desktop por protocolo: se incluyen nuevos filtros enautenticación y firma (CA Filter, Serial Number Filter)

Se expone el servicio tsaRequest

Se incluye soporte para autenticación con SSL client auth

El objeto Policy en la invocación por Viafirma Desktop por protocolo pasa a ser un parámetro a nivel de cada ficheroenviado en la llamada, en lugar de ser global para la llamada.

Se incorporan dos servicios que complementan a la invocación por Viafirma Desktop por protocolo, para permitirdescargar desde la aplicación integrada la información de la operación de autenticación con certificado y de firmaelectrónica dado un operationId recibido al preparar la operación.

Soporte para invocación a Viafirma Desktop por protocolo, tanto para autenticación como para firma. De esta forma seelimina la página de Viafirma que incluye el applet y el resto de métodos de firma.

Histórico cambios .Net

v3.5.11.0 / 17-junio-2019

v3.5.10.0 / 4-octubre-2018

v3.5.9.0 / 25-septiembre-2018

v3.5.8.0 / 04-septiembre-2018

v3.5.7.0 / 26-julio-2018

v3.5.6.0 / 24-julio-2018

v3.5.5.0 / 20-marzo-2018

26364: Soporte para invocación a Viafirma Desktop por protocolo

v3.5.4.0 / 31-enero-2018

26255: Corregido error al inicializar por nuevo método init de retorno de url

13Históricocambios.Net

Al inicializar el cliente con el nuevo método init, no está aplicando correctamente las credenciales de las aplicacionesde viafirma manager y por tanto ocurre un error de accedo a la aplicación cuando se inicia.

Cuando el estado de verificación de un certificado es "Unknown", no se devuelven los datos ni propiedades delcertificado parseadas debido a que el certificado no está soportado por la plataforma. Para identificarlo, si podemosobtener el "Subject" del certificado, por lo cual lo devolvemos en esta nueva propiedad.

Verificación de certificados

Para consultar la lista de cambios en versiones anteriores, diríjase al portal de viafirma developers

v3.5.3.0 / 5-octubre-2017

26243: Incorpora nuevo atributo SubjetDN en la verificación de certificados

Versiones anteriores

14Históricocambios.Net

https://developers.viafirma.com/sdk-net-0

Desde esta sección podremos obtener las SDKs y ejemplos de nuestra plataforma de autenticación y firma electrónica.Incluye además el soporte para firma digitalizada tanto en pantallas capacitivas tipo Wacom y Topaz (integradas conordenadores de escritorio o tablet PC's), como con iPad y iPhone.

Las versiones de las SDKs, que desde esta sección se pueden obtener, requieren de una versión de la aplicaciónservidor viafirma platform 3.9.0 o superior. Si este no es su caso, rediríjase al portal de Viafirma Developers o pógaseen contacto con el equipo de soporte.

SDK JavaSDK .NetSDK .Net MVC

SDK

15SDK

https://developers.viafirma.com/descargas-viafirma-platform

Librerías de cliente de viafirma platform en Java para dotar a sistemas externos de las funcionalidades deautenticación, firma electrónica, firma digitalizada, firma móvil, verificación y custodia de documentos.

Además de la librería de la propia SDK, se incluyen los siguientes recursos:

Si usas maven, sólo debes actualizar la dependencia en el pom de tu proyecto, y en caso contrario puedesdescargar la librería viafirma-client-all-in-one.jarAplicación de ejemplo publicada en GitHub que consume la librería viafirma-client, la misma que deberá seractualizada (en el caso de nueva versión) en las aplicaciones de terceros que ya integran con viafirma platform.Javadoc.

Para conocer cuáles han sido los cambios en las diferentes versiones, diríjase a la siguiente sección: Histórico decambios Java.

Fecha publicación: 27/04/2020Descargar .jarviafirma-client-2.14.15-all-in-one.jarJavadoc



Fecha publicación: 19/01/2019Descargar .jar

SDK Java

v2.14.15

v2.14.14

v2.14.13

v2.14.12

16SDKJava

https://descargas.viafirma.com/viafirma/sdk-java/viafirma-client-2.14.15.jar

https://descargas.viafirma.com/viafirma/sdk-java/viafirma-client-2.14.15-all-in-one.jar

https://descargas.viafirma.com/viafirma/sdk-java/viafirma-client-2.14.15-javadoc.zip








viafirma-client-2.14.12-all-in-one.jarJavadoc







v2.14.11

v2.14.10

v2.14.9

v2.14.8

v2.14.7

v2.14.6

17SDKJava



















viafirma-client-2.14.6-all-in-one.jarJavadoc




Necesita versión superior a la v3.15 de viafirma platform.



viafirma-client-2.14.3-all-in-one.jar.Aplicación de ejemplo.viafirma-client-2.14.3-javadoc.jar.

v2.14.5

v2.14.4.1

v2.14.4

v2.14.3

Otros recuros

18SDKJava






https://descargas.viafirma.com/viafirma/sdk-java/viafirma-client-2.14.4.1.jar




https://github.com/viavansi/viafirma-platform-example-java

https://descargas.viafirma.com/viafirma/sdk-java/viafirma-client-2.14.3-javadoc.jar

Librerías de cliente de viafirma platform en .Net para dotar a sistemas externos de las funcionalidades de autenticación,firma electrónica, firma digitalizada, firma móvil, verificación y custodia de documentos.

Además de la librería de la propia SDK, se incluyen los siguientes recursos:

Librerías de dependencias (all-in-one) necesarias para el funcionamiento de la SDK.Aplicación de ejemplo publicada en GitHub que consume la librería ViafirmaClientDotNet, la misma que deberá seractualizada (en el caso de nueva versión) en las aplicaciones de terceros que ya integran con viafirma platform.API-doc.

Para conocer cuáles han sido los cambios en las diferentes versiones, diríjase a la siguiente sección: Histórico decambios .Net

Fecha publicación: 17/06/2019.Descargar .dll

Necesita versión superior a la v3.17.1 de viafirma platform.

Fecha publicación: 04/10/2018.Descargar .dll.

Necesita versión superior a la v3.17.1 de viafirma platform.




SDK .Net

v3.5.11.0

v3.5.10.0

v3.5.9.0

v3.5.8.0

19SDK.Net

https://descargas.viafirma.com/viafirma/sdk-dotNet/3.5.11.0/ViafirmaClientDotNet.dll













ViafirmaClientDotNet-all-in-one.zip.Aplicación de ejemplo.Pendiente de generar documentación API.

v3.5.7.0

v3.5.6.0

v3.5.5.0

v3.5.4.0

Otros recuros

20SDK.Net





https://descargas.viafirma.com/viafirma/sdk-dotNet/3.5.5.0/ViafirmaClientDotNet-all-in-one.zip

https://github.com/viavansi/viafirma-platform-example-dotnet

Librería de cliente de viafirma platform en .Net MVC para dotar a sistemas externos de las funcionalidades deautenticación, firma electrónica, firma digitalizada, firma móvil, verificación y custodia de documentos.

Fecha publicación: 17/04/2019Descargar .DLL

SDK .Net MVC

v1.1.0

21SDK.NetMVC

https://descargas.viafirma.com/viafirma/sdk-dotNet-mvc/1.1.0/ViafirmaClientDotNetMVC.dll

Esta sección de Instalación hace referencia a distintos recursos que serán necesarios para la puesta en marcha. Todosestos recursos están disponibles de forma gratuita en la sección de SDK de este mismo manual.

Al mismo tiempo, y para el uso inmediato de los servicios contra nuestro entorno centralizado serán necesarias unascredenciales para desarrollo que podrá solicitar a través del siguiente enlace: http://developers.viafirma.com/solicita

Java

Debemos saber que hay dos formas de instalar el SDK de java de Viafirma Platform en nuestro proyecto:.

A través de MavenA través de una librería .jar

.Net

Desde .net hay que añadir la dll cliente disponible para su descarga:

A través de librerías .dll

Instalación del SDK

Requisitos previos

Credenciales: API-KEY

22InstalacióndelSDK

http://developers.viafirma.com/solicita

A través de MavenA través de una librería .jar

Java

23Java

En el caso de utilizar este tipo de instalación del SDK, en el kit de integración se incluyen los .jar necesarios para que laaplicación pueda consumir la api de viafirma platform.

Se puede obtener el kit de integración a través del la sección SDK Java.

Instalación a través de librerías .jar

24Instalaciónatravésdelibrerías.jar

Si decidimos utilizar maven, tendrémos que añadir el repositorio y la dependencia a nuestro archivo pom.xml. Estasdependencias están disponibles en el repositorio de viafirma.

<repositories>

....

<repository>

<id>Viavansi</id>

<name>ViavansiRepositorio</name>

<url>http://repositorio.viavansi.com/repo</url>

</repository>

....

<repositories>

<dependencies>

....

<dependency>

<groupId>org.viafirma</groupId>

<artifactId>viafirma-client</artifactId>

<version>2.14.3</version>

</dependency>

....

</dependencies>

Instalación a través de Maven

25InstalaciónatravésdeMaven

A través de una librería .dll

.Net

26.Net

En el caso de utilizar este tipo de instalación del SDK, en el kit de integración se incluyen las .dll necesarias para que laaplicación pueda consumir la api de viafirma platform.

BouncyCastle.Crypto.dllDotNetOpenId.dlllog4net.dllViafirmaClientDotNet.dll.

Por otro lado, también necesitaremos añadir el directorio viafirma a la ráiz de su solución, que contiene los ficheros:

Default.aspx: con los métodos que se ejecutarán cuando el proceso de autenticación o firma finalice.viafirmaStyle.css: con la apariencia que viafirma adoptará para el proceso de autenticación o firma. Este css puedeser adaptado a la identidad corporativa de la aplicación cliente, ver más

Se puede obtener el kit de integración a través del siguiente enlace SDK .Net.

Instalación a través de librerías .dll

27Instalaciónatravésdelibrerías.dll

https://github.com/viavansi/viafirma-platform-example-dotnet/tree/master/viafirma

Lo primero que debemos hacer para utilizar viafirma platform a través de cualquiera de las SDK, es inicializar el clientecon una serie de parámetros. A partir de entonces podremos realizar los distintos acciones sobre la plataforma.

Los métodos disponibles para la inicialización del cliente, son los siguientes:

Inicialización JavaInicialización .Net

Inicialización del cliente

28Inicializacióndelcliente

Métodos disponibles para la inicialización:

importorg.viafirma.cliente.ViafirmaClientFactory;

ViafirmaClientFactory.init(urlViafirma,urlViafirmaWS)

ViafirmaClientFactory.init(urlViafirma,urlViafirmaWS,urlApplication)

ViafirmaClientFactory.init(urlViafirma,urlViafirmaWS,urlApplication,apiKey,apiPass)

ViafirmaClientFactory.init(urlViafirma,urlViafirmaWS,apiKey,apiPass)

ViafirmaClientFactory.init(properties)

urlViafirma: (String) Url pública en la que se encuentra viafirma platform (Visible por los usuarios finales).urlViafirmaWS: (String) Url privada de viafirma platform para acceso a los servicios web.urlApplication (String) Url de la aplicación cliente, parámetro opcional y utilizado para el skin en caso de que no seadetectada automáticamente la URL.apiKey: (String) Identificador de acceso al servicio web.apiPass: (String) Contraseña de acceso al servicio web.properties: (java.util.Properties) listado de propiedades disponibles con variables de inicialización.

PARAM_CONFIG_VIAFIRMA_CLIENT: mediante este parámetro podremos indicarle una cadena deconfiguración con el siguiente formato:

properties.put(Constantes.PARAM_CONFIG_VIAFIRMA_CLIENT,URL_VIAFIRMA+";"+URL_VIAFIRMA_WS+";"+API_KEY+";"+API_PASS);

PARAM_MAX_SIZE: para indicar el límite de tamaño (en bytes) del documento a firmar, por defecto 52428800Bytes (50MB).PARAM_URL_PROVIDER_VIAFIRMA: Url pública en la que se encuentra Viafirma (Visible por los usuariosfinales)PARAM_URL_CONECTOR_FIRMA_RMI: Url privada de viafirma para acceso a los servicios web.PARAM_URL_APLICACION: Url de la aplicación cliente, parámetro opcional y utilizado para el skin en casode que no sea detectada automáticamente la URL.PARAM_VIAFIRMA_CLIENT_APP_ID: Identificador de acceso al servicio web.PARAM_VIAFIRMA_CLIENT_APP_PASS: Contraseña de acceso al servicio web.

Inicialización Java

29InicializaciónJava

Métodos disponibles para la inicialización:

usingViafirma;

ViafirmaClientFactory.Init(urlViafirma,urlViafirmaWS)

ViafirmaClientFactory.Init(urlViafirma,urlViafirmaWS,apiKey,apiPass)

ViafirmaClientFactory.Init(urlViafirma,urlViafirmaWS,apiKey,apiPass,maxFileSize)

ViafirmaClientFactory.Init(urlViafirma,urlViafirmaWS,maxFileSize)

ViafirmaClientFactory.init(configProperties)

urlViafirma: (String) Url pública en la que se encuentra viafirma platform ( Visible por los usuarios finales).urlViafirmaWS: (String) Url privada de viafirma platform para acceso a los servicios web. automáticamente la URL.apiKey: (String) Identificador de acceso al servicio web.apiPass: (String) Contraseña de acceso al servicio web.maxFileSize: (int) El tamaño maximo permitido para firmar un archivo se ajusta en megabytes.configProperties: (Viafirma.ConfigProperties) listado de propiedades disponibles con variables de inicialización.

MaxFileSizeToSign: para indicar el límite de tamaño (en MB) del documento a firmar, por defecto 52428800Bytes (50MB).ViafirmaPublicUrl: Url pública en la que se encuentra Viafirma (Visible por los usuarios finales)ViafirmaWSUrl: rl privada de viafirma para acceso a los servicios web.ReturnUrl: Url de la aplicación cliente, parámetro opcional y utilizado para el skin en caso de que no seadetectada automáticamente la URL.ApplicationID: Identificador de acceso al servicio web.ApplicationPass: Contraseña de acceso al servicio web.

Inicialización .Net

30Inicialización.Net

La página donde se solicita el certificado digital al usuario final reside en viafirma platform. Sin embargo, a través deCSS podremos conseguir que el usuario no aprecie un cambio de interfaz, de forma que el salto de la aplicación aviafirma platform parezca transparente a nivel estético, manteniendo en todo momento el look & feel de la aplicaciónoriginal.

Debido a las amplias capacidades de abstracción de viafirma platform, se permite al integrador modificar la capa clienteal gusto de sus necesidades. Esta operación será realizada mediante hojas de estilo (CSS). Simplemente con colocarun fichero llamado “viafirmaStyle.css” en el directorio raíz de la aplicación, viafirma platform automáticamente sevisualizará con el aspecto configurado por esta hoja de estilo.

Copiar viafirmaStyle.css, disponible en las aplicaciones de ejemplo, en el directorio raíz de la aplicación que vaya aintegrar con viafirma platform. La página en la que se cargará el applet de viafirma platform, o en caso de no estardiponible el applet, en la página de selección de aplicaciones de firma, mostrará el aspecto que haya sido definido enesta CSS.

CSS de ejemplo en aplicación JavaCSS de ejemplo en aplicación .Net

A continuación un ejemplo más de hoja de estilo:

body

background:#fff;margin:0;padding:0;

#global

background:#fff;padding-top:0;width:520px;

#cabecera

background:none;height:87px;

#cabecerah1a

background:url(./images/layout/cabecera2.png)no-repeat100%0;height:87px;width:475px;

#contenido

background:none;

#cuerpobackground:none;

Apariencia

Hoja de Estilos (CSS)

Ejemplo de CSS

31Apariencia

https://github.com/viavansi/viafirma-platform-example-java/blob/master/src/main/webapp/css/viafirmaStyle.css

https://github.com/viavansi/viafirma-platform-example-dotnet/blob/master/css/viafirmaStyle.css

#ayuda

background:none;padding-left:8px;

padding-left:120px;

#ayuda.ayudah2

left:15px;

*html#ayuda.ayudah2

#pie

background:none;

Del mismo modo que se utiliza el viafirmaStyle.css, existe la posibilidad de utilizar un viafirmaMobileStyle.css, el cualaplicaría únicamente a dispositivos móviles Android, y Iphone. Tan solo sería necesario colocar este ficheroviafirmaMobileStyle.css junto al viafirmaStyle.css en el directorio raíz de la aplicación.

Viafirma platform ofrece la posibilidad de cargar dos skins diferentes del applet.

default skin (naranja):

blue skin:

Por defecto la configuracion del applet siempre estará en color naranja (default), y para mostrar el applet en color azulse puede optar por dos vías:

Hoja de Estilos para dispositivos móviles (CSS)

Skin del Applet

32Apariencia

Modificar la configuración en servidor (viafirma platform)Informarlo vía API (mediante uso de Policies)

En el primer caso, los cambios a realizar serían los siguientes:

Editar las siguientes páginas:

/autenticacion/viafirmaV1AppletLogin.xhtml/firma/viafirmaV1AppletSign.xhtml

e indicar en ambos casos el siguiente recurso para pulpcore_assets:

pulpcore_assets="$conextPath/includes/appletViafirmaV3/templateBlue.zip";

En el segundo caso, integración via API, se incluye un extracto de la documentación de integradores, donde sedescribe cómo personalizar el aspecto del applet medianto el uso de Policies.

Param name = APPLET_STYLEDescripción = Permite cargar el applet con un skin específico.Tipo = StringValores permitidos = viafirmaAssets o templateBlueVersión de Applet = desde v3.4.6Versión de java-client = desde v2.9.68Versión de viafirma-platform = desde 3.5.4

Además de las hojas de estilo personalizadas es posible definir en la plataforma una hoja de estilos común a todas lasintegraciones, por defecto, esta hoja de estilos está vacía, para que sea cada integración la que defina su propia hojadesde cero.

Esta hoja predefinida se encuentra dentro de la propia aplicación de platform ($deploy_path/includdes/viafirma-v3/css/defaultViafirmaStyle.css), un ejemplo de uso de la misma podría ser utilizarla para ocultar las "opciones extra"de clientes de firma, ya sea alguna en concreto o todas. Si la CSS personalizada contuviera la siguiente información:

#extra-options

display:none;

Se ocultarían todas las opciones de clientes de firma diferentes al applet.

Está hoja de estilos predefinida tiene menos prioridad que las hojas de estilos personalizadas de las integraciones, porlo que siempre se tomarán los estilos que sobrescriban las aplicaciones integradoras.

Estilos predefinidos para todas las integraciones

33Apariencia

A continuación se muestran algunos ejemplos de integración con viafirma platform.

Página con llamada a viafirma:

Tras invocar la autenticación o firma con viafirma platform, se hace push del applet desde servidor y la página que lorenderiza se carga con las CSS contenidas en el fichero viafirmaStyle.css de la aplicación que la invocó.

Página contenedora del applet:

Ejemplos de integraciones

Ejemplo 1: virtual office

34Apariencia

Como se puede observar en la imagen, la cabecerra mantiene el mismo aspecto que la página principal de la aplicaciondesde la que se invocó a viafirma platform.

Otros bloques configurables en la hoja de etilo son las secciones de ayuda y el pie.

En este caso la integracion se realiza in-house, Tanto la aplicación de terceros, etitulo, como viafirma-plattform, estáninstaladas en el mismo servidor del cliente.

Ilustración 5 ejemplo de página que contiene la llamada a viafirma

Ejemplo 2: e-título: portal del titulado

35Apariencia

En este caso, la sección de ayuda la dejan sin contenidos.

Ilustración 6 ejemplo de integración sin pie ni ayuda

Ejemplo 3: RA de avansi: integración tipo "pop-up"

36Apariencia

Existen otras integraciones en las que los integradores prefieren hacer uso de javascript que embeba en un pop-up,dejado a la aplicación de terceros en un segundo plano.

El efecto es totalmente distinto a los ejemplo anteriores, tal y como se puede apreciar en los siguientes ejemplos.

ejemplo de página que contiene la llamada a viafirma:

ejemplo de llamada a viafirma:

37Apariencia

La siguiente captura muestra un mecanismo distinto, en este caso, un pop-up en primer plano donde sólo se muestra elapplet de viafirma platform, quedando en segundo plano, deshabilitada, la aplicación de terceros que la invocó.

ejemplo applet de viafirma mostrado en pop-up:

En este ejemplo de integracion son Sanitas, se opta por cargar el applet en color azul, cuya skin viene precargada entodas las distribuciones de viafirma platform.

ejemplo de integración con skin alternativo:

Ejemplo 4: Sanitas: uso de skin alternativo

38Apariencia

En este ejemplo de integración con SERGAS (Servicio Gallego de Salud), se opta por cargar el applet en color gris.Además se personaliza la cabecera con los respectivos logos de la Xunta de Galicia y SERGAS.

ejemplo de skin alternativo para SERGAS:

En este caso la hoja de estilos utilizada para lograr este aspecto ha sido la siguiente:

Ejemplo 5: SERGAS (Xunta de Galicia)

39Apariencia

/*=GLOBALS------------------------------------------------*/

body

background:#fffurl(bg.png)repeat-x00;

color:#666;

margin:0;

padding:0;

font-family:Arial,Helvetica,sans-serif;

font-size:0.75em;

body,button,input,textarea,select

font:12px/1.231Arial,Helvetica,sans-serif;

#global

margin:0auto;

width:990px;

.layout-wrapper,

#cuerpo,

#ayuda

margin:0auto;

hr

display:none;

label

display:inline;

a

color:#fff;

font-weight:bold;

text-decoration:none;

a:focus,a:hover

text-decoration:underline;

p.volver

background:#666;

color:#fff;

display:inline-block;

padding:0.25em0.75em;

p.volvera

.downloadFilesToSigna

background:#ddd;

border:1pxsolid#ccc;

color:#444;

display:inline-block;

font-weight:bold;

font-size:0.9em;

margin-right:1em;


position:relative;


.downloadFilesToSigna:focus,.downloadFilesToSigna:hover

background:#ccc;

40Apariencia

.downloadFilesToSignul

border-top:1pxsolid#ccc;

margin:001.5em0;

padding:0;

.downloadFilesToSignulli

border-bottom:1pxsolid#ddd;

list-style-type:none;


.downloadFilesToSignullia,

.downloadFilesToSignullia:focus,

.downloadFilesToSignullia:hover,

.downloadFilesToSignullia:active

background:none;

border:0;

margin:0;

padding:0;

#cabecerap,

hr.separador,

#ayuda

display:none;

/*=HEADER--------------------------------------------------------------*/

#cabecera

border:0none;

width:990px;

#cabecerah1

background:url(logo.png)no-repeat50%50%;

height:50px;

margin:35pxauto50pxauto;

padding:0;

width:287px;

#cabecerah1a

display:block;

height:100%;

text-indent:-999em;

width:100%;

#pie

clear:left;

/*=CONTENT-----------------------------------------------------*/

#contenido

#cuerpo.texto

background:#F2F2F2;

color:#6E6E6E;

border:1pxsolid#A0A0A0;

font-size:14px;

margin:0auto2emauto;

padding:0.25em1em;


width:500px;

41Apariencia

42Apariencia

En la página de selección de aplicaciones con la cual seleccionar el certificado a firmar o autenticar, podemos indicarlemediante CSS las opciones que queremos que aparezcan.

Por defecto aparecerán todas las opciones de aplicaciones posibles teniendo en cuenta el navegador y sistemaoperativo.

Ocultar opciones de aplicaciones de firma

43Ocultaropcionesdeaplicacionesdefirma

Por ejemplo:

Windows 7 e Internet Explorer; aparecerán todas las opciones menos Firmar con viafirma Windows 10.Windows 10 y Google Chrome; aparecerán todas las opciones menos el applet.Linux y Mozilla Firefox; solo aparecerá la opción de Firmar con cliente JNLP.Macos y Safari; aparecerán las opciones de applet y Firmar con cliente JNLP.

Si queremos ocultar algunas de las opciones que aparecen por defecto, dependiendo del sistema operativo ynavegador, podemos hacerlo mediante CSS, combinando las siguientes opciones dentro del fichero viafirmaSyle.css.

viafirmaStyle.css

li#jnlpOption

display:none!important;

li#windows10AppOption


li#windowsAppdMobile


#applet


En el caso del código anterior, estaríamos ocultando todas las opciones.

Con el siguiente código añadido al fichero viafirmaStyle.css, ocultaremos todas las opciones menos la de Autenticarcon viafirma Windows 10.

viafirmaStyle.css

li#jnlpOption


li#windows10AppOption

display:block!important;

li#windowsAppdMobile


#applet


Indicar opciones de aplicaciones a mostrar

Ejemplo


Se mostraría de la siguiente forma:


Como parte de las distintas operaciones que se pueden llevar a cabo en viafirma platform, desde las sdk podremosinvocar métodos con parámetros de configuración para realizar una autenticación con la aplicación que deseemosintegrar.

//Obtenemoslainstanciadelclientequepreviamentehasidoinicializado

ViafirmaClientviafirmaClient=ViafirmaClientFactory.getInstance();

//Iniciamoslaautenticaciónindicandolaurideretorno.

Policypolicy=newPolicy();

//OptionalRequest

viafirmaClient.addOptionalRequest(OptionalRequest.AUTO_SEND);

viafirmaClient.authWithPolicy(policy,request,response,"/viafirmaClientResponseServlet");

Cuando el usuario pulse sobre el enlace “Solicitar autenticación” el usuario será redirigido a viafirma platform, donde sele solicitará su certificado digital. La plataforma validará y tratará el certificado del cliente y retornará el resultado de laautenticación a la aplicación que estamos desarrollando. En el ejemplo le indicamos a viafirma platform que la url deretorno (donde viafirma debe mandarnos el resultado de la autenticación) es /viafirmaClientResponseServlet .

En esta ubicación la aplicación que estamos integrando deberá tener un un servlet escuchando la respuesta que nosretornará viafirma platform para su correspondiente procesado. Podemos encontrar un ejemplo de ese servlet en laaplicación de ejemplo, donde, en este caso, el método authenticateOK es el que recuperaría los datos del usuarioautenticado. En el subapartado de procesar respuesta Java se explica detalladamente cada método.

//IniciamoselprocesodeautenticarredireccionandoelusuarioaViafirma.

ViafirmaClientclienteViafirma=ViafirmaClientFactory.GetInstance();

//Policy

policypol=newpolicy();

//OptionalRequest

viafirmaClient.AddOptionalRequest(ViafirmaClient.AUTO_SEND);

clienteViafirma.AuthWithPolicy(pol)

Con este simple código ya conseguimos que nuestra aplicación ASP.NET utilice viafirma platform para que sea ésta laresponsable de solicitar, validar, recuperar el certificado del usuario y autenticar.

Una vez que el proceso termine, viafirma platform devolverá el control a la aplicación ASP.NET retornando todos los

Operaciones de Autenticación

Java

.Net

46OperacionesdeAutenticación

https://github.com/viavansi/viafirma-platform-example-java/blob/master/src/main/java/com/viafirma/examples/ViafirmaClientResponseServlet.java

datos obtenidos del certificado.

Una vez que viafirma platform obtenga los datos del certificado de usuario invocará al métodoProcessResponseAutenticaction, que se encuentra en el fichero Default.aspx dentro del directorio viafirma. Lo únicoque tendremos que hacer es sobreescribir dicho método con el comportamiento deseado y recuperar todos los datosdel usuario. Podemos encontrar un ejemplo del fichero Default.aspx en la aplicación de ejemplo. En el subapartado deprocesar respuesta .Net se explica detalladamente cada método.

En todos los casos, a la política de autenticación (policy) le podemos añadir diferentes opciones de autenticación; comopuede ser, por ejemplo, filtrar los certificados a mostrar a la hora de seleccionar uno para realizar el proceso deautenticación. Esta política de autenticación y otras más, se detallan en el apartado de Policy.

Existen parámetros que se le pueden pasar de manera opcional a la plataforma de viafirma platform para modificar elcomportamiento de la operación. Se detallan en el apartado Optional Request.

Políticas de autenticación

Peticiones opcionales

47OperacionesdeAutenticación

https://github.com/viavansi/viafirma-platform-example-dotnet/blob/master/viafirma/Default.aspx

Servlet en la aplicación de ejemplo.

Para procesar la respuesta de viafirma platform nos ayudaremos de un servlet que tendremos a la eschucha en laaplicación, que deberá extender de org.viafirma.cliente.ViafirmaClientServlet y tendrá que sobrescribir los siguientesmétodos:

authenticateOK: viafirma platform ha recuperado correctamente los datos del certificado digital del usuario final ynos lo devuelve para que nuestra aplicación los procese y decida qué hacer con ellos.

cancel: método invocado por viafirma platform en su respuesta cuando el usuario final ha cancelado el procesovoluntariamente (pulsó sobre el botón “cancelar”).

error: viafirma platform ha lanzado algún error y la autenticación no ha podido ser completada con éxito. Nuestraaplicación procesará el mensaje de error y poder continuar con la lógica necearia. Ej. “CA no reconocida,certificado revocado, certificado caducado, etc.”.

En la respuesta recibida, se invocará al método ViafirmaClientResponse, que se encuentra dentro del directorioViafirma. Este método será sobrescrito para implementar la lógica de negocio deseada con los datos recuperados delcertificado digital, los cuales vendrán contenidos en el objeto UsuarioGenericoViafirma.

En el siguiente ejemplo, si la autenticación ha sido correcta, guardamos los datos del usuario en la request yredireccionamos al usuario final a una página de destino.

publicclassViafirmaClientResponseServletextendsViafirmaClientServlet

@Override

publicvoidauthenticateOK(UsuarioGenericoViafirmausuario,HttpServletRequestrequest,HttpServletResponseresponse)

//Lógicaespecíficadecadaaplicaciónparagestionarelresultadodelaautenticación

try

request.setAttribute(“usuarioAutenticado”,usuario);

request.getRequestDispatcher("/resultadoAutenticacion.jsp").forward(request,response);

catch(ServletExceptione)

e.printStackTrace();

catch(IOExceptione)


@Override

publicvoidcancel(HttpServletRequestrequest,HttpServletResponseresponse)

//Gestióndecancelacióndelusuarioalautenticarofirmar

request.setAttribute(“error”,“Elusuariohacanceladolaautenticación”);

request.getRequestDispatcher(“/resultadoAutenticacion.jsp”).forward(request,response);

@Override

publicvoiderror(CodigoErrorcodError,HttpServletRequestrequest,HttpServletResponseresponse)

//Gestióndeerroralautenticarofirmar

request.setAttribute(“codError”,codError);

request.getRequestDispatcher(“/resultadoAutenticacion.jsp”).forward(request,response);

Procesar respuesta Java

48ProcesarrespuestaJava


49ProcesarrespuestaJava

Clase en la aplicación de ejemplo

Para procesar la respuesta de viafirma platform nos ayudaremos de la clase Default.aspx dentro del directorio viafirmaque tendremos a la eschucha en la aplicación, que deberá importar la calse Viafirma.ViafirmaClient , y tendrá queimplementar los siguientes métodos:

ProcessResponseAutenticaction: viafirma platform ha recuperado correctamente los datos del certificado digital delusuario final y nos lo devuelve para que nuestra aplicación los procese y decida qué hacer con ellos. Dentro deeste método se controla los siguientes aspectos:

cancel: respuesta cuando el usuario final ha cancelado el proceso voluntariamente (pulsó sobre el botón“cancelar”).

error: viafirma platform ha lanzado algún error y la autenticación no ha podido ser completada con éxito.Nuestra aplicación procesará el mensaje de error y poder continuar con la lógica necearia. Ej. “CA noreconocida, certificado revocado, certificado caducado, etc.”.

En la respuesta recibida, redirigirá a la página indicada. En este método son recuperados los datos del certificadodigital, los cuales vendrán contenidos en el objeto UsuarioGenericoViafirma.

En el siguiente ejemplo, si la autenticación ha sido correcta, guardamos los datos del usuario en la request yredireccionamos al usuario final a una página de destino.

<%@PageLanguage="C#"Inherits="Viafirma.ViafirmaClient"%>

<%--

PáginaparalagestióndelacomunicaciónconViafirma.

Nota:Estapáginanuncaseravisibleporelusuario,soloesutilizadaparagestionarlasrefireccionesyconfiguraciónespecífica.

--%>

<scriptrunat="server">

//AlgargarlapáginaserealizatodoelprocesadoparaelintercambiodeinformaciónconViafirma.

publicvoidPage_Load(Objectsender,EventArgse)

//Esposibleenviarciertosparametrosalservidorenestepuntoparaobteneralgunasfuncionalidadesadicinales

//this.AddOptionalRequest(PEM);//Obligaaqueelservidorenvíeelcertificadofirmante

//this.AddOptionalRequest(AUTO_SEND);//Silaplataformadetectasolouncertificado,loutilizapordefecto

try

ProcessViafirma();

catch(InvalidOperationExceptionexc)

System.Console.WriteLine(exc.Message);

StringmessageError=exc.Message;

Uriurl=newUri(HttpContext.Current.Request.Url,HttpContext.Current.Response.ApplyAppPathModifier("~/errorPage.aspx?errorMessage="+exc.Message));

HttpContext.Current.Response.Redirect(url.AbsoluteUri);

overridepublicvoidProcessResponseAutenticaction(Viafirma.Estadoestado,Viafirma.UsuarioGenericoViafirmausuario)

Procesar respuesta .Net

50Procesarrespuesta.Net


Viafirma.Log.Debug("AutenticaciónViafirmarealizadacorrectamente.");

//Aquíyatenemostodoslosdatosasociadosalcliente.yredireccionaralusuarioalapáginadestino

//considerandoelusuarioyaautenticado.

if(Viafirma.Estado.OK==estado)

Session["resultadoAutenticacion"]=usuario;

Uriurl=newUri(HttpContext.Current.Request.Url,HttpContext.Current.Response.ApplyAppPathModifier("~/resultadoAutenticacion.aspx"));


elseif(Viafirma.Estado.FAIL==estado)

stringerror=getCodError();

stringmensage=getMessage();

System.Console.WriteLine("HayproblemasalrealizarlaverificacionCodError="+error+"Mensage="+mensage);

Uriurl=newUri(HttpContext.Current.Request.Url,HttpContext.Current.Response.ApplyAppPathModifier("~/"));


elseif(Viafirma.Estado.CANCEL==estado)

System.Console.WriteLine("Elusuariocancelólaoperación");



else

thrownewException("Sehaproducidounerroralautenticar.");

overridepublicvoidProcessResponseSign(Viafirma.Estadoestado,Viafirma.FirmaInfoViafirmafirma)

Viafirma.Log.Debug("FirmaViafirmarealizadacorrectamente.");

//Aquíyatenemostodoslosdatosasociadosalclienteyasufirma.

//redireccionamosalusuarioalapáginadestinoconsiderandoelusuarioyahafinalizadolafirma.


Session["resultadoFirma"]=firma;

Uriurl=newUri(HttpContext.Current.Request.Url,HttpContext.Current.Response.ApplyAppPathModifier("~/resultadoFirma.aspx"));





//Hayproblemasalvalidar.

System.Console.WriteLine("HayproblemasalrealizarlafirmaCodError="+error+"Mensage="+mensage);

thrownewException("HayproblemasalrealizarlaverificacionCodError="+error+"Mensage="+mensage);





else

System.Console.WriteLine("Procesocanceladoporelusuario");

//thrownewException("Procesocanceladoporelusuario");

</script>

51Procesarrespuesta.Net

Desde la versión 3.15 de viafirma platform se soporta una modalidad (inicialmente solo para windows) que permiteutilizar directamente Viafirma Desktop (versión mínima: 1.6.0) invocando la aplicación por protocolo. Para ello, laestrategia reside en la preparación inicial de la operación mediante una invocación a servicios REST, devolviendo elservidor un código de operación y un enlace para abrir la aplicación por protocolo. Al abrirlo la aplicación pierde elcontrol de lo que ocurre, por lo que debe iniciar un polling Javascript a otro servicio REST donde consulta el estado dela operación, sabiendo si está finalizada o no, con errores, etc. y se exponen funciones que son invocadasautomáticamente (callback) en caso de error, éxito, cancelación, etc., pasando un objeto JSON con los datos de laoperación.

Podemos encontrar un ejemplo de uso de esta lógica de invocación directa en la aplicación de ejemplo.

Como se verá en ese ejemplo de código, se realiza una preparación de la operación, devolviendo el servidor un objetocon el código de operación y el enlace para abrir la aplicación.



//NowusethenewprepareAuthForDirectDesktopmethod

AuthOperationRequestauthRequest=newAuthOperationRequest();//authRequest.setAutoSend(true);

CertFiltercertFilter=newCertFilter();

//Example:useonlyFNMTcertificates

certFilter.setOperator(FilterOperator.contains);

certFilter.getFilterValues().add("FNMT");

//Morechances:CAFilter,NumberUserIdFilter

CertFiltercaFilter=newCertFilter();

caFilter.setOperator(FilterOperator.contains);

caFilter.getFilterValues().add("FNMT");

CertFilternumberUserIdFilter=newCertFilter();

numberUserIdFilter.setOperator(FilterOperator.contains);

numberUserIdFilter.getFilterValues().add("4");

//authRequest.setCertFilter(certFilter);

//authRequest.setCaFilter(caFilter);

//authRequest.setNumberUserIdFilter(numberUserIdFilter);

authRequest.setAutoSend(true);

authRequest.setSessionId(request.getSession().getId());

//Themethodreturnsanobjectwiththeinformationrequiredto:

//a)CreateabuttonthatopensViafirmaDesktopbyprotocol

//b)Getsthejust-preparedoperationIDtostartpollingusingJavascriot

DirectDesktopInvocationdirectCall=viafirmaClient.prepareAuthForDirectDesktop(authRequest);

StringoperationId=directCall.getOperationId();

StringviafirmaDesktopLink=directCall.getViafirmaDesktopInvocationLink();

En este código fuente se ha creado un objeto que da propiedades concretas a la operación de autenticación, y se hace

Uso Viafirma Desktop por protocolo - autenticación

Java

52UsoViafirmaDesktopporprotocolo-autenticación

https://github.com/viavansi/viafirma-platform-example-java/blob/master/src/main/webapp/examples/exampleAuthenticationViafirmaDesktop.jsp

la llamada utilizando viafirma client, obteniendo, como se ve, el operationId y el link para abrir la aplicación. En eseobjeto se pueden añadir tres tipos de filtros distintos: CA Filter (filtra por CAs emisoras de certificados), Number User Id(filtra por el serial number del certificado) y el genérico que filtra por cualquier valor dentro del certificado. El uso de losfiltros de CA y Serial Number requiere una versión mínima de Viafirma Desktop = 1.6.7.

Dentro del objeto de autenticación se incluye el sessionId del usuario; para evitar riesgos de seguridad el sistemacomprobará que la recuperación de los datos de la autenticación se haga con la misma sesión que se inició laoperación. Nuestra página ubicará un enlace para abrir Viafirma Desktop por protocolo con ese enlace, e iniciará unproceso de polling Javascript. Para ello, debemos haber incluido código Javascript en nuestra página, como elsiguiente:

<scriptsrc="<%=ConfigureUtil.getViafirmaServer()%>/viafirma.js?t=<%=System.currentTimeMillis()%>">

//IncludingthisremoteJavascriptismandatory,itincludesthepollinglogic

</script>

<script>

//Customizethisinyourownclientwebapp...thisisjustasample!

//Whenthepollingdetectsanerror,itinvokesthisfunction

functionshowError(response)

document.getElementById("loading").innerHTML="";

document.getElementById("authError").innerHTML="Ocurrióunproblemadurantelaautenticación:"+JSON.stringify(response);

//IftheusercancelstheoperationinViafirmaDesktopapp,thisfunctionisinvoked

functionshowCancel(response)


document.getElementById("authCancel").innerHTML="Laautenticaciónfuecancelada:"+JSON.stringify(response);

//Iftheauthenticationrunsok,thisfunctionisinvoked-customizeitwithyourownlogic

functionshowSuccess(response)

window.location.replace("./exampleAuthenticationViafirmaDesktopResult.jsp?operationId="+response.operationId);

//IfViafirmaDesktopisnotloaded,thisfunctionisinvoked

functionshowUnloaded()

alert("ViafirmaDesktopnoencontrado");

document.getElementById("loading").style="display:none;";

document.getElementById("authSuccess").innerHTML=

"<p>ViafirmaDesktopnohasidocargado,aquísepuedeincluircódigoparagestionarlainstalación,instrucciones,etc.</p>";

//Hereweinitializetheviafirma.jspolling

functioninitAuth()

document.getElementById("authButton").style="display:none;";

document.getElementById("loading").innerHTML="<imgsrc='../images/icons/ajax-loader.gif'/>";

//StarttheviafirmaJSclient:watchthestatusofagivenoperationId

//-iftheoperationfails,"errorCallback"willbecalled

//-iftheoperationiscancelled,"cancelCallback"willbecalled

//-iftheoperationiscompleted:"successCallback"willbecalled

//-ifViafirmaclientisnotloadedafterunloadedTimeseconds:"unloadedCallback"

viafirma.init(

//Hereweinclude

operationId:"<%=operationId%>",

viafirmaUrl:"<%=ConfigureUtil.getViafirmaServer()%>/",

unloadedTime:30,

errorCallback:function(response)

showError(response);

,

successCallback:function(response)

showSuccess(response);

,

cancelCallback:function(response)

showCancel(response);

,


unloadedCallback:function(response)

showUnloaded();

);

</script>

Obsérvese que se ha incluido una query param al cargar el Javascript remoto viafirma.js, para evitar posiblesproblemas de caché en los usuarios en el caso de que este Javascript se modifique en futuras versiones.

Podemos encontrar un ejemplo de uso de esta lógica de invocación directa en la aplicación de ejemplo aspx - aspx.cs

El código es muy similar al ejemplo anterior Java, realizando una preparación de la operación, devolviendo el servidorun objeto con el código de operación y el enlace para abrir la aplicación.

Code behind:


publicasyncvoidAutenticar_ClickAsync(objectsender,EventArgse)



AuthOperationRequestrequest=newAuthOperationRequest();

request.AutoSend=true;

desktopInvocation=awaitclienteViafirma.PrepareAuthForDirectDesktopAsync(request);

En este código fuente se ha creado un objeto que da propiedades concretas a la operación de autenticación, y se hacela llamada utilizando viafirma client, obteniendo, como se ve, el operationId y el link para abrir la aplicación. Nuestrapágina ubicará un enlace para abrir Viafirma Desktop por protocolo con ese enlace, e iniciará un proceso de pollingJavascript. Para ello, debemos haber incluido código Javascript en nuestra página, como el siguiente:

<formid="form1"runat="server">

<%if(desktopInvocation==null)%>

<p>

<asp:buttonID="autenticarBoton"runat="server"

Text="Iniciarprocesodeautenticación"OnClick="Autenticar_ClickAsync"

Width="245px"/>

</p>

<%

else

%>

<scriptsrc="<%=Viafirma.ViafirmaClientFactory.GetInstance().UrlPublica%>/viafirma.js">

//IncludethisremoteJavascriptismandatory,itincludesthepollinglogic

</script>

<script>




.NET


https://github.com/viavansi/viafirma-platform-example-dotnet/blob/master/loginDirectViafirmaDesktop.aspx

https://github.com/viavansi/viafirma-platform-example-dotnet/blob/master/loginDirectViafirmaDesktop.aspx.cs


document.getElementById("authError").innerHTML="Ocurrióunproblemadurantelaautenticación:"+JSON.stringify(response);




document.getElementById("authCancel").innerHTML="Laautenticaciónfuecancelada:"+JSON.stringify(response);

//Iftheauthenticationrunsok,thisfunctionisinvoked-customizeitwithyourownlogic


window.location.replace("./exampleAuthenticationViafirmaDesktopResult.jsp?operationId="+response.operationId);

//TheserverwillbeabletoretrievecertificatevalidationusingtheoperationId:

//viafirmaClient.getCertificateValidationResponse(operationId,sessionId);

//ThesessionIdwillbechecked.


functioninitAuth()

document.getElementById("authButton").style="display:none;";

document.getElementById("loading").innerHTML="<imgsrc='./images/icons/ajax-loader.gif'/>";





viafirma.init(

//Hereweinclude

operationId:"<%=desktopInvocation.OperationId%>",

viafirmaUrl:"<%=Viafirma.ViafirmaClientFactory.GetInstance().UrlPublica%>/",



,



,



);

</script>

<pid="authError"></p>

<pid="authCancel"></p>

<pid="authSuccess"></p>

<pid="loading"></p>

<pid="authButton">

<aclass="button"href="<%=desktopInvocation.ViafirmaDesktopInvocationLink%>"onClick="initAuth();">AutenticarconViafirmaDesktop</a>

</p>

<%

%>

</form>

Obsérvese que, al igual que en el caso Java, se ha incluido una query param al cargar el Javascript remoto viafirma.js,para evitar posibles problemas de caché en los usuarios en el caso de que este Javascript se modifique en futurasversiones.

Si el polling falla recibiendo un HTTP status distinto de 200/OK -la operación no ha finalizado todavía-, el objetoresponse recibido en el callback de error sólo tendrá un campo "message" y el operationId. Si la operación estáfinalizada, el objeto será de este tipo:

Especificaciones de objetos JSON de respuesta en callbacks


"operationId":"12345678",

"isFinished":true,

"isCancelled":false,

"hasErrors":true,

"isSignature":false,

"errorCode":"1",

"errorMessage":"Errordescription"

Los códigos de error son los mismos que con el resto del API. Son especialmente relevantes los códigos relacionadoscon los estados CADUCADO (código 104) y REVOCADO (código 107) de un certificado. Si la aplicación ViafirmaDesktop tiene algún problema local que comunique al servidor, se recibirá un errorCode = 2.

Si la operación ha sido cancelada, el callback de cancelación recibe un JSON como el siguiente:


"isFinished":true,

"isCancelled":true,

"hasErrors":false,

"isSignature":false

Si la operación ha acabado con éxito, la operación recibe un JSON con todos los datos del certificado y eloperationId. Esta información está en el callback Javascript successCallback, y debe hacerse llegar a la lógica deservidor. No es recomendable consumir un servicio REST interno con la información del certificado, dado que seríasencillo que un atacante impersonase a otro usuario invocando a dicho servicio, pasando información de unatercera persona. Lo recomendable es invocar a lógica de servidor con el ID de operacion, y desde la lógica deservidor utilizar el servicio de viafirma cliente determinado, o simplemente consumir el servicio REST de Platformpara descargar dicha información.

Los datos incluidos en el JSON son:

operationId: ID de operación devuelto en el primer proceso de preparación de la operaciónnumberUserId: número de identificador del usuario (NIF, cédula...)name: Nombre del usuariosurname1: Primer apellidosurname2: Segundo apellidoemail: Email del usuarioca: Autoridad de Certificación emisora (por ejemplo Fábrica Nacional de Moneda y Timbre)shortCa: Autoridad de Certificación emisora - descripción corta (por ejemplo FNMT)jobTitle: Cargo del usuariotype: Tipo de certificadocn: Common Nameorganization: Nombre de la organización / empresa del usuariocertificateProperties: lista de variables del certificado (en formato key/value)isValidated: booleano - obtiene valor true si el certificado ha sido validado correctamenteisExpired: booleano - obtiene valor true si el certificado está caducado


isRevoked: booleano - obtiene valor true si el certificado está revocado

Para poder lanzar Viafirma Desktop, el usuario debe tener la aplicación instalada; si no la tiene, transcurridos unossegundos la plataforma redirigirá a la URL de descarga de la aplicación:

https://descargas.viavansi.com/viafirma/viafirmaWPFclientInstall/viafirma-desktop.exe

Este comportamiento se puede personalizar en la aplicación cliente, para poder mostrar algún tipo de indicación en laaplicación, redirigir a una URL distinta (por ejemplo, a una versión de Viafirma Desktop específicamente compilada parauna organización), etc.

Para ello, en la invocación a viafirma.init() podemos pasar dos parámetros adicionales:

unloadedCallback: una función que recibirá un callback si la aplicación no se ha ejecutado y ha descargado losdatos de la aplicación transcurridos N segundos, siendo N el parámetro unloadedTime.unloadedTime: tiempo que debe transcurrir para invocar la llamada a unloadedCallback. Si no es especifica, pordefecto el valor es 10 segundos.

Otra opciones de customización


https://descargas.viavansi.com/viafirma/viafirmaWPFclientInstall/viafirma-desktop.exe

Desde la versión 3.16 de viafirma platform se soporta una modalidad de autenticación basada en SSL client auth(handshake entre el servidor y el navegador por el cual se solicita al cliente un certificado digital). Para utilizarlo, esnecesario disponer del módulo Viafirma ssl-authenticator. En este caso, no aplican los parámetros de Policy deautenticación; el usuario podrá escoger cualquier certificado de usuario, y se devolverán los datos a la aplicación, lacual podrá decidir qué hacer con el usuario (permitirle acceder, denegar acceso, verificar si la Autoridad de Certificaciónes adecuada, etc.).

El proceso que se sigue es el siguiente:

La aplicación cliente prepara la operación de autenticación: se invoca a Platform recibiendo como respuesta unoperationId y una URL de redirección. Como parámetro en la llamada, la aplicación cliente pasa una URL decallback, a la cual se hará un GET añadiendo como query param el operationId.La aplicación cliente recibe como respuesta el operationId y la URL a la que redirigir. Por seguridad, esrecomendable almacenar este operationId unido, por ejemplo, a la IP o ID de sesión, de forma que se puedecomprobar en el último paso que estos valores no han cambiado.Se redirige al usuario a la URL de redirección, donde se le pide el certificado de usuario.El usuario escoge su certificado y la plataforma lo valida, almacenando esta información de validación.Posteriormente, redirige al usuario a la URL de callback pasada en el primer paso, y añadiendo como query paramoperationId=XXXX.La aplicación cliente recibe esta llamada, recoge el operationId, y lo utiliza para pedirle a Viafirma Platform losdatos de validación. En este paso también podría realizar una verificación, por ejemplo, de que la IP o el sessionIdson los que había en el primer paso para ese operationId.Una vez recibidos los datos del certificado del usuario, la aplicación cliente continúa con su propia lógica denegocio.

Para hacer esta integración, se pueden utilizar los clientes Java o .NET, o realizar directamente llamadas a serviciosREST.


Como se verá en ese ejemplo de código, se realiza una preparación de la operación, devolviendo el servidor un objetocon el código de operación y el enlace al que redirigir al usuario.

ConfigureUtil.initViafirmaClient();


SSLClientAuthOperationResponseresult=viafirmaClient.prepareSSLClientAuthentication(callbackURL);

StringredirectURL=result.getRedirectURL();

response.sendRedirect(redirectURL);

Autenticación sin cliente rico (applet, Viafirma Desktop...):SSL client auth

Java

58Autenticaciónsinappletoclientesricos:SSLclientauth

https://github.com/viavansi/viafirma-platform-example-java/blob/master/src/main/webapp/examples/exampleAuthenticationSSLClientAuth.jsp

La callbackURL es una URL interna de la aplicación a la que se llamará recibiendo el operationId como query param.En el caso de la aplicación de ejemplo, esta URL es exampleAuthenticationSSLClientAuthResult.jsp, que contiene lasiguiente lógica:

ConfigureUtil.initViafirmaClient();


StringoperationId=(String)request.getParameter("operationId");

CertificateValidationResponsecertificateValidationResponse=viafirmaClient.getCertificateValidationResponse(operationId,null);

Pudiendo ya hacer uso de los valores incluidos en CertificateValidationResponse.

En proceso.

.NET

59Autenticaciónsinappletoclientesricos:SSLclientauth

Como parte de las distintas operaciones que se pueden llevar a cabo en viafirma platform, desde las sdk podremosinvocar métodos con parámetros de configuración para realizar una firma con la aplicación que deseemos integrar.

A parte de la firma tradicional en la que el usuario interviene para seleccionar el certificado con el que firmar, tambiénexiste un tipo de firma en la que no es necesario que intervenga. Esta última firma, a la que llamaremos firma enservidor, viene ya configurada para que firme con un certificado en concreto.

Firma con intervención de usuarioFirma sin intervención de usuarioObtener información de firmaFirma en loteFirma en buclePromoción de firmaSellado de tiempo

Operaciones de Firma

60OperacionesdeFirma

Como parte de las distintas operaciones que se pueden llevar a cabo en viafirma platform, desde las sdk podremosinvocar métodos con parámetros de configuración para realizar una firma con intervención de usuario (firma en cliente)con la aplicación que deseemos integrar.

Antes de invocar a la página de selección de certificados, debemos indicarle a la SDK la operación que vamos arealizar y las diferentes opciones de firma que deseamos llevar a cabo.

//Instanciamoselcliente


//Tipodeformatodefirma

TypeFormatSignformat=TypeFormatSign.PAdES_BASIC;

//Tipodeficheroafirmar

TypeFiletypeFile=TypeFile.PDF;

//Tipodefirma

TypeSigntypeSign=TypeSign.ENVELOPED;

//Datosdocumentoafirmar

byte[]datosAFirmar=IOUtils.toByteArray(getClass().getResourceAsStream("/exampleSign.pdf"));

//Creamoslapolíticadefirmadefiniendolosvaloresobligatoriosmínimos


policy.setTypeFormatSign(format);

policy.setTypeSign(typeSign);

//Generamoselobjetodocumento,dondeincluiremoselbyte[]delficheroafirmar

Documentodocumento=newDocumento("firmado.pdf",datosAFirmar,typeFile,format);

//Estemétodoseráelencargadodeavisaraviafirmaplatformdequeestamospreparandounafirma,dondelepasamoslaspolíticasdelamismayeldocumentoafirmar

//Esteidentificadortemporalnoesnecesarioqueseaalmacenadoyaquesólotienevalidezduranteelprocesodefirma.

StringidTemporalFirma=viafirmaClient.prepareSignWithPolicy(policy,documento);

//Recuperamoslainstanciadelcliente



typeFormatSignformat=typeFormatSign.PAdES_BASIC;


typeFiletypeFile=typeFile.PDF;

//Tipodefirma

typeSigntypeSign=typeSign.ENVELOPED;

Firma con intervención de usuario

Preparación de la firma

Java

.Net

61Firmaconintervencióndeusuario

//Recuperamoseldocumentoafirmar.

Assemblyassembly=Assembly.GetExecutingAssembly();

Streamfs=assembly.GetManifestResourceStream("EjemploWebViafirmaClientDotNet.resources.exampleSign.pdf");

byte[]datos_a_firmar=newbyte[fs.Length];

fs.Read(datos_a_firmar,0,datos_a_firmar.Length);


policypol=PolicyUtil.newPolicy(typeFormatSign.PAdES_BASIC,typeSign.ATTACHED);

//Creamoselobjetodocumentoconlosdatosafirmar

documentodoc=newdocumento();

doc.nombre="firmado.pdf";

doc.datos=datos_a_firmar;

doc.typeFormatSign=format;

doc.tipo=typeFile;

//Registramoseldocumentoquedeseamosfirmar.Obteniendounidentificadortemporal.

//Esteidentificadortemporalnoesnecesarioqueseaalmacenadoyaquesólotienevalidezduranteelprocesodefirma.

stringidTemporalFirma=clienteViafirma.PrepareSignWithPolicy(pol,doc);

En todos los casos, a la política de firma (policy) le podemos añadir diferentes opciones de firma; como puede ser, porejemplo, filtrar los certificados a mostrar a la hora de seleccionar uno para realizar el proceso de firmado. Esteparámetro de política de firma y otras más, se detallan en el apartado de Policy.

Existen parámetros que se le pueden pasar de manera opcional a la plataforma de viafirma platform para modificar elcomportamiento de la operación. Se detallan en el apartado Optional Request.

Con el identificador temportal de firma (idTemporalFirma) que se ha obtenido en la operación de preparación de firma,podemos solicitar la operación de firma, la cual mostrará las distintas aplicaciones disponibles para seleccionar elcertificado con el que realizar la firma.

//Solicitamoslafirma

viafirmaClient.solicitarFirma(idTemporal,request,response,

"/viafirmaClientResponseServlet");

La plataforma validará y tratará el certificado del cliente y retornará el resultado de la firma a la aplicación cliente queestamos desarrollando. En el ejemplo le indicamos a viafirma platform que la url de retorno (donde viafirma debemandarnos el resultado de la firma) es /viafirmaClientResponseServlet .

En esta ubicación la aplicación que estamos integrando deberá tener un un servlet escuchando la respuesta que nos

Políticas de firma

Peticiones opcionales

Solicitar firma

Java


retornará viafirma platform para su correspondiente procesado. Podemos encontrar un ejemplo de ese servlet en laaplicación de ejemplo, donde, en este caso, el método signOK es el que recuperaría los datos de la firma. En elsubapartado de procesar respuesta firma Java se explica detalladamente cada método.

//IniciamoselprocesodefirmaredireccionandoalusuarioaViafirma..

clienteViafirma.Sign(idTemporalFirma);

Con este simple código ya conseguimos que nuestra aplicación ASP.NET utilice viafirma platform para que sea ésta laresponsable de solicitar, validar, recuperar el certificado del usuario y firmar.

Una vez que el proceso termine, viafirma platform devolverá el control a la aplicación ASP.NET retornando todos losdatos de la firma.

Una vez que viafirma platform obtenga los datos de la firma, invocará al método ProcessResponseSign, que seencuentra en el fichero Default.aspx dentro del directorio viafirma. Lo único que tendremos que hacer es sobreescribirdicho método con el comportamiento deseado y recuperar todos los datos de firma. Podemos encontrar un ejemplo delfichero Default.aspx en la aplicación de ejemplo. En el subapartado de procesar respuesta firma .Net se explicadetalladamente cada método.

.Net




Servlet en la aplicación de ejemplo.

Al igual que para el proceso de autenticación, para procesar la respuesta de firma, nos ayudaremos del servlet quetendremos a la eschucha en la aplicación, y que deberá extender de org.viafirma.cliente.ViafirmaClientServlet, y que eneste caso tendrá que sobrescribir el siguiente método:

signOK: viafirma platform ha firmado correctamente y nos devuelve en la response el objeto Firma para quenuestra aplicación los procese y continúe con la lógica de negocio correspondiente.

En la respuesta recibida, se invocará al método ViafirmaClientResponse, que se encuentra dentro del directorioViafirma. Este método será sobrescrito para implementar la lógica de negocio deseada con los datos recuperados de lafirma, los cuales vendrán contenidos en el objeto FirmaInfoViafirma.

En el siguiente ejemplo, si la firma ha sido correcta, guardamos los datos del usuario en la request y redireccionamos alusuario final a una página de destino.

publicclassViafirmaClientResponseServletextendsViafirmaClientServlet

@Override

publicvoidsignOK(FirmaInfoViafirmaarg0,HttpServletRequestarg1,

HttpServletResponsearg2)

//Lógicaespecíficadecadaaplicaciónparagestionarelresultadodela

//firma

request.setAttribute("resultado",firma);

try

request.getRequestDispatcher("/resultadoFirma.jsp").forward(request,response);

catch(ServletExceptione)


catch(IOExceptione)


Procesar respuesta firma Java

64ProcesarrespuestafirmaJava


Clase en la aplicación de ejemplo

Para procesar la respuesta de viafirma platform nos ayudaremos de la clase Default.aspx dentro del directorio viafirmaque tendremos a la eschucha en la aplicación, que deberá importar la calse Viafirma.ViafirmaClient , y tendrá queimplementa el siguiente método:

ProcessResponseSign: viafirma platform ha recuperado correctamente los datos del de la firma y nos lo devuelvepara que nuestra aplicación los procese y decida qué hacer con ellos.

En la respuesta recibida, se invocará y se redirigirá a la página indicada. En este método son recuperados los datos dela firma, los cuales vendrán contenidos en el objeto FirmaInfoViafirma.

En el siguiente ejemplo, si la firma ha sido correcta, guardamos los datos del usuario en la request y redireccionamos alusuario final a una página de destino.

<%@PageLanguage="C#"Inherits="Viafirma.ViafirmaClient"%>

<%--

PáginaparalagestióndelacomunicaciónconViafirma.

Nota:Estapáginanuncaseravisibleporelusuario,soloesutilizadaparagestionarlasrefireccionesyconfiguraciónespecífica.

--%>

<scriptrunat="server">

//AlgargarlapáginaserealizatodoelprocesadoparaelintercambiodeinformaciónconViafirma.

publicvoidPage_Load(Objectsender,EventArgse)

//Esposibleenviarciertosparametrosalservidorenestepuntoparaobteneralgunasfuncionalidadesadicinales

//this.AddOptionalRequest(PEM);//Obligaaqueelservidorenvíeelcertificadofirmante

//this.AddOptionalRequest(AUTO_SEND);//Silaplataformadetectasolouncertificado,loutilizapordefecto

try

ProcessViafirma();

catch(InvalidOperationExceptionexc)

System.Console.WriteLine(exc.Message);

StringmessageError=exc.Message;

Uriurl=newUri(HttpContext.Current.Request.Url,HttpContext.Current.Response.ApplyAppPathModifier("~/errorPage.aspx?errorMessage="+exc.Message));


overridepublicvoidProcessResponseSign(Viafirma.Estadoestado,Viafirma.FirmaInfoViafirmafirma)

Viafirma.Log.Debug("FirmaViafirmarealizadacorrectamente.");

//Aquíyatenemostodoslosdatosasociadosalclienteyasufirma.

//redireccionamosalusuarioalapáginadestinoconsiderandoelusuarioyahafinalizadolafirma.


Session["resultadoFirma"]=firma;

Uriurl=newUri(HttpContext.Current.Request.Url,HttpContext.Current.Response.ApplyAppPathModifier("~/resultadoFirma.aspx"));



Procesar respuesta firma .Net

65Procesarrespuestafirma.Net




//Hayproblemasalvalidar.

System.Console.WriteLine("HayproblemasalrealizarlafirmaCodError="+error+"Mensage="+mensage);

thrownewException("HayproblemasalrealizarlaverificacionCodError="+error+"Mensage="+mensage);





else

System.Console.WriteLine("Procesocanceladoporelusuario");

//thrownewException("Procesocanceladoporelusuario");

</script>

66Procesarrespuestafirma.Net

La diferencia principal de este tipo de firma con la que intervienen los usuarios, es que en esta el usuario no intervienepara seleccionar el certificado con el cual se va a realizar la firma. El certificado firmante debe estar previamenteconfigurado en el servidor para poder realizar correctamente este tipo de firmas.

En este tipo de firmas, no es necesario preparar la firma, ya que desde el principio del inicio de la operación tenemosidentificado el certificado con el cual vamos a realizarla. Por lo tanto ejecutamos directamente el método de firma conlas políticas, el documento a a firmar, el alias y contraseña del certificado firmante.

El certificado firmante debe estar instalado previamente en el almacén de certificados configurado en viafirma platform.

//Aliasdelcertificadoinstalado

finalStringalias="alias_cert";

//Contraseñadelcertificadoinstalado

finalStringpass="pass_cert";

//Recuperarlainstanciainiciadadeviafirmaclient


//Formatodefirma

TypeFormatSignformat=TypeFormatSign.PAdES_BASIC;

TypeFiletypeFile=TypeFile.PDF;

TypeSigntypeSign=TypeSign.ENVELOPED;

StringnameDoc="doc.pdf";

//Configuracióndelapolíticadefirma


policy.setTypeFormatSign(format);

policy.setTypeSign(typeSign);


byte[]datosAFirmar=IOUtils.toByteArray(getClass().getResourceAsStream("/exampleSign.pdf"));

//GenerarelobjetoDocumentoconlosdatosafirmar

Documentodocumento=newDocumento(nameDoc,datosAFirmar,typeFile,format);

//Firmaenservidor

StringidFirma=ViafirmaClientFactory.getInstance().signByServerWithPolicy(policy,documento,alias,pass);

//Aliasdelcertificadoinstalado

Stringalias="alias_cert";

//Contraseñadelcertificadoinstalado

Firma sin intervención de usuario

Solicitar la firma

Java

.Net

67Firmasinintervencióndeusuario

Stringpass="pass_cert";



//Formatodefirma

typeFormatSignformat=typeFormatSign.PAdES_BASIC;


typeSigntypeSign=typeSign.ENVELOPED;

StringnameDoc="doc.pdf";

//Configuracióndelapolíticadefirma

policypol=PolicyUtil.newPolicy(format,typeSign);



Streamfs=assembly.GetManifestResourceStream("EjemploWebViafirmaClientDotNet.resources.exampleSign.pdf");



//GenerarelobjetoDocumentoconlosdatosafirmar

documentodoc=newdocumento();

doc.nombre=nameDoc;

doc.datos=datos_a_firmar;

doc.typeFormatSign=typeSign;

doc.tipo=typeFile.PDF;

//Firmaenservidor

stringidFirma=clienteViafirma.SignByServerWithPolicy(pol,doc,Global.ALIAS,Global.PASS_CERT);

En este tipo de firmas vemos que no es necesario procesar la respuesta del servidor, ya que no interviene ningúnusuario en su proceso. La respuesta del servidor es inmediata, y el método que invoca a la firma devuelve directamenteel identificador de la misma, el cual podremos usar para recuperar la información relativa a la misma.

En todos los casos, a la política de firma (policy) le podemos añadir diferentes opciones de firma; como puede ser, porejemplo, filtrar los certificados a mostrar a la hora de seleccionar uno para realizar el proceso de firma. Este parámetrode política de firma y otras más, se detallan en el apartado de Policy.

Políticas de firma

68Firmasinintervencióndeusuario

En la SDK de viafirma platform existen también métodos desde los cuales podemos obtener la información de firmamediante el propio identificador de la misma.

Estos métodos son aplicables tanto a la firma que ha sido realizada mediante intervención de usuario como sin ella. Elúnico requisito es disponer del identificador de la misma.

Mediante los métodos de la sección de Operaciones de verificación también podremos obtener información aún masprecisa de los que se explican en esta sección. Por lo tanto recomendamos el uso de dichos métodos, al menos que,desde éstos obtengamos algún dato que no sea posible obtener desde los métodos de verificación.

A continuación se listan algunos métodos para la recuperación de información de la firma:

Obtener información avanzada de firmaObtener documento custodiado firmadoObtener documento original

Obtener información firma

69Obtenerinformaciónfirma



//ObtenemoselobjetoFirmaInfoViafirmadeldocumentooriginalfirmado

FirmaInfoViafirmainfo=viafirmaClient.getSignInfo(idFirma);



//ObtenemoselobjetofirmaInfoViafirmadeldocumentofirmado

FirmaInfoViafirmainfo=clienteViafirma.getSignInfo(idFirma);

El objeto FirmaInfoViafirma que obtenemos desde este método posee información que va desde los datos delcertificado que ha realizado la firma del documetno, pasando por el estado de validación de la firma, hasta lainformación del sello de tiempo.

Desde las siguientes urls podremos acceder a ejemplos donde se muestra información de diferentes atributos de esteobjeto:

Ejemplo en Java del resultado de una firma con intevención de usuario.Ejemplo en .Net del resultado de una firma con intevención de usuario.

Otra alternativa de recuperar este documento sería mediante url de navegador, con la siguiente nomenclatura.

https://testservices.viafirma.com/viafirma/v/IDENTIFICADOR_FIRMA

Al ingresar la anterior url en el navegador, se mostrará una página con la información de la firma.

Obtener información avanzada de firma

Java

.Net

70Obtenerinformaciónavanzadadefirma

https://github.com/viavansi/viafirma-platform-example-java/blob/master/src/main/webapp/resultadoFirma.jsp

https://github.com/viavansi/viafirma-platform-example-dotnet/blob/master/resultadoFirma.aspx

https://testservices.viafirma.com/viafirma/v/IDENTIFICADOR_FIRMA



//Obtenemoslosbytesdeldocumentofirmado

byte[]signedDoc=viafirmaClient.getDocumentoCustodiado(idFirma);



//Obtenemoslosbytesdeldocumentofirmado

byte[]signedDoc=clienteViafirma.getDocumentoCustodiado(idFirma);

Como podemos observar, desde este método se obtiene el documento firmado asociado al indentificador de firmapasado como parámetro.


https://testservices.viafirma.com/viafirma/v/IDENTIFICADOR_FIRMA?d=true

Al ingresar la anterior url en el navegador, se iniciará la descarga del documento firmado.

Obtener documento custodiado firmado

Java

.Net

71Obtenerdocumentocustodiadofirmado

https://testservices.viafirma.com/viafirma/v/IDENTIFICADOR_FIRMA?d=true



//ObtenemoselobjetoDocumentodeldocumentooriginalfirmado

byte[]originalDoc=viafirmaClient.getOriginalDocument(idFirma);

//EntrelosatributosdedelobjetoDocumento,hayunoparaobtenerlosbytesdeldocumento.

byte[]signedDoc=originalDoc.getDatos();



//Obtenemoselobjetodocumentodeldocumentooriginalfirmado

byte[]originalDoc=clienteViafirma.getOriginalDocument(idFirma);

//Entrelosatributosdedelobjetodocumento,hayunoparaobtenerlosbytesdeldocumento.

byte[]signedDoc=originalDoc.datos;

Como podemos observar, desde este método se obtiene el documento original del firmado asociado al indentificador defirma pasado como parámetro.


https://testservices.viafirma.com/viafirma/v/IDENTIFICADOR_FIRMA?o=true

Al ingresar la anterior url en el navegador, se iniciará la descarga del documento original al firmado.

Obtener documento original

Java

.Net

72Obtenerdocumentooriginal

https://testservices.viafirma.com/viafirma/v/IDENTIFICADOR_FIRMA?o=true

Como parte de las distintas operaciones que se pueden llevar a cabo en viafirma platform, es posible realizar la firmasimultánea de un conjunto de documentos (lote). La firma en lotes puede realizarse tanto desde una firma conintervención de usuario como en servidor, si intervención.

Debemos indicarle a la SDK la operación que vamos a realizar una firma de un lote de documentos.



//Documentosafirmar

byte[]datosAFirmarTXT=IOUtils.toByteArray(getClass().getResourceAsStream("/ejemplo.txt"));

byte[]datosAFirmarXML=IOUtils.toByteArray(getClass().getResourceAsStream("/prueba.xml"));

byte[]datosAFirmarPDF=IOUtils.toByteArray(getClass().getResourceAsStream("/exampleSign.pdf"));

//Indicamosalaplataformaquedeseamosiniciarunafirmaenlote

StringidLote=viafirmaClient.iniciarFirmaEnLotes(TypeFormatSign.XADES_EPES_ENVELOPED);

//Agregamoslosdocumentosallote

StringidDoc1=viafirmaClient.addDocumentoFirmaEnLote(idTemporalLote,"Documento1.txt",TypeFile.TXT,datosAFirmarTXT);

StringidDoc2=viafirmaClient.addDocumentoFirmaEnLote(idTemporalLote,"Documento2.xml",TypeFile.XML,datosAFirmarXML);

StringidDoc3=viafirmaClient.addDocumentoFirmaEnLote(idTemporalLote,"Documento3.pdf",TypeFile.PDF,datosAFirmarPDF);

//IniciamoslafirmaenviandoalusuarioaViafirmaindicandolaurideretorno.

viafirmaClient.solicitarFirma(idLote,request,response,"/viafirmaClientResponseServlet");



//Documentosafirmar


Streamfs=assembly.GetManifestResourceStream("ejemplo.txt");

byte[]datos_a_firmar1=newbyte[fs.Length];

fs.Read(datos_a_firmar1,0,datos_a_firmar1.Length);

assembly.GetManifestResourceStream("/prueba.xml");



assembly.GetManifestResourceStream("/exampleSign.pdf");



//Generamosunidtemporaldeloteparaañadirdocumentosenél

Firma en lote


Java

.Net

73Firmaenlote

stringidLote=clienteViafirma.iniciarFirmaEnLotes(typeFormatSign.XADES_EPES_ENVELOPED);

//Agregamoslosdocumentosallote

clienteViafirma.addDocumentoFirmaEnLote(idLote,"DocumentoEjemplo1.txt",typeFile.TXT,datos_a_firmar1);

clienteViafirma.addDocumentoFirmaEnLote(idLote,"DocumentoEjemplo2.xml",typeFile.XML,datos_a_firmar2);

clienteViafirma.addDocumentoFirmaEnLote(idLote,"DocumentoEjemplo3.pdf",typeFile.pdf,datos_a_firmar3);

//Firmamos

clienteViafirma.Sign(idLote);

En caso de tratarse de una firma en servidor, la inicialización de los parámetros será idéntica a la firma en cliente,únicamente varía la solicitud de firma, que sería de la siguiente forma:

//Iniciamoslafirmadelloteenelservidor

StringsignId=viafirmaClient.signByServerEnLotes(idLote,certificateAlias,certificatePassword);

//Iniciamoslafirmadelloteenelservidor

stringidFirma=clienteViafirma.signByServerEnLotes(idLote,certificateAlias,certificatePassword);

Java

.Net

74Firmaenlote

Como parte de las distintas operaciones que se pueden llevar a cabo en viafirma platform, es posible realizar la firmaen bucle de múltiples documentos en un mismo acto de firma con intervención del usuario, es decir, en cliente,mediante el método solicitarFirmasIndependientes de la SDK.

Debemos indicarle a la SDK la operación que vamos a realizar una firma en bucle de varios documentos.



//Definimosellistadodeiddefirmasaañadiralbucle

List<String>firmas=newLinkedList<String>();

//Datosdocumentosafirmar

byte[]datosAFirmar1=IOUtils.toByteArray(getClass().getResourceAsStream("/ejemplo.txt"));;

byte[]datosAFirmar2=IOUtils.toByteArray(getClass().getResourceAsStream("/ejemplo.txt"));;

//Preparamoslosficherosquedeseamosfirmar

Stringid1=viafirmaClient.prepareFirmaWithTypeFileAndFormatSign("datos1.txt",TypeFile.txt,TypeFormatSign.XADES_EPES_ENVELOPED,datosAFirmar1);

Stringid2=viafirmaClient.prepareFirmaWithTypeFileAndFormatSign("datos2.txt",TypeFile.txt,TypeFormatSign.XADES_EPES_ENVELOPED,datosAFirmar2);

//Ylosadjuntamosallistadodeidsdefirma

firmas.add(id1);

firmas.add(id2);

//Iniciamostambienunlote,paramostrarquedentrodelafirmaenbuclesepuedenitroducriunficherofirmadoenlotedevarios.

StringidLote=viafirmaClient.iniciarFirmaEnLotes(TypeFormatSign.XADES_EPES_ENVELOPED);

//Incorporamosotrosdocumentosallote

viafirmaClient.addDocumentoFirmaEnLote(idLote,"datosLote1.txt",TypeFile.txt,datosAFirmar1);

viafirmaClient.addDocumentoFirmaEnLote(idLote,"datosLote2.txt",TypeFile.txt,datosAFirmar2);

//Yagregamoseliddelloteallistado

firmas.add(idLote);

//Agregamostambiénundocumentoyafirmadoparavolverloafirmar

//(Viafirmaseencargaautomaticamentedehabilitarelprocesodemultifirma)

StringidFirmaServidor=viafirmaClient.signByServerWithTypeFileAndFormatSign("datosYaFirmados.txt",datosAFirmar1,ConfigureUtil.CERTALIAS,ConfigureUtil.CERTPASS,TypeFile.txt,TypeFormatSign.XADES_EPES_ENVELOPED);

//Yagregamoseliddelafirmaenservidorallistado

firmas.add(idFirmaServidor);

//FinalmenteiniciamoslafirmaenviandoalusuarioaViafirmaeindicandolaURIderetorno.

viafirmaClient.solicitarFirmasIndependientes(firmas,request,response,"/viafirmaClientResponseServlet");

Firma en bucle


Java

.Net

75Firmaenbucle




typeFormatSignformat=typeFormatSign.PAdES_BES;



//Tipodefirma

typeSigntypeSign=typeSign.ATTACHED;

//Recuperamoslosdocumentosafirmar.


StreamfsPDF=assembly.GetManifestResourceStream("prueba1.pdf");

byte[]tragsaPdf1=newbyte[fsPDF.Length];

fsPDF.Read(tragsaPdf1,0,tragsaPdf1.Length);

//Creamoselobjetodocumentoconlosdatosafirmar

documentodoc1=newdocumento();

doc1.nombre="firmado1.pdf";

doc1.datos=tragsaPdf1;

doc1.typeFormatSign=format;

doc1.tipo=typeFile;

fsPDF=assembly.GetManifestResourceStream("prueba2.pdf");







doc2.tipo=typeFile;

fsPDF=assembly.GetManifestResourceStream("prueba3.pdf");







doc3.tipo=typeFile;


policypol=PolicyUtil.newPolicy(format,typeSign);

//Registramoslosdocumentoquedeseamosfirmarenunlistado.

List<string>idsFirma=newList<string>();

//Estelistadopuedeincluirvariostiposdistintosdefirmadentrodelproceso.

//Archivossinfirmar:

stringidTemporal1=clienteViafirma.PrepareSignWithPolicy(pol,doc1);



idsFirma.Add(idTemporal1);



//IniciamoselprocesodefirmaredireccionandoalusuarioaViafirma..

//Estoredireccionaráalusuarioparalafirmadelosdocumentos

//conunasolaintervencióndelusuario.

clienteViafirma.solicitarFirmasIndependientes(idsFirma.ToArray());

76Firmaenbucle

77Firmaenbucle

Como parte de las distintas operaciones que se pueden llevar a cabo en viafirma platform, es posible realizar lapromoción de firmas para los distintos formatos de firmas conocidos, de ésta forma resulta muy sencillo realizar, porejemplo, la promoción de una firma XAdES BES a XAdES XL y luego dicha firma XAdES XL promocionarla a XAdES A.

En el siguiente ejemplo se realiza una firma XAdES BES en servidor de un documento XML, luego se recupera eldocumento firmado para promocionar su firma a XAdES A.




byte[]datosAFirmar=IOUtils.toByteArray(getClass().getResourceAsStream("/prueba.xml"));

Policypol=newPolicy();

pol.setTypeFormatSign(TypeFormatSign.XADES_BES);

Documentodocumento=newDocumento("original.xml",datosAFirmar,TypeFile.XML,TypeFormatSign.XADES_BES);

//Iniciamoslafirmaenviandoaliasypass

StringidFirma=ViafirmaClientFactory.getInstance().signByServerWithPolicy(pol,documento,alias,pass);

pol=newPolicy();

pol.setTypeFormatSign(TypeFormatSign.XADES_A_ENVELOPED);

documento=newDocumento("signed.xml",viafirmaClient.getDocumentoCustodiado(idFirma),TypeFile.XML,TypeFormatSign.XADES_A_ENVELOPED);

//SepromocionalafirrmapreviaXAdESBESalformatoXAdESA

viafirmaClient.upgradeSignature(pol,documento);

Promoción (upgrade) de firma


Java

78Promoción(upgrade)defirma

Como parte de las distintas operaciones que se pueden llevar a cabo en viafirma platform, desde la SDK podremosinvocar al método tsaRequest con la finalidad de añadir un sellado de tiempo a un documento. Para su correctofuncionamiento la plataforma debe tener configurada una TSA, la cual debe estar disponible en el momento de lainvocación.

En el siguiente ejemplo se lleva a cabo el sellado de tiempo de un documento XML, pasando su contenido al métododel SDK tsaRequest



//Datosdocumentoasellar

byte[]datosAFirmar=IOUtils.toByteArray(getClass().getResourceAsStream("/prueba.xml"));

byte[]datosSellados=viafirmaClient.tsaRequest(datosAFirmar);

StringselloB64=Base64.encode(datosSellados);


ViafirmaClientviafirmaClient=ViafirmaClientFactory.GetInstance();

//Datosdocumentoasellar

byte[]datosAFirmar=...

byte[]datosSellados=viafirmaClient.tsaRequest(datosAFirmar);

Sellado de tiempo

Ejemplo

Java

.Net

79Selladodetiempo

Al igual que ocurre con la autenticación, desde la versión 3.15 de viafirma platform se soporta una modalidad(inicialmente solo para windows) que permite utilizar directamente Viafirma Desktop (versión mínima: 1.6.0) invocandola aplicación por protocolo para realizar firma de documentos (incluyendo firma múltiple). Para ello, la estrategia resideen la preparación inicial de la operación mediante una invocación a servicios REST, devolviendo el servidor un códigode operación y un enlace para abrir la aplicación por protocolo. Al abrirlo la aplicación pierde el control de lo que ocurre,por lo que debe iniciar un polling Javascript a otro servicio REST donde consulta el estado de la operación, sabiendo siestá finalizada o no, con errores, etc. y se exponen funciones que son invocadas automáticamente (callback) en casode error, éxito, cancelación, etc., pasando un objeto JSON con los datos de la operación.

Desde la versión 3.17.1 de Viafirma Platform y versión mínima 1.6.7 de Viafirma Desktop, se pueden utilizar filtros deCA y Serial Number tal y como se explica en el apartado de autenticación usando Viafirma Desktop.


Como se verá en ese ejemplo de código, se realiza una preparación de la operación, devolviendo el servidor un objetocon el código de operación y el enlace para abrir la aplicación, al igual que ocurría con la autenticación. En el caso de lafirma, también se puede inicializar información similar a la de autenticación (filtros de certificado, autosend) peroobviamente también hay que enviar información de la firma: ficheros, formatos, políticas, etc.

//NowusethenewprepareSignatureForDirectDesktopmethod

//Themethodrequires:

//1.-AnAuthOperationRequestobject(includeslogictofiltercertificates,autosend,etc.)-optional(canbenull)

//2.-Filestobesigned,inalistofOperationFile(base64andfilename)-mandatory

//3.-Policyobject-mandatory

AuthOperationRequestauthRequest=newAuthOperationRequest();

//Forinstance...

authRequest.setAutoSend(true);

//Policy(mandatory)

//Sinceviafirma-client2.14.6-viafirmaplatform3.15.6,policyisaparamoffile!


policy.setTypeFormatSign(TypeFormatSign.PAdES_BASIC);

policy.setTypeSign(TypeSign.ATTACHED);

policy.addParameter(PolicyParams.DIGITAL_SIGN_PAGE.getKey(),"1");

policy.addParameter(PolicyParams.DIGITAL_SIGN_RECTANGLE.getKey(),neworg.viafirma.cliente.vo.Rectangle(40,10,550,75));

//Filestobesigned

byte[]documentBinaryContent=IOUtils.toByteArray(getClass().getResourceAsStream("/exampleSign.pdf"));

List<OperationFile>files=newLinkedList<OperationFile>();

OperationFilefile=newOperationFile();

file.setFilename("exampleSign.pdf");

file.setBase64Content(Base64.encodeBase64String(documentBinaryContent));

file.setPolicy(policy);

files.add(file);

documentBinaryContent=IOUtils.toByteArray(getClass().getResourceAsStream("/exampleSign.pdf"));

file=newOperationFile();

file.setFilename("exampleSign2.pdf");

file.setBase64Content(Base64.encodeBase64String(documentBinaryContent));

Uso Viafirma Desktop por protocolo - firma

Java

80UsoViafirmaDesktopporprotocolo-firma

https://github.com/viavansi/viafirma-platform-example-java/blob/master/src/main/webapp/examples/exampleSignatureViafirmaDesktop.jsp

file.setPolicy(policy);

files.add(file);

//Themethodreturnsanobjectwiththeinformationrequiredto:

//a)CreateabuttonthatopensViafirmaDesktopbyprotocol

//b)Getsthejust-preparedoperationIDtostartpollingusingJavascript

DirectDesktopInvocationdirectCall=viafirmaClient.prepareSignatureForDirectDesktop(authRequest,files,request);

StringoperationId=directCall.getOperationId();

StringviafirmaDesktopLink=directCall.getViafirmaDesktopInvocationLink();

Al igual que ocurre con la autenticación, se hace una estrategia de polling Javascript para saber cuándo finaliza lafirma, recibiendo callbacks para los casos de error, cancelación, imposibilidad de arrancar Viafirma Desktop (noinstalado) o finalización de la operación, con la principal diferencia del JSON de firma, que en este caso es distinto delde autenticación (contiene también los datos del certificado, pero así mismo los de la operación de firma).

<scriptsrc="<%=ConfigureUtil.getViafirmaServer()%>/viafirma.js?t=<%=System.currentTimeMillis()%>">


</script>

<script>





document.getElementById("signatureError").innerHTML="Ocurrióunproblemadurantelafirma:"+JSON.stringify(response);




document.getElementById("signatureCancel").innerHTML="Lafirmafuecancelada:"+JSON.stringify(response);

//Ifthesignatureoperationrunsok,thisfunctionisinvoked-customizeitwithyourownlogic


window.location.replace("./exampleSignatureViafirmaDesktopResult.jsp?operationId="+response.operationId);

//IfViafirmaDesktopisnotloaded,thisfunctionisinvoked

functionshowUnloaded()

alert("ViafirmaDesktopnoencontrado");


document.getElementById("signatureSuccess").innerHTML=

"<p>ViafirmaDesktopnohasidocargado,aquísepuedeincluircódigoparagestionarlainstalación,instrucciones,etc.</p>";


functioninitSignature()

document.getElementById("signatureButton").style="display:none;";

document.getElementById("loading").innerHTML="<imgsrc='../images/icons/ajax-loader.gif'/>";





//-ifViafirmaclientisnotloadedafterunloadedTimeseconds:"unloadedCallback"

viafirma.init(

//Hereweinclude

operationId:"<%=operationId%>",

viafirmaUrl:"<%=ConfigureUtil.getViafirmaServer()%>/",

unloadedTime:30,



,




,



,

unloadedCallback:function(response)

showUnloaded();

);

</script>

Podemos encontrar un ejemplo de uso de esta lógica de invocación directa en la aplicación de ejemplo aspx - aspx.cs

El código es muy similar al ejemplo anterior Java, realizando una preparación de la operación, devolviendo el servidorun objeto con el código de operación y el enlace para abrir la aplicación.

Code behind:

publicasyncvoidFirmar_ClickAsync(objectsender,EventArgse)



AuthOperationRequestauthRequest=newAuthOperationRequest();

authRequest.AutoSend=true;

stringsessionId=HttpContext.Current.Session.SessionID;

string[]languages=HttpContext.Current.Request.UserLanguages;

stringlocale=languages[0];

//Creamoslapoliticadefirma


//Creamoselrectangle

rectangler=PolicyUtil.newRectangle(40,10,550,75);

//Seteamoslapolitica

PolicyUtil.AddParameter(pol,PolicyParams.DIGITAL_SIGN_PAGE,"1");

PolicyUtil.AddParameter(pol,PolicyParams.DIGITAL_SIGN_RECTANGLE,PolicyUtil.rectangleToJson(r));

PolicyUtil.AddParameter(pol,PolicyParams.DIGITAL_SIGN_STAMPER_HIDE_STATUS,"true");

PolicyUtil.AddParameter(pol,PolicyParams.DIGITAL_SIGN_STAMPER_TEXT,"Firmadopor[CN]conDNI[SERIALNUMBER]\ntrabajadorde[O]eneldepartamentode[OU]");

PolicyUtil.AddParameter(pol,PolicyParams.DIGITAL_SIGN_STAMPER_TYPE,"QR-BAR-H");

PolicyUtil.AddParameter(pol,PolicyParams.DIGITAL_SIGN_STAMPER_ROTATION_ANGLE,"90");

//Recuperamoseldocumentoafirmar.


Streamfs=assembly.GetManifestResourceStream(Global.DEMO_FILE_PDF_PATH);



OperationFilefile=newOperationFile();

file.Filename="example.pdf";

file.Base64Content=System.Convert.ToBase64String(datos_a_firmar);

file.Policy=pol;

List<OperationFile>files=newList<OperationFile>();

files.Add(file);

.NET


https://github.com/viavansi/viafirma-platform-example-dotnet/blob/master/signatureDirectViafirmaDesktop.aspx

https://github.com/viavansi/viafirma-platform-example-dotnet/blob/master/signatureDirectViafirmaDesktop.aspx.cs

desktopInvocation=awaitclienteViafirma.PrepareSignatureForDirectDesktopAsync(authRequest,files,sessionId,locale);

System.Console.Write("OperationId:"+desktopInvocation.OperationId);

Al igual que ocurre con la autenticación, se hace una estrategia de polling Javascript para saber cuándo finaliza lafirma, recibiendo callbacks para los casos de error, cancelación o finalización de la operación, con la principal diferenciadel JSON de firma, que en este caso es distinto del de autenticación (contiene también los datos del certificado, peroasí mismo los de la operación de firma).

<formid="form1"runat="server">

<%if(desktopInvocation==null)%>

<p>

<asp:buttonID="firmarBoton"runat="server"

Text="Iniciarprocesodefirma"OnClick="Firmar_ClickAsync"

Width="245px"/>

</p>

<%

else

%>

<scriptsrc="<%=Viafirma.ViafirmaClientFactory.GetInstance().UrlPublica%>/viafirma.js">


</script>

<script>





document.getElementById("signatureError").innerHTML="Ocurrióunproblemadurantelafirma:"+JSON.stringify(response);




document.getElementById("signatureCancel").innerHTML="Lafirmafuecancelada:"+JSON.stringify(response);

//Ifthesignatureoperationrunsok,thisfunctionisinvoked-customizeitwithyourownlogic

//Forinstance,probablyyouwillneedtoinvokeaninternalRESTservicethatreceivesthesignatureresponseobject



document.getElementById("signatureSuccess").innerHTML="<p>Operacióndefirmarealizadaconéxito.Informaciónobtenida:</p><ul>"+

"<li><strong>IDdeoperación</strong>:"+response.operationId+"</li>"+

"<li><strong>Identificaciónusuario</strong>:"+response.certificateValidationData.numberUserId+"</li>"+

"<li><strong>Usuario</strong>:"+response.certificateValidationData.name+""+response.certificateValidationData.surname1+""+response.certificateValidationData.surname2+"</li>"+

"<li><strong>CA</strong>:"+response.certificateValidationData.shortCa+"</li>"+

"<li><strong>IDFirma</strong>:"+response.signatureId+"</li>"+

"</ul>";


functioninitSignature()

document.getElementById("signatureButton").style="display:none;";

document.getElementById("loading").innerHTML="<imgsrc='./images/icons/ajax-loader.gif'/>";





viafirma.init(

//Hereweinclude

operationId:"<%=desktopInvocation.OperationId%>",

viafirmaUrl:"<%=Viafirma.ViafirmaClientFactory.GetInstance().UrlPublica%>/",




,



,



);

</script>

<pid="signatureError"></p>

<pid="signatureCancel"></p>

<pid="signatureSuccess"></p>

<pid="loading"></p>

<pid="signatureButton">

<aclass="button"href="<%=desktopInvocation.ViafirmaDesktopInvocationLink%>"onClick="initSignature();">FirmarconViafirmaDesktop</a>

</p>

<%

%>

</form>

Obsérvese que, al igual que en el caso Java, se ha incluido una query param al cargar el Javascript remoto viafirma.js,para evitar posibles problemas de caché en los usuarios en el caso de que este Javascript se modifique en futurasversiones.

Si el polling falla recibiendo un HTTP status distinto de 200/OK -la operación no ha finalizado todavía-, el objetoresponse recibido en el callback de error sólo tendrá un campo "message" y el operationId. Si la operación estáfinalizada, el objeto será de este tipo:


"isFinished":true,

"isCancelled":false,

"hasErrors":true,

"isSignature":true,

"errorCode":"1",

"errorMessage":"Errordescription"

Los códigos de error son los mismos que con el resto del API. Son especialmente relevantes los códigos relacionadoscon los estados CADUCADO (código 104) y REVOCADO (código 107) de un certificado. Si la aplicación ViafirmaDesktop tiene algún problema local que comunique al servidor, se recibirá un errorCode = 2.

Si la operación ha sido cancelada, el callback de cancelación recibe un JSON como el siguiente:


"isFinished":true,

"isCancelled":true,

"hasErrors":false,

"isSignature":true

Especificaciones de objetos JSON de respuesta en callbacks


Si la operación ha acabado con éxito, la operación recibe un JSON con todos los datos de la firma y el operationId.Esta información está en el callback Javascript successCallback, y debe hacerse llegar a la lógica de servidor. Noes recomendable consumir un servicio REST interno con la información de la firma, dado que sería sencillo que unatacante realizase un ataque enviando un JSON modificado. Lo recomendable es invocar a lógica de servidor conel ID de operacion, y desde la lógica de servidor utilizar el servicio de viafirma cliente determinado, o simplementeconsumir el servicio REST de Platform para descargar dicha información.


operationId: ID de operación devuelto en el primer proceso de preparación de la operación.signatureId: ID de firma de Viafirma (si son varios documentos, los IDs van separados por comas).certificateValidationData, datos del certificado, con los mismos campos que la respuesta de autenticación:

numberUserId: número de identificador del usuario (NIF, cédula...)name: Nombre del usuariosurname1: Primer apellidosurname2: Segundo apellidoemail: Email del usuarioca: Autoridad de Certificación emisora (por ejemplo Fábrica Nacional de Moneda y Timbre)shortCa: Autoridad de Certificación emisora - descripción corta (por ejemplo FNMT)jobTitle: Cargo del usuariotype: Tipo de certificadocn: Common Nameorganization: Nombre de la organización / empresa del usuariocertificateProperties: lista de variables del certificado (en formato key/value)isValidated: booleano - obtiene valor true si el certificado ha sido validado correctamenteisExpired: booleano - obtiene valor true si el certificado está caducadoisRevoked: booleano - obtiene valor true si el certificado está revocado


Para verificar el estado de validez, recuperar el documento firmado o información más avanzada de la firma, podremosutilizar estos métodos de verificación que están disponibles en la SDK.

Estos métodos no solo verifican u obtienen la información de los documentos que han sido firmados por viafirmaplatform mediante su identificador de firma, si no que también, podremos verificar documentos firmados por otrasplataformas. Para esta última función, sería necesario disponer del documento firmado, y en algunos casos deldocumento original.

Dentro de las opciones de verificación, nos encontramos dos:

Verificación de certificado.Verificación de firma.

Podemos verificar un certificado de forma independiente, o bien verificar una firma. En el resultado de la verificación defirma vendrá incorporado, además, el resultado de verificación del certificado firmante.

Operaciones de verificación

86Operacionesdeverificación

Una de las operaciones que podemos llevar a cabo es la verificación de certificados. Esta validación devuelveinformación sobre el certificado a verificar y sobre los certificados padres.

La información que devuelve la verificación va desde; si es un certificado válido o no, si está soportado por viafirmaplatform, hasta comprobar su estado de revocación o caducidad.

Los requisitos previos a la validación son disponer de la clave pública del certificado a validar (.pem), o el al alias de uncertificado que esté instalado en el servidor viafirma platform, el cual puede ser validado también.

A continuación mostramos ejemplos de uso de este método:

Ejemplo pasando el pem del certificado cliente:



//Cargoelpemalmacenadolocalmente

byte[]pem=IOUtils.toByteArray(getClass().getResourceAsStream("/cert_prueba.pem"));

//Obtengoelobjetoderespuesta

CertificateResponsecertificateResponse=viafirmaClient.verifyCertificate(pem);

Ejemplo pasando el alias del certificado en servidor:




CertificateResponsecertificateResponse=viafirmaClient.verifyCertificateByAlias("alias_cert");

Ejemplo pasando el pem del certificado cliente:



//Cargoelpemalmacenadolocalmente

Stringpem=Request.Form["pem"];

byte[]pemBytes=Encoding.ASCII.GetBytes(pem);


Verificación de certificado

Java

.Net

87Verificacióndecertificado

certificateResponsecertificateResponse=viafirmaClient.verifyCertificate(pemBytes);

Ejemplo pasando el alias del certificado en servidor:




certificateResponsecertificateResponse=viafirmaClient.verifyCertificateByAlias("alias_cert");

El objeto resultante de la respuesta es de tipo CertificateResponse el cual contiene información sobre el certificado averificar.

Puede encontrar ejemplos de la implementación de este método y de parte de la información que obtiene desde lassiguientes urls:

Ejemplo validación clave pública en clienteEjemplo validación certificado en servidor

Ejemplo validación clave pública en cliente

Java

.Net

88Verificacióndecertificado

https://github.com/viavansi/viafirma-platform-example-java/blob/master/src/main/webapp/examples/utils/valideCertificateUploaded.jsp

https://github.com/viavansi/viafirma-platform-example-java/blob/master/src/main/webapp/examples/utils/valideServerCert.jsp

https://github.com/viavansi/viafirma-platform-example-dotnet/blob/master/utils/checkVerificateCert.aspx.cs

Otra de las operaciones que podemos llevar a cabo es la verificación de firmas. Esta validación devuelve informaciónsobre el documento firmado a verificar y sobre los certificados implicados en la firma.

La información que devuelve la verificación va desde; si es una firma es válido o no, si los certificados de firma estánsoportados por viafirma platform, hasta comparar la firma con el documento original.

Los requisitos previos a la validación son disponer del identificador de firma, en el caso de que la firma se hayarealizado en viafirma platform, o el documento firmado y original, en el caso de que el documento haya sido firmado enotra plataforma, o firmado en viafirma platform pero se opta por validarlo por el documento firmado en vez de por elidentificador de firma.

En el caso de validar la firma de un documento pasándole como parámetro solo el documento firmado, es decir, sinespecificar el documento original, viafirma platform es capaz de extraer el original mediante el firmado. Por tanto eldocumento original no es obligatorio para este tipo de validación.

Además de los requisitos comentados anteriormente, también se necesita conocer previamente los siguiente aspectos:

El estándar de la firma (SIGNATURE_STANDARD): PADES, XADES o CADES.El Hash del ocumento original en el caso de que no dispongamos del documento original de la firma.

A continuación mostramos ejemplos de uso de este método:

Ejemplo pasando el identificador de firma para validar una firma PAdES:



//Instaciamoslaclaseencargadadeañadirlosparámetrosdelapetición

VerificationSignatureRequestverificationSignatureRequest=newVerificationSignatureRequest();

//Vamosañadiendolosparámetrosallistado

//SignatureStandard

StringsignatureStandardKey=VerificationSignatureRequest.ParameterKey.SIGNATURE_STANDARD.name();

StringsignatureStandardValue=VerificationSignatureRequest.SignatureStandard.PADES.name();

//AñadimoselparámetroSignatureStandard

verificationSignatureRequest.addParameter(signatureStandardKey,signatureStandardValue);

//SignID

StringsignIdKey=VerificationSignatureRequest.ParameterKey.SIGNATURE_ID.name();

StringsignIdValue="YGOF-2OTF-Y5M1-5180-0820-0761";

//AñadimoselparámetroTypeSign

verificationSignatureRequest.addParameter(signIdKey,signIdValue);

//ObtengounlistadodeobjetosSignatureVerificationconlavalidacióndelasdistintasfirmasquepudiesetenereldocumentofirmado

List<SignatureVerification>signatureVerificationList=viafirmaClient.verifySignature(verificationSignatureRequest);

Verificación de firma

Java

89Verificacióndefirma

Ejemplo pasando el documento firmado y original para validar una firma XAdES:



//Cargoeldocumentooriginal

byte[]docOrigin=IOUtils.toByteArray(getClass().getResourceAsStream("/example.xml"));

//Cargoeldocumentofirmado

byte[]docSigned=IOUtils.toByteArray(getClass().getResourceAsStream("/signedExample.xml"));

//Instanciamoslaclaseencargadadeañadirlosparámetrosdelapetición

VerificationSignatureRequestverificationSignatureRequest=newVerificationSignatureRequest();


//SignatureStandard

StringsignatureStandardKey=VerificationSignatureRequest.ParameterKey.SIGNATURE_STANDARD.name();

StringsignatureStandardValue=VerificationSignatureRequest.SignatureStandard.XADES.name();


verificationSignatureRequest.addParameter(signatureStandardKey,signatureStandardValue);

//Añadoeldocumentoorginalyelfirmado

verificationSignatureRequest.setOriginalDocument(docOrigin);

verificationSignatureRequest.setSignedDocument(docSigned);

//ObtengounlistadodeobjetosSignatureVerificationconlavalidacióndelasdistintasfirmasquepudiesetenereldocumentofirmado

List<SignatureVerification>signatureVerificationList=viafirmaClient.verifySignature(verificationSignatureRequest);

Ejemplo pasando el identificador de firma para validar una firma PAdES:




//Instanciamoslaclaseencargadadeañadirlosparámetros

verificationSignatureRequestverificationSignatureRequest=VerifyUtil.newVerify();


//SignatureStandard

StringsignatureStandardKey=VerifyParams.SIGNATURE_STANDARD_KEY;

StringsignatureStandardValue=VerifyParams.PADES_SIGNATURE_STANDARD;


VerifyUtil.AddParameter(verificationSignatureRequest,signatureStandardKey,signatureStandardValue);

//SignID

StringsignIdKey=VerifyParams.SIGNATURE_ID_KEY;

StringsignIdValue="YGOF-2OTF-Y5M1-5180-0820-0761";

//AñadimoselparámetroTypeSign

VerifyUtil.AddParameter(verificationSignatureRequest,signIdKey,signIdValue);

//ObtengounarraydeobjetossignatureVerificationconlavalidacióndelasdistintasfirmasquepudiesetenereldocumentofirmado

signatureVerification[]signatureVerification=viafirmaClient.verifySignature(verificationSignatureRequest);

.Net


Ejemplo pasando el documento firmado y original para validar una firma XAdES:



//Cargoeldocumentooriginal


Streamfs=assembly.GetManifestResourceStream("example.xml");

byte[]docOrigin=newbyte[fs.Length];

fs.Read(docOrigin,0,datos_a_firmar.Length);

//Cargoeldocumentofirmado

Streamfs=assembly.GetManifestResourceStream("signedExample.xml");

byte[]docSigned=newbyte[fs.Length];

fs.Read(docSigned,0,datos_a_firmar.Length);


verificationSignatureRequestverificationSignatureRequest=VerifyUtil.newVerify();


//SignatureStandard

StringsignatureStandardKey=VerifyParams.SIGNATURE_STANDARD_KEY;

StringsignatureStandardValue=VerifyParams.XADES_SIGNATURE_STANDARD;


VerifyUtil.AddParameter(verificationSignatureRequest,signatureStandardKey,signatureStandardValue);

//Añadoeldocumentoorginalyelfirmado

verificationSignatureRequest.originalDocument=docOrigin;

verificationSignatureRequest.signedDocument=docSigned;

//ObtengounarraydeobjetossignatureVerificationconlavalidacióndelasdistintasfirmasquepudiesetenereldocumentofirmado

signatureVerification[]signatureVerification=viafirmaClient.verifySignature(verificationSignatureRequest);

El resultante de la respuesta es un listado de tipo SignatureVerification que contiene la información de verificación delas distintas firmas que pudiese tener el documento firmado.

Puede encontrar ejemplos de la implementación de este método y de parte de la información que obtiene desde lassiguientes urls:

Ejemplo de validación de firma subiendo documento firmado

Ejemplo de validación de mediante el identificador

Java

.Net


https://github.com/viavansi/viafirma-platform-example-java/blob/master/src/main/webapp/examples/utils/valideSignUploaded.jsp

https://github.com/viavansi/viafirma-platform-example-dotnet/blob/master/utils/checkVerificateSign.aspx.cs

El objeto Policy permite configurar las opciones de la firma a realizar de un modo más sencillo y potente que utilizandootros de nuestros métodos de firma. Aún así los métodos que usan Policy no sustituyen a la totalidad del resto demétodos, que para algunos casos seguirán siendo usados.

A continuación un ejemplo sencillo de la configuración de firma a través de policy:


policy.setTypeFormatSign(TypeFormatSign.XADES_EPES_ENVELOPED);

policy.setTypeSign(TypeSign.ENVELOPED);


Como se puede ver en el código anterior lo básico de un Policy será el formato de firma y el tipo de firma: el formato defirma podrá ser cualquiera de los que se encuentran en el TypeFormatSign y el tipo de firma en TypeSign. Estos dosparámetros del Policy serán siempre obligatorios en los procesos de firmas, no así en los de autenticación.

Además de los métodos para definir el TypeFormatSign y el TypeSign, el objeto Policy dispone de dos métodos quepermiten realizar configuraciones de firma más avanzadas.

Policy paramsOptional request



policy.setTypeFormatSign(TypeFormatSign.XADES_EPES_ENVELOPED);

policy.setTypeSign(TypeSign.ENVELOPED);

//PolicyParam

policy.addParameter(PolicyParams.FILTER_CA_NAME.getKey(),"Avansi;FNMT");

//OptionalRequest


Policy

Java

.Net

Java

.Net

93Policy



//PolicyParam

PolicyUtil.AddParameter(pol,PolicyParams.DIGITAL_SIGN_PAGE,"1");

//OptionalRequest


94Policy

En los apartados anteriores se ha expuesto una firma básica utilizando el objeto Policy, sin embargo podemos realizarfirmar más complejas de forma que podemos realizar firmas con incrustación de sello, personalizar la skin del applet defirma, firma digitalizada...

Para conocer todas los parámetros que podemos utilizar en

Parámetros para la firma digitalizadaParámetros para el sello de firmaParámetros para la configuración de firma

Parámetros

95Parámetros

En viafirma platform se puede configurar mediante los siguientes parámetros las distintas características de la firmadigitalizada tales como el tamaño, la posición el color del trazo de firma, etc.

Los parámetros básicos para realizar una firma digitalizada son los siguientes:

DIGITALIZED_LOCATION_STATUSDIGITALIZED_PRESSURE_INFODIGITALIZED_PRESSURE_STYLUSDIGITALIZED_SIGN_ALIASDIGITALIZED_SIGN_BACK_COLOURDIGITALIZED_SIGN_BIOMETRIC_ALIASDIGITALIZED_SIGN_BIOMETRIC_CRYPTO_PEMDIGITALIZED_SIGN_BIOMETRIC_PASSDIGITALIZED_SIGN_COLOURDIGITALIZED_SIGN_HELP_TEXTDIGITALIZED_SIGN_LOGODIGITALIZED_SIGN_PAGEDIGITALIZED_SIGN_PASSDIGITALIZED_SIGN_PDF_SIGNATURE_FORMATDIGITALIZED_SIGN_RECTANGLEDIGITALIZED_SIGNATURE_FORMATDIGITALIZED_SIGNATURE_INFO

y que podrás usarlo en tus políticas de firma como verás en los siguientes ejemplo.

//iniciamoselobjetoPolicy

PolicypolicyDigitalizedSign=newPolicy();

//Indicamoslosparametrosquetendráelobjeto

policyDigitalizedSign.setTypeFormatSign(TypeFormatSign.DIGITALIZED_SIGN);

policyDigitalizedSign.setTypeSign(TypeSign.ATTACHED);

//Firmaenservidordeldocumento

//Tendremosqueindicarleelaliasdelcertificadoylaclaveconlaquequeramosrealizarlafirmadeldocumento

policyDigitalizedSign.addParameter(PolicyParams.DIGITALIZED_SIGN_ALIAS.getKey(),"alias_cert");

policyDigitalizedSign.addParamter(PolicyParams.DIGITALIZED_SIGN_PASS.getKey(),"pass_cert"

//iniciamoselobjetoPolicy

Parámetros firma digitalizada

Java

.Net

96Parámetrosparalafirmadigitalizada

policypolicyDigitalizedSign=PolicyUtil.newPolicy(TypeFormatSign.DIGITALIZED_SIGN,typeSign.ATTACHED);

//Firmaenservidordeldocumento

//Tendremosqueindicarleelaliasdelcertificadoylaclaveconlaquequeramosrealizarlafirmadeldocumento

PolicyUtil.AddParameter(policyDigitalizedSign,PolicyParams.DIGITALIZED_SIGN_ALIAS,"alias_cert");

PolicyUtil.AddParameter(policyDigitalizedSign,PolicyParams.DIGITALIZED_SIGN_PASS,"pass_cert");


Con este parámetro podremos indicar la información de localización por GPS recogida en la firma por dispositivosmóviles.

Esta información es devuleta en forma de cadena de texto.

Tendríamos que indicar 0 si está desactivado o el valor correcto si está activado. Por defecto, si no se hace uso de esteparámetro, no se mostrará la información de localización.

A continuación un ejemplo de como se realizaría el uso de este parámetro:


policy.addParameter(PolicyParams.DIGITALIZED_LOCATION_STATUS.getKey(),"0");

policypolicy=PolicyUtil.newPolicy(TypeFormatSign.DIGITALIZED_SIGN,typeSign.ATTACHED);

PolicyUtil.AddParameter(policy,PolicyParams.DIGITALIZED_LOCATION_STATUS,"0");

DIGITALIZED_LOCATION_STATUS

Java

.Net


Con este parámetro podremos indicar la información de presión recogida en la firma por el stylus empleado.

Esta información es devuleta en forma de cadena de texto.

Tendríamos que indicar true si queremos mostrar dicha información o false para ocultarla. Por defecto, si no se haceuso de este parámetro, no se mostrará la información de presión.

A continuación un ejemplo de cómo se realizaría el uso de este parámetro:


policy.addParameter(PolicyParams.DIGITALIZED_PRESSURE_INFO.getKey(),"true");


PolicyUtil.AddParameter(policy,PolicyParams.DIGITALIZED_PRESSURE_INFO,"true");

DIGITALIZED_PRESSURE_INFO

Java

.Net


Utilizando este parámetro en el objeto policy, podemos determinar los stylus que están permitidos para realizar la firmadigitalizada.

Actualmente los stylus permitidos son los siguientes:

Jot TouchPogo

Los posibles valores que se pueden indicar son los que se listan a continuación:

ALLJOT_TOUCHPOGOPRESSURENONE

Si no se especifica el parámetro en la operación, el valor por defecto será "ALL".

En las siguientes lineas se pueden ver unos ejemplos de cómo utilizar el parámetro en las distintas SDK:


policy.addParameter(PolicyParams.DIGITALIZED_PRESSURE_STYLUS.getKey(),"JOT_TOUCH");


PolicyUtil.AddParameter(policy,PolicyParams.DIGITALIZED_PRESSURE_STYLUS,"JOT_TOUCH");

DIGITALIZED_PRESSURE_STYLUS

Java

.Net


Este es uno de los parámetros obligatorios para que la firma digitalizada funcione correctamente.

Sirve para indicar el alias del certificado con el que queremos que se firme el documento digitalmente, este alias deberáexistir en el keystore de certificados de confianza de viafirma platform o si se dispone de Viafirma Manager, indicar elalias que posee el certificado de la aplicación.

A continuación se pasa a presentar un ejemplo de uso del parámetro:


policy.addParameter(PolicyParams.DIGITALIZED_SIGN_ALIAS.getKey(),"alias_cert");


PolicyUtil.AddParameter(policy,PolicyParams.DIGITALIZED_SIGN_ALIAS,"alias_cert");

DIGITALIZED_SIGN_ALIAS

Java

.Net


Utilizando este parámetro podremos modificar el color del lienzo de firma en la firma digitalizada.

Los valores aceptados son los colores RGB indicados en hexadecimal.

A continuación mostraremos un ejemplo de como utilizar dicho parámetro.


policy.addParameter(PolicyParams.DIGITALIZED_SIGN_BACK_COLOUR.getKey(),"#FFFFFF");


PolicyUtil.AddParameter(policy,PolicyParams.DIGITALIZED_SIGN_BACK_COLOUR,"#FFFFFF");

DIGITALIZED_SIGN_BACK_COLOUR

Java

.Net


Sirve para indicar el alias del certificado con el que queremos que se firmen los datos biométricos registrados en eltrazo de la firma, este alias deberá existir en el keystore de certificados de confianza de viafirma platform o si sedispone de Viafirma Manager, indicar el alias que posee el certificado de la aplicación.

A continuación se pasa a presentar un ejemplo de uso del parámetro:


policy.addParameter(PolicyParams.DIGITALIZED_SIGN_BIOMETRIC_ALIAS.getKey(),"alias_biometric_cert");


PolicyUtil.AddParameter(policy,PolicyParams.DIGITALIZED_SIGN_BIOMETRIC_ALIAS,"alias_biometric_cert");

DIGITALIZED_SIGN_BIOMETRIC_ALIAS

Java

.Net


Con este parámetro indicamos con que certificado en formato pem queremos que se cifren los datos biométricosrecogidos al trazar la firma.

El parámetro recibe un String en el que informamos el la clave pública del certificado con el que queremos encriptar losdatos biometricos.

A continuación se mostrará una ejemplo de integración utilizando dicho parámetro.

Stringpem=IOUtils.toString(this.getClass().getResourceAsStream("/certificado.pem"));


policy.addParameter(PolicyParams.addParameter(DIGITALIZED_SING_BIOMETRIC_CRYPTO_PEM.getKey()),pem);


PolicyUtil.AddParameter(policy,PolicyParams.DIGITALIZED_SING_BIOMETRIC_CRYPTO_PEM,pem);

DIGITALIZED_SIGN_BIOMETRIC_CRYPTO_PEM

Java

.Net


Con el uso de este parámetro indicaremos la contraseña del alias utilizado en el parametroDIGITALIZED_SIGN_BIOMETRIC_ALIAS como se menciona en el correspondiente apartado, el uso de ambosparámetros dan como resultado la firma de los datos biometricos empleados a la hora de realizar el dibujo de la firma.

El uso de dicho parámetro se puede observar en los siguientes ejemplos:


policy.addParameter(PolicyParams.DIGITALIZED_SIGN_BIOMETRIC_ALIAS.getKey(),"alias_biometric_cert");

policy.addParameter(PolicyParams.DIGITALIZED_SIGN_BIOMETRIC_PASS.getKey(),"pass_biometric_cert");


PolicyUtil.AddParameter(policy,PolicyParams.DIGITALIZED_SING_BIOMETRIC_CRYPTO_PEM,"alias_biometric_cert");

PolicyUtil.AddParameter(policy,PolicyParams.DIGITALIZED_SIGN_BIOMETRIC_PASS,"pass_biometric_cert");

DIGITALIZED_SIGN_BIOMETRIC_PASS

Java

.Net


Este prámetro es opcional, se utiliza para modificar el color del dibujo (trazo) de la firma, así, si quisieramos que la firmadigitalizada fuese de color azul, usaríamos este parámetro.

Se le indica un color en valor hexadecimal siguiendo la composición de colores RGB.

En los siguientes ejemeplos se demuestra como se utilizaría el parámetro para que la línea de nuestro trazo sea decolor azul:


policy.addParameter(PolicyParams.DIGITALIZED_SIGN_COLOR.getKey(),"#00FF00");


PolicyUtil.AddParameter(policy,PolicyParams.DIGITALIZED_SIGN_COLOR,"#00FF00");

DIGITALIZED_SIGN_COLOUR

Java

.Net


El uso de este parámetro nos permite indcar un pequeño texto de ayuda para el usuario que vaya a realizar la firmadigitalizada. Dicho texto aparecerá en el componente en la pantalla del equipo, y también aparecerá en la pantalla de latableta digitalizadora.

El parametro se indica a través de una cadena de texto, como vemos en los siguientes ejemplos:


policy.addParameter(PolicyParams.DIGITALIZED_SIGN_HELP_TEXT.getKey(),"Firmeaquí");


PolicyUtil.AddParameter(policy,PolicyParams.DIGITALIZED_SIGN_HELP_TEXT,"Firmeaquí");

DIGITALIZED_SIGN_HELP_TEXT

Java

.Net


El uso de este parámetro nos permite indicar una imagen a modo del logo de la compañía, por ejemplo, como fondo deltrazo de la firma.

El parametro se indica a través de un byte array, como vemos en los siguientes ejemplos:

////Obtengolaimagenaestampar

byte[]logoStamp=IOUtils.toByteArray(this.getClass().getResourceAsStream("logoStamp.jpg"));


policy.addParameter(PolicyParams.DIGITALIZED_SIGN_LOGO.getKey(),logoStamp);

//Obtengolaimagenaestampar

StreamstampImage=assembly.GetManifestResourceStream(logoStamp.jpg);

byte[]logoStamp=newbyte[stampImage.Length];

stampImage.Read(logoStamp,0,logoStamp.Length);

StringimageB64=System.Convert.ToBase64String(image);


PolicyUtil.AddParameter(policy,PolicyParams.DIGITALIZED_SIGN_LOGO,imageB64);

DIGITALIZED_SIGN_LOGO

Java

.Net


Para indicar la página en el que queremos que se posicione la firma digitalizada en el documento, tendremos queutilizar este parámetro.

Por ejemplo, si quisiéramos posicionar la firma en la primera página del documento indicaríamos el número "1", en lasegunda "2" y así sucesivamente. En el caso de que queramos mostrarla en la última página, el valor sería "-1".


policy.addParameter(PolicyParams.DIGITALIZED_SIGN_PAGE,"0");


PolicyUtil.AddParameter(policy,PolicyParams.DIGITALIZED_SIGN_PAGE,"0");

DIGITALIZED_SIGN_PAGE

Java

.Net


Este es uno de los parámetros obligatorios que tendremos que utilizar si queremos hacer una operación de firmadigitalizada. Es complementario al parámetro DIGITALIZED_SIGN_ALIAS con lo que con estos dos parámetrosconseguimos indicar con qué certificado queremos que se firme el documento.

En el siguiente ejemplo se puede ver como utilizar el parámetro:


policy.addParameter(PolicyParams.DIGITALIZED_SING_ALIAS,"alias_cert");

policy.addParameter(PolicyParams.DIGITALIZED_SING_PASS,"pass_cert");


PolicyUtil.AddParameter(policy,PolicyParams.DIGITALIZED_SING_ALIAS,"alias_cert");

PolicyUtil.AddParameter(policy,PolicyParams.DIGITALIZED_SING_PASS,"pass_cert");

DIGITALIZED_SIGN_PASS

Java

.Net


Tipo de firma para firma en servidor del documento firmado con firma manuscrita. Los valores permitidos son losmismos que obtenemos del objeto TypeFormatSign, para tipos de firmas compatibles con PDF, como pueden ser lossiguientes.

PDF_PKCS7PDF_PKCS7_TPAdES_BASICPAdES_BESPAdES_EPESPAdES_LTV



policy.addParameter(PolicyParams.DIGITALIZED_SIGN_PDF_SIGNATURE_FORMAT,TypeFormatSign.PAdES_BASIC);


PolicyUtil.AddParameter(policy,PolicyParams.DIGITALIZED_SIGN_PDF_SIGNATURE_FORMAT,TypeFormatSign.PAdES_BASIC);

DIGITALIZED_SIGN_PDF_SIGNATURE_FORMAT

Java

.Net


Con el uso de este parámetro indicamos las dimensiones y posición que ocupará el sello generado con la firmadigitalizada del usuario.

El objeto que le pasamos por parámetro es Rectangle el cual a su vez es el que a través de sus parámetros indicamoslos valores de posición. Los dos primeros parámetros corresponden a la posición del rectángulo (X e Ycorrespondientemente) y los otros dos a las dimensiones del mismo (ancho y alto correspondientemente).

A continuación se muestra un ejemplo de uso del paramétro:


policy.addParameter(PolicyParams.DIGITALIZED_SIGN_RECTANGLE.getKey(),newRectangle(40,60,100,80));




PolicyUtil.AddParameter(policy,PolicyParams.DIGITALIZED_SIGN_RECTANGLE,PolicyUtil.rectangleToJson(r));

DIGITALIZED_SIGN_RECTANGLE

Java

.Net


Desde este parámetro se puede especificar el formato de firma con el cual firmar el documento xml generado con losdatos biométrico que va adjuntado al pdf principal.

Los tipos de firmas disponibles son todas las opciones de la clase TypeFormatSign.



policy.addParameter(PolicyParams.DIGITALIZED_SIGNATURE_FORMAT,TypeFormatSign.PAdES_BASIC);


PolicyUtil.AddParameter(policy,PolicyParams.DIGITALIZED_SIGNATURE_FORMAT,yypeFormatSign.PAdES_BASIC);

DIGITALIZED_SIGNATURE_FORMAT

Java

.Net


Si queremos añadir información adicional a la firma, tendríamos que hacer uso de este parámetro, el cual recibecualquier cadena de texto y la añade a la información de la firma.

Un ejemplo de uso de este parámetro es el siguiente:


policy.addParameter(PolicyParams.DIGITALIZED_SIGNATURE_INFO.getKey();


PolicyUtil.AddParameter(policy,PolicyParams.DIGITALIZED_SIGNATURE_INFO,"aditionalinformation");

DIGITALIZED_SIGNATURE_INFO

Java

.Net


Para identificar más facilmente si un documento pdf está firmado normalmente se le añade un sello, ya bien seagenerado por Adobe al comprobar la validez de la firma o bien que seamos nosotros mismos los que indiquemos através de una política de firma en nuestra aplicación.

Para realizar un sello genérico utilizaremos la siguiente configuración en la política de firma:

PolicypolicyGenericStamper=newPolicy();

policyGenericStamper.addParameter(PolicyParams.DIGITAL_SIGN_PAGE.getKey(),"0");

policy.addParameter(PolicyParams.DIGITAL_SIGN_RECTANGLE.getKey(),neworg.viafirma.cliente.vo.Rectangle(40,10

A continuación se muestran los parámetros disponibles para configurar el sello de firma.

DIGITAL_SIGN_CONTACTDIGITAL_SIGN_IMAGE_STAMPERDIGITAL_SIGN_IMAGE_STAMPER_AUTOGENERATEDIGITAL_SIGN_LOCATIONDIGITAL_SIGN_TIMEZONEDIGITAL_SIGN_PAGEDIGITAL_SIGN_REASONDIGITAL_SIGN_RECTANGLEDIGITAL_SIGN_STAMPER_CSV_CODEDIGITAL_SIGN_STAMPER_CSV_URLDIGITAL_SIGN_STAMPER_FONT_SIZEDIGITAL_SIGN_STAMPER_HIDE_BARCODEDIGITAL_SIGN_STAMPER_HIDE_QRCODEDIGITAL_SIGN_STAMPER_HIDE_STATUSDIGITAL_SIGN_STAMPER_ROTATION_ANGLEDIGITAL_SIGN_STAMPER_TEXTDIGITAL_SIGN_STAMPER_TRANSPARENT_BACKGROUNDDIGITAL_SIGN_STAMPER_TYPE

Parámetros para sello de firma

115Parámetrosparasellodefirma

Este parámetro añade información de contacto del firmante.

Un ejemplo de uso de este parámetro es el siiguiente:


policy.addParameter(PolicyParams.DIGITAL_SIGN_CONTACT.getKey(),"ContactPersonName");

policypolicy=PolicyUtil.newPolicy(typeFormatSign.PAdES_BASIC,typeSign.ATTACHED);

PolicyUtil.AddParameter(policy,PolicyParams.DIGITAL_SIGN_CONTACT,"ContactPersonName");

DIGITAL_SIGN_CONTACT

Java

.Net


Si queremos que nuestro sello de firma tenga una imagen de fondo, deberemos usar el siguiente parámetro, el cualrecibe un byte[] de la imagen a mostrar.

A continuación se mostratá una ejemplo del uso de este parámetro:

byte[]logo=IOUtils.toByteArray(getClass().getResourceAsStream("/stamperWatermark.png"));

PolicypolicyImageStamper=newPolicy();

policyImageStamper.addParameter(PolicyParams.DIGITAL_SIGN_IMAGE_STAMPER.getKey(),logo);

//Obtengolaimagenaestampar

StreamstampImage=assembly.GetManifestResourceStream(stamperWatermark.jpg);





PolicyUtil.AddParameter(policy,PolicyParams.DIGITAL_SIGN_IMAGE_STAMPER,imageB64);

DIGITAL_SIGN_IMAGE_STAMPER

Java

.Net


Si se indica este parámetro con valor "true", añade el nombre y nif del firmante generando una imagen con esainformación.

Su valor por edefecto si no se indica es "false".



policy.addParameter(PolicyParams.DIGITAL_SIGN_IMAGE_STAMPER_AUTOGENERATE.getKey(),"true");


PolicyUtil.AddParameter(policy,PolicyParams.DIGITAL_SIGN_IMAGE_STAMPER_AUTOGENERATE,"true");

DIGITAL_SIGN_IMAGE_STAMPER_AUTOGENERATE

Java

.Net


Este parámetro añade información de localización, en texto libre, del firmante.



policy.addParameter(PolicyParams.DIGITAL_SIGN_LOCATION.getKey(),"Madrid");


PolicyUtil.AddParameter(policy,PolicyParams.DIGITAL_SIGN_LOCATION,"Madrid");

DIGITAL_SIGN_LOCATION

Java

.Net


El uso de este parámetro nos permite inidicar en qué pagina situaremos el sello de la firma. Se deberá pasar el númerode página como String.

Por ejemplo, si quisiéramos posicionar la firma en la primera página del documento indicaríamos el número "1", en lasegunda "2" y así sucesivamente. En el caso de que queramos mostrarla en la última página, el valor sería "-1", y porúltimo, si queremos mostrarla en todas las páginas, el valor será "0".

Para ver mejor cómo hacer uso del parámetro vamos a dejar a continuación unos ejemplos:


policy.addParameter(PolicyParams.DIGITAL_SIGN_PAGE.getKey(),"1");


PolicyUtil.AddParameter(policy,PolicyParams.DIGITAL_SIGN_PAGE,"1");

DIGITAL_SIGN_PAGE

Java

.Net


Este parámetro añade información de la razón de la firma en texto libre.



policy.addParameter(PolicyParams.DIGITAL_SIGN_REASON.getKey(),"Signreason");


PolicyUtil.AddParameter(policy,PolicyParams.DIGITAL_SIGN_REASON,"Signreason");

DIGITAL_SIGN_REASON

Java

.Net


Para definir las dimensiones y la posición del sello de la firma sobre la página, haremos uso de este parámetro el cualrecibe un objeto Rectangle proporcionado por la API de viafirma platform. Este objeto tiene 4 parámetros los cuales losdos primeros corresponden a la posición del rectángulo (X e Y correspondientemente) y los otros dos a las dimensionesdel mismo (ancho y alto correspondientemente).

En el ejemplo que veremos a continuación se puede observar cómo se implementa el parámetro mencionado:


policy.addParameter(PolicyParams.DIGITAL_SIGN_RECTANGLE.getKey(),newRectangle(255,100,150,100));



policypolicy=PolicyUtil.newPolicy(TypeFormatSign.PAdES_BASIC,typeSign.ATTACHED);

PolicyUtil.AddParameter(policy,PolicyParams.DIGITAL_SIGN_RECTANGLE,PolicyUtil.rectangleToJson(r));

DIGITAL_SIGN_RECTANGLE

Java

.NET


Mediante este párametro podemos usar un codigo CSV personalizado en PdfSignature Appearance. El texto del códigoCSV es una cadena de texto libre.



policy.addParameter(PolicyParams.DIGITAL_SIGN_STAMPER_CSV_CODE.getKey(),"codigocsvpersonalizado");


PolicyUtil.AddParameter(policy,PolicyParams.DIGITAL_SIGN_STAMPER_CSV_CODE,"codigocsvpersonalizado");

DIGITAL_SIGN_STAMPER_CSV_CODE

Java

.Net


Mediante este párametro podemos usar una url personalizada de CSV en PdfSignature Appearance. La url es unacadena de texto libre.



policy.addParameter(PolicyParams.DIGITAL_SIGN_STAMPER_CSV_URL.getKey(),"http://customurl.com/");


PolicyUtil.AddParameter(policy,PolicyParams.DIGITAL_SIGN_STAMPER_CSV_URL,"http://customurl.com/");

DIGITAL_SIGN_STAMPER_CSV_URL

Java

.Net


Define el tamaño de la fuente en sellos de tipo texto. El texto a pasar debe ser un tamaño de fuente válido.



policy.addParameter(PolicyParams.DIGITAL_SIGN_STAMPER_FONT_SIZE.getKey(),"12");


PolicyUtil.AddParameter(policy,PolicyParams.DIGITAL_SIGN_STAMPER_FONT_SIZE,"12");

DIGITAL_SIGN_STAMPER_FONT_SIZE

Java

.Net


En los sellos de firma podemos personalizarlos de forma que si no queremos ciertos elementos podemos utilizar unaserie de parámetros con los cuales podemos descartar.

Con este parámetro podremos indicar si queremos o no el código de barras que está incluido. Por defecto, si nohacemos uso de este parámetro, el codigo de barras será visible.

En el siguiente ejemplo mostramos cómo hacer uso este parámetro.

PolicypolicyHideBarcode=newPolicy();

policyHideBarcode.addParameters(PolicyParams.DIGITAL_SIGN_STAMPER_HIDE_BARCODE.getKey(),"true");


PolicyUtil.AddParameter(policy,PolicyParams.DIGITAL_SIGN_STAMPER_HIDE_BARCODE,"true");

DIGITAL_SIGN_STAMPER_HIDE_BARCODE

Java

.Net


Al igual que el anterior parámetro éste sirve para ocultar elementos del sello de firma que implementa viafirma platformen los documentos. Este parámetro se encarga de ocultar el código QR. Por defecto, si no se indica, el valor será"false" con lo que se mostrará el elemento en el sello de firma.

En el siguiente ejemplo se puede ver como hacer uso del parámetro:

PolicypolicyHideQRCode=newPolicy();

policyHideQRCode.addParameter(PolicyParams.DIGITAL_SIGN_STAMPER_HIDE_QR_CODE.getKey(),"true");


PolicyUtil.AddParameter(policy,PolicyParams.DIGITAL_SIGN_STAMPER_HIDE_QR_CODE,"true");

DIGITAL_SIGN_STAMPER_HIDE_QRCODE

Java

.Net


Al igual que los anteriores con este parámetro conseguimos ocultar un elemento en el sello de firma que estampa laplataforma en el documento, concretamente el estado de la misma. Por defecto, si no se indica, la plataforma ponedicho elemento en el sello de firma.

Para ver mejor como implementar el parámetro, vamos a realizar el siguiente ejemplo:

PolicypolicyHideStatus=newPolicy();

policyHideStatus.addParameter(PolicyParams.DIGITAL_SIGN_STAMPER_HIDE_SATUS.getKey(),"true");


PolicyUtil.AddParameter(policy,PolicyParams.DIGITAL_SIGN_STAMPER_HIDE_STATUS,"true");

DIGITAL_SIGN_STAMPER_HIDE_STATUS

Java

.Net


Hay ocasiones en las que queremos que el sello esté de manera vertical en lugar de horizontal. Éste es el uso delparámetro que estamos comentando.

Por defecto, si no se indica el parámetro el sello se mostrará de forma horizontal. La rotación se hará siguiendo lasmanecillas del reloj.

En el siguiente ejemplo veremos como implementar el parámetro para girar el sello 90º y así tenerlo de forma vertical.

PolicypolicyRotationAngle=newPolicy();

policyRotationAngle.addParameter(PolicyParams.DIGITAL_SIGN_STAMPER_ROTATION_ANGLE.getKey(),"90");


PolicyUtil.AddParameter(policy,PolicyParams.DIGITAL_SIGN_STAMPER_ROTATION_ANGLE,"90");

DIGITAL_SIGN_STAMPER_ROTATION_ANGLE

Java

.Net


Si utilizamos este parámetro, en el sello de firma se mostrará el texto que le indiquemos como parámetro. Por defecto,si no se indica el parámetro no se visualizará ningún texto.

En la cadena de texto libre que introduciremos en este parámetro, podemos hacer uso de los siguientes comodines detexto.

[key-oid]: cualquier parámetro de las propiedades oid que vienen parseados dentro de los datos del certificado, porejemplo: [CN], [SERIALNUMBER], [O], etc ... En el caso de que no existan esos valores en el certificado firmante,se mostrará un espacio en blanco en su lugar.[vSignIdKey]: esta cadena de texto será reemplazada por el identificador de la firma.[vCSVKey]: esta cadena de texto será reemplazada por la URL del CSV más el identificador de la firma.[vSignTimeKey]: esta cadena de texto será reemplazada por la fecha/hora de la firma. Es posible especificar elformato de fecha/hora que se desea imprimir, por ejemplo de la siguiente forma: [vSignTimeKey(dd/MM/yyyyHH:mm:ss)], si no es especifica, el formato por defecto será yyyy-MM-dd HH:mm:ss Z

En el siguiente ejemplo vemos como hacer uso de este parámetro:

PolicypolicyStamperText=newPolicy();

policyStamperText.addParameter(PolicyParams.DIGITAL_SIGN_STAMPER_TEXT.getKey(),"Firmadopor[CN]conDNI[SERIALNUMBER]\ntrabajadorde[O]eneldepartamentode[OU].\nFechadefirma:[vSignTimeKey(dd/MM/yyyyHH:mm:ss)]\nIdentificadordelafirma:[vSignIdKey]);

policypolicy=PolicyUtil.newPolicy(typeFormatSign.DIGITAL_SIGN_STAMPER_TEXT,typeSign.ATTACHED);

PolicyUtil.AddParameter(policy,PolicyParams.DIGITAL_SIGN_STAMPER_ROTATION_ANGLE,"Firmadopor[CN]conDNI[SERIALNUMBER]\ntrabajadorde[O]eneldepartamentode[OU].\nFechadefirma:[vSignTimeKey(dd/MM/yyyyHH:mm:ss)]\nIdentificadordelafirma:[vSignIdKey]);

DIGITAL_SIGN_STAMPER_TEXT

Java

.Net


Con este parámetro podemos indicar que el fondo del sello de la firma sea transparente o no. Por defecto el valor estrue.



policy.addParamenter(PolicyParams.DIGITAL_SIGN_STAMPER_TRANSPARENT_BACKGROUND.getKey(),"true");


PolicyUtil.AddParameter(policy,PolicyParams.DIGITAL_SIGN_STAMPER_TRANSPARENT_BACKGROUND,"true");

DIGITAL_SIGN_STAMPER_TRANSPARENT_BACKGROUND

Java

.Net


Con este parámetro indicamos que tipo de sello de firma es el que estampará la plataforma en el documento firmado.Puede recibir los siguientes valores:

PDF417-HQR-BAR-H

En el siguiente ejemplo se puede ver el código necesario para implementar este parámetro:


policy.addParameter(PolicyParams.DIGITAL_SIGN_STAMPER_TYPE.getKey(),"QR-BAR-H");


PolicyUtil.AddParameter(policy,PolicyParams.DIGITAL_SIGN_STAMPER_TYPE,"QR-BAR-H");

DIGITAL_SIGN_STAMPER_TYPE

Java

.Net


Este parámetro permite incluir la zona horaria de la aplicación, para representar la fecha y hora si el sello configuradoincluye esta información.

El formato del timezone es, por ejemplo, "GMT", "GMT+1", "GMT-8", pero también es válido "Europe/Madrid" paraevitar problemas en aplicaciones ubicadas en regiones que tengan horario de verano / invierno. Otros ejemplos serían"America/Santiago", "Europe/Madrid", "AST", "PST"... El formato es el utilizado internamente por Java (más informaciónen https://www.mkyong.com/java/java-display-list-of-timezone-with-gmt/) Si el formato de timezone pasado no esreconocido por el sistema, se tomará por defecto GMT.



policy.addParameter(PolicyParams.DIGITAL_SIGN_TIMEZONE.getKey(),"Europe/Madrid");


PolicyUtil.AddParameter(policy,PolicyParams.DIGITAL_SIGN_TIMEZONE,"Europe/Madrid");

DIGITAL_SIGN_TIMEZONE

Java

.Net


https://www.mkyong.com/java/java-display-list-of-timezone-with-gmt/

Podemos configurar la firma para adaptarla a nuestras necesidades, desde filtrar qué certificados mostrar a cambiar laaparencia de la aplicación de selección de certificados.

Para ello tenemos disponible los siguientes parámetros en los que podemos configurar y que detallaremos más a fondoen su correspondiente sección:

APPLET_STYLEBINARY_NODE_CONTENT_MIME_TYPECADES_DO_COUNTERSIGNATURECALLBACK_URLCLIENT_LOCALECONTINUE_LOOP_WITH_ERRORSCSV_MINIMUM_SIZECSV_PREFIXDETACHED_REFERENCE_URLDETACHED_TYPEDIGEST_METHODDISCARD_EXPIRED_CERTIFICATESENVELOPED_TARGET_NODEFILTER_CA_NAMEFILTER_CERTIFICATE_BYFILTER_GENERICFILTER_NUMBER_USER_IDHIDE_ERROR_PAGEHIDE_MOBILE_BUTTONSNODE_ID_TO_SIGNORIGINAL_HASHPADES_INCLUDE_TSAPDF_ANNOTATION_IMAGEPDF_ANNOTATION_PAGEPDF_ANNOTATION_RECTANGLESIGN_BINARY_NODE_CONTENTSIGNATURE_ALGORITHMSIGNATURE_POLICY_DESCRIPTIONSIGNATURE_POLICY_HASH_DATASIGNATURE_POLICY_IDSIGNATURE_POLICY_TRANSFORMSIGNATURE_POLICY_URISIGNER_ROLEXML_CANONICALIZATION_METHODXML_CANONIZATION_TRANSFORM

Parámetros configuración de firma

134Parámetrosconfiguracióndefirma

Este parámetro permite especificar por policy la URL de la hoja de estilos CSS con el que quiere que Viafirma Platformmuestre la página de autenticación/firma



policy.addParameter(PolicyParams.CUSTOM_CSS_URL.getKey(),"https://custom-url/custom.css");

PolicyUtil.AddParameter(policy,PolicyParams.CUSTOM_CSS_URL,"https://custom-url/custom.css");

CUSTOM_CSS_URL

Java

.Net


Con este parámetro podemos indicar el estilo que puede tener el applet de selector de certificados de viafirma platform.

En el siguiente ejemplo se puede ver como utilizar el parámetro.


policy.addParameter(PolicyParams.APPLET_STYLE.getKey(),"templateBlue")


PolicyUtil.AddParameter(policy,PolicyParams.APPLET_STYLE,"templateBlue");

APPLET_STYLE

Java

.Net


Añadiendo este parámetro indicamos el tipo de formato (mime type) del contenido binario que se incluye en parámetroNODE_ID_TO_SIGN.

Solo se puede usar cuando SIGN_BINARY_NODE_CONTENT está configurado como true.



policy.addParameter(PolicyParams.BINARY_NODE_CONTENT_MIME_TYPE.getKey(),"true")

policypolicy=PolicyUtil.newPolicy(typeFormatSign.XADES_EPES_ENVELOPED,typeSign.ENVELOPED);

PolicyUtil.AddParameter(policy,PolicyParams.BINARY_NODE_CONTENT_MIME_TYPE,"true");

BINARY_NODE_CONTENT_MIME_TYPE

Java

.Net


Marcando este parámetro como a true, se fuerza la contrafirma en las firmas en formato CAdES en los casos que seaposible.



policy.addParameter(PolicyParams.CADES_DO_COUNTERSIGNATURE.getKey(),"true")

policypolicy=PolicyUtil.newPolicy(typeFormatSign.CADES_BES,typeSign.ENVELOPED);

PolicyUtil.AddParameter(policy,PolicyParams.CADES_DO_COUNTERSIGNATURE,"true");

CADES_DO_COUNTERSIGNATURE

Java

.Net


Con el uso de este parámetro podemos indicar la url de respuesta al terminar el la operación de firma, de forma quepodemos enviar la respuesta a una aplicación externa.

En el siguiente codigo podemos ver un ejemplo en el que se integra este parámetro.


policy.addParameter(PolicyParams.CALLBACK_URL.getKey(),"http://testservices.viafirma.com/ejemploViafirma/ViafirmaCallbackServlet");


PolicyUtil.AddParameter(policy,PolicyParams.CALLBACK_URL,"http://testservices.viafirma.com/ejemploViafirma/ViafirmaCallbackServlet");

CALLBACK_URL

Java

.Net


Podemos cambiar el idioma en el que se muestran las aplicaciones de selección de certificados, así como las propiasventanas de viafirma platform, utilizando este parámetro. En el caso que no se indique este parámetro, el idioma que semostrará será el configurado en el navegador del usuario final. Los posibles valores son los siguientes:

es_ES: Españolca_ES: Catalánen_EN: Inglés

Con el código que se muestra a continuación se puede ver la forma de implementar este parámetro


policy.addParameter(PolicyParams.CLIENT_LOCALE.getKey(),"es_ES");


PolicyUtil.AddParameter(policy,PolicyParams.CLIENT_LOCALE,"es_ES");

CLIENT_LOCALE

Java

.Net


Puede darse el caso de que, en una firma en bucle, falle la firma de algunos de los documento del listado a firmar. Encuyo caso, la firma del resto de los documentos se cancelará, dando el proceso como no válido.

Este parámetro, configurado como a true, permite continuar el proceso de firmado en bucle aunque una o varias de lasfirmas fallen. El identificador final entregado consistirá en una lista, serpada por ";" de los ids y errores en el mismoorden en que fueron solicitadas las firmas. Los errores en la lista seguirán en el siguiente patrón:

ERROR: errorCode:errorMessage

Por defecto este parámetro si no se indica valdrá false.


policy.addParameter(PolicyParams.CONTINUE_LOOP_WITH_ERRORS.getKey(),"true")


PolicyUtil.AddParameter(policy,PolicyParams.CONTINUE_LOOP_WITH_ERRORS,"true");

CONTINUE_LOOP_WITH_ERRORS

Java

.Net


Define el tamaño mínimo de la salida CSV (identificador de firma) para una operación de firma. El tamaño máximopermitido por un CSV son 127 caracteres (incluyendo separadores)

Los caracteres que se añadirán para llegar al mínimo establecido serán generados de forma aleatoria.

Con el código que se muestra a continuación se puede ver la forma de implementar este parámetro:


policy.addParameter(PolicyParams.CSV_MINIMUM_SIZE.getKey(),"150");


PolicyUtil.AddParameter(policy,PolicyParams.CSV_MINIMUM_SIZE,"150");

CSV_MINIMUM_SIZE

Java

.Net


Define un prefijo para incorporar en la calida CSV (identificador de firma) para operaciones de firmas. La cadena detexto que incorporemos será texto libre.



policy.addParameter(PolicyParams.CSV_PREFIX.getKey(),"PREFIXTEST");


PolicyUtil.AddParameter(policy,PolicyParams.CSV_PREFIX,"PREFIXTEST");

CSV_PREFIX

Java

.Net


Añadiendo este parámetro, indicamos cual va a ser la url pública de descarga del documento original de un documentofirmado de tipo DETACHED, ya que para este tipo de firma no se puede obtener el documento original desde elfirmado.


policy.addParameter(PolicyParams.DETACHED_REFERENCE_URL.getKey(),"https://descargas.viafirma.com/viafirma/exampleSign.pdf");

policypolicy=PolicyUtil.newPolicy(typeFormatSign.XADES_BES,typeSign.DETACHED);

PolicyUtil.AddParameter(policy,PolicyParams.DETACHED_REFERENCE_URL,"https://descargas.viafirma.com/viafirma/exampleSign.pdf");

DETACHED_REFERENCE_URL

Java

.Net


En una firma de tipo DETACHED, podemos indicarle que tipo de firma DETACHED deaseamos configurar. Desde el laPolicyParams.DetachedType encontraremos los valores disponibles que se pueden añadir a éste parámetro:

INTERNALLYEXTERNALLY



policy.addParameter(PolicyParams.DETACHED_TYPE.getKey(),PolicyParams.DetachedType.INTERNALLY.name());

policypolicy=PolicyUtil.newPolicy(typeFormatSign.XADES_BES,typeSign.DETACHED);

PolicyUtil.AddParameter(policy,PolicyParams.DETACHED_TYPE,"INTERNALLY");

DETACHED_TYPE

Java

.Net


Podemos indicar el algoritmo usado para calcular el digest de la firma mediante este parámetro. Solo aplicable aformato XAdES, para otros formatos no debería estar informado o informado con el metodo correspondiente alalgoritmo de firma SIGNATURE_ALGORITHM.

Los posibles valores vienen definidos en la clase DigestMethod y son los siguientes:

SHA1SHA256SHA384SHA512

El valor por defecto, si no se define nada en este parámetro, es SHA1.


policy.addParameter(PolicyParams.DIGEST_METHOD.getKey(),DigestMethod.SHA256.name());


PolicyUtil.AddParameter(policy,PolicyParams.DIGEST_METHOD,"SHA256");

DIGEST_METHOD

Java

.Net


Si en la lista de certificados disponibles para su selección por parte de un usuario, desde la aplicación elegida deselección de certificados, no queremos que se muestren los certificados que hayan expidado, debemos configurar esteparámetro como true.

El valor por defecto, si no se define nada en este parámetro, es "false".


policy.addParameter(PolicyParams.DISCARD_EXPIRED_CERTIFICATES.getKey(),"true");


PolicyUtil.AddParameter(policy,PolicyParams.DISCARD_EXPIRED_CERTIFICATES,"true");

DISCARD_EXPIRED_CERTIFICATES

Java

.Net


Desde este parámetro, indicamos que el nodo generado por la firma en XAdES, sea incluido en un nodo existente delXML a firmar, el cual le indicamos el valor de este parámetro.

El valor introducido acepta expresiones xpath.


//nododestinodelafirma

policy.addParameter(PolicyParams.ENVELOPED_TARGET_NODE.getKey(),"//*[local-name()='indice']/*[local-name()='firmas']/*[local-name()='firma']/*[local-name()='ContenidoFirma']/*[local-name()='FirmaConCertificado']");


//nododestinodelafirma

PolicyUtil.AddParameter(policy,PolicyParams.ENVELOPED_TARGET_NODE,"//*[local-name()='indice']/*[local-name()='firmas']/*[local-name()='firma']/*[local-name()='ContenidoFirma']/*[local-name()='FirmaConCertificado']");

ENVELOPED_TARGET_NODE

Java

.Net


Podemos hacer que las aplicaciones de selección de certificados de viafirma platform muestren únicamente loscertificados de una CA concreta. Esto podemos conseguirlo con el uso de este parámetro, el cual recibe el nombre dela CA a filtrar, por ejemplo FNMT.

Este filtro es algo flexible, pudiendo configurar más de una coincidencia de CA, separando los valores por ';', ejemploFNMT;CAMERFIRMA;etc.

También podemos usar operadores que indiquen si deseamos que la coincidencia sea idéntica, que contenga lapalabra o que no. Los operadores son los siguientes:

equals: Las cadenas indicadas deben ser iguales a la CA del certificado. Esta es la opción por defecto en el casode que no se especifique un operador.contains: El nombre de la CA debe contener alguna de las cadenas indicadas en el parámetro.starts_with: El nombre de la CA debe empezar por alguna de las cadenas indicadas en el parámetro.ends_with: El nombre de la CA debe terminar por alguna de las cadenas indicadas en el parámetro.

Se usan de la siguiente forma: Contains;FNTM;CAMERFIRMA.

Para ver más claro como implementar este parámetro os mostramos el siguiente código.


policy.addParameter(PolicyParams.FILTER_CA_NAME.getKey(),"Contains;FNTM;CAMERFIRMA")


PolicyUtil.AddParameter(policy,PolicyParams.FILTER_CA_NAME,"Contains;FNTM;CAMERFIRMA");

FILTER_CA_NAME

Java

.Net


Podemos hacer que las aplicaciones de selección de certificados de viafirma platform muestren únicamente loscertificados que configuremos con este parámetro.

A este filtro le indicamos un mapa de atributos que deben coincidir con los del certificados que queremos filtrar.

Si se usa el prefijo ISSUER., también tendrá en cuenta los atributos del padre de los certificados a firmar.

List<Map<String,String>>filtros=newjava.util.ArrayList<Map<String,String>>();

Map<String,String>filtro1=newHashMap<String,String>();

filtro1.put("ISSUER.O","FNMT");

Map<String,String>filtro2=newHashMap<String,String>();

filtro2.put("1.3.6.1.4.1.5734.1.8","*");

filtro2.put("ISSUER.CN","AVANSICERTIFICADOSDIGITALES");

filtros.add(filtro1);

filtros.add(filtro2);


policy.addParameter(PolicyParams.FILTER_CERTIFICATE_BY.getKey(),filtros)

List<Dictionary<String,String>>filters=newList<Dictionary<String,String>>();

Dictionary<String,String>filter1=newDictionary<String,String>();

filter1.Add("O","FNMT");

Dictionary<String,String>filter2=newDictionary<String,String>();

filter2.Add("1.3.6.1.4.1.5734.1.8","*");

filter2.Add("ISSUER.CN","AVANSICERTIFICADOSDIGITALES");

filters.Add(filter1);

filters.Add(filter2);


PolicyUtil.AddParameter(policy,PolicyParams.FILTER_CERTIFICATE_BY,PolicyUtil.ObjectToJson(filters));

FILTER_CERTIFICATE_BY

Java

.Net


En el caso de que deseemos filtrar los certificados, a mostrar en las aplicaciones de selección de certificados, filtrandopor cualquier campo que contenga el certificado, debemos usar este parámetro.

Este filtro es algo flexible, pudiendo configurar más de una coincidencia de cualquier campo, separando los valores por';', ejemplo FNMT;56987455;Madrid.

También podemos usar operadores que indiquen si deseamos que la coincidencia sea idéntica, que contenga lapalabra o que no. Los operadores son los siguientes:

equals: Las cadenas indicadas deben ser iguales a los campos que coincidan del certificado. Esta es la opciónpor defecto en el caso de que no se especifique un operador.contains: El valor del campo que coincida debe contener alguna de las cadenas indicadas en el parámetro.starts_with: El valor del campo que coincida debe empezar por alguna de las cadenas indicadas en el parámetro.ends_with:El valor del campo que coincida debe terminar por alguna de las cadenas indicadas en el parámetro.

Se usan de la siguiente forma: starts_with;FNMT;56987455;Madrid.



policy.addParameter(PolicyParams.FILTER_GENERIC.getKey(),"starts_with;FNMT;56987455;Madrid")


PolicyUtil.AddParameter(policy,PolicyParams.FILTER_GENERIC,"starts_with;FNMT;56987455;MadridA");

FILTER_GENERIC

Java

.Net


Podemos realizar filtros por la propiedad NumberUserId de los certificados, de forma que podemos mostrar únicamentelos certificados cuyo valor en dicho campo sea igual al que facilitamos.

Si queremos filtrar por múltiples NumberUserIds, podemos pasarlos separados por ; tal y como puede apreciarse en elejemplo a continuación. 123456789L;K56987455.

equals: Las cadenas indicadas deben ser iguales a los campos que coincidan del certificado. Esta es la opciónpor defecto en el caso de que no se especifique un operador.contains: El valor del campo que coincida debe contener alguna de las cadenas indicadas en el parámetro.starts_with: El valor del campo que coincida debe empezar por alguna de las cadenas indicadas en el parámetro.ends_with:El valor del campo que coincida debe terminar por alguna de las cadenas indicadas en el parámetro.

Se usan de la siguiente forma: ends_with;123456789L;K56987455.



policy.addParameter(PolicyParams.FILTER_NUMBER_USER_ID.getKey(),"ends_with;123456789L;K56987455")


PolicyUtil.AddParameter(policy,PolicyParams.FILTER_NUMBER_USER_ID,"ends_with;123456789L;K56987455");

FILTER_NUMBER_USER_ID

Java

.Net


En el caso en el que no se desee mostrar la página de control de errores al usuario final, configuramos esta propiedadcomo true. El valor por defecto es false.

Aunque la aplicación falle en el proceso de firmado o autenticación, el usuario no notará que ha fallado.

Normalmente se configura para para que los errores vuelvan a la url de callback sin pasar por la pagina de error deViafirma, y desde allí hacer un control propio de errores.



policy.addParameter(PolicyParams.HIDE_ERROR_PAGE.getKey(),"true")


PolicyUtil.AddParameter(policy,PolicyParams.HIDE_ERROR_PAGE,"true");

HIDE_ERROR_PAGE

Java

.Net


En las aplicaciones de selección de certificados, tanto móviles como de PC, existen una serie de botones con lasfuncionalidades de Ver documento (PC y móvil), usar smartcard(móvil), llaveros de credenciales (móvil) e importarcertificado .pfx o .p12 (PC y móvil).

Éstos botones pueden ser ocultados, dependiendo de nuestras necesidades, mediante la utilización de este parámetro,indicando los valores separados por ";" de los botones a ocultar.

Los posibles valores que se le pueden indicar son los contenidos en la clase MobileButtonLabel:

VIEW_DOCUMENT: Ver documento (PC y móvil).SMARTCARD: usar smartcard(móvil).P12_FILE: Importar certificado .pfx o .p12 (PC y móvil).KEYCHAIN: llaveros de credenciales (móvil).



policy.addParameter(PolicyParams.HIDE_MOBILE_BUTTONS.getKey(),"MobileButtonLabel.VIEW_DOCUMENT.name();MobileButtonLabel.P12_FILE.name()")

policypolicy=PolicyUtil.newPolicy(typeFormatSign.PADES_BASIC,typeSign.ATTACHED);

PolicyUtil.AddParameter(policy,PolicyParams.HIDE_MOBILE_BUTTONS,"VIEW_DOCUMENT;P12_FILE");

HIDE_MOBILE_BUTTONS

Java

.Net


En las firmas XAdES podemos firmar un nodo específico del fichero XML. Para ello usaremos este parámetro en el queindicamos dicho nodo del fichero.

En el siguiente ejemplo podemos ver como podemos implementar este parámetro.


policy.addParameter(PolicyParams.NODE_ID_TO_SIGN.getKey(),"N2");


PolicyUtil.AddParameter(policy,PolicyParams.NODE_ID_TO_SIGN,"N2");

NODE_ID_TO_SIGN

Java

.Net


En las firmas de tipo DETACHED, podemos indicarle cual va a ser el hash del documento original.


policy.addParameter(PolicyParams.ORIGINAL_HASH.getKey(),Base64.encodeBase64(DigestUtils.sha(newByteArrayInputStream(datosOriginales))));


PolicyUtil.AddParameter(policy,PolicyParams.ORIGINAL_HASH,datosOriginales);

ORIGINAL_HASH

Java

.Net


Parametro opcional para incluir o no el sello de tiempo en la firma de un documento. Solo PAdES_BES yPAdES_EPES.

El valor por defecto es true y si se indica false, estos tipos de firma no llevarán sellado de tiempo.

En el siguiente ejemplo podemos ver como podemos implementar este parámetro.


policy.addParameter(PolicyParams.PADES_INCLUDE_TSA.getKey(),"false");

policypolicy=PolicyUtil.newPolicy(typeFormatSign.PADES_BES,typeSign.ATTACHED);

PolicyUtil.AddParameter(policy,PolicyParams.PADES_INCLUDE_TSA,"false");

PADES_INCLUDE_TSA

Java

.Net


Con el uso de este parámetro podemos añadir imágenes como anotaciones e incrustralas en el PDF firmado. Para eluso de este parámetro es necesario implementar también el parámetro PDF_ANOTATION_PAGE el cual se detalla ensu correspondiente sección.

A este parámetro se le pasa una imagen codificada en Base64.

//Datosimagendefirma

byte[]imageStamp=IOUtils.toByteArray(this.getClass().getResourceAsStream("logoStamp.jpg"));

//ImagenenBase64

Stringbase64Image=Base64.encodeBase64(imageStamp);


policy.addParameter(PolicyParams.PDF_ANNOTATION_IMAGE.getKey(),base64Image);

//Datosimagendefirma

StreamstampImage=assembly.GetManifestResourceStream(logoStamp.jpg);



//ImagenenBase64



PolicyUtil.AddParameter(policy,PolicyParams.PDF_ANNOTATION_IMAGE,imageB64);

PDF_ANNOTATION_IMAGE

Java

.Net


Junto con el parámetro mencionado en el punto anterior PDF_ANOTATION_IMAGE, éste sirve para indicar en quépágina del documento se insertará la imagen como anotación.

Por ejemplo, si quisiéramos posicionar la anotaciónm en la primera página del documento indicaríamos el número "1",en la segunda "2" y así sucesivamente. En el caso de que queramos mostrarla en la última página, el valor sería "-1", ypor último, si queremos mostrarla en todas las páginas, el valor será "0".

Para ver un ejemplo de implementación del parámetro os facilitamos el siguiente ejemplo


policy.addParameter(PolicyParams.PDF_ANNOTATION_PAGE.getKey(),"1");


PolicyUtil.AddParameter(policy,PolicyParams.PDF_ANNOTATION_PAGE,"1");

PDF_ANNOTATION_PAGE

Java

.Net


Este parámetro nos permite indicar las dimensiones y la posición en la página que estará en la anotación que creemoscon la imagen seleccionada y la página en los anteriores parámetros.

El objeto que se facilita como valor del parámetro es un Recatangle de la librería de viafirma, el cual se usa tambiénpara los parámetros de sello y firma digitalizada.

Para ver como sería la implementación del parámetro podemos ver el código que hay a continuación.

PolicypolicyAnnotationRectangle=newPolicy();

policyAnnotationRectangle.addParameter(PolicyParams.PDF_ANNOTATION_RECTANLGE.getKey(),newRectangle(255,100,150,100));




PolicyUtil.AddParameter(policy,PolicyParams.PDF_ANNOTATION_RECTANLGE,PolicyUtil.rectangleToJson(r));

PDF_ANNOTATION_RECTANGLE

Java

.Net


Indica si la firma se aplica al contenido del nodo indicado en NODE_ID_TO_SIGN o sobre el nodo completo.

Los valores posibles son true o false, en el caso de no indicar ningún valor, tomará por defecto el valor false.



policy.addParameter(PolicyParams.SIGN_BINARY_NODE_CONTENT.getKey(),"true");


PolicyUtil.AddParameter(policy,PolicyParams.SIGN_BINARY_NODE_CONTENT,"true");

SIGN_BINARY_NODE_CONTENT

Java

.Net


Podemos indicar el algoritmo que será usado en la firma mediante este parámetro.

Los posibles valores vienen definidos en la clase SignatureAlgorithm y son los siguientes:

SHA1withRSASHA256withRSASHA384withRSASHA512withRSA

El valor por defecto, si no se define nada en este parámetro, es SHA256withRSA.


policy.addParameter(PolicyParams.SIGNATURE_ALGORITHM.getKey(),SignatureAlgorithm.SHA256withRSA.name());

policypolicy=PolicyUtil.newPolicy(typeFormatSign.PADES_BES,typeSign.ENVELOPED);

PolicyUtil.AddParameter(policy,PolicyParams.SIGNATURE_ALGORITHM,"SHA256withRSA");

SIGNATURE_ALGORITHM

Java

.Net


Esta configuración se trata de un parámetro opcional el cual indica la descripción de la política de firma a asociar aldocumento firmado.

El valor que podremos intruducir en este campo se trata de una cadena de texto libre, que debe ser descriptivo alSIGNATURE_POLICY_ID y al SIGNATURE_POLICY_URI asociada.

Para ver un ejemplo de implementación del parámetro os facilitamos el siguiente ejemplo:


policy.addParameter(PolicyParams.SIGNATURE_POLICY_DESCRIPTION.getKey(),"PolíticadefirmaelectrónicabasadaencertificadosGobiernodeEspaña.");


PolicyUtil.AddParameter(policy,PolicyParams.SIGNATURE_POLICY_DESCRIPTION,"PolíticadefirmaelectrónicabasadaencertificadosGobiernodeEspaña.");

SIGNATURE_POLICY_DESCRIPTION

Java

.Net


Hash (codificado en base64) para la política de firma utilizando el algoritmo de viafirma para digest (por defecto SHA-1),o lista con hash como primer elemento y algoritmo de resumen en el segundo.

Este parámetro no es obligatorio, si no se indica, la plataforma tratará de acceder a la url del documento informada enSIGNATURE_POLICY_URI y calculará el hash de la política automáticamente.

Si no se informa URI o sabemos que ésta no es accesible desde el servidor de viafirma platform, entonces informamosel parámetro éste parámetro.

Podríamos indicar este dato de varias formas:


//SOLOHASH

policy.addParameter(PolicyParams.SIGNATURE_POLICY_HASH_DATA.getKey(),"M97XDPtxhg1Tv6qBNYcM8mEl0OE=");


PolicyUtil.AddParameter(policy,PolicyParams.SIGNATURE_POLICY_HASH_DATA,"M97XDPtxhg1Tv6qBNYcM8mEl0OE=.");

El primer elemento sería como el anterior, calculando el hash usando el algoritmo que luego se deberá informar en elsegundo elemento. En ese segundo elemento se informaría el algoritmo con el que se ha calculado el hash previo, elvalor a utilizar sería algo como DigestMethod.SHA256.name() o el algoritmo que corresponda de este enumDigestMethod.

Los posibles valores vienen definidos en la clase DigestMethod y son los siguientes:

SHA1SHA256SHA384SHA512

SIGNATURE_POLICY_HASH_DATA

Calculando el hash, usando SHA-1, y colocarlo en base 64

Java

.Net

Calculando el hash usando un algoritmo de digest distinto a SHA-1 y colocarlo en base 64

Java



//HASH+ALGORITHM

List<String>hashData=newArrayList<String>();

hashData.add("RT97dsfttxhg2Tv5qHNYcN45mAlasE0=");

hashData.add(DigestMethod.SHA256.name());

policy.addParameter(PolicyParams.SIGNATURE_POLICY_HASH_DATA.getKey(),hashData);


//HASH+ALGORITHM

List<String>hashData=newList<String>();

hashData.Add("RT97dsfttxhg2Tv5qHNYcN45mAlasE0=");

hashData.Add("SHA256");

PolicyUtil.AddParameter(policy,PolicyParams.SIGNATURE_POLICY_HASH_DATA,hashData");

.Net


Desde este parámetro podremos asociar un Identificador de Política de firma al documento firmado, que estaráasociado con la url de la misma definida en el parámetro SIGNATURE_POLICY_URI.

El valor que se indique en este parámetro, puede ser cualquier String mientras se asegure de que pertenece a unidentificador real de una Política de Firma.



policy.addParameter(PolicyParams.SIGNATURE_POLICY_ID.getKey(),"2.16.724.1.3.1.1.2.1.8");

policypolicy=PolicyUtil.newPolicy(typeFormatSign.PADES_EPES,typeSign.ENVELOPED);

PolicyUtil.AddParameter(policy,PolicyParams.SIGNATURE_POLICY_ID,"2.16.724.1.3.1.1.2.1.8");

SIGNATURE_POLICY_ID

Java

.Net


En este parámetro se indica una lista de transforms (definidos en Apache xml Transforms) usados para calcularSIGNATURE_POLICY_HASH, que es opcional.

Como decimos, los valores que se pueden emplear en este parámetro, son los definidos en Apache xml Transforms.

Al indicar el trasnform en este parámetro, creará el siguiente nodo en una firma XADES.

<ds:Transforms>

<ds:TransformAlgorithm="http://www.example.com/">

Anytext,intermingledwith:



</ds:Transform>

</ds:Transforms>


policy.addParameter(PolicyParams.SIGNATURE_POLICY_TRANSFORM.getKey(),"http://www.example.com/");


PolicyUtil.AddParameter(policy,PolicyParams.SIGNATURE_POLICY_TRANSFORM,"http://www.example.com/");

SIGNATURE_POLICY_TRANSFORM

Java

.Net

Desde este parámetro podremos asociar una URL de la Política de firma al documento firmado, que estará asociadocon el Identificador de la misma definida en el parámetro SIGNATURE_POLICY_ID.

El valor que se indique en este parámetro, puede ser cualquier String mientras se asegure de que pertenece a una URLreal de una Política de Firma.



policy.addParameter(PolicyParams.SIGNATURE_POLICY_URI.getKey(),"http://administracionelectronica.gob.es/es/ctt/politicafirma");


PolicyUtil.AddParameter(policy,PolicyParams.SIGNATURE_POLICY_URI,"http://administracionelectronica.gob.es/es/ctt/politicafirma");

SIGNATURE_POLICY_URI

Java

.Net


Este parámetro solo es usado en las Firmas de tipo XAdES, ya que indicado una cadena de texto libre, se creará unnuevo nodo indicando el ROL del firmante dentro de la firma del XML.



policy.addParameter(PolicyParams.SIGNER_ROLE.getKey(),"Roldeprueba");

policypolicy=PolicyUtil.newPolicy(typeFormatSign.XADES_BES,typeSign.ENVELOPED);

PolicyUtil.AddParameter(policy,PolicyParams.SIGNER_ROLE,"Roldeprueba");

SIGNER_ROLE

Java

.Net


Mediante éste parámetro se define el algoritmo de canonicalización en las firmas de los documentosXAdES/XMLDESIG.

Basicamente se refiere al nodo:

<ds:CanonicalizationMethodAlgorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315">

</ds:CanonicalizationMethod>

Los valores permitidos es este campo son las siguientes cadenas de texto:

http://www.w3.org/TR/2001/REC-xml-c14n-20010315http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithCommentshttp://www.w3.org/2001/10/xml-exc-c14n#http://www.w3.org/2001/10/xml-exc-c14n#WithComments

Si no se indica este parámetro, por defecto pondrá el que esté configurado en viafirma platform, y si en viafirmaplatform no hay ninguno configurado, se pondrá por defecto el primero del listado anterior,(http://www.w3.org/TR/2001/REC-xml-c14n-20010315).

Para ver un ejemplo de implementación del parámetro facilitamos el siguiente ejemplo


policy.addParameter(PolicyParams.XML_CANONICALIZATION_METHOD.getKey(),"http://www.w3.org/2001/10/xml-exc-c14n#");

policypolicy=PolicyUtil.newPolicy(typeFormatSign.XMLDSIG,typeSign.ENVELOPING);

PolicyUtil.AddParameter(policy,PolicyParams.XML_CANONICALIZATION_METHOD,"http://www.w3.org/2001/10/xml-exc-c14n#");

XML_CANONICALIZATION_METHOD

Java

.Net


http://www.w3.org/TR/2001/REC-xml-c14n-20010315

http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments

http://www.w3.org/2001/10/xml-exc-c14n

http://www.w3.org/2001/10/xml-exc-c14n#WithComments

http://www.w3.org/TR/2001/REC-xml-c14n-20010315

Mediante este parámetro añadimos soporte de diferentes canonizadores mediante politica de firma en formatos XAdES.

Los valores que podemos asignar a este parámetro son los definidos por la calseorg.apache.xml.security.transforms.Transform.

Para ver un ejemplo de implementación del parámetro facilitamos el siguiente ejemplo


policy.addParameter(PolicyParams.XML_CANONIZATION_TRANSFORM.getKey(),Transforms.TRANSFORM_C14N_EXCL_OMIT_COMMENTS);


PolicyUtil.AddParameter(policy,PolicyParams.XML_CANONIZATION_TRANSFORM,Transforms.TRANSFORM_C14N_EXCL_OMIT_COMMENTS);

XML_CANONIZATION_TRANSFORM

Java

.Net


Al iniciar el cliente de viafirma puede ser seteado con distintos parámetros opcionales que están enumerados enOptionalRequest. A continuación se listan las funcionalidades asociadas al conjunto de optionalRequest disponibles.

AUTO_SEND

Optional Request

173OptionalRequest

Con este parámetro indicamos a la aplicación usada para seleccionar certifcados, que en el caso de que solo haya unoen la lista, se seleccione y envíe automáticamente sin necesidad que el usuario tenga que seleccionarlo.

En el caso de que este parámetro no esté añadido, el comportamiento sería el normal, el usuario tendría queseleccionar el certificado a usar aunque solamente haya uno instalado.

A continuacición un ejemplo de como se realizaría el uso de este parámetro:


//OptionalRequest



//OptionalRequest


AUTO_SEND

Java

.Net

174AUTO_SEND

En esta aplicación de ejemplo te mostraremos cómo nuestro cliente para Java y .Net permiten de una forma muysencilla integrar aplicaciones desarrolladas en estas tecnologías con los servicios que ofrece viafirma platform.Mediante los distintos ejemplos de usos, aprenderás a realizar una operación de autenticación con viafirma platform decara a obtener los datos del certificado digital del usuario. También aprenderás a realizar firmas con certificados digitaly obtener los documentos firmados, así como a poder verificar la validez de dichas firmas.

Está orientado a un perfil de desarrollador habituado a desarrollos JEE o .Net, por lo que el nivel de detalles de algunosaspectos tratados necesitan de un conocimiento previo en estas tecnologías.

En esta pantalla ya se podrán realizar las diferentes pruebas para el correcto funcionamiento de la plataforma(autenticación, firmas en cliente, firmas en servidor, policies etc.).

Autenticación: se tratan distintas formas de autenticación contra la plataforma.Firma con intervención del usuario: se muestran los distintos tipos de firma utilizando los diferentes clientes deselección de certificados.Firma sin intervencion del usuario: se muestran los distintos tipos de firma utilizando firma en servidor, es

Aplicación de ejemplo

175Aplicacióndeejemplo

obligatorio para realizar estas firmas disponer de un certificado instalado en el KeyStore usado por viafirma.Métodos de utilidad: se muestran diferentes métodos del API de viafirma.

Desde los siguientes enlaces se explica el proceso de instalación y configuración de la aplicación de ejemplo, tanto enJava como para .Net:

Aplicación de ejemplo en JavaAplicación de ejemplo en .Net

176Aplicacióndeejemplo

InstalaciónConfiguración

Aplicación de ejemplo Java

177AplicaciónejemploJava

En este apartado se describe el proceso de instalación del war generado desde maven, solo para Apache Tomcat, oejecutar el ejemploViafirma directamente desde un IDE, por ejemplo Eclipse. También se indicará la realización deunas pruebas para verificar el correcto funcionamiento de la instalación apuntando a viafirma platform.

Lo primero sería descargar o clonar el proyecto del ejemploViafirma desde el portal GitHub a nuestra máquina.


Una vez descargado podemos optar por generar un empaquetado war e instalarlo en un contenedor Apache Tomcat oimportarlo como proyecto dentro de un IDE.

Antes de seguir con los pasos de instalación, como requisito previo debe tener instalado Maven 3 o superior y ApacheTomcat 6 o superior.

1. Generar empaquetado war mediante Maven. Estando situados dentro de la carpeta, ejecutar el siguiente comandomaven.

>mvncleanpackage

Cuando termine el proceso de Maven, dentro de la carpeta target del proyecto encontraremos el empaquetadogenerado.

2. Copiar el empaquetado .war a la carpeta contenedora del Apache Tomcat.

>TOMCAT-HOME/webapps

3. Una vez realizado el proceso anterior y arracando el Apache Tomcat, se podrá acceder a la siguiente url desde unnavegador.

http://HOST:PORT/ejemploViafirma

Dicha url será la ip de su máquina y el puerto configurado en Apache Tomcat, por defecto será el 8080.

Instalación

Generación de empaquetado war

Importar como proyecto Maven en IDE

178Instalación


El IDE que recomendamos usar para este proceso es Eclipse.

1. Importamos el proyecto como maven.2. Posteriormente se realiza un poceso de Update para que se descargue las dependencias del proyecto.3. Agregar un server basado en Apache Tomcat 6 o superior4. Agregar el proyecto de ejemplo5. Arrancar.

Una vez arrancado el server, podemos acceder mediante la url en un navegador.


Dicha URL será la ip de su máquina y el puerto configurado en el server, por defecto será el 8080.

179Instalación

En esta documentación se explicará cómo configurar la aplicación de ejemplo para que consuma los servicios de tuviafirma platform.

La configuración de la aplicación de ejemplo se puede llevar a cabo mediante dos métodos.

Por defecto, la aplicación apunta a la url que puedes ver en la siguiente imagen:

Para configurarla a nuestro entorno hacer click en el link Administrar ejemplo:

Configuración

Configuración en la pantalla de la aplicación

180Configuración

A continuación se describen los diferentes campos:

URL_VIAFIRMA: en este campo indicaremos la url donde está instalado viafirma platform.URL_VIAFIRMA_WS: aquí indicaremos la url del WS de viafirma platform.Alias: en este campo indicamos el alias del certificado con el que queremos realizar las firmas en servidor, estecertificado debe estar instalado en el KeyStore que utiliza viafirma platform(requerido para firma en servidor).PASS: en este campo pondremos la password del certificado que hemos indicado en el campo anterior (requeridopara firma en servidor).API_KEY: en el caso de utilizar viafirma manager podremos indicar las credenciales asignadas, en caso contrariodejar valores por defecto.PASS_KEY: en el caso de utilizar viafirma manager podremos indicar las credenciales asignadas, en casocontrario dejar valores por defecto.

En caso de usar proxy para la salida a internet en esta sección se podrá especificar la configuración que corresponda.

181Configuración

Mencionar, que cuando la aplicación sea reiniciada, los datos de configuración introducidos en esta página seránreseteados.

En el siguiente apartado Configuración en contexto de Apache Tomcat, se explica como configurar la aplicación paraque no se reseteen los datos cada vez que se realice un reinicio del servidor.

Tanto como si arranca la aplicación desde un Apache Tomcat instalado en local como instalado desde Eclipse, puedeañadir la siguiente configuración al fichero server.xml para configurar la aplicación a su gusto y que no se pierdan losdatos de configuración cada vez que se reinicie el servidor.

<ContextdocBase="viafirma-platform-example-java"path="/ejemploViafirma"reloadable="true"source="org.eclipse.jst.j2ee.server:viafirma-platform-example-java">

<Environmentdescription="ConfiguraciondelClientedeviafirma,losdatossiguenlasiguienteestructura:URL_VIAFIRMA;URL_VIAFIRMA_WS;API_KEY;API_PASS"

name="CONFIG_VIAFIRMA_CLIENT"override="false"type="java.lang.String"

value="http://192.168.10.114:7080/viafirma;http://192.168.10.114:7080/viafirma;xnoccio;12345"/>

</Context>

Este tipo de configuración también se puede complementar con la explicada en el anterior apartado, la deConfiguración en la pantalla de la aplicación.

Configuración en contexto de Apache Tomcat

182Configuración

InstalaciónConfiguración

Aplicación de ejemplo .Net

183Aplicaciónejemplo.Net

En este apartado se describe el proceso de instalación y ejecutar el ejemploViafirma directamente desde Visual Studio.También se indicará la realización de una pruebas para verificar el correcto funcionamiento de la instalación apuntandoa viafirma platform.

Lo primero sería descargar o clonar el proyecto del ejemploViafirma desde el portal GitHub a nuestra máquina.


Una vez descargado, procederemos con la instalación y ejecución de la aplicación de ejemplo.

Para la instalación y ejecución, es recomendable tener instalado la herramienta Visual Studio, en versiones igual osuperior a la 2013.

1. Ejecutar el archivo EjemploWebViafirmaClientDotNet.sln situado en la ráiz del proyecto. Este proceso abrirá laaplicación Visual Studio con el proyecto ya importado.

2. Recompilar la solución.3. Ejecutar la aplicación por medio del botón Ejecutar o por la tecla [F11] y se mostrará la aplicación en el navegador

seleccionado.

Una vez ejecutada, como hemos comentado anteriormente, se abrirá el navegador, si esto no ocurre, podemos accedermediante la url en un navegador.


Dicha URL será la ip de su máquina y el puerto configurado.

Instalación

Importar proyecto en Visual Studio

184Instalación


Si deseamos realizar una configuración personalizada de la aplicación de ejemplo, para que apunte, por ejemplo, a otroviafirma platform, antes de ejecutar la aplicación debemos tener en cuenta lo que se describe a continuación:

La configuración de la aplicación se realizará mediante un fichero de configuración existente en el ráiz del proyecto.Dicho fichero se llama Global.asax y contienen los siguiente parámetros de configuración:

URL_VIAFIRMA: en este campo indicaremos la url donde está instalado viafirma platform.URL_VIAFIRMA_WS: aquí indicaremos la url del WS de viafirma platform.ALIAS: en este campo indicamos el alias del certificado con el que queremos realizar las firmas en servidor, estecertificado debe estar instalado en el KeyStore que utiliza viafirma (requerido para firma en servidor).PASS_CERT: en este campo pondremos la password del certificado que hemos indicado en el campo anterior(requerido para firma en servidor).API_KEY: en el caso de utilizar viafirma manager podremos indicar las credenciales asignadas, en caso contrariodejar valores por defecto.PASS_KEY: en el caso de utilizar viafirma manager podremos indicar las credenciales asignadas, en casocontrario dejar valores por defecto.

Configuración

185Configuración

En el presente capítulo se mostrarán ciertos snippets de utilidad para solventar las dudas más comunes.

Cambiar el tamaño máximo d e los ficheros a firmarObtener PEM de un certificado después de una autenticaciónExtraer certificado firmante de una firma CMS/CAdESVerificar firma CMS con su documento originalExtraer certificado firmante de una firma CMD/CAdESUpgrade de firma XAdES

Snippets de utilidad

186Snippetsdeutilidad

Para cambiar el tamaño máximo de los documentos a firmar hay que tener en cuenta primero que intervienen dosfactores:

1. El servidor Tomcat.2. La aplicación de viafirma.

Tendremos que cambiar la configuración del servidor Tomcat para que acepte peticiones de más de dos megas que esel tamaño máximo por defecto. Esto se modifica en el el fichero server.xml.

NOTA hay que tener en cuenta que las peticiones llevan consigo otros datos de los cuales ocupan espacio, por lo quesi queremos firmar un documento de 5 megas, el tamaño máximo que debería de aceptar tomcat sería, por ejemplo,5,5 megas.

La otra parte es la aplicación de viafirma, para cambiar el tamaño máximo hay que definir una Properties a la hora derealizar el init de ViafirmaClientFactory, un ejemplo sería el siguiente

Propertiesproperties=newProperties();

properties.put(Constantes.PARAM_CONFIG_VIAFIRMA_CLIENT,URL_VIAFIRMA+";"+URL_VIAFIRMA_WS+";"+API_KEY+";"+API_PASS);

LongmaxSize=20*1024l*1024l;

StringmaxSizeProperty=String.valueOf(maxSize);

properties.put(Constantes.PARAM_MAX_SIZE,maxSizeProperty);

ViafirmaClientFactory.init(properties);

Básicamente al properties se la añaden dos parámetros:

Constantes.PARAM_CONFIG_VIAFIRMA_CLIENT: Donde se indica un String con los parametrosURL_VIAFIRMA, URL_VIAFIRMA_WS, API_KEY y API_PASS se parados por el caracter punto y coma ;

Constantes.PARAM_MAX_SIZE: Donde se pasa un long con el tamaño en bytes deseado. Por último se invoca aViafirmaClientFactory.init con el properties.

ViafirmaClientFactory.Init(urlViafirma,urlViafirmaWS,apiKey,apiPass,maxFileSize)

maxFileSize: (int) El tamaño maximo permitido para firmar un archivo se ajusta en megabytes.

Cambiar el tamaño máximo de los documentos a firmar

Java

.Net

187Cambiareltamañomáximodelosdocumentosafirmar

188Cambiareltamañomáximodelosdocumentosafirmar

Con el siguiente código hacemos que en la respuesta de la autenticación (cuando es válida) nos devuelva el certificadoX509 en formato pem:


viafirmaClient.addOptionalRequest(OptionalRequest.PEM_X509);

//Iniciamoslaautenticaciónindicandolaurideretorno.

viafirmaClient.solicitarAutenticacion(request,response,"/viafirmaClientResponseServlet");

//PararecuperarloenelmétododelservletdevueltaauthenticateOK(UsuarioGenericoViafirma,HttpServletRequest,HttpServletResponse)haremoslosiguiente:

Stringpem=usuarioGenericoViafirma.getProperties().get("pem")

//ParaconvertiresePEMaunX509Certificatesepuedeutilizaruncódigocomoelsiguiente(yateniendolavariable'pem'):

java.security.cert.CertificateFactorycf=java.security.cert.CertificateFactory.getInstance("X509");

java.security.cert.X509Certificatex509=cf.generateCertificate(newjava.io.ByteArrayInputStream(pem.getBytes()));

El resultado es que la variable pem es un string con el certificado en formato .pem. El valor de este string debería deser algo parecido a esto:

MIIFbDCCBFSgAwIBAgIIP+3SprFWtmwwDQYJKoZIhvcNAQEFBQAweTELMAkGA1UEBhMCRE8xGjAYBgNVBAcMEVdXVy5BVkFOU0kuQ09NLkRPMSYwJAYDVQQKDB1BVkFOU0kgUy5SLkwuIC0gUk5DIDEzMDIyMjUwOTEmMCQGA1UEAwwdQVZBTlNJIENFUlRJRklDQURPUyBESUdJVEFMRVMwHhcNMTUwNDA4MDgxMTQxWhcNMTcwNDA3MDgxMTQxWjCBlTELMAkGA1UEBhMCRE8xEzARBgNVBAQMCkRFVkVMT1BFUlMxETAPBgNVBCoMCFZJQUZJUk1BMQ0wCwYDVQQFEwQyMjU1MRwwGgYDVQQDDBNWSUFGSVJNQSBERVZFTE9QRVJTMTEwLwYKKwYBBAGB1gMIAQwhQ0VSVElGSUNBRE8gREUgUEVSU09OQSBJTkRJVklEVUFMMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvQUEmTVMViO3K1rzYu4eL4QarT3sLw7iyqGINY/cDxTQBl/iBQiRfNkHaFoa66rr145Lgc0/wbTDR/Yllfy9nfaKXCdSs3kGp6Zty2Nv1a4zRPsKmQdcWAWdwjBXrylaKtd9tdncJN5xVvaesSVK/q1l/CU4lyhlRZBDiSikzV/B+f2IzHdKx0X3PHA7ehWYblZOXcecVa6MFijlkZ+smCkHEb98lAavUxXpu0oHwDMT6bYGCU6VcrNSeffAqmAT+P60FtVVDyT5BEVZoJNxlVGwVhcvNBQxhFkEnfB1m/Q+boMLZO1lJNovEo4OElNYXYigqkpliZfztBtClr1wiQIDAQABo4IB2TCCAdUwNQYIKwYBBQUHAQEEKTAnMCUGCCsGAQUFBzABhhlodHRwOi8vb2NzcC5hdmFuc2kuY29tLmRvMB0GA1UdDgQWBBRs7PQLmuojxRCUbiIHIiKosIEpaDAMBgNVHRMBAf8EAjAAMB8GA1UdIwQYMBaAFCHCDuOFfstMEU4JWywVimxAHg7hMIGVBgNVHSAEgY0wgYowgYcGCysGAQQBgdYDBgIEMHgwJAYIKwYBBQUHAgEWGGh0dHA6Ly9jcHMuYXZhbnNpLmNvbS5kbzBQBggrBgEFBQcCAjBEHkIAQwBFAFIAVABJAEYASQBDAEEARABPACAARABFACAAUABFAFIAUwBPAE4AQQAg

Obtener PEM de un certificado después de unaautenticación o firma

Java

189ObtenerPEMdeuncertificadodespuésdeunaautenticaciónofirma

AEkATgBEAEkAVgBJAEQAVQBBAEwwZgYDVR0fBF8wXTAsoCqgKIYmaHR0cDovL2NybC5hdmFuc2kuY29tLmRvL2F2YW5zaXN1Yi5jcmwwLaAroCmGJ2h0dHA6Ly9jcmwyLmF2YW5zaS5jb20uZG8vYXZhbnNpc3ViLmNybDAOBgNVHQ8BAf8EBAMCA/gwHQYDVR0lBBYwFAYIKwYBBQUHAwIGCCsGAQUFBwMEMB8GA1UdEQQYMBaBFFNPUE9SVEVAVklBRklSTUEuQ09NMA0GCSqGSIb3DQEBBQUAA4IBAQBXM27tsgtsmXxiasef3bv9nSP+cQBZCufUIf9kzi9kYHzMa0L7xK5GMG9kvD/SJRH7bM+gEUhSayhzCiCgNqMUnSLp7lD8uM0T5u1Glshcb66/P6RrLbD1XUEWLq+lJMY+2WSuk3xnEIFLBD8Kre5298OVmKJrVHCPf8rpJGH4FedlXDpRCnrJ4pHK/ewZFWYEBvfHipmNP99GkjdSSZXDzg9h5DdpQlMPKcZFHCBZu3lcwZiDwGUN1ZNaH4ZU9L9hs4AFzARWnMD9yUvWsAvZOcTvExZka3fePcbVYsFsQWtklmJpy86+gjuYQEpogK+H2X1d2hPtFf/d7slu3RpZ

Para firma utilizamos el mismo método addOptionalRequest con el mismo resultado.

190ObtenerPEMdeuncertificadodespuésdeunaautenticaciónofirma

En esta sección se mostrarán los snippets de utilidad relacionados con la firma CAdES:

Verificar la correspondencia de una firma CMS con su documento original

Extraer certificado firmante de una firma CMS/CAdES

CAdES

191CAdES

Para validar una firma CMS DETACHED contra su documento original utilizamo el método proporcionado por la API deviafirma checkSignedHasDocumentValidity().

A continuación se expone un ejemplo de cómo utilizar el método:

try

//Obtenemoslosbyte[]delosdocumentos,tantoeloriginalcomoelfirmado

byte[]original=FileUtils.readFileToByteArray(newFile("documento.txt"));

byte[]cmsFirmado=FileUtils.readFileToByteArray(newFile("firma.txt"));

//Acontinuaciónsacamoselhashdeldocumentooriginal

StringhashOriginalDoc=newString(Base64.encodeBase64(DigestUtils.sha(original)));

//PorúltimoejecutamoselmétodocheckSignedHasDocumentValidity()

FirmaInfoViafirmafirmaInfo=clienteVaifirma.checkSignedHasDocumentValidity(cmsFirmado,hasOriginal,TypeFormatSign.CMS_DETACHED);

System.out.println("¿Válido?"+firmaInfo.isValid());

catch(IOExceptione)


catch(InternalExceptione)


Verificar la correspondencia de una firma CMS con sudocumento original

Java

192VerificarcorrespondenciadefirmaCMScondocumentofirmado

En el siguiente ejemplo obtenemos el primer certificado (será de tipo X509CertificateHolder) de almacén del CMSfirmado, que será el certificado firmante y lo convertimos a X509Certificate para, de él, extraer la PublicKey.

//recuperamoselcmsfirmado

byte[]signed=ViafirmaClientFactory.getInstance().getDocumentoCustodiado(idFirma);

//LoconvertimosaltipoCMSSignedData

CMSSignedDatacms=newCMSSignedData(signed);

//Obtenemoselalmacendondeestanloscertificados

Storestore=cms.getCertificates();

//ObtenemosunIteratorpararecorrerlos.

//PasandonullengetMatches(...)serecuperantodosloscertifcados,eltipoparacadacertseráX509CertificateHolder

Iteratori=store.getMatches(null).iterator();

//Elprimerelementodeliteradorsecorrespondesiempreconelcertificadofirmante,elrestoseránlacadenadeconfianza

ByteArrayInputStreamcertBytes=newByteArrayInputStream(((org.bouncycastle.cert.X509CertificateHolder)i.next()).getEncoded());

//ConvertimosaX509Certificate

X509Certificatex509=(X509Certificate)(CertificateFactory.getInstance("X509").generateCertificate(certBytes));

//Obtenemoslaclavepublica

PublicKeypubKey=x509.getPublicKey();

Extraer certificado firmante de una firma CMS/CAdES

Java

193ExtraercertificadofirmantedeunafirmaCMS/CAdES

En esta sección se mostrarán los snippets de utilidad relacionados con la firma XAdES:

Upgrade de firma XAdES

XAdES

194XAdES

La plataforma permite realizar la actualización de una firma a un formato superior, por ejemplo podemos pasar de unafirma XAdES_BES a una firma XAdES_A

El método a utilizar para realizar esta acción es:

viafirmaClient.upgradeSignature(pol,documento);

Un ejemplo de integración utilizando este método es el siguiente:


Policypol=newPolicy();

pol.setTypeFormatSign(TypeFormatSign.XADES_A_ENVELOPED);

pol.setTypeSign(TypeSign.ENVELOPED);

byte[]documentToUpgrade=getDocumentToUpgrade();

Documentodocumento=newDocumento("original.pdf",documentToUpgrade,TypeFile.XML,TypeFormatSign.XADES_BES);

idFirma_A=viafirmaClient.upgradeSignature(pol,documento);

byte[]xades_XL_upgraded_to_A=viafirmaClient.getDocumentoCustodiado(idFirma_A);

En la primera línea del snippet de código se instancia el cliente de viafirma.

A continuación se crea el objeto 'Policy' en el que se configurará el formato de firma al que actualizar, este formatotiene que ser del mismo tipo y con un nivel superior a la firma con la que está firmado el documento, en este casoutilizaremos un formato XAdES_A, se informará también el tipo de envoltura que deberá coincidir con la de la firmaprevia, en este caso usamos ENVELOPED.

Seguidamente se crea el objeto 'Documento' cuyos parámetros son:

String con el nombre del documento (incluir también la extensión del documento)byte[] del documento al que le queremos realizar el upgrade'TypeFile' del documento'TypeFormatSign' con el que está firmado el documento actualmente

En la siguiente línea se hace uso del método upgradeSignature(pol, documento) donde se tiene que pasar comoparámetros el objeto 'Policy' y el objeto 'Documento' que creamos anteriormente. Este método nos devuelve un String

Upgrade de firma XAdES

Java

Java

195UpgradedefirmaXAdES

con el id de firma y que, con la última linea del snnipet de código, obtenemos el byte[] del documento con la firmaactualizada.

Existe una forma específica de realizar el resellado de firmas XAdES_XL o XAdES_A que podemos considerar un tipoespecial de upgrade de firma (también se puede realizar el resellado con el método anterior)

byte[]viafirmaClient.xadesAResign(byte[]XL_or_A);

La peculiaridad sobre este método es que solo se pueden indicar documentos firmados en XAdES_XL y XAdES_Aademás de obtener como resultado el byte[] del documento firmado y no el id de firma, por lo que, utilizando estemétodo, el documento no es custodiado por el servidor de viafirma platform, deberá ser el integrador el encargado deguardar el documento donde considere oportuno.

Java

196UpgradedefirmaXAdES

No es necesario utilizar el cliente Java SDK para preparar las operaciones de autenticación y firma mediante invocaciónpor protocolo a Viafirma Desktop, pudiendo realizarse directamente llamadas al servicio REST. El resto de laintegración se mantiene igual, tal y como se explicó en los apartados concretos de autenticación y firma invocando a laaplicación por protocolo.

URL: /api/rest/services/authSeguridad: BASIC Auth pasando el API key / passwordMétodo: POSTBody de ejemplo:

"autoSend":true,

"certFilter":

"operator":"contains",

"filterValues":["FNMT"]

,

"caFilter":


"filterValues":["FNMT"]

,

"numberUserIdFilter":


"filterValues":["4"]

,

"locale":"es",

"sessionId":"XXXXX"

Valores:

autoSend: indica si la aplicación debe realizar un envío de los datos del certificado sin interacción del usuario(sólo posible cuando hay un único certificado).certFilter: objeto con datos de filtrado del certificado (opcional). Internamente utiliza el filtro genérico (busca losvalores en cualquier campo del certificado, con un OR). Dentro del objeto certFilter está el operador de filtrado(equals, contains, starts_with, ends_with) y los valores de los filtros: filterValues.caFilter: filtro específico para filtrar por CAs; si se mete más de un valor, hace lógica de tipo OR. Por ejemplo,con un operador contains, y valores FNMT y DNI, filtraría todos los certificados que sean de FNMT o DNIelectrónico.numberUserIdFilter: filtro específico para filtrar por el serial number del certificado (cédula, DNI, CIF, etc.); sise mete más de un valor, hace lógica de tipo OR. Por ejemplo, con un operador contains, y valores 4 y 5,filtraría todos los certificados que tengan un 4 o 5 en su serialNumber.locale: Locale del usuario que está interactuando con la aplicación a integrar (obtenido del objeto request).sessionId: ID de sesión del usuario que está interactuando con la aplicación a integrar (obtenido del objetorequest).

Invocación a Viafirma Desktop por protocolo

Preparación de operación de autenticación

197InvocaciónaViafirmaDesktopporprotocolo

Los nodos del JSON caFilter y numberUserIdFilter solo están disponibles desde la versión 3.17.1 de viafirmaplatform y requieren una versión mínima 1.6.7 de Viafirma Desktop.

Importante: desde las versiones viafirma-client 2.14.6 y viafirma platform 3.15.6, el objeto policy deja de ser unparámetro de la llamada, ya que obligaba a que para hacer una firma en lotes, todos los ficheros compartan la Policy defirma. A partir de estas versiones, la policy es un parámetro a nivel de fichero:

URL: /api/rest/services/signatureSeguridad: BASIC Auth pasando el API key / passwordMétodo: POSTBody de ejemplo:

"autoSend":true,

"certFilter":

"operator":"CONTAINS",

"filterValues":["09431554J","FNMT"]

,

"files":[

"filename":"test.pdf",

"base64Content":"xxxx",

"signaturePolicy":

"signatureFormat":"PAdES_BES",

"signatureType":"ATTACHED",

"parameters":

"DIGITAL_SIGN_PAGE":"0",

"DIGITAL_SIGN_STAMPER_HIDE_STATUS":"true",

"DIGITAL_SIGN_IMAGE_STAMPER_AUTOGENERATE":"false",

"DIGITAL_SIGN_STAMPER_TEXT":"Documentofirmado",

"DIGITAL_SIGN_STAMPER_TYPE":"QR-BAR-H",

"DIGITAL_SIGN_RECTANGLE":"'x':10,'y':10,'height':540,'width':75"

],

"locale":"es",

"sessionId":"xxxx"

Valores:

autoSend: indica si la aplicación debe realizar un envío de los datos del certificado sin interacción del usuario(sólo posible cuando hay un único certificado).certFilter: objeto con datos de filtrado del certificado (opcional). Dentro del objeto certFilter está el operador defiltrado (equals, contains, starts_with, ends_with) y los valores de los filtros: filterValues.files: campo obligatorio con la lista de objetos de tipo fichero, compuestos por un nombre de fichero (filename),su contenido en base64 (base64Content), y una signaturePolicy:signaturePolicy: objeto obligatorio, para cada fichero enviado a firmar, con los datos de la política de firma.Incluye el formato de firma (signatureFormat), el tipo de firma (signatureType), y parámetros de política defirma. Todos estos parámetros coinciden en valores a los descritos dentro de la documentación de integraciónen otros apartados. Es importante tener en cuenta que cuando se añadan parámetros (parameters) en lapolicy, el JSON debe coincidir con la serialización del objeto como string. Por ello, la página (entero) se incluye

Preparación de operación de firma


como "0" o "1", un parámetro boolean va como "true" o "false", pero un parámetro objeto como el rectángulose envía como 'x':10,'y':10,'height':540,'width':75. Para construir el JSON correcto deberán analizarse lasopciones (valores y tipos: cadenas, números, booleanos, objetos) de las Policy Params del SDK.locale: Locale del usuario que está interactuando con la aplicación a integrar (obtenido del objeto request).sessionId: ID de sesión del usuario que está interactuando con la aplicación a integrar (obtenido del objetorequest).

NOTA: viafirma platform no puede obtener el sessionId y locale del usuario, dado que el objeto request que recibees el de la aplicación integrada, no el del usuario.

Ambas operaciones devuelven simplemente un parámetro llamado operationId:

"operationId":"XXXXX"

Para poder invocar a la aplicación Viafirma Desktop por protocolo, hay que crear un enlace que siga este formato:

viafirmawpfclient://?url=URL_VIAFIRMA_PLATFORM&operationId=OPERATION_ID

Donde URL_VIAFIRMA_PLATFORM es la dirección del servidor de Viafirma Platform, siguiendo el formatohttps://testservices.viafirma.com/viafirma, y OPERATION_ID es el parámetro operationId recuperado de la llamada depreparación de la operación de autenticación o firma.

La estrategia de iniciar un proceso de polling Javascript es idéntica a los casos de integración cuando se usa el SDKJava o .NET; en estos casos, viafirma-client únicamente está encapsulando las llamadas a los servicios REST descritosen este apartado.

Una vez que con el polling se verifica que la operación de autenticación o firma está finalizada, se puede invocar a lalógica de servidor de la aplicación para poder descargar la información de la autenticación o firma, disponiendo del IDde operación y el session ID.

URL: URL_VIAFIRMA/api/rest/services/auth/validation/OPERATION_ID (sustituyendo los valores correctos deURL_VIAFIRMA y OPERATION_ID)Query params:

delete = true: elimina la información de la operación en el servidorsessionId = : se envía el ID de sesión del usuario, que deberá coincidir con el enviado en la preparación de laoperación.

Seguridad: BASIC Auth pasando el API key / passwordMétodo: GET

El JSON de respuesta incluye los siguiente campos:

operationId: ID de operación devuelto en el primer proceso de preparación de la operación

Descarga de información de validación del certificado


https://testservices.viafirma.com/viafirma

numberUserId: número de identificador del usuario (NIF, cédula...)name: Nombre del usuariosurname1: Primer apellidosurname2: Segundo apellidoemail: Email del usuarioca: Autoridad de Certificación emisora (por ejemplo Fábrica Nacional de Moneda y Timbre)shortCa: Autoridad de Certificación emisora - descripción corta (por ejemplo FNMT)jobTitle: Cargo del usuariotype: Tipo de certificadocn: Common Nameorganization: Nombre de la organización / empresa del usuariocertificateProperties: lista de variables del certificado (en formato key/value)isValidated: booleano - obtiene valor true si el certificado ha sido validado correctamenteisExpired: booleano - obtiene valor true si el certificado está caducadoisRevoked: booleano - obtiene valor true si el certificado está revocado

URL: URL_VIAFIRMA/api/rest/services/signature/OPERATION_ID (sustituyendo los valores correctos deURL_VIAFIRMA y OPERATION_ID)Query params:

delete = true: elimina la información de la operación en el servidorsessionId = : se envía el ID de sesión del usuario, que deberá coincidir con el enviado en la preparación de laoperación.

Seguridad: BASIC Auth pasando el API key / passwordMétodo: GET


operationId: ID de operación devuelto en el primer proceso de preparación de la operación.signatureId: ID de firma de Viafirma (si son varios documentos, los IDs van separados por comas).certificateValidationData, datos del certificado, con los mismos campos que la respuesta de autenticación:

numberUserId: número de identificador del usuario (NIF, cédula...)name: Nombre del usuariosurname1: Primer apellidosurname2: Segundo apellidoemail: Email del usuarioca: Autoridad de Certificación emisora (por ejemplo Fábrica Nacional de Moneda y Timbre)shortCa: Autoridad de Certificación emisora - descripción corta (por ejemplo FNMT)jobTitle: Cargo del usuariotype: Tipo de certificadocn: Common Nameorganization: Nombre de la organización / empresa del usuariocertificateProperties: lista de variables del certificado (en formato key/value)isValidated: booleano - obtiene valor true si el certificado ha sido validado correctamenteisExpired: booleano - obtiene valor true si el certificado está caducado

Descarga de información de firma


isRevoked: booleano - obtiene valor true si el certificado está revocado


Para autenticar a los usuarios mediante SSL client auth, sin clientes ricos (applets, JNLP, Viafirma Desktop, etc.), no esnecesario utilizar los SDK (Java, .NET, etc.), pudiendo realizarse la integración con dos sencillas llamadas REST.

URL: /api/rest/services/ssl/authSeguridad: BASIC Auth pasando el API key / passwordMétodo: POSTBody de ejemplo:

"callbackURL":"URLdelaaplicación"

Valores:

callbackURL: es una URL de la aplicación a la que se redirigirá al usuario una vez haya seleccionado sucertificado. A esta URL se le añadirá como query param operationId=XXXX.

Body de respuesta:

"redirectURL":"URLalaqueredirigiralusuario",

"operationId":"IDdeoperación"

Cuando se recibe la respuesta, es recomendable por seguridad almacenar el operationId y algún parámetro del usuariocomo la IP de origen o el sessionId, de forma que cuando se reciba la llamada a la callbackURL con el operationIdcomo query param, se pueda comprobar que esos valores no han sido modificados.

Una vez que se ha recibido la llamada a la callbackURL con el operationId como parámetro, se pueden recuperar losdatos del certificado:

URL: /api/rest/services/auth/validation/operationIdSeguridad: BASIC Auth pasando el API key / passwordMétodo: GETBody de respuesta:

Invocación a Viafirma Platform para autenticación por SSLclient auth

Preparación de operación de autenticación por SSL client auth

Recuperación de los datos de validación del certificado de usuario

202InvocaciónaViafirmaPlatformparaautenticaciónsincliente(SSLclientauth)

"firstName":"JOHN",

"lastName":"DOESMITH",

"numberUserId":"12345678X",

"email":"[email protected]",

"typeCertificate":"FNMT",

"typeLegal":"CERTIFICADO_PERSONA_FISICA",

"caName":"CN=ACFNMTUsuarios,OU=Ceres,O=FNMT-RCM,C=ES",

"properties":

"1.3.6.1.4.1.5734.3.10.1":"",

"C":"ES",

"1.3.6.1.4.1.5734.1.4":"12345678X",

"SERIALNUMBER":"12345678X",

"1.3.6.1.5.5.7.48.2":"http://www.cert.fnmt.es/certs/ACUSU.crt",

"0.4.0.1862.1.1":"",

"1.3.6.1.5.5.7.48.1":"http://ocspusu.cert.fnmt.es/ocspusu/OcspResponder",

"1.3.6.1.4.1.5734.1.1":"JOHM",

"1.3.6.1.5.5.7.2.2":"Certificadoreconocido.SujetoalascondicionesdeusoexpuestasenlaDPCdelaFNMT-RCM(C/JorgeJuan106-28009-Madrid-España)",

"1.3.6.1.5.5.7.1.3":"",

"pem":"xxxxxx",

"1.3.6.1.4.1.5734.1.3":"SMITH",

"1.3.6.1.4.1.5734.1.2":"DOE",

"GIVENNAME":"JOHN",

"2.5.29.17":"[email protected]",

"apellido2":"SMITH",

"SURNAME":"DOESMITH",

"2.5.29.19":"",

"1.3.6.1.5.5.7.1.1":"",

"apellido1":"DOE",

"1.3.6.1.5.5.7.2.1":"http://www.cert.fnmt.es/dpcs/",

"2.5.29.32":"",

"CN":"DOESMITHJOHN-12345678X",

"2.5.29.15":"5",

"2.5.29.37":"",

"0.4.0.1862.1.3":"15",

"signature_cert_notafter":"WedDec0409:13:53CET2019"

,

"certificateStatus":"VALID",

"message":"[code:100]Elcertificadohasidovalidadocorrectamente",

"revocationMethod":"OCSP",

"revocationDate":null,

"ocspResponse":

"statusOcspCode":"0",

"statusOcspValue":"org.bouncycastle.asn1.ocsp.OCSPResponseStatus@202",

"serverUrl":"http://ocspusu.cert.fnmt.es/ocspusu/OcspResponder",

"responseDate":1536044941000,

"responseOcsp":"xxxx",

"responseIdType":"BY_NAME",

"responseIdData":"CN=ServidorOCSPACFNMTUsuarios,OU=Ceres,O=FNMT-RCM,C=ES"

,

"crlResponse":null,

"issuers":[

"firstName":"",

"lastName":"ACFNMTUsuarios",

"numberUserId":"",

"email":"",

"typeCertificate":"Tiponoreconocido",


"caName":"OU=ACRAIZFNMT-RCM,O=FNMT-RCM,C=ES",

"properties":

"2.5.29.19":"0",

"C":"ES",

"1.3.6.1.5.5.7.1.1":"",

"OU":"Ceres",


"2.5.29.31":"http://www.cert.fnmt.es/crls/ARLFNMTRCM.crl",

"2.5.29.32":"",


"2.5.29.32.0":"",

"CN":"ACFNMTUsuarios",

"1.3.6.1.5.5.7.48.2":"http://www.cert.fnmt.es/certs/ACRAIZFNMTRCM.crt",

"2.5.29.15":"1",

"1.3.6.1.5.5.7.48.1":"http://ocspfnmtrcmca.cert.fnmt.es/ocspfnmtrcmca/OcspResponder",

"O":"FNMT-RCM",

"signature_cert_notafter":"SunOct2812:48:58CET2029",

"1.3.6.1.5.5.7.2.2":"SujetoalascondicionesdeusoexpuestasenlaDeclaracióndePrácticasdeCertificacióndelaFNMT-RCM(C/JorgeJuan,106-28009-Madrid-España)",

"pem":"xxxx"

,





"ocspResponse":





"responseOcsp":"xxxxx",



,

"crlResponse":null,

"issuers":null,

"x509CertificateB64":"xxxx",

"subjectDN":"CN=ACFNMTUsuarios,OU=Ceres,O=FNMT-RCM,C=ES",

"oids":null

,

"firstName":"",

"lastName":"",

"numberUserId":"",

"email":"",

"typeCertificate":"Tiponoreconocido",


"caName":"OU=ACRAIZFNMT-RCM,O=FNMT-RCM,C=ES",

"properties":

"2.5.29.19":"TRUE",

"C":"ES",

"signature_cert_notafter":"TueJan0101:00:00CET2030",

"OU":"ACRAIZFNMT-RCM",


"pem":"xxxx",

"2.5.29.32":"",

"2.5.29.32.0":"",

"2.5.29.15":"1",

"O":"FNMT-RCM"

,





"ocspResponse":





"responseOcsp":"xxxxx",



,

"crlResponse":null,

"issuers":null,

"x509CertificateB64":"xxxxx",

"subjectDN":"OU=ACRAIZFNMT-RCM,O=FNMT-RCM,C=ES",

"oids":null

],

"x509CertificateB64":"xxxxx",


"subjectDN":"CN=DOESMITHJOHN-12345678X,GIVENNAME=JOHN,SURNAME=DOESMITH,SERIALNUMBER=12345678X,C=ES",

"oids":null

El sistema devuelve la información completa de la validación, incluyendo los datos contenidos en el certificado,todos sus OIDs, así como las evidencias de validación no únicamente del certificado del usuario, sino también delos certificados de las subCAs y root CA que componen su cadena de certificación. La aplicación cliente deberáutilizar esta información para poder realizar las operaciones de autenticación.


Tabla de contenido - Viafirma · ii. Instalación a través de Maven ii. .Net i. Instalación a...

Documents

Transcript of Tabla de contenido - Viafirma · ii. Instalación a través de Maven ii. .Net i. Instalación a...