Manual de integración de ecoSignatureJWS Browser – firma electrónica y firma digital para empresas: portal de soporte

Tabla de Contenidos mostrar

Sobre este documento

Este documento tiene el objetivo de describir técnicamente el caso de uso desarrollado por edatalia para la aplicación ecoSignature Java Web Start (JWS de ahora en adelante) desde un entorno web (Browser) con firma de documento en local.

El documento muestra:

la estructura de archivos del zip entregado dependiendo de la tecnología seleccionada para su implementación.
una descripción de los archivos generales más importantes de la aplicación.
una descripción del archivo “jws.js” o “jws-simple.js”, dependiendo de la configuración seleccionada, este archivo es el más importante de la aplicación. Se presentan las variables de configuración para el correcto funcionamiento de la aplicación y las funciones más importantes a analizar.
una descripción de visor de documentos, si se selecciona el firmado de documentos a través del visor.
un flujo de ejemplo en una aplicación.
como se realiza una integración.
los parámetros de configuración de firma.
resolución de errores.

Además a lo largo del documento se hace hincapié en los aspectos más importantes para la integración.

Estructura de archivos

Dependiendo de la tecnología seleccionada, PHP, Java o NET, descomprimir el zip entregado, donde se puede observar los siguientes ficheros/carpetas.

Tecnología PHP

Carpeta “cu”: contiene todo lo relacionado con el caso de uso.
Carpeta “JWS”: contiene todo lo relacionado con el firmado. A su vez presenta una serie de subcarpetas:
- “ecobiometricJWS”: ficheros .jar y librerías de firmado.
- “ecoSignatureJWSHelper”: distribución de herramienta de edatalia ecoSignatureJWSHelper.msi (para Windows) y ELH (edatalia Linux Helper para Linux).
- “css”: hojas de estilo de la aplicación.
- “imagenes”: imágenes empleadas en la aplicación.
- “js”: archivos javascript de la aplicación:
  - “ecoSignatureJWS.js”: librería de firmado.
  - “dtjava.js”: para el lanzamiento de fichero jnlp generado en local.
  - javascript’s relacionados con jQuery: cookies, base 64,….
  - “FileSaver.js”: solución para guardar archivos o información en el lado cliente, empleada para la casuística de generación de fichero jnlp en local.
  - “jws.js” o “jws-simple.js”: implementación de lógica de firmado, dependiendo del caso de uso seleccionado.
  - “tools.js”: implementación de funciones auxiliares necesarias en la aplicación y caso de uso.
  - “alert.js”: implementación para la visualización de errores.
- “jnlp”: carpeta temporal donde se guardan los ficheros jnlp generados.
- “temp”: carpeta temporal donde se guardan los documentos firmados.
- “WebServiceSOAP_ecobiometricJWS”: todo lo relacionado con la definición del web service.
- “WebSocket_ecobiometricJWS”: todo lo relacionado con la definición del web socket.
- archivos como EBP’s y generales para el correcto funcionamiento de la aplicación (“generateJNLP.php”, “deleteJNLP.php” y “results.php”), dependiendo de las opciones seleccionadas para la generación de fichero jnlp y del tipo de devolución del documento PDF firmado.

Para la integración cabe destacar el archivo “jws.js” ó “jws-simple.js”, contenido en la subcarpeta “js”, que contiene toda la lógica de firmado y es el único archivo que se debe de analizar y cambiar para las necesidades de cada integración.

Mencionar que se debe eliminar los archivos “personalizacion.js” y la carpeta “cu” y sus referencias, ya que es donde está implementado todo lo relacionado con el caso de uso y no se utilizará en la integración. El caso de uso está desarrollado con jQuery, que es una biblioteca open source de JavaScript, creada inicialmente por John Resig, que permite simplificar la manera de interactuar con los documentos HTML, manipular el árbol DOM, manejar eventos, desarrollar animaciones y agregar interacción con la técnica AJAX a páginas web. La principal ventaja que presenta es que es totalmente compatible con la mayoría de los exploradores, Internet Explorer, Firefox, Opera, Apple, Safari etc.

Carpeta “view”: contiene todo lo relacionado con el visor (solamente necesaria para el caso de uso con visor). No se debe de cambiar nada, excepto el archivo “view/web/viewer.html” que contiene las referencias a archivos de hojas de estilo y javascript.
.htaccess: archivo que permite definir diferentes directivas de configuración para cada directorio en el servidor. En nuestro caso está introduciendo que se aumente el tamaño de los archivos que pueda recibir el servidor. Es responsabilidad del integrador la solución a tomar respecto a este tema. Podrá usar otras alternativas, como la configuración en servidor y eliminar dicho archivo.
index.html: archivo de entrada de la aplicación para el caso de uso seleccionado. No es necesario para la integración.

“personalizacion.js”: definición de variables para la personalización del caso de uso.

El integrador solamente debe tener en cuenta el archivo “jws.js” o “jws-simple.js”, la implementación de los tipos de comunicación y los archivos generales para el correcto funcionamiento de la aplicación.

Tecnología Java

Se distribuye un fichero zip para ser importado como proyecto web dinámico y desplegado en un entorno de desarrollo como ECLIPSE, para el caso de uso se ha desarrollado con la versión “Mars.2”.

Se describen los pasos necesarios para su importación y despliegue:

Importar al workspace el archivo ecoSignatureJWS.zip

File Import General Proyecto existente en workspace Next Seleccionar archivo.

Windows Preferencias:
1. Desplegar Java JREs Instalados: en el caso de uso se utiliza una jre 1.7.0_80-b15. (Versión de Java: Java 1.6+ WebService o Java 1.7+ WebSocket). Para el correcto funcionamiento de despliegue del caso de uso usar Java 1.7+.
2. Desplegar Server Runtime environments: en el caso de uso se utiliza un Apache Tomcat 7.0. (Versión mínima soportada: Tomcat 7).
Seleccionar proyecto ecoSignatureJWS Botón derecho Propiedades Java Build Path En la pestaña de Librerías asegurarse que tenemos librerías asociadas a la jre y al runtime anteriores. En caso de no existir alguna de ellas, añadirlas.
En la pestaña de Servers, añadir un nuevo servidor Apache Tomcat v7.0, añadir el proyecto ecoSignatureJWS.
Lanzar el servidor.
Abrir navegador, tenemos desplegada la aplicación en http:\\localhost:8080\ecoSignatureJWS.

Al importar el proyecto podemos observar las siguientes carpetas más importantes:

Java Resources src edatalia: contiene los servlets y la implementación de los tipos de comunicación (webService o webSocket).

Nota: El servlet “GetFiles” es usado para la generación del select de selección de documentos a firmar del caso de uso. En una integración se debe eliminar.

Carpeta “Web Content”: a su vez se definen las siguientes subcarpetas:
- Subcarpeta “cu”: contiene todo lo relacionado con el caso de uso.
- Subcarpeta “JWS”: contiene todo lo relacionado con el firmado. A su vez presenta una serie de subcarpetas:
  - “ecobiometricJWS”: ficheros .jar y librerías de firmado.
  - “ecoSignatureJWSHelper”: distribución de herramienta de edatalia ecoSignatureJWSHelper.msi (para Windows) y ELH (edatalia Linux Helper para Linux).
  - “css”: hojas de estilo de la aplicación.
  - “imagenes”: imágenes empleadas en la aplicación.
  - “js”: archivos javascript de la aplicación:
    - “ecoSignatureJWS.js”: librería de firmado.
    - “dtjava.js”: para el lanzamiento de fichero jnlp generado en local.
    - javascript’s relacionados con jQuery: cookies, base 64,….
    - “FileSaver.js”: solución para guardar archivos o información en el lado cliente, empleada para la casuística de generación de fichero jnlp en local.
    - “jws.js” o “jws-simple.js”: implementación de lógica de firmado, dependiendo del caso de uso seleccionado.
    - “tools.js”: implementación de funciones auxiliares necesarias en la aplicación y caso de uso.
    - “alert.js”: implementación para la visualización de errores.
  - “jnlp”: carpeta temporal donde se guardan los ficheros jnlp generados.
  - “temp”: carpeta temporal donde se guardan los documentos firmados.
  - archivos como EBP’s.

- Subcarpeta “view”: contiene todo lo relacionado con el visor. No se debe de cambiar nada, excepto el archivo “view/web/viewer.html” que contiene las referencias a archivos de hojas de estilo y javascript.
- Subcarpeta “wsdl”: wsdl del webService generado en el caso de uso.
- Subcarpeta “WEB_INF”: donde se presentan:
  - “lib”: se corresponde con las librerías necesarias para la implementación de la comunicación mediante webService realizada en el caso de uso.
  - los archivos de configuración “sun-jaxws.xml”, que indica quien implementa y donde se despliega el servicio web y “web.xml” donde se define el servlet que responde al WebService.
- index.html: archivo de entrada de la aplicación para el caso de uso seleccionado. No es necesario para la integración.
- “personalizacion.js”: definición de variables para la personalización del caso de uso.

El integrador solamente debe tener en cuenta el archivo “jws.js” o “jws-simple.js” para el firmado, los servlets propios de la aplicación y los archivos que implementan los tipos de comunicación.

Tecnología NET

Carpeta “Server webSocket”: contiene todo lo relacionado con la implementación del servidor web socket en local (para Windows).
- Archivo “ecoSignatureJWS_Helper_WebSocket.exe”: para lanzamiento de servidor web socket en local.

Carpeta “web”: contiene todo lo relacionado con el despliegue web de la aplicación. A su vez presenta una serie de subcarpetas:

- Subcarpeta “cu”: contiene todo lo relacionado con el caso de uso.
- Subcarpeta “JWS”: contiene todo lo relacionado con el firmado. A su vez presenta una serie de subcarpetas:
  - “ecobiometricJWS”: ficheros .jar y librerías de firmado.
  - “ecoSignatureJWSHelper”: distribución de herramienta de edatalia ecoSignatureJWSHelper.msi (para Windows) y ELH (edatalia Linux Helper para Linux).
  - “css”: hojas de estilo de la aplicación.
  - “imagenes”: imágenes empleadas en la aplicación.
  - “js”: archivos javascript de la aplicación:
    - “ecoSignatureJWS.js”: librería de firmado.
    - “dtjava.js”: para el lanzamiento de fichero jnlp generado en local.
    - javascript’s relacionados con jQuery: cookies, base 64,….
    - “FileSaver.js”: solución para guardar archivos o información en el lado cliente, empleada para la casuística de generación de fichero jnlp en local.
    - “jws.js” o “jws-simple.js”: implementación de lógica de firmado, dependiendo del caso de uso seleccionado.
    - “tools.js”: implementación de funciones auxiliares necesarias en la aplicación y caso de uso.
    - “alert.js”: implementación para la visualización de errores.
  - “jnlp”: carpeta temporal donde se guardan los ficheros jnlp generados.
  - “temp”: carpeta temporal donde se guardan los documentos firmados.
  - archivos como documentos, EBP’s y generales para el correcto funcionamiento de la aplicación (“generateJNLP.aspx”, “deleteJNLP.aspx” y “results.aspx”), dependiendo de las opciones seleccionadas para la generación de fichero jnlp y del tipo de devolución del documento PDF firmado.

- Subcarpeta “view”: contiene todo lo relacionado con el visor. No se debe de cambiar nada, excepto el archivo “view/web/viewer.html” que contiene las referencias a archivos de hojas de estilo y javascript.
- Subcarpeta “WebServiceSOAP”: contiene la implementación del servicio web.
- Subcarpeta “WebSocket”: contiene la implementación del web socket en servidor.
- Subcarpeta “bin”: contiene una biblioteca de servicios (.dll) con la implementación del servicio web y del web socket en servidor.

- web.config: archivo de configuración web.
- index.html: archivo de entrada de la aplicación para el caso de uso. No es necesario para la integración.
- “personalizacion.js”: definición de variables para la personalización del caso de uso.

IMPORTANTE: Cualquier despliegue de la aplicación en otro tipo de servidor de los expuestos anteriormente del caso de uso puede implicar cambios de configuración en servidor y de programación en la aplicación ecoSignature JWS.

Librerías de firmado

Se ha mencionado en el punto anterior la existencia de una serie de ficheros .jar y librerías de firmado contenidas en la ruta “JWS/ecobiometricJWS/” relacionadas con el firmado, que presentan dependencia con el sistema operativo del cliente, recordar que el firmado de documento se realiza a nivel local.

Librerías comunes

A continuación se describen las librerías comunes independientemente del sistema operativo del cliente contenidas en la ruta “JWS/ecobiometricJWS/”:

ecobiometric.jar: librería principal de firmado.
commons-logging-1.1.1.jar, fontbox-2.0.6.jar, icu4j-53_1.jar, xmpbox-2.0.6.jar, pdfbox-2.0.6.jar y pdfbox-tools-2.0.6.jar: necesarias para el posicionamiento flotante.

SO Windows

A continuación se describen las librerías comunes para un sistema operativo Windows del cliente contenidas en la ruta “JWS/ecobiometricJWS/libs”:

ess_win_x64 y ess_win_x86: relacionadas con la firma de documentos.
wacomSTU_win_x64 y wacomSTU_win_x86: relacionadas con dispositivos de captura biométrica Wacom STU 430 y STU 520-530-540.
stylusapi_win_x64 y stylusapi_win_x86: relacionadas con dispositivos de captura biométrica Windows Stylus (surface pro 3).
citrixapi_win_x64 y citrixapi_win_x86: relacionadas con el canal Virtual Citrix.
vdesa_win_x64 y vdesa_win_x86: relacionadas con el canal virtual Citrix para Wacom STU 430 y STU 520-530.
vdesas_win_x64 y vdesas_win_x86: relacionadas con el canal virtual Citrix para Windows Stylus (Surface pro 3).

SO LINUX

A continuación se describen las librerías comunes para un sistema operativo Linux del cliente contenidas en la ruta “JWS/ecobiometricJWS/libs”:

ess_linux_x64 y ess_linux_x86: relacionadas con la firma de documentos.
wacomSTU_linux_x64 y wacomSTU_linux_x86: relacionadas con dispositivos de captura biométrica Wacom STU 430 y STU 520-530-540.

Archivos generales

El firmado con la aplicación ecoSignature JWS permite la selección de diferentes opciones de firmado:

dependiendo del tipo de implementación del intermediario seleccionada:
- WebService SOAP
- WebSocket
dependiendo de la generación del fichero jnlp para el lanzamiento de la aplicación:
- en servidor
- en local
dependiendo del uso o no de protocolo.

Estas diferentes opciones de firmado no son excluyentes entre sí, es decir, cualquier integración debe de contar con la mezcla o suma de éstas tres opciones SIEMPRE expuestas anteriormente para el correcto funcionamiento, en dependencia de las necesidades o los requisitos de la integración:

con un tipo de intermediario, selección de WebService SOAP o de WebSocket.

con la generación de fichero jnlp bien en servidor o en local.

uso o no de protocolo.

Ejemplo: Se realiza una integración con intermediario WebService SOAP, generación de fichero jnlp en servidor y uso de protocolo.

Dependiendo del tipo de implementación del intermediario (WebService SOAP o WebSocket), de la tecnología (PHP, Java o .NET) seleccionada y de la generación del fichero jnlp (en servidor o en local), deberemos tener en cuenta los siguientes archivos:

Intermediario implementado con WebService SOAP:
- PHP: en el fichero “server.php” es donde se define el servicio web SOAP, se encuentra en la carpeta “JWS/WebServiceSOAP_ecobiometricJWS/”. El servicio web está implementado a partir de la librería nusoap, que incluye SOAP 1.1, WSDL 1.1 y HTTP 1.0/1.1 que nos facilita la creación de webservices y además de ser muy estable nos provee una herramienta completa (no se necesitan módulos adicionales).
- Java: se dispone de la clase “SOAP.java” que define el servicio web SOAP, y los archivos de configuración “sun-jaxws.xml”, que indica quien implementa y donde se despliega el servicio web y “web.xml” donde se define el servlet que responde al WebService. El servicio web está desarrollado mediante la tecnología JAX-WS (Java API for XML Web Services) que es una API de Java para la creación de servicios web. Es parte de la plataforma Java EE de Sun Microsystems. Al igual que las otras API de Java EE, JAX-WS utiliza anotaciones, introducidas en Java SE 5, para simplificar el desarrollo y despliegue de los clientes y puntos finales del servicios web.
- .NET: se dispone del archivo “WebServiceSOAPJWS.asmx” que se encuentra en la carpeta “WebServiceSOAP” y el archivo “WebServiceSOAPJWS.dll” que se encuentra en la carpeta “bin” e implementa el servicio web.

El WebService consta de dos métodos para la comunicación entre actores:

- get_status: para la petición de eventos, a partir de un identificador, por parte del navegador al intermediario.

A partir del identificador, se retorna un string con todos los eventos que aún no habían sido pedidos y que se encuentran guardados en un fichero temporal.

- set_status: para la actualización de estados de un identificador, de ecoSignature JWS al intermediario. Método que es llamado por ecoSignature JWS donde se le pasa el identificador y el evento que es guardado en un fichero temporal, de la forma evento+”\n”.

Intermediario implementado con WebSocket:

- PHP: se dispone de la carpeta “WebSocket_ecobiometricJWS” que implementa la lógica de comunicación, a través del proyecto PHP WebSockets, que describe un servidor web sockets desarrollado en PHP.
- Java: se dispone de la clase “WebSocket.java” que implementa la lógica de comunicación.
- .NET: se dispone, dependiendo del despliegue del web socket:
  - Local: se dispone de la carpeta “Server web socket”, donde se encuentra un archivo “.exe” para el lanzamiento del servidor web socket.
  - Servidor: se dispone del archivo “WebSocketJWS.ashx” que se encuentra en la carpeta “WebSocket” y los archivos “WebSocketJWS.dll” y “Microsofts.WebSockets.dll” que se encuentran en la carpeta “bin” e implementan el web socket.

IMPORTANTE: El servidor web socket en local se puede levantar en modo normal o en modo seguro. Para su funcionamiento en modo seguro necesita disponer en la misma ruta de lanzamiento de un certificado, denominado “certificado.pfx” con contraseña vacía. Si se requiere realizar algún cambio en el comportamiento, se dispone del proyecto a su disposición.

En el web socket, el evento proporcionado por ecoSignatureJWS es recibido con el formato “set_statusIDEvento” y se transmite el evento al navegador para una ID específica, que es mostrado posteriormente y en tiempo real en la ventana de espera de firmado.

Si se selecciona la generación de fichero jnlp en servidor, deberemos tener en cuenta los siguientes ficheros, dependiendo de la tecnología seleccionada:

“generateJNLP.php” (para PHP), “GenerateJNLP.java” (para Java) o “generateJNLP.aspx” (para NET): genera un fichero [id].jnlp en el servidor en la carpeta “JWS/ecobiometricJWS” que servirá para lanzar el Java Web Star.

“deleteJNLP.php” (para PHP), “DeleteJNLP.java” (para Java) o “deleteJNLP.aspx” (para NET): elimina el fichero [id].jnlp en el servidor en la carpeta “JWS/ecobiometricJWS“, generado anteriormente después de que es lanzado el Java Web Start.

IMPORTANTE: El fichero jnlp generado debe codificarse en UTF-8.

Además, si se selecciona la obtención del PDF firmado vía POST, deberemos tener en cuenta el siguiente fichero, dependiendo de la tecnología seleccionada, para el correcto funcionamiento del firmado con ecoSignature JWS:

“results.php” (papa PHP), “Results.java” (para Java) o “results.aspx” (para NET): nos deja el archivo pdf firmado en el servidor en la carpeta “JWS/temp“.

IMPORTANTE: Las comunicaciones de generar y eliminar fichero jnlp si se selecciona la generación de fichero jnlp en servidor, como las peticiones al intermediario si es implementado con WebService SOAP se realizan mediante tecnología Ajax.

Es responsabilidad del integrador el correcto funcionamiento de la aplicación si introduce algún cambio en los archivos expuestos.

IMPORTANTE: Una misma integración se puede desarrollar con varias tecnologías, es decir, se puede tener la aplicación desplegada en un tipo de servidor (por ejemplo IIS (tecnología NET)) y tener levantado el servidor web socket o el web service SOAP en otro servidor (por ejemplo Apache (tecnología PHP)).

Proceso de firmado

Librería javascript ecoSignatureJWS

Edatalia ha desarrollado la librería ecoSignatureJWS en javascript para facilitar la integración de un proceso de firmado.

Parametrización

La librería presenta las siguientes propiedades parametrizables, presentando en algunos casos valores por defecto:

PROPIEDAD	DESCRIPCIÓN
URLecoSignatureJWS	OBLIGATORIA. Url de despliegue de solución ecoSignatureJWS.
generationJNLP	OPCIONAL. Configuración de generación de archivo JNLP (en servidor o en local). Posibles valores: 0: en servidor (Valor por defecto). 1: en local.
protocol	OPCIONAL. Uso o no de protocolo para lanzamiento de JNLP en Windows. Necesaria si generación de JNLP en local. Posibles valores; 0: No uso de protocolo (Valor por defecto). 1: Uso de protocolo.
fileGenerateJNLP	OBLIGATORIA para generación de JNLP en servidor. Url relativa o absoluta de fichero de acción de generación de fichero JNLP.
fileDeleteJNLP	OBLIGATORIA para generación de JNLP en servidor. Url relativa o absoluta de fichero de acción de eliminación de fichero JNLP.
maxAttemptsCreateWebSocket_JNLP	OPCIONAL. Máximo número de intentos para lanzamiento de web socket. Valor por defecto 5. Utilizada para el lanzamiento del jnlp en local mediante protocolo.
tempAttemptsCreateWebSocket_JNLP	OPCIONAL. Tiempo en segundos entre intentos para lanzar el web socket. Valor por defecto 1. Utilizada para el lanzamiento del jnlp en local mediante protocolo.
portWebSocketLaunchLocal	OPCIONAL. Puerto para el lanzamiento del web socket local. Valor por defecto 8282. Utilizada para el lanzamiento del jnlp en local mediante protocolo.
showEvent	OPCIONAL. Mostrar ventana de eventos en el proceso de firma. Por defecto true (activada).
intervalWebService	OPCIONAL.Tiempo en milisegundos de polling de Servicio Web. Por defecto 1000. Utilizada para intermediario implementado mediante Web Service.

Además, se puede obtener el identificador del proceso autogenerado internamente durante la creación del objeto, a partir del parámetro “id” y que no debe ser modificado para el correcto funcionamiento del proceso de firmado.

IMPORTANTE: El tipo de intermediario se obtiene a través del parámetro JNLP de configuración “jwsType”.

IMPORTANTE: En un proceso de firmado trabajando con la librería ecoSignatureJWS lo importante es:

inicialización de la librería.

parametrización de las propiedades de la librería relacionadas con:

la generación de jnlp en servidor o en local.

el uso o no de protocolo en el lanzamiento del jnlp generado.

introducción de parámetros JNLP de configuración para la posterior generación de fichero jnlp. (Ver apartado: Parámetros de configuración).

lanzamiento del proceso de firmado.

Funciones

La librería dispone de una serie de métodos públicos:

setParamJNLP(param, value):

Introducción de parámetro JNLP de configuración con su valor.

setParamsJNLP(map):

Introducción de un Map (pares clave/valor) de parámetros JNLP de configuración.

IMPORTANTE: Esta función hace un clonado en la librería del map, sustituyendo lo que tuviese anteriormente, de ahí que generar el map con todos los parámetros JNLP de configuración necesarios para el proceso de firmado antes de la clonación.

getParamJNLP(param):

Obtención de parámetro JNLP de configuración.

getPdfSignedB64():

Obtención del documento pdf firmado en base 64 si se ha optado por este tipo de devolución.

launch():

Lanzamiento de proceso de firmado con ecoSignatureJWS.

Funciones externas

La librería llama a funciones implementadas externamente para determinados eventos durante el proceso de firmado:

successEcoSignatureJWS():

Éxito en el proceso de firmado.

cancelEcoSignatureJWS():

Cancelación del proceso de firmado.

errorEcoSignatureJWS(message):

Error en el proceso de firmado

errorHelperEcoSignatureJWS().

Error en Helper.

Archivo “jws.js”

El archivo “jws.js” o “jws-simple.js”, dependiendo del caso de uso seleccionado, contiene la lógica de la implementación del proceso de firmado de ecoSignature JWS, desarrollado en javascript, a través de la librería ecoSignatureJWS.js.

Nota: La variable tecnology es de uso exclusivo de edatalia y sirve para el control de expresiones condicionales en referencia a la tecnología con la que se desarrolla la implementación, es definida en el fichero “personalizacion.js”. En una integración solo debe aparecer el código correspondiente a la tecnología en desarrollo.

Variables relacionadas con URL’s

URLecoSignatureJWS: URL de despliegue de la aplicación de firmado.

Ejemplo:

var URLecoSignatureJWS = ‘http://localhost:8080/JWS/‘

Dependiendo del intermediario o tipo de comunicación elegida:

URLWebService: URL del ServiceWeb SOAP (NECESARIA CON TIPO DE COMUNICACIÓN WEBSERVICE)

Ejemplo:

var URLWebService = ‘http://localhost:8080/JWS/

WebServiceSOAP_ecobiometricJWS/server.php‘;

URLWebSocket: URL del WebSocket (NECESARIA CON TIPO DE COMUNICACIÓN WEB SOCKET)

Ejemplo:

var URLWebSocket = ‘ws://127.0.0.1:8888/serverWebSocket’;

Es responsabilidad del integrador configurar estas url’s para el correcto funcionamiento de la aplicación.

Variables relacionadas con URL’s de archivos

Se dispone de tres variables que contienen las url’s de archivos de acciones para el correcto funcionamiento del firmado, dependiendo de las opciones seleccionadas para generación del fichero jnlp (en servidor o en local) y para la devolución del documento PDF firmado:

fileGenerateJNLP: url donde se encuentra el fichero “generateJNLP.php” (para PHP), “GenerateJNLP.java” (para Java) o “generateJNLP.aspx” (para NET), el cual genera un fichero [id].jnlp en el servidor en la carpeta “ecobiometricJWS” que servirá para lanzar el Java Web Start.

Ejemplo:

var fileGenerateJNLP = ‘../../JWS/generateJNLP.php’;

fileDeleteJNLP: url donde se encuentra el fichero “deleteJNLP.php” (para PHP), “DeleteJNLP.java” (para Java) o “deleteJNLP.aspx” (para NET), el cual elimina el fichero [id].jnlp en el servidor en la carpeta “ecobiometricJWS“, generado anteriormente después de que es lanzado el Java Web Start.

Ejemplo:

var fileDeleteJNLP = ‘../../JWS/deleteJNLP.php’;

IMPORTANTE: Las variables fileGenerateJNLP y fileDeleteJNLP solo se deben de tener en cuenta si la generación del fichero jnlp se realiza en el servidor.

fileResults: url donde se encuentra el fichero “results.php” (para PHP), “Results.java” (para Java) o “results.aspx” (para NET), el cual nos deja el archivo pdf firmado en el servidor en la carpeta “temp“.

Ejemplo:

var fileResults = ‘../results.php’;

IMPORTANTE: La variable fileResults solo se debe de tener en cuenta si se ha seleccionado la devolución del PDF firmado vía POST.

IMPORTANTE: Si no se usan rutas absolutas, tener en cuenta que para fileGenerateJNLP y fileDeleteJNLP se referencian desde el HTML en ejecución, mientras que fileResults se referencia desde el directorio “JWS/ecobiometricJWS”, que es el que contiene el jar de firmado.

Así, para el de uso con visor, los ficheros de “generateJNLP.xxx” y “fileDeleteJNLP.xxx” se referencian desde la ruta “view/web/” que es donde se está ejecutando el “viewer.html” que se encarga de mostrar el visor.

Es responsabilidad del integrador configurar estos parámetros para el correcto funcionamiento de la aplicación.

Funciones

Se dispone de una serie de funciones para el correcto funcionamiento del caso de uso y de la aplicación ecoSignature JWS:

Función openSignatureAsPDFJWS()

Es la función más IMPORTANTE en el caso de uso simple, es la que se encarga de realizar todos los pasos necesarios para inicializar y parametrizar la librería y lanzar la aplicación ecoSignature JWS.

Función signedViewPDF()

Es la función más IMPORTANTE en el caso de uso con visor, es llamada en el lanzamiento de la firma desde el visor, es la que se encarga de realizar todos los pasos necesarios para inicializar y parametrizar la librería y lanzar la aplicación ecoSignature JWS.

Función loadParamJNLPFromCaseUse()

Esta función es la encargada de la actualización de los parámetros JNLP de configuración de firma con los valores seleccionados en el caso de uso simple.

Esta función en una integración debe desaparecer.

Función loadParamJWSFromCoockies()

Esta función es la encargada de la actualización de los parámetros JNLP de configuración de firma con los valores seleccionados en el caso de uso con visor.

Esta función en una integración debe desaparecer.

Plugin jQuery alert

Este plugin jQuery denominado alert se encuentra en el archivo “alert.js”, es utilizado para la muestra de errores en la aplicación, el cual muestra una ventana de error.

Visor de documentos

El visor está implementado a través de la librería javascript PDF.js, la cual es una herramienta de Mozilla Corporation. El objetivo de esta librería es aprovechar las novedades de HTML5/Javascript para visualizar ficheros PDF en un canvas, para incrustar un documento PDF en una página sin emplear plugins adicionales o programas externos.

En ocasiones, programas externos tienen sus propias formas de interacción en el documento. Con esta librería se consigue que desde la propia web, decida cómo desea que se navegue por el documento mejorando la experiencia de usuario de la aplicación web.

El visor de documentos permite las siguientes formas/acciones de trabajo:

visualización de un documento PDF:
- visor de documentos PDF propiamente dicho sin acción asociada a ejecutar, es el visor original que presenta Mozilla.
- visor de documentos PDF con acción asociada a ejecutar: aparece un botón (parte superior izquierda de la pantalla) de “volver” que al ser pulsado lanza una acción, invocando a la función “backViewPDF()”, esta función es descrita posteriormente.
firma de documento PDF: dependiendo del tipo de posicionamiento seleccionado, se tiene:
- posicionamiento manual: se tiene un botón (parte superior izquierda de la pantalla) de lanzamiento de firma, que al ser pulsado, abre la ventana de firma, la cual puede ser redimensionada y trasladada por parte del usuario por la página del documento. Al pulsar sobre la ventana se lanza la firma.
- posicionamiento fijo.
- posicionamiento flotante.

Para éstos dos últimos posicionamientos se tiene un botón (parte superior izquierda de la pantalla) de lanzamiento de firma, que al ser pulsado, abre la ventana de firma y automáticamente lanza la firma.

IMPORTANTE: Una vez posicionada la ventana de firma se invoca a la función “signedViewPDF()”, esta función es descrita posteriormente.

El acceso a la aplicación de visualización se realiza a través de url:

(dir_server)/view/web/viewer.html?file=name_file

El parámetro file, es obligatorio, se pueden mandar más parámetros de configuración en la url concatenados con el carácter ‘&’ y codificados en Base 64 en el parámetro data, así se disponen de los siguientes parámetros de configuración:

x: posición X en píxeles de la ventana de firma. (Para posicionamiento manual o fijo).
y: posición Y en píxeles de la ventana de firma. (Para posicionamiento manual o fijo).
w: ancho en píxeles de la ventana de firma.
h: alto en píxeles de la ventana de firma.
p: página del documento pdf. (Para posicionamiento fijo).
mH: mínima altura en píxeles de la ventana de firma. (Para posicionamiento manual).
t: texto de búsqueda (Para posicionamiento flotante).
dx: desfase X en píxeles. (Para posicionamiento flotante).
dy: desfase Y en píxeles. (Para posicionamiento flotante).
btnpos=1: selección de posicionamiento manual.
btnsgn=1: selección de posicionamiento fijo.
btnback=1: selección de visualizador de documentos PDF con acción asociada.
btncnc=1: muestra en pantalla un botón (parte inferior izquierda de la pantalla) de “cancelar” que al ser pulsado lanza una acción, invocando a la función “cancelViewPDF()”, esta función es descrita posteriormente.
sp: introducción de texto en pantalla.
cu: para presentación de la aplicación por parte de edatalia.
m: acceso desde movilidad.

IMPORTANTE: Para el correcto funcionamiento, solo se debe seleccionar un tipo de posicionamiento. Si no se manda en la url algún parámetro necesario para el tipo de posicionamiento, se recogen los implementados por defecto.

A continuación, se describe una serie de ejemplos de construcción de url para invocación del visor de documentos:

Estructura básica: ../viewer.html?file=name_file&data=…B64…#param_extra

Ejemplos:

selección de posicionamiento manual, con posición de la ventana de firma en las coordenadas x=200 e y=100, con un tamaño de 200×50 píxeles, mínima altura de la ventada de 40 píxeles y botón de cancelación:

data=B64(‘btnpos=1&x=200&y=100&w=200&h=50’&mH=40&btncnc=1)

selección de posicionamiento fijo, con posición de la ventana de firma en las coordenadas x=400 e y=150, con un tamaño de 200×50 píxeles y en la página 4, con texto en pantalla “Firma del paciente”:

data=B64(‘btnsgn=1&x=400&y=150&w=200&h=50&p=4&sp=Firma del paciente’)

selección de posicionamiento flotante, con un tamaño de la ventana de firma de 200×50 píxeles, con texto a buscar “Firme aquí”, desfase X de -50 píxeles y desfase Y de 25 píxeles:

data=B64(‘btnsgn=1&w=200&h=50&t=Firme aquí&dx=-50&dy=25’)

selección de visor de documento PDF con acción asociada:

data=B64(‘btnback=1’)

Cabe destacar que se pueden mandar a la aplicación de visualización de documentos una serie de parámetros extra, a través de la concatenación en la url de la estructura “#param_extra”, así se presentan los parámetros:

“zoom“: zoom de la página. Se recomienda usar un zoom entre 50 y 500.

Ejemplo:

../viewer.html?file=name_file#zoom=100

“page”: inicialización del visor de documento en una determinada página.

Ejemplo:

../viewer.html?file=name_file#zoom=100&page=3′

IMPORTANTE: El cacheo o no del documento pdf es configuración de servidor.

Funciones relacionadas con el visor

A continuación, se enumeran las funciones que presentan relación con el visor de documentos, sólo tienen sentido para el caso de uso con visor.

Función createUrlView()

Esta función se encuentra en el archivo “tools.js”, se utiliza para la obtención/composición de la url de acceso al visor de documentos. Dicha función devuelve un string (url) de la forma:

base+’viewer.html?file=’+file+’data=’+B64(x,y,w,..)+’#’+extra

La función presenta los siguientes parámetros de entrada:

base (string): dirección base de la url del visor.
typePosition (entero): tipo de posicionamiento. Posibles valores:
- null: para visor de documentos con acción asociada, retorna SIEMPRE data=B64(‘btnback=1’).
- 0: para posicionamiento manual, un ejemplo de retorno es:

data=B64(‘btnpos=1&x=200&y=100&w=200&h=50’&mH=40’)

- 1: para posicionamiento fijo, un ejemplo de retorno es:

data=B64(‘btnsgn=1&x=400&y=150&w=200&h=50&p=4’)

- 2: para posicionamiento flotante, un ejemplo de retorno es:

data=B64(‘btnsgn=1&w=200&h=50&t=Firme aquí&dx=-50&dy=25’)

file (string): ruta más nombre del fichero.
x,y,w,h,mH,p,t,dx,dy: parámetros de posicionamiento explicados anteriormente.
extra (string): parámetros extras.
cancel (booleano): existencia o no de botón de cancelación.
span (string): texto a mostrar en pantalla.
cu (booleano): para presentación de la aplicación por parte de edatalia.
m (booleano): acceso desde movilidad.

Nota: Para acceder a la aplicación como visor de documentos, es decir, sin acción asociada a ejecutar, construir la url de acceso a mano: ../viewer.html?file=name_file

Función firstPageRendererViewPDF()

Esta función se encuentra en el archivo “jws.js”, es invocada cuando el visor ha renderizado la primera página de entrada del documento.

Nota: Esta función puede ser utilizada para el lanzamiento automático del proceso de firma (autosign).

Función backViewPDF()

Esta función se encuentra en el archivo “jws.js”, es invocada cuando se trabaja con el visor como visualizador de documentos PDF con acción asociada y es pulsado el botón correspondiente.

Función cancelViewPDF()

Esta función se encuentra en el archivo “jws.js”, es invocada cuando el visor presenta un botón de cancelación, previamente programado y, dicho botón ha sido pulsado.

El integrador, dependiendo del tipo de configuración seleccionado, deberá configurar las acciones a realizar si se invocan las funciones “cancelViewPDF()” y “backViewPDF()”. Si no se realiza se presentarán fallos de javascript.

Función signedViewPDF()

Esta función se encuentra en el archivo “jws.js”, SIEMPRE es invocada cuando se tiene posicionada la ventana de firma y ésta es lanzada desde el visor. Presenta los siguientes parámetros de entrada, que son mandados por el visor:

numPage: número de página del documento donde se posiciona la ventana de firma.
x0: coordenada x que se corresponde con el punto inferior izquierdo en el documento de la ventana de firma.
y0: coordenada y que se corresponde con el punto inferior izquierdo en el documento de la ventana de firma.
x1: coordenada x que se corresponde con el punto inferior derecho en el documento de la ventana de firma.
y1: coordenada y que se corresponde con el punto superior izquierdo en el documento de la ventana de firma.
name: nombre del fichero a firmar.
url: url del fichero a firmar.

Función errorViewPDF()

Esta función se encuentra en el archivo “jws.js”, es invocada cuando el visor lanza un mensaje de error. Presenta los parámetros de entrada:

message: mensaje de error.
cu: para presentación del caso de uso de edatalia.

m: dispositivo móvil o no de acceso (No utilizada).

Función configParameterViewPDF()

Esta función se encuentra en el archivo “jws.js”, es invocada por el visor después de inicializar su configuración de firmado y antes de la inicialización/representación de los elementos relacionados con el firmado y ajenos al visor de la librería pdf.js.

Es útil para cambiar valores por defecto del visor como el tamaño de borde de la página, el color de borde de página seleccionada y de la página a firmar, el tiempo de animación de aparición/desaparición de botones en un acceso con dispositivo no móvil,…

Función updateViewPDF()

Esta función se encuentra en el archivo “jws.js”, es invocada por el visor después de la representación de los elementos relacionados con el firmado y ajenos al visor de la librería pdf.js.

Es útil para añadir nuevos botones, nuevos efectos,…

Función autoSign()

Esta función se encuentra en el archivo “view.js”, se utiliza para el lanzamiento automático del proceso de firmado.

Flujo de ejemplo de una aplicación

Se describe el flujo normal de una aplicación en el que se integra JWS más el visionado de documentos PDF:

Se construye url de acceso al visor con los parámetros de configuración necesarios en un determinado HTML inicial, la forma más habitual será tener un botón o un enlace que nos lleve a dicha url. Observar la función “createUrlView()” en “tools.js” Acceso al visor.
Visualmente, dependiendo del posicionamiento seleccionado, se puede posicionar la ventana de firma manualmente y lanzar la firma o por el contrario, el posicionamiento de la ventana de firma y el lanzamiento es automático Pre-lanzamiento de firma.
Puede existir un botón de cancelación, que al ser pulsado invoca a la función “cancelViewPDF()” en “jws.js” vuelve al HTML inicial.
Invocamos a la función “signedViewPDF()” en “jws.js”, que actualiza valores de firma dependientes del visor y lanza la firma. Previamente se debe haber inicializado la librería de javascript ecoSignatureJWS.
Visualmente, aparece la ventana de espera de firma y la ventana de firma (se muestran los eventos de la firma).
Introducimos la firma y aceptamos.
Se muestra el documento PDF firmado Salida de la visualización (llamada a función “backViewPDF()” en “jws.js”).

A continuación, se describe el flujo normal de una aplicación en el que se integra JWS sin el visionado de documentos PDF:

Invocamos a la función “openSignatureAsPDFJWS()” que lanza la firma (normalmente dispondremos de un botón en la página).
Visualmente, aparece la ventana de espera de firma y la ventana de firma (se muestran los eventos de la firma).
Introducimos la firma y aceptamos.
Se muestra el documento PDF firmado.

Integración

Los pasos orientativos a seguir para la realización de una integración con la aplicación ecoSignature JWS se enumeran a continuación:

Parametrización de librería ecoSignatureJWS.js:

- Url de la aplicación de firmado ecoSignatureJWS.
- Uso o no de protocolo.
- Tipo de generación del fichero jnlp.

Otros parámetros en dependencia de la generación de JNLP.

Otros parámetros en dependencia del uso o no de protocolo.

Configuración de los parámetros JNLP de configuración de firma según necesidades.
Dependiendo de la utilización o no de visor de documentos:
1. Si se utiliza el visor de documentos:

Crear la url de acceso al visor a través de la función createUrlView().

Una vez posicionada la firma, dependiendo del tipo de posicionamiento, se llama a la función signedViewPDF().

Además se disponen de las funciones cancelViewPDF() y backViewPDF() que son invocadas dependiendo de la configuración del visor.

El integrador debe de introducir la lógica necesaria, si es necesario, para dar respuesta a la invocación de estas funciones.

1. Si no se utiliza visor de documentos, invocar a la función de firmado openSignatureAsPDFJWS().
Lanzar proceso de firmado.

Si se desea realizar un tratamiento especial a los errores modificar el plugin jQuery alert según necesidades.

Parámetros de configuración

El firmado con ecoSignature JWS necesita la configuración de una serie de parámetros para adecuarlo a cada escenario específico en el que se desee implementar. A continuación se muestran los diferentes parámetros de configuración con los que contamos para la llamada del JWS.

Entradas y salidas del documento PDF

*Param Name*	*Valor*	*Valor por defecto*	*Comportamiento*
Pdf-Content	PDF en B64		El PDF a firmar en B64.
remotePdf-url	test.pdf		URL de entrada de donde se coge el PDF.Si se informa Pdf-Content, este parámetro remotePdf-url no se tiene en cuenta.
result-url	results.php		Nombre del parámetro que recibirá la imagen en formato binario.
result-formName-signatureImage	imgSignature		Nombre de la imagen en formato PNG.
result-formName-signedPdf	fileSigned		Nombre del PDF resultante ya firmado.
result-FormName-SignatureEVS	String		Si se pone distinto a vacío, al POST de resultado al que se deja el PDF (y el grafo etc), también se le enviará vía POST en éste nombre de parámetro el EVS de la firma en Binario. Por defecto vacío (no se sube vía POST el EVS).
EVS_encKeyB64	String		Llave pública de cifrado para los datos EVS, si es vacía se usará la llave pública embebida en la solución de edatalia.
EVS_pfxB64	String		Certificado para la firma de los datos EVS, si es vacío se usará el certificado embebido por defecto de edatalia. PFX en B64.
EVS_pfxUrl	String		Certificado para la firma de los datos EVS, si es vacío se usará el certificado embebido por defecto de edatalia. PFX proveniente de una URL.
EVS_pfxPw	String		Contraseña en B64 si se usa un PFX diferente al embebido de edatalia.
resizeSignaturePng	booleano	0	Activa la reducción de tamaño, cuando se quiere guardar la imagen PNG.
resizeSignaturePngWidthFactor	0.1 a 1	1 (100%)	0.5 reduce el PNG al 50%.
resizeSignaturePngheightFactor	0.1 a 1	1 (100%)	0.5 reduce el PNG al 50%.
extraParamPost	String		Contenido extra que se dejará en la URL del POST como parámetro “extraParamPost”.
widget-Textcustom	String		Texto custom del widget en B64.
author	String		Autor de la firma (propiedad de un pdf firmado).
reason	String		Razón de la firma (propiedad de un pdf firmado).
contact	String		Info de contacto de la firma (propiedad de un pdf firmado).
location	String		Info de localización de la firma (propiedad de un pdf firmado).
pdfPassword	String		Contraseña del PDF de entrada si la tiene.

Certificados de firma y cifrado

El certificado de firma y de encriptación se pueden informar de varias formas. Por defecto, se utilizarían los certificados embebidos en el JWS. También se puede informar de la ubicación del fichero físico.

En el caso del certificado de firma electrónica, también se puede obtener del almacén estándar de certificados de Windows (CryptoAPI).

*Param Name*	*Valor*	*Valor por defecto*	*Comportamiento*
cert-origin	Booleano	0	Si se activa (1) buscará el certificado en el almacén interno de windows (CryptoAPI).No aplica en Linux.
cert-origin-ca		–	Permite identificar la CA del certificado desde el CryptoAPI.Sólo funciona si cert-origin=1.No aplica en Linux.
pfx-b64	Base64 del contenido del PFX	–	Permite informar el certificado de firma.
pfx-url		–	Es la url al fichero pfx si no se usa “pfx-b64” ni otros orígenes de certificados.
pfx-pw	En Base64	–	Password para activar el certificado.
Chain-CA-b64	En Base64		Cadena de validación completa del certificado.
enc-key-b64	Base64 del contenido del .cer		Clave pública del cert de encriptación(el cifrado no requiere pss).
certificatePDF	Booleano		Firma PDF Certificada (MDP).
TIME STAMP	Sellado de tiempo en el momento de la firma
tsp-activate	Booleano	0	Si se activa (1) activa la consulta TSP.
tsp-url
tsp-user
tsp-password
OCSP	Validación del estado de revocación del certificado en el momento de la firma
ocsp-activate	Booleano	0	Si se activa (1) activa la consulta OCSP.
ocsp-url
ocsp-user
ocsp-password
setValidateErrorContinue	Booleano	0	Si se activa (1) la firma no se para aunque haya un error de validación OCSP.
bufferLTV	Entero	0	Tamaño en Bytes de reserva en caso de querer realizar un PAdES-LTV (TSP+OCSP).Debe dejarse un 2x de la cantidad estimada. Típicamente con 100000 funciona.

Nota: Si está activada la validación del estado de revocación del certificado en el momento de la firma y no se ha introducido la URL del OCSP, se toma automáticamente en la comprobación la URL del OCSP del certificado.

Ubicación del área de firma del documento

Los siguientes parámetros permiten configurar el tamaño del área de firma y ubicarlo en el documento PDF.

*Param Name*	*Valor*	*Valor por defecto*	*Comportamiento*
Ubicación fija del área de firma	El JWS ubica la firma en una página y coordenadas determinadas
widget-Page	Entero	1	0: la firma se muestra en todas las páginas.Si cualquier otro número, indicaría el número de página.4: la firma se muestra en la página 49999: un número suficientemente grande puede servir para indicar la última página del documento.
widget-X	Entero	0	Desplazamiento del widget en horizontal, desde el vértice inferior izquierdo del PDF.
widget-Y	Entero	0	Desplazamiento del widget en vertical, desde el vértice inferior izquierdo del PDF.Un documento PDF estándar, tamaño DIN-A4, tiene una altura de 842 puntos.
widget-Transparent-activate	Booleano	1	Widget transparente o no.
Ubicación relativa a cadena de caracteres	El JWS busca una frase en el documento y ubica la firma en relación al primer carácter. Por ejemplo “Firmado por:”
widget-autoPos-activate	Booleano	0	Si se activa (1) el JWS buscará una cadena de caracteres para ubicar la firma.
widget-autoPos-text	Texto		Texto a buscar. La firma se ubicará de forma relativa al primer carácter.Por ejemplo “Firmado por:”.
widget-autoPos-desfaseX	Entero	0	Desplazamiento relativo en horizontal.
widget-autoPos-desfaseY	Entero	0	Desplazamiento en vertical.
Tamaño del área de firma	Atención: de cara a mantener la proporcionalidad de los trazados de la rúbrica, es muy relevante mantener el ratio de aspecto del área de firma en el EBP
widget-Ancho	Entero	120	Ancho del widget.
widget-Alto	Entero	30	Alto del widget.

IMPORTANTE: Para poder usar esta funcionalidad de “ubicación variable del widget”, se requiere del uso de otras librerías .jar externas (ecobiometric.jar, pdfbox-2.0.6.jar, pdfbox-tools-2.0.6.jar, fontbox-2.0.6.jar, xmpbox-2.0.6.jar, commons-logging-1.1.1.jar e icu4j-53_1.jar) que también hay que indicar que se carguen, en el archivo generateJNLP le debe llegar el parámetro “AutoPosEnabled” a true.

¿Qué ocurre si no encuentra la cadena?

Si la cadena de caracteres especificada no se encuentra por algún motivo se usan los parámetros X,Y por defecto del widget especificados por parámetros del JWS.

Si se encuentra la secuencia, en la consola de Java aparecería: “FOUND text for auto widget positioning”.

Dispositivo de captura biométrica

La firma manuscrita se puede recoger de una tableta Wacom STU o bien desde la propia pantalla del PC (dispositivos con pantalla táctil).

Estos parámetros nos permiten seleccionar el tipo de tableta con la que estamos trabajando y configurar el comportamiento del dispositivo de captura de datos biométricos.

*Param Name*	*Valor*	*Valor por defecto*	*Comportamiento*
Modo mouse	Nos permite probar la funcionalidad del JWS sin necesidad de tabletas de captura biométrica. Recabar la firma desde la pantalla de dispositivos con pantalla táctil.
mouseMode	Booleano	0	Si se activa, la firma se recoge desde el monitor del dispositivo.No requiere tableta de firma (Wacom/Stylus).
mouseSpeed	Booleano	0	Permite configurar la presión relativa a la velocidad.
typeTablet	Entero	0	Tipo de dispositivo de captura biométrica:0: tabletas STU en color STU-520,STU-530.1: tabletas STU monocromo STU-430.2: Stylus (No aplica en Linux). Aplica a tabletas con SO Windows y Wacom DTU.
Min_Points	Entero	100	Mínimo de puntos para que se acepte la firma, siempre tiene que existir como mínimo un punto.Las tabletas Wacom capturan 200 puntos por segundo.
max-sig-time	Entero	60	Segundos por defecto máximo para aceptación de la firma (recomendable no cambiarlo).
Empleo de plantillas EBP	Las plantillas EBP permiten definir la visualización de la tableta
ebp-activate	Entero	1	Activa el uso de plantilla.
ebp-use-internal	Booleano	0	Utiliza el EBP embebido en el JWS.
ebp-url			si ebp-use-internal está a 0, url de donde se coge el EBP.
showEBP	Booleano	1	1: Muestra al operador, en la pantalla del PC, lo que se está visualizando en la tableta Wacom.
noButtonEBP	Booleano	0	si showEBP=1, elige si se muestran los botones de la plantilla EBP (0) o si se ocultan (1).Recomendado a 1 ya que los botones van en el HTML y no en el JWS.
ebp-variables	String		Variables a mostrar en la plantilla EBP.ATENCIÓN: el valor de estas variables se guardan junto a la información biométrica de la firma.Es muy relevante que estos valores se asocien de forma unívoca al acto de firma (el contenido del documento).
STUBackLight	Entero	-1	Solo para dispositivos Wacom STU.0 (mínima intensidad) a 3 (máxima intensidad).Valor por defecto -1 (no cambia el brillo).
driver430Installed	Booleano	1	Parámetro por defecto a verdadero (1). Si se pone desactivado (0), se supondrá que no existen los drivers de la Wacom STU430 instalados en el ordenador local, y se usará una estrategia de inicialización especial para que no se produzcan “parpadeos” en la inicialización de la STU430.
ebp-initial-activate	Booleano	0	Activar o no (por defecto) el uso de la pantalla inicial.Se trata de una pantalla que puede mostrar un texto previo a la pantalla donde se recoge la firma.
ebp-initial-url	String		La url del EBP a usar para pantalla inicial, éste EBP al menos ha de contener 1 área marcada como botón aceptar. Se recomienda un botón para cancelar.
ebp-initial-variables	String		Las variables que se le pasan al EBP inicial, y también serán incluidas con la información biométrica cifrada. Por ejemplo para poner un texto de LOPD.

IMPORTANTE: Con ebp-activate=0 se recomienda un tamaño:

para STU 520,530 y 540 jwsWidth=800 y jwsHeight=510 (480+30 de la botonera).
para STU 430 jwsWidth=320 y jwsHeight=230.

Tamaños más pequeños de los recomendados hace que no se vea lo que se escribe en la STU en la pantalla.

Modo solo firma electrónica (sin biometría)

El JWS permite realizar la firma electrónica del documento sin asociarlo a una firma manuscrita. Sería la firma electrónica convencional basada en certificado digital.

*Param Name*	*Valor*	*Valor por defecto*	*Comportamiento*
jsigMode	Booleano	0	Si se activa (1), sólo se realiza firma usando el certificado digital, desactivado (0) se usa la firma biométrica.
jsigJPG	JPEG en BASE64		Permite pasar un JPEG como imagen para la firma digital del PDF.

Es importante que el JWS tenga un tamaño de 1×1 píxeles mínimo para el correcto funcionamiento.

Específicos de JWS

A continuación se describen los parámetros relacionados con la edición de la aplicación JWS:

*Param Name*	*Valor*	*Valor por defecto*	*Comportamiento*
jwsType	Entero	0	Permite configurar el tipo de comunicación:0: WebService SOAP.1: WebSocket.
WebSocketJWS	String		URL del WebSocket.
WebServiceJWS	String		URL del WebService SOAP.
jwsWidth	Entero	800	Anchura en píxeles de la ventana de la aplicación.
jwsHeight	Entero	650	Altura en píxeles de la ventana de la aplicación.
jwsTxtBtnReset	String		Texto en el botón de reinicio de la aplicación.
jwsTxtBtnCancel	String		Texto en el botón de cancelación de la aplicación.
jwsTxtBtnSgn	String		Texto en el botón de firma de la aplicación.
jwsBtnReset	Booleano	1	Visibilidad de botón de reinicio de la aplicación.
jwsBtnCancel	Booleano	1	Visibilidad de botón de cancelación de la aplicación.
jwsBtnSgn	Booleano	1	Visibilidad de botón de firma de la aplicación.
jwsBtnResetImage	String		Imagen en botón de reinicio de aplicación.
jwsBtnResetImageRollover	String		Imagen en botón de reinicio de aplicación (mouse over).
jwsBtnCancelImage	String		Imagen en botón de cancelación de la aplicación.
jwsBtnCancelImageRollover	String		Imagen en botón de cancelación de la aplicación (mouse over).
jwsBtnSignImage	String		Imagen en botón de firma de la aplicación.
jwsBtnSignImageRollover	String		Imagen en botón de firma de la aplicación (mouse over).
jwsComment	Boolean	0	Activación de comentarios de la aplicación.
jwsTxtLblComment	String		Label de comentarios.
jwsTxtComment	String		Posibles comentarios predefinidos separados por “;”.
jwsStayOnTop	Boolean	0	Si se activa(1) JWS estará siempre visible en pantalla.
jwsPosX	Entero	Centrado	Coordenada X de inicio de la aplicación en pantalla.
jwsPosY	Entero	Centrado	Coordenada Y de inicio de la aplicación en pantalla.
jwsWebSocketSendPDFB64	Booleano	0	Envío de PDF firmado en Base64 al websocket.
jwsWebSocketSendPDFB64_ChunkSize	Entero	16384	Tamaño máximo de los chunks o bloques de datos a enviar con el PDF en Base64 resultante.
jwsForzarNumMonitor	Entero	0	Número de monitor donde se muestra el JWS.
jwsShowBorderClose	Booleano	1	Si está activo mostrará la ventana de captura de firma con estilo “diálogo” (bordes + cruz para cerrar/cancelar ventana), sino será una ventana sin bordes.
Eventos de teclado	CTRL+carácter
jwsKeyboardAccept	Entero	65 (=A)	Evento de teclado en botón de aceptar firma. CTRL+carácter, donde caracter es el valor en decimal del ASCII (carácter).
jwsKeyboardCancel	Entero	67 (=C)	Evento de teclado en botón de aceptar firma. CTRL+carácter, donde caracter es el valor en decimal del ASCII (carácter).
jwsKeyboardReset	Entero	82 (=R)	Evento de teclado en botón de aceptar firma. CTRL+carácter, donde caracter es el valor en decimal del ASCII (carácter).

IMPORTANTE: Los parámetros de posicionamiento de la ventana de firma “jwsPoxX” y “jwsPosY” presentan el siguiente comportamiento:

Para ambas coordenadas si el valor es -1 o “center” se centra la coordenada en pantalla.
Para la coordenada X:
- Si el valor es 9999 o “right” la ventana de firma se coloca a la derecha en pantalla.
- Si el valor es 0 o “left” la ventana de firma se coloca a la izquierda en pantalla.
- Cualquier otro valor significa posición absoluta de la ventana de firma establecida por el usuario.
Para la coordenada Y:
- Si el valor es 9999 o “bottom” la ventana de firma se coloca en la parte inferior en pantalla.
- Si el valor es 0 o “top” la ventana de firma se coloca en la parte superior en pantalla.
- Cualquier otro valor significa posición absoluta de la ventana de firma establecida por el usuario.

IMPORTANTE: Los parámetros de dimensión de la ventana de firma “jwsWidth” y “jwsHeight” presentan valores por defecto, que dependen del tipo de dispositivo de captura biométrica seleccionado:

Para STU-430: 640 x 400 (typeTablet=1).
Para STU-530, DTU y Stylus: 800 x 480 (typeTablet=0 ó 2).

IMPORTANTE: El valor decimal del carácter para los eventos de teclado puede obtenerse en www.asciitable.com.

Ventana “Controller”

Estos parámetros controlan la aparición de una segunda ventana copia de la de captura de firma para en casos multimonitor (como las DTU) para que tanto el firmante como el controlador de la firma puedan ver y operar sobre el funcionamiento y/o aceptación de la firma:

*Param Name*	*Valor*	*Valor por defecto*	*Comportamiento*
jwsControllerEnable	Booleano	0	Activa o desactiva la ventana “controller”.
jwsControllerShowBorderClose	Booleano	1	Si está activo mostrará la ventana controller con estilo “diálogo” (bordes + cruz para cerrar/cancelar ventana), sino será una ventana sin bordes.
jwsControllerCaption	String		Título de la ventana controller. Solo aplica si jwsControllerShowBorderClose=1.
jwsControllerWidth	Entero		Anchura en píxeles de la ventana de la ventana controller.
jwsControllerHeight	Entero		Altura en píxeles de la ventana de la ventana controller.
jwsControllerTxtBtnReset	String	Reiniciar	Texto en el botón de reinicio de la ventana controller.
jwsControllerTxtBtnCancel	String	Cancelar	Texto en el botón de cancelación de la ventana controller.
jwsControllerTxtBtnSign	String	Firmar	Texto en el botón de firma de la ventana controller.
jwsControllerBtnReset	Booleano	1	Visibilidad de botón de reinicio de la ventana controller.
jwsControllerBtnCancel	Booleano	1	Visibilidad de botón de cancelación de la ventana controller.
jwsControllerBtnSign	Booleano	1	Visibilidad de botón de firma de la ventana controller.
jwsControllerBtnResetImage	String		Imagen en botón de reinicio de la ventana controller .
jwsControllerBtnResetImageRollover	String		Imagen en botón de reinicio de la ventana controller (mouse over).
jwsControllerBtnCancelImage	String		Imagen en botón de cancelación de la ventana controller.
jwsControllerBtnCancelImageRollover	String		Imagen en botón de cancelación de la ventana controller (mouse over).
jwsControllerBtnSignImage	String		Imagen en botón de firma de la ventana controller.
jwsControllerBtnSignImageRollover	String		Imagen en botón de firma de la ventana controller (mouse over).
jwsControllerComment	Boolean	0	Activación de comentarios de la ventana controller.
jwsControllerTxtLblComment	String	Comentario de la firma:	Label de comentarios para la ventana controller.
jwsControllerTxtComment	String		Posibles comentarios para la ventana controller predefinidos separados por “;”.
jwsControllerStayOnTop	Boolean	0	Si se activa(1) la ventana controller estará siempre visible en pantalla.
jwsControllerPosX	Entero	Centrado	Coordenada X de inicio de la ventana controller en pantalla.
jwsControllerPosY	Entero	Centrado	Coordenada Y de inicio de la ventana controller en pantalla.

IMPORTANTE: Los parámetros de posicionamiento de la ventana controller de firma “jwsControllerPoxX” y “jwsControllerPosY” presentan el siguiente comportamiento:

Para ambas coordenadas si el valor es -1 o “center” se centra la ventana controller de firma en pantalla.
Para la coordenada X:
- Si el valor es 9999 o “right” la ventana controller de firma se coloca a la derecha en pantalla.
- Si el valor es 0 o “left” la ventana controller de firma se coloca a la izquierda en pantalla.
- Cualquier otro valor significa posición absoluta de la ventana controller de firma establecida por el usuario.
Para la coordenada Y:
- Si el valor es 9999 o “bottom” la ventana de firma controller se coloca en la parte inferior en pantalla.
- Si el valor es 0 o “top” la ventana controller de firma se coloca en la parte superior en pantalla.
- Cualquier otro valor significa posición absoluta de la ventana controller de firma establecida por el usuario.

IMPORTANTE: Los parámetros de dimensión de la ventana de firma “jwsControllerWidth” y “jwsControllerHeight” presentan valores por defecto, que dependen del tipo de dispositivo de captura biométrica seleccionado:

Para STU-430: 640 x 400 (typeTablet=1).
Para STU-530, DTU y Stylus: 800 x 480 (typeTablet=0 ó 2).

Descarga y ejecución en local del documento firmado

A continuación se describen los parámetros relacionados con la descarga y ejecución en local del documento firmado:

*Param Name*	*Valor*	*Valor por defecto*	*Comportamiento*
saveInLocal	Booleano	0	Guarda el documento pdf firmado en local.
saveInLocalPath	String		Ruta donde se guarda en local el documento pdf firmado. Solo aplica si saveInLocal=1.
saveInLocalName	String	JWS_PDF_Signed.pdf	Nombre (incluyendo la extensión .pdf) para el fichero que se va a generar/guardar en local. Solo aplica si saveInLocal=1.
executeInLocal	Booleano	0	Ejecuta o no el documento pdf con la aplicación que esté asociada para ello. Solo aplica si saveInLocal=1.

Descarga de JPG del grafo en local del documento firmado

A continuación se describen los parámetros relacionados con la descarga de JPG del grafo en local del documento firmado:

*Param Name*	*Valor*	*Valor por defecto*	*Comportamiento*
saveImgInLocal	Booleano	0	Guarda el JPG del grafo del documento pdf firmado en local.
saveImgInLocalPath	String		Ruta donde se guarda en local el JPG del grafo del documento pdf firmado. Solo aplica si saveImgInLocal=1.
saveImgInLocalName	String	JWS_Img_Signature.jpg	Nombre (incluyendo la extensión .jpg) para el fichero que se va a generar/guardar en local. Solo aplica si saveImgInLocal=1.

Parámetros criptográficos

A continuación se describen parámetros para que los datos biométricos de la firma vayan cifrados desde la STU.

*Param Name*	*Valor*	*Valor por defecto*	*Comportamiento*
useSTUEncryption	Booleano	0	Si se activa, se usará la encriptación directa con el dispositivo de captura de firma STU de forma que nadie puede interceptar la comunicación entre el dispositivo y JWS. Tabletas soportadas: STU520, STU530, STU540 y STU430.
useSTUEncryption_ContinueUnencryptedIfNotAvailable	Booleano	1	En conjunción con useSTUEncryption, si está activado y no es posible el cifrado (desactivado en la tableta o cualquier otro problema), si éste valor está a 1 se seguirá la carga de JWS, si está a 0 se mostrará un error y se parará la carga de JWS.

Otros parámetros

A continuación se describen otros parámetros que pueden ser relevantes.

*Param Name*	*Valor*	*Valor por defecto*	*Comportamiento*
checkInstances	Booleano	1	Detectar múltiples instancias del JWS. No deben existir varias instancias simultáneas del JWS, con este check si se encuentra una instancia previa del JWS la instancia que está comenzando a iniciarse es automáticamente parada y terminada.
disabledWMI	Booleano	0	Permite desactivar WMI, WMI consigue información del hardware del equipo firmante que incrusta en la firma. Puede desactivar la incrustación de datos WMI con disabledWMI=1.
StylusSleep	Entero	10	milisegundos usando Stylus para el procesado de puntos. NO DEBIERA SER CAMBIADO.
max_pen	Entero	5	Ancho de la línea del grafo para la presión máxima en píxeles.
time_new_t	Entero	100	Milisegundos para detectar un nuevo trazo. NO DEBIERA SER CAMBIADO.
forceCloseJava	booleano	0	Si está activado (=1) fuerza al terminar el JWS la salida de Java, previene problemas en determinados escenarios en los que la máquina virtual de Java se queda colgada
license	String		OBLIGATORIO. Licencia necesaria para el correcto funcionamiento de JWS. Le será suministrada por su proveedor.
ess-log-file	String		Ruta del log.
enablePDFEmptySig	Booleano	0	Si un PDF contiene firmas vacías preexistentes, estampar la firma en ese campo
fieldnamePDFEmptySig	String		Si está activo enablePDFEmptySig, campo de firma en el que estampar la firma, si se pone vacío, se usará el primer campo vacío existente

Citrix (solo Windows)

El JWS permite su uso a través de citrix de dispositivos de recogida de firma. STU y Stylus soportados a través de canales virtuales en el ICA Client (debe instalar el .msi que le proporcionará edatalia en los clientes previamente)

*Param Name*	*Valor*	*Valor por defecto*	*Comportamiento*
useCitrixVC	Booleano	0	Activar o no el uso de canales virtuales. Si no está en un entorno Citrix no active esta opción.
CitrixVCSleep	Entero	10	milisegundos usando Citrix para el procesado de puntos. NO DEBIERA SER CAMBIADO.
CitrixVCSleepClear	Entero	1000	milisegundos usando Citrix para espera a limpiado de pantalla. NO DEBIERA SER CAMBIADO.
CitrixVCsWnd	Entero	0	Usando Citrix + Stylus, tipo de ventana de captura de firma creada en el cliente. Disponibles tipos 0,1,2,3.
CitrixVCsWnd3X	Entero	0	Si CitrixVCsWnd=3, X de la ventana de captura de firma.
CitrixVCsWnd3Y	Entero	0	Si CitrixVCsWnd=3, Y de la ventana de captura de firma.
CitrixVCsWnd3Width	Entero	0	Si CitrixVCsWnd=3, Ancho de la ventana de captura de firma.
CitrixVCsWnd3Height	Entero	0	Si CitrixVCsWnd=3, Alto de la ventana de captura de firma.

Parámetros mínimos de configuración

El firmado con ecoSignature JWS necesita la configuración mínima de una serie de parámetros para la realización de un proceso de firmado inicial y básico:

Licencia parámetro ‘license’.
Paso del documento PDF a firmar seleccionado:
- por url parámetro ‘remotePdf-url’.
- en Base64 parámetro ‘Pdf-Content’.
Parámetros relacionados con la firma ’author’, ’reason’, ’contact’ y ‘location’.
Tipo de tableta parámetro ‘typeTablet’.
Modo de firma con o sin biometría parámetro ‘jsigMode’.
Tipo de intermediario seleccionado parámetro ‘jwsType’:
- si jwsType=0 parámetro ‘WebServiceJWS’.
- si jwsType=1 parámetro ‘WebSocketJWS’.
Tamaño de widget parámetros ‘widget-Ancho’ y ‘widget-Alto’.
Tipo de posicionamiento seleccionado parámetro ‘widget-autoPos-activate’.
- si widget-autoPos-activate=0 parámetros ‘widget-Page’, ‘widget-X’ y ‘widget-Y’. (Posicionamiento fijo).
- si widget-autoPos-activate=1 parámetros ‘widget-autoPos-text’, ‘widget-autoPos-desfaseX’ y ‘widget-autoPos-desfaseY’.

(Posicionamiento por texto).

Texto personalizado parámetro ‘widget-Textcustom’.
Uso de EBP’s parámetros ‘ebp-activate’, ‘showEBP’, ‘ebp-use-internal’, ‘ebp-url’ y ‘ebp-variables’.
Parámetros relacionados con la ventana de firmado en el PC parámetros ‘jwsWidth’, ‘jwsHeight’, ‘jwsStayOnTop’, ‘jwsPosX’ y ‘jwsPosY’.
Devolución del documento pdf firmado seleccionada:
- vía POST parámetros ‘result-url’, ‘extraParamPost’ y ‘result-formName-signedPdf’.

en Base64 parámetros ‘jwsWebSocketSendPDFB64’ y ‘jwsWebSocketSendPDFB64_ChunkSize’. (Solamente con jwsType=1).

Resolución de errores

Ante un problema con la solución JWS, compruebe primero que el HTML que carga el JWS está bien construido y no hay errores de Javascript.

A continuación, active la consola de Java, vaya al panel de configuración de Java (https://www.java.com/en/download/help/win_controlpanel.xml) y en la pestaña Avanzado active los checks de “Activar Rastreo”, “Activar Registro”, “Mostrar excepciones del ciclo de vida del applet” y “Ver consola” como en la siguiente imagen:

Ante cualquier error, se muestra una traza tanto en la consola de Java, como se generan ficheros de traza por defecto en:

para Windows: C:\Users\[Usuario]\AppData\LocalLow\Sun\Java\Deployment\log
para Linux: /home/[Usuario]/.java/deployment/log

En esa traza podría identificar los siguientes eventos:

Started… version_date: XXX Es la primera instrucción del JWS, hasta que ocurra ésta línea el JWS aún no estará en ejecución. Java previamente al lanzado del JWS hace comprobaciones de seguridad al JWS entre otras cosas. Si ocurre un error previamente a ésta línea compruebe con su equipo de sistemas la seguridad de Java y los certificados de seguridad de Java. Es muy importante el XXX cuando comunique con soporte un problema para que sepamos si existe una actualización disponible.
Start signature result: 0 Se ha terminado de configurar el dispositivo que se hubiera seleccionado y el sistema está esperando para recoger la firma biométrica
Response message: OK (la firma ha sido exitosa) y se ha dejado el PDF correctamente al POST que ha respondido OK
Exiting… El JWS ha finalizado completamente

En caso de error, se puede ver por ejemplo:

…

Error EcoBioSign* ess. code: -66701. API Exception: “PDFSignM”: Signing failed: Invalid PDF File

ESS.d: Error signing pdf. code: -66701

at ecobiometric.logic.d.a(Unknown Source)

at ecobiometric.services.PublicAPI.finishSignaturePdfInternal(Unknown Source)

at ecobiometric.services.PublicAPI.aceptSignaturePdfInternal(Unknown Source)

at ecobiometric.services.PublicAPI.access$2000(Unknown Source)

at ecobiometric.services.d.call(Unknown Source)

at java.util.concurrent.FutureTask.run(Unknown Source)

at java.util.concurrent.ThreadPoolExecutor.runWorker(Unknown Source)

at java.util.concurrent.ThreadPoolExecutor$Worker.run(Unknown Source)

at java.lang.Thread.run(Unknown Source)

…

Comunicándonos los parámetros que ha usado y/o ficheros de entrada y ésta traza podremos resolver el problema.

*Categoría:* Errores en ESS
-1	Error general. Revise su licencia y ficheros de entrada. La traza debiera dar más información
-2	Revise su licencia
-66601	Error al cargar certificado para cifrar datos biométricos.
-66602	Error al cifrar datos biométricos.
-66603	Error al cargar datos biométricos cifrados en el API.
-66610	Error al añadir certificado firmador de PFX, no se ha encontrado, la contraseña no coincide.
-66611	Error al añadir certificado firmador de PFX, no hay llave privada disponible.
-66612	Se ha especificado validar el certificado firmante y éste no es válido por el motivo que sea, ocsp, expirado, etc…
-66600	Error al cargar la imagen jpeg en memoria.
-66700+X	Error al FIRMAR EL PDF. No ha servido para nada, no se ha generado fichero. Res es un valor negativo también, es el resultado de llamar a la función de firmar un pdf, así que por ejemplo puede dar un -66701 que sería error general al firmar el pdf.