Esta documentación es válida para CryptoApplet versión 2.0.1 o superiores.

CryptoApplet es un applet de realización de firma que pretende ser versatil y flexible adaptándose desde los entornos más simples a los entornos más exigentes.

Este applet ofrece un entorno de trabajo, inicialmente para la creación de firma en diversos formatos, se prevee que su evolución sea hacia un entorno completo de creación y verificación de firma debido a su diseño modular. Para obtener información más general sobre el proyecto, visite http://cryptoapplet.nisu.org

El proyecto se compone de cuatro módulos:

1. ujiApplet: Este módulo contiene todo el código referente al Applet, como es el código de gestión de la ventana, carga de pkcs#12, carga de pkcs#11, gestión del flujo del proceso de firma, composición del árbol que muestra los certificados, etc.
2. ujiCrypto: El objetivo de este módulo es gestionar todo lo relativo a criptografía, en este módulo se encuentran las clases encargadas de realizar la firma, gestionar los almacenes de certificados, implementar los proveedores necesarios, etc.
3. ujiUtils: Es un módulo con utilidades genéricas de apoyo, el objetivo de este módulo es ofrecer clases para gestionar la internacionalización, configuración, codificación, etc.
4. ujiConfig: Este es un pseudo-módulo en el sentido de que no contiene código, solo una serie de ficheros de certificados y un fichero de configuración que puede servir de ejemplo y base para adaptarlo a cada caso. Cabe indicar en este punto que este paquete de cofiguración no debe entenderse como la única y mejor configuración existente, sino como una base sobre la que trabajar.

Como se comenta en la introducción de la página web del proyecto, el applet recibe una entrada de datos desde una fuente, permite al usuario realizar un firma y envía el resultado a su destino. En el contexto del applet existen dos formas de obtener la entrada de datos que son desde una URL y como un parámetro a una de sus funciones exportadas. En cuanto a la salida, el applet la ofrece también de dos formas distintas, la primera realizando una llamada a una función javascript que contiene como parámetro la firma y la segunda forma haciendo un post a una URL determinada. Para más información con respecto al comportamiento de las funciones ver el punto “Funciones Javascript”.

En Cryptoapplet, los formatos de firma se especifican mediante la función exportada a javascript

  setSignatureOutputFormat(String format);

En adelante nos referiremos a cadenas de formato siendo estos el parámetro que debe recibir la función anterior en cada caso.

Para el formato raw, la cadena debe ser RAW, al indicar este formato de salida, el applet obtendra los datos de entrada, los resumirá utilizando el algorítmo de firma SHA1 y devolverá un PKCS#1 con padding que contendrá el hash de los datos de entrada firmados.

Otra posibilidad para el formato de salida es que el applet genere un PKCS#7, a partir de los datos de entrada se calculará el resumen SHA1 de los mismos, se generará una estructura PKCS#7 y se ofrecerá como resultado. Cabe indicar en este punto que el PKCS#7 generado únicamente contiene el certificado del firmante y no los certificados de CAs intermedias como permite el estándar, de esta forma la verificación debe realizarse contra toda la cadena de certificación que expidió el certificado del firmante.

La cadena de formato que debe utilizarse para obtener la firma en formato PKCS#7 es CMS

  setSignatureOutputFormat("CMS");

En algunos entornos puede ser interesante realizar la firma a partir resumen de los datos, a pesar de que esto podría vulnerar el derecho del firmante a ver el contenido que firma parece razonable en entornos como los sistemas de envio de mail utilizar esta metodología. Si pensamos en un Mail User Agent basado en el Web y en una situación en la que un usuario pretenda enviar adjuntos de suficiente tamaño, el servidor debería devolver al cliente el MIME compuesto con todos los adjuntos para que este pudiera calcular la firma, si utilizamos únicamente el hash, el servidor devolverá los 20 bytes de los que se compone el resumen y el cliente tendrá suficiente información para componer la firma. Obviamente el cliente podría enviarse una copia de ese correo para comprobar los datos que ha firmado. Puede verse un ejemplo de lo expuesto en http://cryptoapplet.nisu.org/samples/v2/signmail.php

La cadena de formato que debe utilizarse para obtener la firma en formato PKCS#7 a partir del hash es CMS_HASH

  setSignatureOutputFormat("CMS_HASH");

CryptoApplet utiliza las bibliotecas iText (http://www.lowagie.com/iText/) para realizar la firma electrónica sobre documentos pdf, dada la entrada de datos, CryptoApplet sitúa una firma invisible en el documento pdf que puede ser verificada por Adobe Reader. Los campos Reason, Location y Contact de la firma son configurables (véase abajo el punto relativo a la configuración). En la firma generada se incluye el certificado del firmante y el de la CA raíz o intermedia que lo expidió.

Este formato, permite también añadir un Sello de Tiempo gracias al parche desarrollado por Aiken Sam y Martin Brunecky para iText. La activación de esta característica así como la dirección URL desde donde se debe obtener la marca de tiempo, se configuran en el fichero de configuración.

La cadena de formato que debe utilizarse para obtener la firma de un PDF es PDF

  setSignatureOutputFormat("PDF");

Hay que tener en cuenta que para la obtención de este formato de firma sólo podemos proporcionar como entrada un documento PDF.

Este applet hace uso de una versión de la biblioteca JDigiDoc considerablemente modificada por nosotros que genera una representación de firma compatible compatible con la especificación TS 101 903 - V1.1.1 del ETSI, siendo capaz de generar los formatos XAdES, XAdES-T y XAdES-X-L. El applet generará uno u otro formato dependiendo de la configuración. (véase abajo el punto relativo a la configuración) Las particularidades, de un modo general, de estos formatos son:

1. XAdES: Es el formato más básico, equiparable al generado por el formato de firma XMLDsig más ciertos datos adicionales relativos al certificado del firmante y a la hora que ofreció su máquina.
2. XAdES-T: Contiene además de lo mismo que el formato anterior, un sello de tiempo obtenido de la autoridad de sellado de tiempo indicada en el fichero de configuración.
3. XAdES-X-L: Contiene datos relativos a la validación con el objetivo de permitir que ésta perdure en el tiempo, estos datos son básicamente aquellos en relación a la respuesta OCSP recibida con respecto a la validación del certificado.

La cadena de formato que debe utilizarse para obtener la firma en formato DigiDoc es XADES

  setSignatureOutputFormat("XADES");

El applet también soporta la realización de firmas en paralelo para el formato XAdES, de forma que en un mismo documento XML se encuentre el contenido sobre el cual se realizó la firma y a continuación uno por uno el resultado de todos los procedimientos de firma que se llevaron a cabo sobre él. Cabe mencionar con respecto a este método que la entrada de datos debe ser un documento en formato DigiDoc previamente firmado con el applet utilizando el formato de firma “XAdES”.

La cadena de formato que debe utilizarse para obtener cofirma en XAdES es XADES_COSIGN

  setSignatureOutputFormat("XADES_COSIGN");

En la versión 2.0.1 del applet se ha implementado también el soporte para la generación de firma XMLDsig enveloped siendo ésta soportada por la versión de la máquina virtual de java (y su plugin) 1.6 o superior. En el código fuente del applet puede obtenerse un ejemplo de validación de esta modalidad de firma, concretamente en el paquete es.uji.dsign.crypto.test

Este formato de salida recibe datos en formato XML como entrada con los datos y genera la representación de la firma en formato XMLDsig.

La cadena de formato que debe utilizarse para obtener la firma en formato XMLDsig es XMLDSIG

  setSignatureOutputFormat("XMLDSIG");

La interacción con el Applet se realiza plenamente mediante funciones JavaScript. Para comprender mejor el procedimiento general, comentaremos el siguiente código:

En primer lugar el siguiente código HTML instancia el applet y crea un botón cuya acción será invocar la función javascript Sign(), este botón se encuentra deshabilitado para impedir que el usuario lo presione antes de que el applet se cargue.

 
<applet id="CryptoApplet" name="CryptoApplet" code="es.uji.dsign.applet2.SignatureApplet" width="0" height="0" codebase="applet"
  archive="ujiApplet-2.0.1-signed.jar,ujiCrypto-2.0.1-signed.jar,ujiUtils-2.0.1-signed.jar,ujiConfig-2.0.1.jar,
  bcprov-jdk15-138.jar,bcmail-jdk15-138.jar,jakarta-log4j-1.2.6.jar" mayscript>
</applet>
 
<input id="bt1" type="button" disabled="true" value="Sign" onClick="Sign();">

El código JavaScript más básico que podemos implementar en la página es el siguiente:

<script language="javascript">
 
function onInitOk(){
 document.getElementById("bt1").disabled=false;
}
 
function onSignOk(signature){
 alert(signature);
}
 
function onSignOkFinalize(signature){
 alert(signature);
}
 
function onSignError(errorDesc){
  alert(errorDesc);
}
 
function onSignCancel(){
  alert("User Canceled");
}
 
function Sign(){
  CryptoApplet= document.getElementById('CryptoApplet');
  CryptoApplet.setInputDataEncoding("PLAIN");
  CryptoApplet.setSignatureOutputFormat("CMS");
  CryptoApplet.signDataUrlToFunc("http://www.foo.com","onSignOk");
}
 
</script>

El flujo de ejecución del proceso de firma es el siguiente, el applet se instanciará y se invocará su método init, una vez hecho esto, él mismo invocará la función JavaScript onInitOk. El usuario presionará el botón y le aparecerá la ventana principal del applet, durante el proceso de selección de certificado, introducción de password y realización de firma, si el usuario cancela la operación o sucede algún error, las funciones onSignCancel y onSignError serán invocadas respectivamente, en caso contrario, si la realización de la firma ha sido correcta se invocará la función javaScript que se haya indicado como segundo parámetro de la función signDataUrlToFunc, por defecto se invocará la función onSignOk.

En el caso anterior, la función Sign, indica al Applet que la codificación de los datos de entrada es “texto plano”, que el formato de representación de firma debe ser CMS y que se utilizará como entrada / salida de datos la url http://www.foo.com y la función onSignOk respectivamente.

1. onInitOk() : Esta función es invocada por el applet cuando la carga e inicialización del mismo se ha completado. Su uso común es el de activación o desactivación del botón de firma para que el usuario no pueda presionarlo antes de que el applet este correctamente inicializado.
2. onSignOk([String sig]): Esta función es invocada cuando el proceso de firma finaliza correctamente, si éste se ha realizado invocando alguna función de las que ofrecen la salida como parámetro a función javascript, la función onSignOk recibirá el el resultado de la firma como único parámetro.
3. onSignError(): Esta función es invocada cuando sucede algún error en el proceso de firma.
4. onSignCancel(): Esta función se invoca si el usuario presiona el botón de cancelación del Applet.

A continuación puede verse código fuente de ejemplos de utilización del applet para los diferentes formatos de firma.

Raw signature.

CMS signature.

PDF signature

XMLDsig signature

DigiDoc (XAdES-X-L) signature.

Batch signature creation (XAdES-X-L based example)

XAdES-X-L verifier

La instalación es sencilla, únicamente hay que obtener la última versión de la página de descargas y descomprimir el fichero en el directorio destinado a tal fin dentro de la estructura de la página web para la cual va a ser utilizado. Esto nos creará un directorio CryptoApplet_VX.Y.Z que contiene los ficheros .jar principales y un directorio libs que contiene las bibliotecas necesarias para la correcta ejecución del applet, puesto que en cada caso, las bibliotecas necesarias son distintas, a contnuación puede verse una tabla que relaciona el formato de firma de salida con las bibliotecas necesarias. Estas bibliotecas deben ser especificadas en el atributo “archive” de la etiqueta applet que configura su instanciación.

Para todos los formatos deben incluirse las bibliotecas ujiUtils-x.y.z-signed.jar, ujiApplet-x.y.z-signed.jar, ujiCrypto-x.y.z-signed.jar si además pretende utilizarse la configuración de ejemplo ujiConfig-x.y.z.jar deberá ser incluido, en caso contrario deberá incluirse otro fichero jar que contenga la configuración específica.

La configuración se establece por medio del fichero ujiCrypto.conf, éste fichero contiene pares nombre=valor que determinan el comportamiento y algunas de las características del applet durante el proceso de firma. Por el momento, solo existen opciones que afectan a las modalidades de firma XAdES-X-L y PDF. Podemos ver estas opciones a continuación de forma tabulada.

Para más información relacionada con las opciones de esta modalidad de firma puede consultarse la documentación del proyecto JDigiDoc.

El interfaz del applet utiliza conjuntos de propiedades para permitir la internacionalización, de forma que mediante la función exportada javascript setLanguage(lang); y el uso de los ficheros i18n_XY_ZT.properties consguimos que el applet muestre los mensajes en el idioma deseado. Por el momento, el applet dispone de las siguientes traducciones:

• i18n_ES_es.properties: Castellano.
• i18n_EN_en.properties: Inglés.
• i18n_CA_ca.properties: Catalán.