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:

  1. Importar al workspace el archivo ecoSignatureJWS.zip

File Import General Proyecto existente en workspace Next Seleccionar archivo.

  1. 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).
  2. 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.
  3. En la pestaña de Servers, añadir un nuevo servidor Apache Tomcat v7.0, añadir el proyecto ecoSignatureJWS.
  4. Lanzar el servidor.
  5. 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.

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.

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

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.

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

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.

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

  1. 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óncreateUrlView()” en “tools.js Acceso al visor.
  2. 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.
  3. 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.
  4. 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.
  5. Visualmente, aparece la ventana de espera de firma y la ventana de firma (se muestran los eventos de la firma).
  6. Introducimos la firma y aceptamos.
  7. 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

  1. Invocamos a la función “openSignatureAsPDFJWS()” que lanza la firma (normalmente dispondremos de un botón en la página).
  2. Visualmente, aparece la ventana de espera de firma y la ventana de firma (se muestran los eventos de la firma).
  3. Introducimos la firma y aceptamos.
  4. 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:

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

 

  1. Configuración de los parámetros JNLP de configuración de firma según necesidades.
  2. 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().
  1. 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 NameValorValor por defectoComportamiento
Pdf-ContentPDF en B64 El PDF a firmar en B64.
remotePdf-urltest.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-urlresults.php Nombre del parámetro que recibirá la imagen en formato binario.
result-formName-signatureImageimgSignature Nombre de la imagen en formato PNG.
result-formName-signedPdffileSigned Nombre del PDF resultante ya firmado.
result-FormName-SignatureEVSString 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_encKeyB64String 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_pfxB64String 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_pfxUrlString 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_pfxPwString Contraseña en B64 si se usa un PFX diferente al embebido de edatalia.
resizeSignaturePngbooleano0Activa la reducción de tamaño, cuando se quiere guardar la imagen PNG.
resizeSignaturePngWidthFactor0.1 a 11 (100%)0.5 reduce el PNG al 50%.
resizeSignaturePngheightFactor0.1 a 11 (100%)0.5 reduce el PNG al 50%.
extraParamPostString Contenido extra que se dejará en la URL del POST como parámetro “extraParamPost”.
widget-TextcustomString Texto custom del widget en B64.
authorString Autor de la firma (propiedad de un pdf firmado).
reasonString Razón de la firma (propiedad de un pdf firmado).
contactString Info de contacto de la firma (propiedad de un pdf firmado).
locationString Info de localización de la firma (propiedad de un pdf firmado).
pdfPasswordString 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 NameValorValor por defectoComportamiento
cert-originBooleano0Si 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-b64Base64 del contenido del PFXPermite 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-pwEn Base64Password para activar el certificado.
Chain-CA-b64En Base64 Cadena de validación completa del certificado.
enc-key-b64Base64 del contenido del .cer Clave pública del cert de encriptación(el cifrado no requiere pss).
certificatePDFBooleano Firma PDF Certificada (MDP).
TIME STAMPSellado de tiempo en el momento de la firma
tsp-activateBooleano0Si se activa (1) activa la consulta TSP.
tsp-url   
tsp-user   
tsp-password   
OCSPValidación del estado de revocación del certificado en el momento de la firma
ocsp-activateBooleano0Si se activa (1) activa la consulta OCSP.
ocsp-url   
ocsp-user   
ocsp-password   
setValidateErrorContinueBooleano0Si se activa (1) la firma no se para aunque haya un error de validación OCSP.
bufferLTVEntero0Tamañ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 NameValorValor por defectoComportamiento
Ubicación fija del área de firmaEl JWS ubica la firma en una página y coordenadas determinadas
widget-PageEntero10: 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-XEntero0Desplazamiento del widget en horizontal, desde el vértice inferior izquierdo del PDF.
widget-YEntero0Desplazamiento 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-activateBooleano1Widget transparente o no.
Ubicación relativa a cadena de caracteresEl JWS busca una frase en el documento y ubica la firma en relación al primer carácter. Por ejemplo “Firmado por:”
widget-autoPos-activateBooleano0Si se activa (1) el JWS buscará una cadena de caracteres para ubicar la firma.
widget-autoPos-textTexto Texto a buscar. La firma se ubicará de forma relativa al primer carácter.Por ejemplo “Firmado por:”.
widget-autoPos-desfaseXEntero0Desplazamiento relativo en horizontal.
widget-autoPos-desfaseYEntero0Desplazamiento en vertical.
Tamaño del área de firmaAtenció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-AnchoEntero120Ancho del widget.
widget-AltoEntero30Alto 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 NameValorValor por defectoComportamiento
Modo mouseNos 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.
mouseModeBooleano0Si se activa, la firma se recoge desde el monitor del dispositivo.No requiere tableta de firma (Wacom/Stylus).
mouseSpeedBooleano0Permite configurar la presión relativa a la velocidad.
typeTabletEntero0Tipo 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_PointsEntero100Mí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-timeEntero60Segundos por defecto máximo para aceptación de la firma (recomendable no cambiarlo).
Empleo de plantillas EBPLas plantillas EBP permiten definir la visualización de la tableta
ebp-activateEntero1Activa el uso de plantilla.
ebp-use-internalBooleano0Utiliza el EBP embebido en el JWS.
ebp-url  si ebp-use-internal está a 0, url de donde se coge el EBP.
showEBPBooleano11: Muestra al operador, en la pantalla del PC, lo que se está visualizando en la tableta Wacom.
noButtonEBPBooleano0si 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-variablesString 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).
STUBackLightEntero-1Solo para dispositivos Wacom STU.0 (mínima intensidad) a 3 (máxima intensidad).Valor por defecto -1 (no cambia el brillo).
driver430InstalledBooleano1Pará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-activateBooleano0Activar 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-urlString 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-variablesString 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 NameValorValor por defectoComportamiento
jsigModeBooleano0Si se activa (1), sólo se realiza firma usando el certificado digital, desactivado (0) se usa la firma biométrica.
jsigJPGJPEG 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 NameValorValor por defectoComportamiento
jwsTypeEntero0Permite configurar el tipo de comunicación:0: WebService SOAP.1: WebSocket.
WebSocketJWSString URL del WebSocket.
WebServiceJWSString URL del WebService SOAP.
jwsWidthEntero800Anchura en píxeles de la ventana de la aplicación.
jwsHeightEntero650Altura en píxeles de la ventana de la aplicación.
jwsTxtBtnResetString Texto en el botón de reinicio de la aplicación.
jwsTxtBtnCancelString Texto en el botón de cancelación de la aplicación.
jwsTxtBtnSgnString Texto en el botón de firma de la aplicación.
jwsBtnResetBooleano1Visibilidad de botón de reinicio de la aplicación.
jwsBtnCancelBooleano1Visibilidad de botón de cancelación de la aplicación.
jwsBtnSgnBooleano1Visibilidad de botón de firma de la aplicación.
jwsBtnResetImageString Imagen en botón de reinicio de aplicación.
jwsBtnResetImageRolloverString Imagen en botón de reinicio de aplicación (mouse over).
jwsBtnCancelImageString Imagen en botón de cancelación de la aplicación.
jwsBtnCancelImageRolloverString Imagen en botón de cancelación de la aplicación (mouse over).
jwsBtnSignImageString Imagen en botón de firma de la aplicación.
jwsBtnSignImageRolloverString Imagen en botón de firma de la aplicación (mouse over).
jwsCommentBoolean0Activación de comentarios de la aplicación.
jwsTxtLblCommentString Label de comentarios.
jwsTxtCommentString Posibles comentarios predefinidos separados por “;”.
jwsStayOnTopBoolean0Si se activa(1) JWS estará siempre visible en pantalla.
jwsPosXEnteroCentradoCoordenada X de inicio de la aplicación en pantalla.
jwsPosYEnteroCentradoCoordenada Y de inicio de la aplicación en pantalla.
jwsWebSocketSendPDFB64Booleano0Envío de PDF firmado en Base64 al websocket.
jwsWebSocketSendPDFB64_ChunkSizeEntero16384Tamaño máximo de los chunks o bloques de datos a enviar con el PDF en Base64 resultante.
jwsForzarNumMonitorEntero0Número de monitor donde se muestra el JWS.
jwsShowBorderCloseBooleano1Si 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 tecladoCTRL+carácter
jwsKeyboardAcceptEntero65 (=A)Evento de teclado en botón de aceptar firma. CTRL+carácter, donde caracter es el valor en decimal del ASCII (carácter).
jwsKeyboardCancelEntero67 (=C)Evento de teclado en botón de aceptar firma. CTRL+carácter, donde caracter es el valor en decimal del ASCII (carácter).
jwsKeyboardResetEntero82 (=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 NameValorValor por defectoComportamiento
jwsControllerEnableBooleano0Activa o desactiva la ventana “controller”.
jwsControllerShowBorderCloseBooleano1Si está activo mostrará la ventana controller con estilo “diálogo” (bordes + cruz para cerrar/cancelar ventana), sino será una ventana sin bordes.
jwsControllerCaptionString Título de la ventana controller. Solo aplica si jwsControllerShowBorderClose=1.
jwsControllerWidthEntero Anchura en píxeles de la ventana de la ventana controller.
jwsControllerHeightEntero Altura en píxeles de la ventana de la ventana controller.
jwsControllerTxtBtnResetStringReiniciarTexto en el botón de reinicio de la ventana controller.
jwsControllerTxtBtnCancelStringCancelarTexto en el botón de cancelación de la ventana controller.
jwsControllerTxtBtnSignStringFirmarTexto en el botón de firma de la ventana controller.
jwsControllerBtnResetBooleano1Visibilidad de botón de reinicio de la ventana controller.
jwsControllerBtnCancelBooleano1Visibilidad de botón de cancelación de la ventana controller.
jwsControllerBtnSignBooleano1Visibilidad de botón de firma de la ventana controller.
jwsControllerBtnResetImageString Imagen en botón de reinicio de la ventana controller .
jwsControllerBtnResetImageRolloverString Imagen en botón de reinicio de la ventana controller (mouse over).
jwsControllerBtnCancelImageString Imagen en botón de cancelación de la ventana controller.
jwsControllerBtnCancelImageRolloverString Imagen en botón de cancelación de la ventana controller (mouse over).
jwsControllerBtnSignImageString Imagen en botón de firma de la ventana controller.
jwsControllerBtnSignImageRolloverString Imagen en botón de firma de la ventana controller (mouse over).
jwsControllerCommentBoolean0Activación de comentarios de la ventana controller.
jwsControllerTxtLblCommentStringComentario de la firma: Label de comentarios para la ventana controller.
jwsControllerTxtCommentString Posibles comentarios para la ventana controller predefinidos separados por “;”.
jwsControllerStayOnTopBoolean0Si se activa(1) la ventana controller estará siempre visible en pantalla.
jwsControllerPosXEnteroCentradoCoordenada X de inicio de la ventana controller en pantalla.
jwsControllerPosYEnteroCentradoCoordenada 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 NameValorValor por defectoComportamiento

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

Booleano0Ejecuta 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 NameValorValor por defectoComportamiento
useSTUEncryptionBooleano0Si 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_ContinueUnencryptedIfNotAvailableBooleano1En 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.

enablePDFEmptySigBooleano0Si un PDF contiene firmas vacías preexistentes, estampar la firma en ese campo
fieldnamePDFEmptySigString 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 NameValorValor por defectoComportamiento
useCitrixVCBooleano0Activar 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

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

  • Share: