Introducción

Componentes de Firma es una iniciativa del Ministerio de Industria, Energía y Turismo consistente en el desarrollo de unas librerías Java de firma electrónica XML avanzadas (XAdES) para facilitar la generación y validación de firmas digitales, especialmente a las PYMES y MicroPYMES, y distribuida bajo una licencia de software libre (LGPL).

¿Cómo se distribuyen?

Actualmente existen las siguientes distribuciones de los componentes;

  • componentes-X.Y.Z-no-deps.zip: Se corresponde con una distribución binaria de los componentes sin incluir las dependencias de terceros necesarias.
  • componentes-X.Y.Z-with-deps.zip: Se corresponde con una distribución binaria de los componentes incluyendo las dependencias de terceros necesarias.
  • componentes-X.Y.Z-docs.zip: Contiene la documentación completa del proyecto.
  • componentes-X.Y.Z-sources.zip: Contiene las fuentes del proyecto completo (tanto el código fuente como los archivos necesarios para la construcción de las distribuciones).

En todos los casos X.Y.Z se corresponde con la versión de los Componentes.

Sobre el sistema de versionado

El sistema de versionado utiliza tres números de la forma MAJOR.MINOR.FIX. El primer número (X o MAJOR) está destinado a gestionar cambios en la arquitectura de los Componentes. El segundo número (Y o MINOR) se destina a gestionar nuevas funcionalidades que provocan un cambio en el API, de forma que la compatibilidad hacia atrás no está garantizada. El tercer y último número (Z o FIX) está destinado a la corrección de errores con total compatibilidad hacia atrás. Por último, y de forma excepcional, un cambio en el FIX podría suponer una nueva funcionalidad manteniendo la compatibilidad hacia atrás.

¿Qué contiene la documentación?

Toda la documentación técnica del proyecto se distribuye como un sitio Web generado con Maven. Además, es posible descargase esta documentación para poder visualizarla sin necesidad de tener conexión a Internet mediante la distribución componentes-X.Y.Z-docs.zip. Una vez descargado y descomprimido el archivo anterior se creará el directorio componentes-X.Y.Z. En adelante, a la ubicación del directorio componentes-X.Y.Z nos referiremos como $COMPONENTES_HOME

El contenido de la documentación es el siguiente:

  • Sitio Web general del proyecto de Componentes. Para visualizarlo bastará con abrir con un navegador Web el fichero $COMPONENTES_HOME/docs/index.html.
  • Sitio Web específico de cada uno de los Componentes. Para visualizarlo se podrá acceder mediante los enlaces que aparecen en el menú principal (situado a la izquierda) del sitio general o bien abriendo directamente con un navegador Web los archivos $COMPONENTES_HOME/<componente_especifico>/docs/index.html.
  • Histórico de cambios realizados en las distintas versiones del proyecto, al que se puede acceder desde el menú principal del sitio Web general en "Componentes de firma -> ChangeLog".
  • JavaDocs de cada uno de los componentes. El acceso a los Javadocs se encuentra en el menú principal de cada componente en "Documentación del proyecto -> Informes del proyecto -> JavaDocs". Al mismo nivel también se encuentra un acceso a los JavaDocs de los tests unitarios de cada componente, llamado "Test JavaDocs".
  • Código fuente en formato HTML con hiperenlaces entre los fuentes. El acceso a los fuentes se encuentra en el menú principal de cada componente en "Documentación del proyecto -> Informes del proyecto -> Source Xref". Al mismo nivel también se encuentra un acceso a los fuentes de los tests unitarios de cada componente, llamado "Test Source Xref".
  • Ejemplos explicando las operaciones más típicas que se pueden realizar con los componentes. Dichos ejemplos están accesibles desde el menú principal del sitio Web de cada uno de los componentes dentro de la sección "Ejemplos de uso". Además de la explicación de cada ejemplo se proporciona un enlace al código fuente completo de dicho ejemplo.

¿Cómo se desarrollan los Componentes?

Los componentes se distribuyen bajo licencia LGPL de forma que, bajo los términos de la licencia, podrían ser usados, distribuidos y modificados por terceras partes. El desarrollo del proyecto se ha realizado utilizando el IDE Eclipse, mientras que el ciclo de vida se ha gestionado mediante la herramienta Maven. Puesto que con los fuentes del proyecto se distribuyen los ficheros de configuración de los distintos proyectos para Eclipse y los ficheros POM (Projecto Object Model) correspondientes a Maven, si bien no es necesario, se recomienda el uso de Eclipse y Maven en el caso de querer modificar los Componentes.

A continuación se describen las instrucciones básicas para modificar, construir y generar las distribuciones del proyecto:

  1. Descargar las distribuciones correspondientes a las fuentes, es decir, componentes-X.Y.Z-sources.zip, y a los binarios con dependencias, es decir, componentes-X.Y.Z-with-deps.zip. La distribución binaria con dependencias, si bien no es necesaria, es recomendable para tener exactamente las mismas dependencias con las que se generó las distribuciones originales.
  2. Descomprimir ambos ficheros ZIP en una determinada ubicación. Una vez descomprimidos, se habrá creado el directorio componentes-X.Y.Z. En adelante, a la ubicación del directorio componentes-X.Y.Z nos referiremos como $COMPONENTES_HOME.
  3. Puesto que los componentes dependen de librerías de terceros que no están en los repositorios oficiales Maven, habrá que hacer accesibles estas dependencias al Maven que esté usando el desarrollador. Para resolver este problema existen dos alternativas:
    • Instalar las dependencias en el respositorio local.
    • Desplegar las dependencias en un posible repositorio remoto en el que el desarrollador tenga permisos de escritura.

    Puesto que es habitual no disponer de un repositorio remoto, asumimos que el desarrollador instala las dependencias en su repositorio local. Para ello los comandos serían:

    mvn install:install-file -DgroupId=es.mityc.jumbo.adsi \
    -DartifactId=xmlsec-1.4.2-ADSI -Dversion=1.0 -Dpackaging=jar \
    -Dfile=%COMPONENTES_HOME%\core\xmlsec-1.4.2-ADSI-1.0.jar
     
    mvn install:install-file -DgroupId=org.mozilla \
    -DartifactId=jss -Dversion=4.2.5 -Dpackaging=jar \
    -Dfile=%COMPONENTES_HOME%\deps\jss-4.2.5.jar
    

    Las librerías anteriores son las siguientes:

  4. Una vez instaladas las dependencias se estaría en disposición de modificar el código fuente. Como se ha dicho anteriormente, el desarrollo de los componentes se realiza mediante el IDE Eclipse. Por tanto, la forma más sencilla de tener un entorno de desarrollo amigable es importando los distintos proyectos que se distribuyen en el Eclipse. Para ello se puede entrar en la opción "File -> Import -> General -> Existing Projects into Workspace" y en la opción de "Select root directory" seleccionar el directorio $COMPONENTES_HOME. Una vez realizado ésto se debería tener un proyecto por cada componente.

    Llegados a este punto es muy importante tener en cuenta que la codificación que se utiliza en las fuentes de los Componentes es UTF-8, por lo que habrá que configurar el entorno de desarrollo elegido para que use esa codificación. Además, en algunos componentes se utilizan clases del API restringido (esto es, clases que sólo existen en la máquina virtual de Sun). El uso del API restringido, en entornos como el Eclipse, puede dar errores en tiempo de compilación. En el caso de Eclipse, para evitar dichos errores hay que cambiar el nivel de errores de compilación. Para ello entrar en "Window -> Preferences -> Java -> Compiler -> Error/Warnings -> Deprecated and restricted API" y en la opción de "Forbidden references (access rules)" marcar como "Ignore" o "Warning".

  5. Una vez instaladas las dependencias se podrían generar los artefactos asociados al proyecto, ésto es, los JARs de cada una de las librerías. Para ello, desde el directorio $COMPONENTES_HOME/sources habría que ejecutar lo siguiente:
    mvn package
    

    Debido al funcionamiento de Maven, durante la fase de package se ejecutarán los tests unitarios definidos en cada uno de los componentes. La ejecución de estos tests es transparentes al usuario en todos los componentes salvo en la librería MITyCLibCert. Para poder superar los tests de esta librería el usuario deberá hacer lo siguiente:

    • Instalar el certificado de test usr0061.p12 en el almacén de certificados personal del usuario actual (almacén My de Current User). Dicho certificado se puede encontrar en $COMPONENTES_HOME/sources/MITyCLibCert/testres/keystores/usr0061.p12 y su contraseña es usr0061.
    • Modificar el archivo testMozilla.properties que se encuentra la en ubicación $COMPONENTES_HOME/sources/MITyCLibCert/testres para asignar el valor correspondiente a la propiedad test.mozilla.profile. El valor de dicha propiedad debe ser el directorio del perfil de Firefox asociado al usuario que ejecuta los tests. Dicho directorio varía de un sistema operativo a otro. En los sistemas operativos más habituales suele el siguiente:
      • Windows: C:/Documents and Settings/<usuario>/Datos de programa/Mozilla/Firefox/Profiles/<perfil>
      • Linux: ~/.mozilla/firefox/<perfil>

    Puesto que algún usuario podría no querer instalar dicho certificado o podría no tener instalado el navegador Web Firefox, podría evitar la ejecución de los tests con el siguiente comando:

    mvn -DskipTests=true package
    

    Tanto si se ejecutan los tests como si no, los artefactos generados quedarán en $COMPONENTES_HOME/sources/<componente_determinado>/dist/release

  6. Por último, alguien podría querer generar las distribuciones o ensamblados del proyecto (por ejemplo, para modificar la documentación y volverla a distribuir), para lo cual habría que ejecutar lo siguiente:
    mvn clean site install assembly:assembly
    

    En el caso de no querer ejecutar los tests que automáticamente se ejecutan en la fase de package, habría que añadir la opción -DskipTests=true al comando anterior.

    Una vez ejecutado el proceso completo (el cuál es bastante costoso y puede tardar bastante) los ensamblados generados quedarán en el directorio $COMPONENTES_HOME/sources/dist/release

    Debido a la complejidad del proceso anterior podría suceder que la máquina virtual bajo la que se ejecuta Maven se quedara sin memoria. Si ocurre esto una posible solución es aumentar el máximo de memoria. Para ello, ejecutar lo siguiente:

    • Windows:
      set MAVEN_OPTS="-Xmx1024M"
      
    • Linux:
      export MAVEN_OPTS="-Xmx1024M"
      

¿Cómo se utilizan los Componentes?

Llegados a este punto, un posible integrador de sistemas se podría preguntar cómo utilizar los Componentes. Dependiendo de lo que quiera realizar las necesidades serán unas u otras. A continuación se explica cómo realizar las operaciones más típicas.

Acceso a almacenes de certificados

Esta operación es típica cuando se quiere obtener desde código Java acceso a distintos almacenes de certificados. Actualmente, los almacenes soportados son los siguientes:

  • Almacén de certificados Windows utilizando el proveedor SunMSCAPI: Requiere Java 1.6+.
  • Almacén de certificados Windows utilizando una librería nativa desarrollada por el MINETUR: Requiere Java 1.5+ y, a diferencia del almacén anterior, sólo requiere aceptar los términos de la licencia LGPL.
  • Almacén de certificados de Mac OS X: Requiere Java 1.5+.
  • Almacén de certificados de Firefox: Requiere Java 1.5+ y navegador Web Firefox instalado
  • Almacén de certificados de Java: Requiere Java 1.5+.
  • Almacén de certificados de una tarjeta inteligente que cumple el estándar PKCS#11: Requiere Java 1.5+, un lector de tarjetas inteligentes con los drivers del fabricante instalados y, por último, tener instalados los drivers de los diferentes fabricantes de tarjetas (que serán diferentes a los drivers del lector) a las que se desee acceder. El acceso a este tipo de almacenes PKCS#11 ya se encuentra implementado en las pasarelas de Windows o Firefox. Sólo será necesario emplear este tipo de acceso si se quiere acceder directamente a las tarjetas inteligentes.

Junto con el código fuente de la librería MITyCLibCert se distribuyen ejemplos que realizan un listado de todos los almacenes. Siempre que se haya descargado y descomprimido la distribución de las fuentes, los ejemplos se encontrarán en $COMPONENTES_HOME/sources/MITyCLibCert/test/es/mityc/javasign/pkstore/examples. Además, dentro del sitio Web del componente MITyCLibCert se encuentra la descripción detallada de cada uno de los ejemplos, accesible desde el menú principal en la sección de "Ejemplos de uso".

Los pasos para poder probar los ejemplos son los siguientes:

  1. Crear un proyecto con el IDE preferido.
  2. Incluir los archivos fuentes de los ejemplos (paquete $COMPONENTES_HOME/sources/MITyCLibCert/test/es/mityc/javasign/pkstore/examples completo), manteniendo la paquetería definida.
  3. Incluir en el classpath del proyecto las dependencias necesarias, que se pueden encontrar en la distribución componentes-X.Y.Z-with-deps.zip:
    • MITyCLibAPI.jar
    • MITyCLibCert.jar
    • bcprov.jar
    • bcmail.jar
    • bctsp.jar
    • commons-logging.jar
    • iaikpkcs11wrapper.jar
    • jss.jar
    • sunpkcs11.jar

    NOTA: Los números de versión de las dependencias han sido omitidos para simplificar.

  4. Compilar y ejecutar los ejemplos.
  5. Una vez que los ejemplos compilan y ejecutan correctamente, implementar la operación necesaria según los requisitos específicos del integrador.

Consulta de estado de certificados mediante protocolo OCSP

Cuando se consulta el estado de un certificado el objetivo es saber si ese certificado es válido o, por el contrario, está revocado. Tradicionalmente la forma de realizar esto era consultar las CRLs (listas de revocación) que emitía el prestador de dicho certificado y comprobar si el certificado estaba en la lista en cuestión. En caso de que estuviera, el estado del certificado sería revocado. En caso contrario el certificado se podía considerar válido. Sin embargo, la validación basada en CRLs presenta varios inconvenientes:

  • El prestador de certificados debería generar una CRL cada vez que existe un cambio en el estado de un certificado (es decir, cada vez que un certificado es revocado).
  • El validador se debe de encargar de obtener la última CRL en vigor asociada al prestador del certificado que se desea validar.
  • El tamaño de las CRLs no está acotado y dependiendo del número de revocaciones podrían crecer indefinidamente.

Para solventar estos problemas surgió el protocolo OCSP, Online Certificate Status Protocol, mediante el cual se puede conocer el estado de un certificado en tiempo real mediante una consulta a un OCSP responder (es decir, un servidor que entiende el protocolo OCSP). Para más información sobre OCSP consultar la RFC 2560.

Dependiendo del prestador a consultar, el servicio OCSP puede ser o no de pago. En cuanto al DNIe sí que existe un OCSP responder gratuito en la ubicación http://ocsp.ctpa.mityc.es. En otros casos, como la FNMT, el servicio no es gratuito.

Junto con el código fuente de la librería MITyCLibOCSP se distribuyen ejemplos que realizan validaciones de certificados contra un OCSP responder. Siempre que se haya descargado y descomprimido la distribución de las fuentes, los ejemplos se encontrarán en $COMPONENTES_HOME/sources/MITyCLibOCSP/test/es/mityc/javasign/certificate/ocsp/examples. Además, dentro del sitio Web del componente MITyCLibOCSP se encuentra la descripción detallada de cada uno de los ejemplos, accesible desde el menú principal en la sección de "Ejemplos de uso".

Los pasos para poder probar los ejemplos son los siguientes (requiere Java 1.5+):

  1. Crear un proyecto con el IDE preferido.
  2. Incluir los archivos fuentes de los ejemplos (paquete $COMPONENTES_HOME/sources/MITyCLibOCSP/test/es/mityc/javasign/certificate/ocsp/examples completo), manteniendo la paquetería definida.
  3. Incluir el certificado a validar como recurso de la aplicación.
  4. Incluir la configuración del validador de confianza que se utiilza durante los ejemplos. Es decir, incluir el directorio $COMPONENTES_HOME/sources/MITyCLibXAdES/testres/trust y todos sus subdirectorios de forma que queden accesibles como recursos bajo la ruta /trust
  5. Modificar los ejemplos según se indica en la descripción detallada del sitio Web para definir el OCSP responder a utilizar y el certificado a validar.
  6. Incluir en el classpath del proyecto las dependencias necesarias, que se pueden encontrar en la distribución componentes-X.Y.Z-with-deps.zip:
    • MITyCLibAPI.jar
    • MITyCLibCert.jar
    • MITyCLibOCSP.jar
    • MITyCLibTrust.jar
      • bcmail.jar
      • bcprov.jar
      • bctsp.jar
      • commons-codec.jar
    • commons-httpclient.jar
    • commons-logging.jar

    NOTA: Los números de versión de las dependencias han sido omitidos para simplificar.

  7. Compilar y ejecutar los ejemplos.
  8. Una vez que los ejemplos compilan y ejecutan correctamente, implementar la operación necesaria según los requisitos específicos del integrador.

Peticiones/Validaciones de sellos de tiempo

Los sellos de tiempo se utilizan para tener constancia, por medio de una autoridad de sellado de tiempo, de que ciertos datos han existido y no han sido modificados a partir del instante en el que se realiza el sello. Para más información sobre el sellado de tiempo consultar la RFC 3161.

En ocasiones, un integrador que esté usando los Componentes, podría necesitar hacer peticiones de sellos de tiempos o validaciones de sellos generados previamente. Para mostrar estas operaciones se dispone de ejemplos que se distribuyen junto con el código fuente de la librería MITyCLibTSA. Siempre que se haya descargado y descomprimido la distribución de las fuentes, los ejemplos se encontrarán en $COMPONENTES_HOME/sources/MITyCLibTSA/test/es/mityc/javasign/ts/examples. Además, dentro del sitio Web del componente MITyCLibTSA se encuentra la descripción detallada de cada uno de los ejemplos, accesible desde el menú principal en la sección de "Ejemplos de uso".

Debido a que los sellos de tiempo tienen implicaciones legales y a que no suele ser un servicio gratuito, no se dispone de ninguna TSA oficial para realizar sellos válidos. Para realizar pruebas se podría utilizar alguna de las TSAs de pruebas que ofrece el IAIK. Es importante tener en cuenta que la librería MITyCLibTSA únicamente es válida para hacer peticiones/validaciones de sellos de tiempo siguiendo el protocolo HTTP.

Los pasos para poder probar los ejemplos son los siguientes (requiere Java 1.5+):

  1. Crear un proyecto con el IDE preferido.
  2. Incluir los archivos fuentes de los ejemplos (paquete $COMPONENTES_HOME/sources/MITyCLibTSA/test/es/mityc/javasign/ts/examples completo y la clase $COMPONENTES_HOME/sources/MITyCLibTSA/test/es/mityc/javasign/ts/AllTrustedManager.java), manteniendo la paquetería definida.
  3. Modificar los ejemplos según se indica en la descripción detallada del sitio Web para definir la autoridad de sellado de tiempo a utilizar (que siga el protocolo HTTP).
  4. Incluir en el classpath del proyecto las dependencias necesarias, que se pueden encontrar en la distribución componentes-X.Y.Z-with-deps.zip:
    • MITyCLibAPI.jar
    • MITyCLibTSA.jar
    • bcmail.jar
    • bcprov.jar
    • bctsp.jar
    • commons-logging.jar
    • commons-httpclient.jar
    • commons-codec.jar

    NOTA: Los números de versión de las dependencias han sido omitidos para simplificar.

  5. Compilar y ejecutar los ejemplos.
  6. Una vez que los ejemplos compilan y ejecutan correctamente, implementar la operación necesaria según los requisitos específicos del integrador.

Firmas/Validaciones XAdES

La operación de más alto nivel que un integrador podría hacer con los Componentes sería una firma XAdES. Actualmente se soportan los siguientes tipos de firma:

  • XAdES Enveloping
  • XAdES Enveloped
  • XAdES Detached, donde los archivos externos están en URIs correspondientes a ficheros (URIs del tipo file:)

Los esquemas de XAdES soportados son los siguientes:

  • XAdES 1.1.1
  • XAdES 1.2.2
  • XAdES 1.3.2

Por último, se soportan los siguientes niveles de XAdES:

  • XAdES-BES
  • XAdES-EPES
  • XAdES-T
  • XAdES-C
  • XAdES-X
  • XAdES-X-L
  • XAdES-A (validación)

Junto con el código fuente de la librería MITyCLibXAdES se distribuyen ejemplos que realizan diversos tipos de firma y validaciones de firmas. Siempre que se haya descargado y descomprimido la distribución de las fuentes, los ejemplos se encontrarán en $COMPONENTES_HOME/sources/MITyCLibXAdES/test/es/mityc/javasign/xades/examples y en sus subdirectorios. Además, dentro del sitio Web del componente MITyCLibOCSP se encuentra la descripción detallada de cada uno de los ejemplos, accesible desde el menú principal en la sección de "Ejemplos de uso".

Los pasos para poder probar los ejemplos son los siguientes (requiere Java 1.5+):

  1. Crear un proyecto con el IDE preferido.
  2. Incluir los archivos fuentes de los ejemplos (paquete $COMPONENTES_HOME/sources/MITyCLibXAdES/test/es/mityc/javasign/xades/examples completo, junto con sus subpaquetes, y la clase $COMPONENTES_HOME/sources/MITyCLibXAdES/test/es/mityc/javasign/issues/PassStoreKS.java), manteniendo la paquetería definida.
  3. Incluir el certificado con el que se realiza las firmas como recurso de la aplicación. Es decir, incluir el paquete P12 que se encuentra en $COMPONENTES_HOME/sources/MITyCLibXAdES/testres/examples/usr0061.p12 de forma que quede accesible como recurso bajo la ruta /examples/usr0061.p12. Su contraseña es usr0061.
  4. Incluir la configuración del validador de confianza que se utiilza en algunos ejemplos de firma y validación. Es decir, incluir el directorio $COMPONENTES_HOME/sources/MITyCLibXAdES/testres/trust y todos sus subdirectorios de forma que queden accesibles como recursos bajo la ruta /trust
  5. Modificar los ejemplos según se indica en la descripción detallada del sitio Web para, en ciertos casos, definir el OCSP responder y la URL de la TSA a utilizar.
  6. Incluir en el classpath del proyecto las dependencias necesarias, que se pueden encontrar en la distribución componentes-X.Y.Z-with-deps.zip:
    • MITyCLibTrust.jar
    • MITyCLibAPI.jar
    • MITyCLibCert.jar
    • MITyCLibOCSP.jar
    • MITyCLibTrust.jar
    • MITyCLibTSA.jar
    • MITyCLibXADES.jar
      • bcmail.jar
    • bcprov.jar
      • bctsp.jar
      • commons-codec.jar
    • commons-httpclient.jar
    • commons-lang.jar
    • commons-logging.jar
    • iaikpkcs11wrapper.jar
    • sunpkcs11.jar
    • serializer.jar
    • xmlapis.jar
    • xmlsec.jar
    • xalan.jar

    NOTA: Los números de versión de las dependencias han sido omitidos para simplificar.

  7. Compilar y ejecutar los ejemplos.
  8. Una vez que los ejemplos compilan y ejecutan correctamente, implementar la operación necesaria según los requisitos específicos del integrador.