Sobre este documento
Este documento tiene el objetivo de mostrar el caso de uso desarrollado por edatalia para el lanzamiento exterior de la solución ecoSignature Java Web Start (JWS de ahora en adelante) Desktop desde una aplicación tercera, mostrando la configuración de los posibles parámetros con los que podemos invocar a la aplicación y la construcción del fichero de configuración de parámetros pasado en la llamada a la solución, para la realización del firmado. Así como la obtención de las salidas del proceso.
Introducción
Requerimientos
Los requisitos mínimos del funcionamiento de ecoSignature JWS son:
puesto cliente: PC de eFirma
Dispositivos hardware para captura biométrica: Wacom STU (430, 520, 530), Wacom DTU (1031, 1141) y Pencil-Stylus.
Puesto PC:
Sistema operativo Windows 7 o superior.
Sistema operativo Linux Ubuntu 14.04 32 ó 64 bits o superior. (Recomendable 16.04+ 64 bits).
Java 1.7+.
Para el correcto funcionamiento del caso de uso, para tabletas STU y DTU por favor consultar el siguiente enlace. Para poder descargarse el caso de uso, por favor acceda a la página de descarga.
Nota
Se debe estar familiarizado con la solución ecoSignature JWS Desktop y estar desplegada en el PC local
Instalación en Pc local del caso de uso
SO Windows
Para la instalación del caso de uso de la solución ecoSignature JWS Desktop en un entorno Windows se deben realizar los siguientes pasos:
- Descomprimir archivo entregado (caso de uso comprimido en zip).
- Copiar los dos archivos en una nueva carpeta, en la ruta que se desee.
Ejecutar el archivo ecoSignatureJWS_Desktop_Caso_De_Uso.exe.
SO Linux
Para la instalación del caso de uso de la solución ecoSignature JWS Desktop en un entorno Linux se deben realizar los siguientes pasos:
- Descomprimir archivo entregado (caso de uso comprimido en tar.gz).
- Copiar los dos archivos en una nueva carpeta, en la ruta que se desee.
- Ejecutar el archivo ecoSignatureJWS_Desktop_Caso_De_Uso.jar.
IMPORTANTE: Se debe tener desplegada la solución ecoSignature JWS Desktop en el PC local.
Nota
Si se han copiado los dos archivos en la carpeta donde tenemos desplegada la solución ecoSignature JWS Desktop no hay problemas a la hora de realizar un proceso de firmado. En caso contrario aparece la siguiente ventana de error:
Linux
Para su solución configure el parámetro “path-ecoSignatureJWS-Desktop”. (Ver apartado Personalización del caso de uso).
Nota
En Linux el mensaje de error es equivalente, pero en vez de no encontrarse el .exe de lanzamiento, no se encuentra el .jar de lanzamiento.
Nota
Se observa en el archivo zip entregado la existencia de un nuevo archivo zip que contiene el código de desarrollo del caso de uso en tecnología Java para ser importado como proyecto y desplegado en un entorno de desarrollo como ECLIPSE.
Caso de uso: ecoSignature JWS
En el caso de uso se puede observar que disponemos de siete bloques definidos, uno para la selección del documento pdf de ejemplo para firmar, cuatro para configuración de parámetros de firma, uno para visualización en pantalla de la solución de firma y otro para la selección de otras opciones.
Nota
Para que el caso de uso funcione correctamente se recomienda que el archivo de configuración ecoSignatureJWS.ini perteneciente a la solución ecoSignature JWS Desktop no presente ninguna parametrización hasta que se coja soltura con la solución o se elimine de la carpeta correspondiente.
Nota
Para la correcta visualización del caso de uso se recomienda en Linux instalar las fuentes de Windows. sudo apt-get install msttcorefonts sudo fc-cache -fv
A continuación, se describe el contenido y la funcionalidad de los diferentes parámetros que podemos configurar:
1. Selección de documento PDF de ejemplo para firmar:
Seleccionar documento:
Selección de documento a firmar.
PDF en Base 64:
Nos da la posibilidad de trabajar internamente, en el proceso de firma, con el documento seleccionado en base 64.
Nota: Por defecto, inicialmente el caso de uso nos selecciona el documento a firmar presente en la ruta “C:/ecoSignatureJWS/ecoSignatureJWS.pdf” (Windows).
2. Selección del tipo de firmado:
Firma digital manuscrita:
El documento se firma con biometría.
Firma digital:
El documento se firma con un certificado electrónico, sin captura de rúbrica.
Nota: En la firma digital (sin biometría) por defecto, se puede observar la aparición de una imagen de fondo desarrollada por edatalia incrustada en la firma.
Por defecto la firma se realiza mediante un certificado embebido en el propio JWS.
Dependiendo del tipo de firmado seleccionado, se presentan unas opciones u otras habilitadas/deshabilitadas para el resto de parámetros de configuración.
3. Opciones de visualización en dispositivos de captura biométrica:
Selección de dispositivo de captura biométrica:
Seleccionamos el tipo de dispositivo con el que vamos a realizar la firma biométrica (nos encontramos con los siguientes valores de STU-Color (STU-530 y STU-520), STU-B/N (STU-430), Stylus y Pantalla táctil (firma con ratón)).
En Linux la opción de dispositivo de captura biométrica Stylus no se encuentra.
Mostrar botones en dispositivo USB de captura biométrica:
Si está chequeado nos aparecerán los botones en el dispositivo USB de captura biométrica. Para estar esta opción habilitada debemos haber seleccionado anteriormente un dispositivo de captura biométrica físico.
Variables a mostrar en la tableta:
La visualización en la tableta se gestiona por medio de plantillas EBP que pueden contener imágenes, textos y botones (veáse documentación correspondiente a la gestión de plantillas EBP).
Para el caso de uso se presentan varias plantillas EBP, dependiendo del tipo de dispositivo de captura biométrico seleccionado.
En este caso de uso, las plantillas engloban las variables Título, Subtítulo, Nombre, ÁreaFirma y LOPD.
Pantalla de aceptación de cláusula anterior a la firma:
Si está chequeado se activa el uso de una pantalla inicial, es decir, se trata de una pantalla que puede mostrar un texto previo a la pantalla donde se recoge la firma, este texto es configurable.
Anchura del lápiz en píxeles para la presión máxima:
Selección de la anchura de la línea del grafo para la presión máxima en píxeles.
Mostrar plantilla EBP en el PC:
Si está chequeado muestra al operador en la pantalla del PC, lo que se está visualizando en la tableta.
4. Opciones de descarga y ejecución en local del documento PDF firmado:
Selección de descarga:
Nos da la opción de si queremos la descarga en local del documento pdf firmado. Se permite la introducción de una ruta local de descarga.
Nota: Se debe tener en cuenta en la introducción de la ruta:
Si se deja vacía, se descarga el documento en temporales.
Si la ruta es inexistente, mal formada, no accesible, se descarga en temporales.
La ruta debe existir, se usan caracteres “/” en vez de “\”. Ejemplo: “C:/Temp/”.
El componente de introducción de ruta solamente está habilitado si se ha seleccionado la descarga del documento pdf firmado.
Nota: Inicialmente el caso de uso descarga el documento firmado en la ruta “C:/ecoSignatureJWS/Firmados/” (Windows).
Selección de abrir documento firmado:
Si se habilita la opción se permite la ejecución del documento pdf firmado con la aplicación que esté asociada para ello.
Nota: Está habilitada si se ha seleccionado la descarga del documento pdf firmado.
Está deshabilitada siempre si se ha seleccionado la opción de ver el documento firmado.
5. Opciones de configuración de firma digital:
Selección de usar certificado del almacén de windows:
Si se habilita la opción se permite firmar con un certificado del almacén de windows que dispongamos.
En Linux esta opción se encuentra deshabilitada.
Selección de certificar el PDF:
Nos da la opción de si queremos la certificación de la firma del pdf o no.
La firma certificada no permite volver a firmar el documento.
La firma certificada es un estándar de adobe que presenta características especiales.
Dimensiones de la firma (Widget):
Definición de la anchura y de la altura de la firma en el documento pdf. Se recomienda un ratio igual al área de la firma que se presente en las plantillas EBP (en el caso de uso se utiliza un ratio 4:1).
Posicionamiento de la firma:
Se presentan tres tipos de posicionamiento a seleccionar:
Posicionamiento manual:
La ventana de firma inicialmente se posiciona en el centro de la página del documento pdf seleccionada.
El usuario puede mover/trasladar y redimensionar la ventana de firma por la página del documento pdf.
Nota: Está habilitada cuando se visualice el documento a firmar.
Posicionamiento fijo:
Definición de posición de coordenadas X e Y fija y del número de página de la firma en el documento pdf, cuando sabemos el lugar concreto en el que queremos que se firme.
Un documento PDF DINA4 tiene una altura aproximada de 842 píxeles.
Posicionamiento flotante:
Indicamos que nos busque en el documento pdf la cadena de caracteres que a continuación le definiremos para poder situar la firma en una determinada posición respecto a la cadena de caracteres del pdf en la que queremos situar la firma.
El desfase indica el número entero de unidades de desfase (positivo o negativo) en el eje X e Y desde el vértice inferior izquierdo de la página, no confundir con píxeles.
6. Dimensiones de la pantalla de controlador en píxeles:
Selección de anchura y altura de la ventana de la aplicación ecoSignature JWS.
7. Otras opciones:
Ver documento a firmar:
Si está chequeado se muestra el documento antes de firmar.
Ver documento firmado:
Si está chequeado se muestra el documento antes de firmado.
Pantalla completa:
Si está chequeado se visualiza el documento a firmar o firmado a pantalla completa.
Nota: Está habilitada cuando se visualice el documento a firmar o firmado.
Ver ventana de eventos:
Si está chequeado muestra la ventana de espera de firma o de eventos a la hora de realizar el firmado.
Mostrar alertas:
Si está chequeado muestra las alertas de ecoSignature JWS Desktop.
Activar Virtual Channel Citrix.
En Linux la activación de Virtual Channel Citrix está deshabilitado.
8. Salida de ecoSignature JWS Desktop:
Muestra en dos campos el código de salida y la información asociada a dicho código de la ejecución por lanzamiento externo de la solución ecoSignature JWS Desktop.
La solución ecoSignature JWS Desktop devuelve una serie de códigos de respuesta a la llamada externa de la aplicación. Estos códigos están definidos en el Apartado Códigos de salida del manual.
En la parte inferior de la ventana de configuración de parámetros se muestran los botones que nos permiten realizar diferentes acciones:
Botón “Reset”:
Inicializa a valores por defecto los valores de los parámetros de configuración.
Botón “Firmar”:
Lanza el proceso de firma con los parámetros de configuración seleccionados, invocando a la solución ecoSignature JWS Desktop.
Una vez que es lanzada la firma, nos aparece la ventana de espera de firmado (si previamente se ha configurado) y la ventana de introducción de firma de la aplicación ecoSignature JWS (para firma digital manuscrita), ésta última puede mostrarse en diferentes tamaños/formatos dependiendo de los parámetros de configuración seleccionados anteriormente.
En la imagen, se muestra la ventana de espera, que permanece activa mientras se realiza el proceso de firmado.
La ventana de espera de firmado muestra los eventos de firmado recibidos por parte de la aplicación ecoSignature JWS, es decir, el estado en el que se encuentra el proceso de firma en todo momento. Estos eventos son observados en el bloque de “Eventos recibidos”.
En la siguiente imagen podemos observar la ventana de introducción de firma de la aplicación:
En la ventana de introducción de firma se pueden realizar las siguientes operaciones:
Reiniciar: reinicio de la firma.
Cancelar: cancelación de la firma.
Firmar: firma del documento.
Una vez realizada la firma se puede observar el documento pdf firmado en la ubicación seleccionada como descarga. Además se puede visualizar el documento pdf firmado de dos maneras:
Si se ha activado la opción de “Ver documento firmado”, se abre el documento pdf firmado con el visualizador de la solución.
Si se ha activado la opción de “Abrir documento firmado”, se abre el documento con la con la aplicación asociada para ello (Adobe Acrobat Reader, Foxit Reader,…).
Nota: Este último parámetro es deshabilitado si se ha activado el anterior parámetro.
Nota: Para un firma electrónica se observa la incrustación de una imagen de fondo.
Nota
Este último parámetro es deshabilitado si se ha activado el anterior parámetro.
Nota
Para un firma electrónica se observa la incrustación de una imagen de fondo.
Personalización del caso de uso
Para la personalización del caso de uso se dispone del fichero “personalizacion.ini” donde se pueden configurar los siguientes parámetros relacionados con la inicialización del caso de uso:
Path de ecoSignature JWS Desktop (path-ecoSignatureJWS-Desktop (Cadena de texto))
Path del fichero que aparece en la selección de documento (filePath (Cadena de texto))
Trabajar con el documento en base 64 (pdfBase64 (Booleano)).
Tipo de firmado (typeSigned (Entero)).
Tipo de tableta (typeTablet (Entero)).
Activación de botones en dispositivo USB de captura (EBPBotonesUSB (Booleano)).
Variables de tableta (textTitulo (Cadena de texto), textSubtitulo (Cadena de texto), textNombre (Cadena de texto), textAreaFirma (Cadena de texto) y textLOPD (Cadena de texto)).
Activación de pantalla previa (checkEBPInicial (Booleano) y textTextoPrevio (Cadena de texto)).
Anchura del lápiz (maxPen (Entero)).
Mostrar plantilla EBP en el PC (showEBP (Booleano)).
Usar certificado del almacén de windows (useCryptoAPI (Booleano)).
Certificar documento (certificar (Booleano)).
Dimensiones del widget (widgetAncho (Entero) y widgetAlto (Entero)).
Selección de posicionamiento (typePosition (Entero)).
Parámetros para posicionamiento fijo (widgetX (Entero), widgetY (Entero) y widgetPage (Entero)).
Parámetros para posicionamiento flotante (textAutoPos (Cadena de texto), desfaseX (Entero) y desfaseY (Entero)).
Descarga y ejecución en local de documento pdf firmado (checkDownload (Booleano), textFolderDownload (Cadena de texto) y checkExecution (Booleano)).
Visualización de documento a firmar (showPDF (Booleano)) y firmado (showPDFSigned (Booleano)).
Visualización en modo full screen (fullScreen (Booleano)).
Visualización de la ventana de eventos (showEvents (Booleano)) y muestra de alertas en la aplicación (showAlert (Booleano)).
Activación de Virtual Channel Citrix (useCitrix (Booleano)).
Además, se presenta la configuración de otros parámetros de firmado no presentes en el caso de uso:
Parámetros relacionados con las plantillas o ebp’s:
Para la STU-430 (ebpInitial430 (Cadena de texto), ebpConBotones430 (Cadena de texto) y ebpSinBotones430 (Cadena de texto)).
Para las STU-520 y STU-530 (ebpInitial (Cadena de texto), ebpConBotones (Cadena de texto) y ebpSinBotones (Cadena de texto)).
Activación del sellado de tiempo en el momento de la firma (tspActivate (Booleano), tspUrl (Cadena de texto), tspUser (Cadena de texto) y tspPassword (Cadena de texto)).
Activación de la validación del estado de revocación del certificado en el momento de la firma (ocspActivate (Booleano), ocspUrl (Cadena de texto), ocspUser (Cadena de texto), ocspPassword (Cadena de texto) y setValidateErrorContinue (Booleano)).
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.
Nota
Los valores booleanos son introducidos como “1” activado y “0” no activado.
Nota
Para evitar problemas de codificación, el fichero “personalizacion.ini” debe estar codificado en UTF-8.
Nota
Para que los parámetros modificados en el fichero de personalización surtan efecto, se debe inicializar la aplicación.
Nota
Para los parámetros personalizables y que no se pueden modificar por pantalla en el caso de uso, parámetros relacionados con: las plantillas o ebp’s, la activación del sellado de tiempo en el momento de la firma, y la activación de la validación del estado de revocación del certificado en el momento de la firma.
Se podrían modificar en el fichero de configuración ecoSignatureJWS.ini de la solución ecoSignatureJWS Desktop.
Integración
Estructura de los archivos
Se distribuye un fichero zip para ser importado como proyecto 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 fichero zip distribuido:
File Import General Proyecto existente en workspace Next Seleccionar archivo.
- Windows Preferencias Desplegar Java JREs Instalados: en el caso de uso se utiliza una jre 1.8.0_131.
- Seleccionar proyecto ecoSignatureJWS – Desktop – Caso de uso Botón derecho Propiedades Java Build Path En la pestaña de Librerías asegurarse que tenemos librerías asociadas a la jre. En caso de no existir alguna de ellas, añadirlas.
- Configuración de lanzamiento: Run Run Configurations En el árbol de la izquierda de la pantalla seleccionar Java Application Botón derecho New. Pinchar sobre la aplicación creada y configurar los parámetros necesarios en la parte derecha de la pantalla.
- Lanzar la aplicación.
Al importar el proyecto podemos observar las siguientes carpetas más importantes:
- Carpeta “src”: a su vez se definen las siguientes subcarpetas:
- Subcarpeta “main”: contiene la clase relacionada con la implementación de lógica para el lanzamiento de la aplicación.
- Subcarpeta “util”: contiene clases útiles para trabajar en base 64.
- Subcarpeta “windows”: contiene clases relacionadas con la implementación de la lógica para el caso de uso.
El integrador solamente debe tener en cuenta la clase WindowsCaseUse.java que se encuentra en la carpeta “windows”.
Clase WindowsCaseUse
Esta clase es la que se encarga de la generación y visualización del caso de uso, así como del lanzamiento de la solución ecoSignature JWS Desktop.
La función más importante de la clase es la función signed(), en la cual se realizan los siguientes procesos:
- Creación del fichero temporal que contiene los parámetros que son pasados a la solución:
File tempFile = File.createTempFile(“tmp”, “.ini”);
- Se abre un buffer de escritura con codificación UTF-8 para ir escribiendo los diferentes parámetros:
BufferedWriter out = new BufferedWriter(new OutputStreamWriter(new FileOutputStream(tempFile), StandardCharsets.UTF_8));
- Se escriben los parámetros, uno por línea:
// Se introduce la licencia
out.write("license=serverlic.lic");
out.newLine();
- Se cierra el fichero:
// Cierre de fichero
out.close();
- Se lanza la solución ecoSignature JWS Desktop:
- En Windows se lanza un fichero .exe:
ProcessBuilder pb = new ProcessBuilder(pathEcoSignatureDesktopDefault+ "ecoSignatureJWS_Desktop.exe","ini="+tempFile.getAbsolutePath());
Process p = pb.start();
- En Linux se lanza un fichero .jar:
ProcessBuilder pb = new ProcessBuilder("java","-jar",pathEcoSignatureDesktopDefault+ "ecoSignatureJWS_Desktop.jar","ini="+tempFile.getAbsolutePath());
Process p = pb.start();
Nota: En Windows también se puede lanzar la solución desde un fichero .jar.
- Se puede obtener la salida estándar del proceso:
InputStreamReader isrConsole = new InputStreamReader(p.getInputStream());
BufferedReader brConsole = new BufferedReader(isrConsole);
String lineRead;
while ((lineRead = brConsole.readLine()) != null) {
.…….
}
- Se puede obtener la salida de error del proceso:
InputStreamReader isrError = new InputStreamReader(p.getErrorStream());
BufferedReader brError = new BufferedReader(isrError);
String lineReadError;
while ((lineReadError = brError .readLine()) != null) {
……….
try{
value = Integer.parseInt(lineReadError);
} catch (Exception e1) {
}
// Podríamos actuar si hay error, es decir value != null
// if (value != null) {
// …..
// }
- Se puede obtener directamente el código de salida de la solución:
int exitProcess = p.waitFor();
Nota
En Windows si se lanza el fichero. exe el valor devuelto siempre es 0 debido a que el control del proceso lo toma el sistema operativo y no la máquina virtual de Java (JVM), por lo que hay que leer las salidas estándar del proceso.
Nota
En Linux la salida de la solución la devuelve como no firmada. Observar la función convertSigned() que convierte un entero sin signo a un entero con signo.
Nota
Si la solución ecoSignature JWS Desktop devuelve error, se puede obtener el código de error devuelto en la lectura de la última línea de la salida de error. Dichos códigos de error se pueden observar en el Apartado 6.3. Códigos de salida del manual “ecoSignature JWS Desktop - Manual de usuario - Configuración” entregado anteriormente. Si no devuelve error es que el proceso de firmado se ha realizado correctamente.