servicio de firma electrónica de gobierno de...

Servicio de Firma Electrónica de Gobierno de Aragón

Referencia: AST-EFIRMA-ManualIntegracion_ComponenteCliente.doc

Autor: Aragonesa de Servicios Telemáticos

Fecha de creación: 28/01/2015

Última actualización: 25/09/2015

Versión: v2.7

Clasificación: Uso Público

Manual Integración Componente Cliente (WebSigner)



Ref.: AST-EFIRMA-ManualIntegracion_ComponenteCliente.doc Fecha: 25.09.2015 Versión: v2.7 Pág. 2 de 21

Entidad Pública Aragonesa de Servicios TelemáticosPº María Agustín 25-27-29 • 50071 ZARAGOZA

Tel. 976 71 4495 • Fax. 976 71 4395www.aragon.es

Control del documento

Registro de cambios

Versión Fecha Autor Descripción

V1.0 20/10/2008 Sergio Loras Creación del documento inicial

V1.1 10/11/2008 Sergio Loras Modificaciones para integración con Firefox3

V1.2 30/11/2009 Mª Eugenia Pamplona Reestructuración del documento

V1.2.1 04/02/2010 Mª Eugenia Pamplona Añadida introducción de componente y modificaciones para integración Firefox 3


V2.1 16/02/2011 AMS Actualización documento para versión websigner 6.0.0.1






V2.7 25/09/2015 Mª Eugenia Pamplona Homogeneización Servicio

Revisores

Nombre Área

Mª Eugenia Pamplona AST - Unidad de Producción de Servicios Software

Lista de distribución

Nombre Área

Integradores del servicio Gobierno de Aragón y Empresas Desarrolladoras Software

Equipo AMS Servicio de Mantenimiento de Aplicaciones






Contenido

1. COMPONENTE CLIENTE .................................................................................................................. 4

1.1. REQUISITOS ................................................................................................................................ 4

2. INSTALACIÓN .................................... ................................................................................................ 5

3. INTEGRACIÓN ................................................................................................................................... 6

3.1. ORDEN LÓGICO DEL FLUJO DE INVOCACIÓN .............. ......................................................... 6

3.2. ENTORNOS .................................................................................................................................. 6

3.3. CARGA DEL COMPONENTE .............................. ........................................................................ 6

3.4. DIFERENCIAS Y LIMITACIONES DE LAS FUNCIONES DE FIRM A ........................................ 7

3.4.1. Firma de datos .......................................................................................................................... 8

3.4.1.1. Funciones sign ...................................................................................................................... 8

3.4.1.2. Limitaciones de las funciones sign ....................................................................................... 8

3.4.2. Firma de fichero ........................................................................................................................ 9

3.4.2.1. Funciones signFile ................................................................................................................ 9

3.4.2.2. Limitaciones de las funciones signFile ................................................................................. 9

3.4.2.3. Funciones signFileOneStep .................................................................................................. 9

3.4.2.4. Limitaciones de las funciones signFileOneStep ................................................................. 10

3.4.2.5. Funciones signFileToFileOneStep ...................................................................................... 10

3.4.2.6. Limitaciones de las funciones signFileToFileOneStep ....................................................... 10

3.4.2.7. Funciones signFileByBlockOneStep ................................................................................... 11

3.4.2.8. Funciones signHash ........................................................................................................... 11

3.4.3. Firmas secuenciales ............................................................................................................... 12

3.4.3.1. Añadir Firmante Secuencial ................................................................................................ 12

3.4.3.2. Añadir Firmante Secuencial desde fichero ......................................................................... 12

3.4.3.3. Añadir Firmante Secuencial Fichero a Fichero en un paso ................................................ 13

3.4.3.4. Añadir Firmante Secuencial Fichero por bloques ............................................................... 13

3.4.3.5. Restricciones de las firmas múltiples secuenciales ............................................................ 13

3.4.3.6. Limitaciones de las firmas múltiples secuenciales ............................................................. 14

3.4.4. Firmas paralelas ...................................................................................................................... 14

3.4.4.1. Añadir Firmante Paralelo .................................................................................................... 14

3.4.4.2. Añadir Firmante Paralelo desde fichero ............................................................................. 15

3.4.4.3. Añadir Firmante Paralelo Fichero a Fichero en un paso .................................................... 15

3.4.4.4. Añadir Firmante Paralelo Fichero por bloques ................................................................... 16

3.4.4.5. Restricciones de las firmas múltiples paralelas .................................................................. 16

3.4.4.6. Limitaciones de las firmas múltiples paralelas.................................................................... 16

4. FAQS ................................................................................................................................................. 18

4.1. PROBLEMAS CON INPUTFILE............................ ..................................................................... 18

4.2. ERROR EN LA CARGA DE LAS LIBRERÍAS DEL APPLET ..... .............................................. 18

4.3. COMO AUMENTAR MEMORIA PARA EVITAR LIMITACIÓN DE LA JRE ............................. 19

4.3.1. Configuración memoria virtual ................................................................................................ 19






1. Componente Cliente

El componente cliente del Servicio de Firma permite ofrecer las funcionalidades a un usuario de firmar y cifrado documentos electrónicos y formularios web desde una aplicación web, pudiendo acceder a los almacenes locales de certificados del equipo del usuario.

Las funcionalidades técnicas del componente cliente son las siguientes:

� Firma de cualquier tipo de documento y formulario web.

� Uso de firma única o múltiple (mancomunada) en formatos PKCS#7, CMS, XMLDSig, XAdES (subtipos AdES-BES y XAdES-EPES), CAdES (subtipos CAdES-BES y CAdES-EPES) y Adobe PDF en sistemas basados en tecnología web.

� Filtrado de certificados autorizados para el proceso, en función de las políticas de confianza definidas para el proceso en la plataforma de Firma.

� Cifrado y descifrado de un formulario o documento en formatos PKCS#7, CMS y XMLEncryption

1.1. Requisitos

Para la correcta utilización del componente cliente y de sus funcionalidades es necesario tener en cuenta cierto número de requisitos previos.

Dichos requisitos se detallan en el documento “AST-EFIRMA-InstalacionComponenteCliente”

Indicar que para seguir las buenas prácticas de seguridad las aplicaciones que hagan uso del componente de firma deberían publicarse bajo HTTPS y no HTTP.






2. Instalación

Cuando se acceda a una aplicación web que haga uso del componente cliente, si éste no estaba instalado con anterioridad en el equipo cliente o es una versión posterior al instalado, se lanzara el proceso de instalación automáticamente.

El proceso de instalación/desinstalación se detalla en el documento “AST-EFIRMA-InstalacionComponenteCliente”






3. Integración

3.1. Orden lógico del flujo de invocación

Este punto recoge el orden lógico de invocación de los procedimientos anteriores:

1. Inicialización del componente y librerías Javascript

2. Obtención de certificados para firmar

3. Invocar la función necesaria para la funcionalidad requerida

a. Firma de datos

b. Firma de fichero

c. Firma de fichero por bloques (para ficheros grandes)

d. Añadir firmantes secuencialmente a firmas ya generadas

e. Añadir firmantes de forma paralela a firmas ya generadas

f. Cifrado/Descifrado de datos

g. Cifrado/Descifrado de fichero

3.2. Entornos

Dependiendo de si la aplicación invocante requiere el uso de firmas XML, el javascript será diferente

Cliente Básico Cliente Completo (firmas XML)

URL https://XXX.aragon.es/websigner/js/WS.js https://XXX.aragon.es/websigner/js/WS_Full.js

Si el desarrollo de la aplicación se realiza desde fuera del entorno corporativo, será necesario apuntar al entorno de https://prefirmaelectronica.aragon.es/websigner ya que el entorno de desarrollo no es accesible desde fuera.

3.3. Carga del componente

Se han detectado problemas de sincronización en el motor Javascript de Mozilla Firefox , con el fin de evitar dichos problemas se recomienda realizar la carga del código javascript de forma asíncrona. El código siguiente realiza la inicialización del componente cliente y se mantiene en espera mientras el objeto no se encuentra completamente disponible (este control se realiza mediante la función isWSLoaded()).

function init(){






initWebSigner(ST_PRI_KEY); init_rec();

} function init_rec(){

if(isWSLoaded()){ init_real(); }else{ window.setTimeout(init_rec,2000); }

} function init_real(){

//Código real del init. }

Debido al problema anteriormente citado, se han detectado problemas con la sincronización por medio de onload, por lo que se recomienda controlar la existencia de la función init antes de realizar la llamada. El código siguiente verifica la existencia de la función init y se mantiene a la espera mientras esto no sea así.

<body onload="function wait4init(){ if(window.init) { init(); }else{ window.setTimeout('wait4init()',2000); }}; wait4ini t();">

Además pueden darse problemas con la utilización de arrays como parámetros para funciones java desde el navegador, se recomienda evitar su utilización por medio de variables internas de java y la implementación de métodos add, remove y clear para su inicialización y manipulación, en caso de ser necesarias este tipo de estructuras.

Se ha detectado que en determinadas condiciones, principalmente en conexiones lentas, aparecen errores con variables javascript no inicializadas notificando por la consola de errores que dicha variba es “undefined”. Para solucionar este problema el componente cliente provee una función javascript (“isJSLoaded ”) que comprueba que los scripts de websigner se han cargado.

La función init modificada que utiliza esta función antes de iniciar el componente cliente quedaría de la siguiente forma:

Function init(){ if(window.isJSLoaded && isJSLoaded()){

initWebSigner(ST_ALL_KEY); init_rec();

}else{ window.setTimeout(init, 500);

}}

El control de la carga de cada script se realiza mediante una variable inicializada al final de cada script con el valor true.

3.4. Diferencias y limitaciones de las funciones de firma

En este punto se comentan las diferencias entre las distintas clases de funciones que se encuentran disponibles para realizar firmas con el componente cliente junto con sus limitaciones, además de cuando deben usarse.

Para la firma de datos se pueden utilizar las siguientes funciones, dependiendo de si se firma un formulario o un fichero. Si se especifica el certificado con el que se firma a partir de un índice respecto a la lista de certificados, o a partir del emisor y el número de serie del certificado.






Nos encontramos con los tipos de función: sign, signFile, signFileOneStep, signFileToFileOneStep, signFileByBlockOneStep y si gnHash

3.4.1. Firma de datos

A continuación se enumeran las funciones que permiten realizar la firma, indicando los datos a firmar directamente (sin informarlos en Base64) y sus limitaciones.

3.4.1.1. Funciones sign

Reciben como datos a firmar una cadena de texto que es procesada y firmada. Devolverá un base64. Esta función es usada para firmar documentos de tamaño reducido.

- signByIssuerAndSerialNumber(sIssuer, sSerialNumbe r, sData, bDetached, sFormat, sHashAlgorithm, envelopetype, signElement, parent, bSignDate, sIdCert, sPolicyIdentifier, sSignerRole, bIncludeSigningCert ificate, sDataObjectFormat, soverrideuri, sEncode, sSigningCertificateAndKeyInf oCombination, sAvoidXPathTransform, sAttachedCertPathLength, sCon tentHintsContentTypeOID, sContentHintsContentDescription, sPrecalculatedPoli cyHash, sPrecalculatedPolicyHashAlgorithm, sPolicyURI, sPol icyDescription, sCountryName, sLocalityName, sPostalCode, sStateOrProvince, sPost alAddresses, sSelectedCommitmentTypeOID, sSelectedCommitmentType URL, sSelectedCommitmentTypeDescription) - signByIndex(iCertificatePos, sData, bDetached, sF ormat, sHashAlgorithm, envelopetype, signElement, parent, bSignDate, sIdCe rt, sPolicyIdentifier, sSignerRole, bIncludeSigningCertificate, sDataObjec tFormat, soverrideuri, sEncode, sSigningCertificateAndKeyInfoCombination, sAvoidXPa thTransform, sAttachedCertPathLength, sContentHintsContentTypeOI D, sContentHintsContentDescription, sPrecalculatedPoli cyHash, sPrecalculatedPolicyHashAlgorithm, sPolicyURI, sPol icyDescription, sCountryName, sLocalityName, sPostalCode, sStateOrProvince, sPost alAddresses, sSelectedCommitmentTypeOID, sSelectedCommitmentType URL, sSelectedCommitmentTypeDescription)

3.4.1.2. Limitaciones de las funciones sign

Limitación en el tamaño a almacenar en una variable javascript

� Hay una limitación de tamaño en las variables javascript. (En las pruebas realizadas se observan problemas a partir de 4MB ó 7MB en función del equipo). Por este motivo, no es posible asignar 4MB en Base64 a una variable javascript.

� Esta limitación aplica a las funciones cuyo resultado se debería "almacenar" en una variable. (getFile, firma attached, etc.).

Limitación en el tamaño del documento a firmar por el applet (limitación de la JRE)

� Hay una limitación en el tamaño del fichero a firmar por la JRE (puede dar problemas de rendimiento a partir de 2 Megas), esta limitación se puede eliminar aumentando la memoria asignada a la maquina virtual desde el panel de control. Ver punto 4.3 donde se explica como solventar la limitación de la JRE.

Para no tener estos problemas se recomienda usar los métodos ByBlock que están preparados para trabajar con ficheros grandes, se explican en el punto 3.4.2.7.






3.4.2. Firma de fichero

Para la firma en fichero existen distintas opciones que se comentan a continuación.

3.4.2.1. Funciones signFile

Las funciones enumeradas a continuación esperan el contenido a firmar en Base64, por este motivo, es conveniente o bien llamar a la función getFile() previamente, o calcular el Base64 del contenido del fichero antes de invocar a las funciones.

- signFileByIndex(iCertificatePos, bDetached, sForm at, sHashAlgorithm, sContent, envelopetype, signElement, parent, bSignDate, sIdCe rt, sPolicyIdentifier, sSignerRole, bIncludeSigningCertificate, sDataObjec tFormat, sEncode, sSigningCertificateAndKeyInfoCombination, sAvoidXPa thTransform, sAttachedCertPathLength, sContentHintsContentTypeOI D, sContentHintsContentDescription, sPrecalculatedPoli cyHash, sPrecalculatedPolicyHashAlgorithm, sPolicyURI, sPol icyDescription, sCountryName, sLocalityName, sPostalCode, sStateOrProvince, sPost alAddresses, sSelectedCommitmentTypeOID, sSelectedCommitmentType URL, sSelectedCommitmentTypeDescription) - signFileByIssuerAndSerialNumber(sIssuer,sSerialNu mber, bDetached, sFormat, sHashAlgorithm, sContent, envelopetype, signElement , parent, bSignDate, sIdCert, sPolicyIdentifier, sSignerRole, bIncludeSigningCert ificate, sDataObjectFormat, sEncode, sSigningCertificateAndKeyInfoCombination, sAvoidXPathTransform, sAttachedCertPathLength, sContentHintsContentTypeOI D, sContentHintsContentDescription, sPrecalculatedPoli cyHash, sPrecalculatedPolicyHashAlgorithm, sPolicyURI, sPol icyDescription, sCountryName, sLocalityName, sPostalCode, sStateOrProvince, sPost alAddresses, sSelectedCommitmentTypeOID, sSelectedCommitmentType URL, sSelectedCommitmentTypeDescription) - getFile() //Función a invocar para calcular el Ba se64 del fichero antes de invocar a las funciones enumeradas anteriormente.

3.4.2.2. Limitaciones de las funciones signFile

Limitación en el tamaño a almacenar en una variable javascript *

Limitación en el tamaño del documento a firmar por el applet (limitación de la JRE)*

* explicadas en el apartado de limitaciones del punto 3.4.1.2

3.4.2.3. Funciones signFileOneStep

Las funciones OneStep abren el archivo binario directamente por path y no hacen esta conversión. Con las funciones OneStep se ahorra la conversión de Base64 a binario. Estas funciones son, en teoría, más rápidas (aunque la diferencia seguramente no sea apreciable).

- signFileByIndexOneStep(iCertificatePos, bDetached , sFormat, sHashAlgorithm, envelopetype, signElement, parent, bSignDate, sIdCe rt, sPathDocument, sPolicyIdentifier, sSignerRole, bIncludeSigningCert ificate, sDataObjectFormat, sEncode, sSigningCertificateAndKeyInfoCombination, sAvoidXPathTransform, sAttachedCertPathLength, sContentHintsContentTypeOI D, sContentHintsContentDescription, sPrecalculatedPoli cyHash, sPrecalculatedPolicyHashAlgorithm, sPolicyURI, sPol icyDescription, sCountryName, sLocalityName, sPostalCode, sStateOrProvince, sPost alAddresses, sSelectedCommitmentTypeOID, sSelectedCommitmentType URL, sSelectedCommitmentTypeDescription)






- signFileByIssuerAndSerialNumberOneStep(sIssuer, s SerialNumber, bDetached, sFormat, sHashAlgorithm, envelopetype, signElement, parent, bSignDate, sIdCert, sPathDocument,sPolicyIdentifier, sSignerRole, bIncl udeSigningCertificate, sDataObjectFormat, sEncode, sSigningCertificateAndK eyInfoCombination, sAvoidXPathTransform, sAttachedCertPathLength, sCon tentHintsContentTypeOID, sContentHintsContentDescription, sPrecalculatedPoli cyHash, sPrecalculatedPolicyHashAlgorithm, sPolicyURI, sPol icyDescription, sCountryName, sLocalityName, sPostalCode, sStateOrProvince, sPost alAddresses, sSelectedCommitmentTypeOID, sSelectedCommitmentType URL, sSelectedCommitmentTypeDescription)

3.4.2.4. Limitaciones de las funciones signFileOneS tep

Limitación en el tamaño a almacenar en una variable javascript *

Limitación en el tamaño del documento a firmar por el applet (limitación de la JRE)*:

La limitación del javascript únicamente afecta si las firmas a realizar son attached.


3.4.2.5. Funciones signFileToFileOneStep

Las funciones enumeradas a continuación esperan que se indique la ruta del fichero a firmar y la ruta del fichero donde se almacenará el resultado de la operación. En caso de que no se informe de alguna o de ambas de las rutas, el componente mostrará un cuadro de diálogo que permitirá al usuario seleccionar los ficheros.

- signFileToFileByIndexOneStep(iCertificatePos, bDe tached, sFormat, sHashAlgorithm, envelopetype, signElement, parent, bSignDate, sIdCert, sPathDocument, sPolicyIdentifier, sSignerRole, bInc ludeSigningCertificate, sDataObjectFormat, sEncode, sPathFileToReturn, sSigningCertificateAndKeyInfoCombination, sAvoidXPa thTransform, sAttachedCertPathLength, sContentHintsContentTypeOI D, sContentHintsContentDescription, sPrecalculatedPoli cyHash, sPrecalculatedPolicyHashAlgorithm, sPolicyURI, sPol icyDescription, sCountryName, sLocalityName, sPostalCode, sStateOrProvince, sPost alAddresses, sSelectedCommitmentTypeOID, sSelectedCommitmentType URL, sSelectedCommitmentTypeDescription) - signFileToFileByIssuerAndSerialNumberOneStep(sIss uer,sSerialNumber, bDetached, sFormat, sHashAlgorithm, sPathDocument, envelopetyp e, signElement, parent, bSignDate, sIdCert, sPolicyIdentifier, sSignerRole, bIncludeSigningCertificate, sDataObjectFormat, sEncode, sPathFileToReturn, sSigningCertificateAndKeyInfoCombination, sAvoidXPa thTransform, sAttachedCertPathLength, sContentHintsContentTypeOI D, sContentHintsContentDescription, sPrecalculatedPoli cyHash, sPrecalculatedPolicyHashAlgorithm, sPolicyURI, sPol icyDescription, sCountryName, sLocalityName, sPostalCode, sStateOrProvince, sPost alAddresses, sSelectedCommitmentTypeOID, sSelectedCommitmentType URL, sSelectedCommitmentTypeDescription)

3.4.2.6. Limitaciones de las funciones signFileToFi leOneStep

Limitación en el tamaño del documento a firmar por el applet (limitación de la JRE)*:







3.4.2.7. Funciones signFileByBlockOneStep

Para ficheros grandes. Se firma de fichero a fichero.

- signFileByBlockByIndexOneStep(iCertificatePos, bD etached, sFormat, sHashAlgorithm, envelopetype, signElement, parent, bSignDate, sIdCert, sPathDocument, sPolicyIdentifier, sSignerRole, bInc ludeSigningCertificate, sDataObjectFormat, sEncode, sPathFileToReturn, sSigningCertificateAndKeyInfoCombination, sAvoidXPa thTransform, sAttachedCertPathLength, sContentHintsContentTypeOI D, sContentHintsContentDescription, sPrecalculatedPoli cyHash, sPrecalculatedPolicyHashAlgorithm, sPolicyURI, sPol icyDescription, sCountryName, sLocalityName, sPostalCode, sStateOrProvince, sPost alAddresses, sSelectedCommitmentTypeOID, sSelectedCommitmentType URL, sSelectedCommitmentTypeDescription) - signFileByBlockByIssuerAndSerialNumberOneStep(sIs suer,sSerialNumber, bDetached, sFormat, sHashAlgorithm, sPathDocument, envelopetyp e, signElement, parent, bSignDate, sIdCert, sPolicyIdentifier, sSignerRole, bIncludeSigningCertificate, sDataObjectFormat, sEncode, sPathFileToReturn, sSigningCertificateAndKeyInfoCombination, sAvoidXPa thTransform, sAttachedCertPathLength, sContentHintsContentTypeOI D, sContentHintsContentDescription, sPrecalculatedPoli cyHash, sPrecalculatedPolicyHashAlgorithm, sPolicyURI, sPol icyDescription, sCountryName, sLocalityName, sPostalCode, sStateOrProvince, sPost alAddresses, sSelectedCommitmentTypeOID, sSelectedCommitmentType URL, sSelectedCommitmentTypeDescription)

Estas funciones deben usarse para firmar ficheros grandes y no se ven limitadas ni por las limitaciones del javascript ni por las de la JRE.

3.4.2.8. Funciones signHash

La función signHash* permite realizar la firma detached de un Fichero informándole el hash de este en Base64 evitando los problemas que el tamaño del fichero ocasiona a los métodos javascript y en la JRE (Al tratarse de una firma de un hash, con este método no se puede realizar una firma attached ya que esta necesita el binario entero del documento).

- signHashByIndex(iCertificatePos, sHashData, sForm at, sHashAlgorithm, envelopetype, parent, bSignDate, sIdCert, sPolicyId entifier, sPolicy, sSignerRole, bIncludeSigningCertificate, sDataObjectFormat, sRef Uri, sRefType, sRefId, aTransforms, aTransformsParams, sEncode, sSigningCertificateAndKeyInfoCombination, sAttache dCertPathLength, sContentHintsContentTypeOID, sContentHintsContentD escription, sPrecalculatedPolicyHash, sPrecalculatedPolicyHash Algorithm, sPolicyURI, sPolicyDescription, sCountryName, sLocalityName, sPostalCode, sStateOrProvince, sPostalAddresses, sSelectedComm itmentTypeOID, sSelectedCommitmentTypeDescription) - signHashByIssuerAndSerialNumber( sIssuer, sSeria lNumber, sHashData, sFormat, sHashAlgorithm, envelopetype, parent, bSignDate, sIdCert , sPolicyIdentifier, sPolicy, sSignerRole, bIncludeSigningCertificate, sDataObjectFormat, sRefUri, sRefType, sRefId, aTransforms, aTransformsParams, sEncode, sSigningCertificateAndKeyInfoCombination, sAttache dCertPathLength, sContentHintsContentTypeOID, sContentHintsContentD escription, sPrecalculatedPolicyHash, sPrecalculatedPolicyHash Algorithm, sPolicyURI, sPolicyDescription, sCountryName, sLocalityName, sPostalCode, sStateOrProvince, sPostalAddresses, sSelectedComm itmentTypeOID, sSelectedCommitmentTypeDescription)

Estas funciones deben usarse para firmar ficheros grandes y no se ven limitadas ni por las limitaciones del javascript ni por las de la JRE.






Si implementáis la firma múltiple en cliente, indicar que no hay alternativa de este método para realizar firma paralela o secuencial (informando únicamente el hash).

3.4.3. Firmas secuenciales

Para añadir firmantes de forma secuencial a firmas ya generadas usaremos las siguientes funciones:

3.4.3.1. Añadir Firmante Secuencial

Se informan los datos a firmar directamente

- addNestedSignByIndex(iCertificatePos, sSourceSign edData, bDetached, sFormat, sHashAlgorithm, envelopetype, signElement, parent, bSignDate, sIdCert, sPolicyIdentifier, sSignerRole, bIncludeSigningCert ificate, sDataObjectFormat, sEncode, sSigningCertificateAndKeyInfoCombination, sAttachedCertPathLength, sContentHintsContentTypeOID, sContentHintsContentDe scription, sPrecalculatedPolicyHash, sPrecalculatedPolicyHashA lgorithm, sPolicyURI, sPolicyDescription, sCountryName, sLocalityName, sP ostalCode, sStateOrProvince, sPostalAddresses, sSelectedCommitmentTypeOID, sSele ctedCommitmentTypeURL, sSelectedCommitmentTypeDescription) - addNestedSignByIssuerAndSerialNumber(sIssuer, sSe rialNumber, sSourceSignedData, bDetached, sFormat, sHashAlgorithm, envelopetype, s ignElement, parent, bSignDate, sIdCert, sPolicyIdentifier, sSignerRole, bIncludeSi gningCertificate, sDataObjectFormat, sEncode, sSigningCertificateAndK eyInfoCombination, sAttachedCertPathLength, sContentHintsContentTypeOI D, sContentHintsContentDescription, sPrecalculatedPoli cyHash, sPrecalculatedPolicyHashAlgorithm, sPolicyURI, sPol icyDescription, sCountryName, sLocalityName, sPostalCode, sStateOrProvince, sPost alAddresses, sSelectedCommitmentTypeOID, sSelectedCommitmentType URL, sSelectedCommitmentTypeDescription)

3.4.3.2. Añadir Firmante Secuencial desde fichero

Se informan los datos en Base64

- addNestedSignFileByIndex(iCertificatePos, sSource SignedData, bDetached, sFormat, sHashAlgorithm, envelopetype, signElement, parent, bSignDate, sIdCert, sPolicyIdentifier, sSignerRole, bIncludeSigningCert ificate, sDataObjectFormat, sEncode, sSigningCertificateAndKeyInfoCombination, sAttachedCertPathLength, sContentHintsContentTypeOID, sContentHintsContentDe scription, sPrecalculatedPolicyHash, sPrecalculatedPolicyHashA lgorithm, sPolicyURI, sPolicyDescription, sCountryName, sLocalityName, sP ostalCode, sStateOrProvince, sPostalAddresses, sSelectedCommitmentTypeOID, sSele ctedCommitmentTypeURL, sSelectedCommitmentTypeDescription) - addNestedSignFileByIssuerAndSerialNumber(sIssuer, sSerialNumber, sSourceSignedData, bDetached, sFormat, sHashAlgorit hm, envelopetype, signElement, parent, bSignDate, sIdCert, sPolicyIdentifier, sSig nerRole, bIncludeSigningCertificate, sDataObjectFormat, sEnc ode, sSigningCertificateAndKeyInfoCombination, sAttached CertPathLength, sContentHintsContentTypeOID, sContentHintsContentDe scription, sPrecalculatedPolicyHash, sPrecalculatedPolicyHashA lgorithm, sPolicyURI, sPolicyDescription, sCountryName, sLocalityName, sP ostalCode, sStateOrProvince, sPostalAddresses, sSelectedCommitmentTypeOID, sSele ctedCommitmentTypeURL, sSelectedCommitmentTypeDescription)






- getFile() //Función a invocar para calcular el Ba se64 del fichero antes de invocar a las funciones enumeradas anteriormente.

3.4.3.3. Añadir Firmante Secuencial Fichero a Fiche ro en un paso

En este caso el resultado de la operación se incluye en un fichero.

- addNestedSignFileToFileByIndexOneStep(iCertificat ePos, sPathDocument, bDetached, sFormat, sHashAlgorithm, envelopetype, signElement, parent, bSignDate, sIdCert, sPolicyIdentifier, sSignerRole, bIncludeSigningCert ificate, sDataObjectFormat, sEncode, sPathFileToReturn, sSigningCertificateAndK eyInfoCombination, sAttachedCertPathLength, sContentHintsContentTypeOI D, sContentHintsContentDescription, sPrecalculatedPoli cyHash, sPrecalculatedPolicyHashAlgorithm, sPolicyURI, sPol icyDescription, sCountryName, sLocalityName, sPostalCode, sStateOrProvince, sPost alAddresses, sSelectedCommitmentTypeOID, sSelectedCommitmentType URL, sSelectedCommitmentTypeDescription) - addNestedSignFileToFileByIssuerAndSerialNumberOne Step(sIssuer, sSerialNumber, sPathDocument, bDetached, sFormat, sHashAlgorithm, envelopetype, signElement, parent, bSignDate, sIdCert, sPolicyIdentifier, sSig nerRole, bIncludeSigningCertificate, sDataObjectFormat, sEnc ode, sPathFileToReturn, sSigningCertificateAndKeyInfoCombination, sAttached CertPathLength, sContentHintsContentTypeOID, sContentHintsContentDe scription, sPrecalculatedPolicyHash, sPrecalculatedPolicyHashA lgorithm, sPolicyURI, sPolicyDescription, sCountryName, sLocalityName, sP ostalCode, sStateOrProvince, sPostalAddresses, sSelectedCommitmentTypeOID, sSele ctedCommitmentTypeURL, sSelectedCommitmentTypeDescription)

3.4.3.4. Añadir Firmante Secuencial Fichero por blo ques

En este caso el resultado de la operación se incluye en un fichero. (Para ficheros grandes)

- addNestedSignFileByBlockByIndexOneStep(iCertifica tePos, sPathDocument, bDetached, sFormat, sHashAlgorithm, envelopetype, s ignElement, parent, bSignDate, sIdCert, sPolicyIdentifier, sSignerRole, bIncludeSi gningCertificate, sDataObjectFormat, sEncode, sPathFileToReturn, sSigningCertificateAndKeyInfoCombination, sAttached CertPathLength, sContentHintsContentTypeOID, sContentHintsContentDe scription, sPrecalculatedPolicyHash, sPrecalculatedPolicyHashA lgorithm, sPolicyURI, sPolicyDescription, sCountryName, sLocalityName, sP ostalCode, sStateOrProvince, sPostalAddresses, sSelectedCommitmentTypeOID, sSele ctedCommitmentTypeURL, sSelectedCommitmentTypeDescription) - addNestedSignFileByBlockByIssuerAndSerialNumberOn eStep(sIssuer, sSerialNumber, sPathDocument, bDetached, sFormat, sHashAlgorithm, envelopetype, signElement, parent, bSignDate, sIdCert, sPolicyIdentifier, sSig nerRole, bIncludeSigningCertificate, sDataObjectFormat, sEnc ode, sPathFileToReturn, sSigningCertificateAndKeyInfoCombination, sAttached CertPathLength, sContentHintsContentTypeOID, sContentHintsContentDe scription, sPrecalculatedPolicyHash, sPrecalculatedPolicyHashA lgorithm, sPolicyURI, sPolicyDescription, sCountryName, sLocalityName, sP ostalCode, sStateOrProvince, sPostalAddresses, sSelectedCommitmentTypeOID, sSele ctedCommitmentTypeURL, sSelectedCommitmentTypeDescription)

3.4.3.5. Restricciones de las firmas múltiples secu enciales

En la generación de firma en formato PKCS#7, CMS o CAdES, no tiene sentido:

� Añadir un firmante detached a algo ya firmado.

En la generación de firma en formato CAdES o XAdES, no tiene sentido:






� Añadir un firmante de un subtipo (BES, EPES,..) distinto a los subtipos de los firmantes ya existentes.

� No pueden existir varios firmantes CAdES-EPES o XAdES-EPES que tengan diferentes políticas, es decir, todas las firmas CAdES-EPES/XAdES-EPES de un objeto firmado deben tener la misma política.

En la generación de firma en formato XMLDSig, no tienen sentido los siguientes tipos de firma:

� Firma múltiple secuencial enveloped. La firma múltiple secuencial debe ser enveloping.

� Firma múltiple secuencial de una parte del documento, y no del documento completo. Cuando se añade un firmante de forma secuencial a algo ya firmado, no puede firmarse solamente una parte del xml, debe firmarse el xml entero, ya que se está firmando el resultado de una firma anterior.

� Añadir un firmante detached. Cuando se añade un firmante al resultado de una firma anterior, debe ser firma attached, ya que la firma detached en el caso del XMLDSig firma un documento accesible por una URI, y se está firmando una firma anterior, no un documento.

3.4.3.6. Limitaciones de las firmas múltiples secue nciales

En los métodos de firma secuencial existen los mismos tipos de función que en los métodos de firma (sign, signFile, signFileOneStep, signFileToFileOneStep y signFileByBlockOneStep) y las limitaciones que sufren estos son las mismas limitaciones que afectan a los métodos de firma (apartados 3.4.1 y 3.4.2 ).

3.4.4. Firmas paralelas

Para añadir firmantes de forma paralela a firmas ya generadas usaremos las siguientes funciones:

3.4.4.1. Añadir Firmante Paralelo

Se informan los datos a firmar directamente

- cosignByIndex(iCertificatePos, sSignedData, bDeta ched, sDetachedData, sFormat, sHashAlgorithm, envelopetype, signElement, parent, bSignDate, sIdCert, sPolicyIdentifier, sSignerRole, bIncludeSigningCert ificate, sDataObjectFormat, sEncode, sSigningCertificateAndKeyInfoCombination, sAttachedCertPathLength, sContentHintsContentTypeOID, sContentHintsContentDe scription, sPrecalculatedPolicyHash, sPrecalculatedPolicyHashA lgorithm, sPolicyURI, sPolicyDescription, sCountryName, sLocalityName, sP ostalCode, sStateOrProvince, sPostalAddresses, sSelectedCommitmentTypeOID, sSele ctedCommitmentTypeURL, sSelectedCommitmentTypeDescription) - cosignByIssuerAndSerialNumber(sIssuer, sSerialNum ber, sSignedData, bDetached, sDetachedData, sFormat, sHashAlgorithm, envelopetyp e, signElement, parent, bSignDate, sIdCert, sPolicyIdentifier, sSignerRole, bIncludeSigningCertificate,






sDataObjectFormat, sEncode, sSigningCertificateAndK eyInfoCombination, sAttachedCertPathLength, sContentHintsContentTypeOI D, sContentHintsContentDescription, sPrecalculatedPoli cyHash, sPrecalculatedPolicyHashAlgorithm, sPolicyURI, sPol icyDescription, sCountryName, sLocalityName, sPostalCode, sStateOrProvince, sPost alAddresses, sSelectedCommitmentTypeOID, sSelectedCommitmentType URL, sSelectedCommitmentTypeDescription)

3.4.4.2. Añadir Firmante Paralelo desde fichero

Se informan los datos en Base64

- cosignFileByIndex(iCertificatePos, sSignedData, b Detached, sDetachedData, sFormat, sHashAlgorithm, envelopetype, signElement, parent, bSignDate, sIdCert, sPolicyIdentifier, sSignerRole, bIncludeSigningCert ificate, sDataObjectFormat, sEncode, sSigningCertificateAndKeyInfoCombination, sAttachedCertPathLength, sContentHintsContentTypeOID, sContentHintsContentDe scription, sPrecalculatedPolicyHash, sPrecalculatedPolicyHashA lgorithm, sPolicyURI, sPolicyDescription, sCountryName, sLocalityName, sP ostalCode, sStateOrProvince, sPostalAddresses, sSelectedCommitmentTypeOID, sSele ctedCommitmentTypeURL, sSelectedCommitmentTypeDescription) - cosignFileByIssuerAndSerialNumber(sIssuer,sSerial Number, sSignedData, bDetached, sDetachedData, sFormat, sHashAlgorithm, envelopetyp e, signElement, parent, bSignDate, sIdCert, sPolicyIdentifier, sSignerRole, bIncludeSigningCertificate, sDataObjectFormat, sEncode, sSigningCertificateAndK eyInfoCombination, sAttachedCertPathLength, sContentHintsContentTypeOI D, sContentHintsContentDescription, sPrecalculatedPoli cyHash, sPrecalculatedPolicyHashAlgorithm, sPolicyURI, sPol icyDescription, sCountryName, sLocalityName, sPostalCode, sStateOrProvince, sPost alAddresses, sSelectedCommitmentTypeOID, sSelectedCommitmentType URL, sSelectedCommitmentTypeDescription) - getFile() //Función a invocar para calcular el Ba se64 del fichero antes de invocar a las funciones enumeradas anteriormente.

3.4.4.3. Añadir Firmante Paralelo Fichero a Fichero en un paso

En este caso el resultado de la operación se incluye en un fichero.

- cosignFileToFileByIndexOneStep(iCertificatePos, s PathDocumentSignedData, bDetached, sPathDocumentDetachedData, sFormat, sHas hAlgorithm, envelopetype, signElement, parent, bSignDate, sIdCert, sPolicyIde ntifier, sSignerRole, bIncludeSigningCertificate, sDataObjectFormat, sEnc ode, sPathFileToReturn, sSigningCertificateAndKeyInfoCombination, sAttached CertPathLength, sContentHintsContentTypeOID, sContentHintsContentDe scription, sPrecalculatedPolicyHash, sPrecalculatedPolicyHashA lgorithm, sPolicyURI, sPolicyDescription, sCountryName, sLocalityName, sP ostalCode, sStateOrProvince, sPostalAddresses, sSelectedCommitmentTypeOID, sSele ctedCommitmentTypeURL, sSelectedCommitmentTypeDescription) - cosignFileToFileByIssuerAndSerialNumberOneStep(sI ssuer,sSerialNumbe, sPathDocumentSignedData, bDetached, sPathDocumentDe tachedData, sFormat, sHashAlgorithm, envelopetype, signElement, parent, bSignDate, sIdCert, sPolicyIdentifier, sSignerRole, bIncludeSigningCert ificate, sDataObjectFormat, sEncode, sPathFileToReturn, sSigningCertificateAndK eyInfoCombination, sAttachedCertPathLength, sContentHintsContentTypeOI D, sContentHintsContentDescription, sPrecalculatedPoli cyHash, sPrecalculatedPolicyHashAlgorithm, sPolicyURI, sPol icyDescription, sCountryName, sLocalityName, sPostalCode, sStateOrProvince, sPost alAddresses, sSelectedCommitmentTypeOID, sSelectedCommitmentType URL, sSelectedCommitmentTypeDescription)






3.4.4.4. Añadir Firmante Paralelo Fichero por bloqu es

En este caso el resultado de la operación se incluye en un fichero. (Para ficheros grandes)

- cosignFileByBlockByIndexOneStep(iCertificatePos, sPathDocumentSignedData, bDetached, sPathDocumentDetachedData, sFormat, sHas hAlgorithm, envelopetype, signElement, parent, bSignDate, sIdCert, sPolicyIde ntifier, sSignerRole, bIncludeSigningCertificate, sDataObjectFormat, sEnc ode, sPathFileToReturn, sSigningCertificateAndKeyInfoCombination, sAttached CertPathLength, sContentHintsContentTypeOID, sContentHintsContentDe scription, sPrecalculatedPolicyHash, sPrecalculatedPolicyHashA lgorithm, sPolicyURI, sPolicyDescription, sCountryName, sLocalityName, sP ostalCode, sStateOrProvince, sPostalAddresses, sSelectedCommitmentTypeOID, sSele ctedCommitmentTypeURL, sSelectedCommitmentTypeDescription) - cosignFileByBlockByIssuerAndSerialNumberOneStep(s Issuer, sSerialNumber, sPathDocumentSignedData, bDetached, sPathDocumentDe tachedData, sFormat, sHashAlgorithm, envelopetype, signElement, parent, bSignDate, sIdCert, sPolicyIdentifier, sSignerRole, bIncludeSigningCert ificate, sDataObjectFormat, sEncode, sPathFileToReturn, sSigningCertificateAndK eyInfoCombination, sAttachedCertPathLength, sContentHintsContentTypeOI D, sContentHintsContentDescription, sPrecalculatedPoli cyHash, sPrecalculatedPolicyHashAlgorithm, sPolicyURI, sPol icyDescription, sCountryName, sLocalityName, sPostalCode, sStateOrProvince, sPost alAddresses, sSelectedCommitmentTypeOID, sSelectedCommitmentType URL, sSelectedCommitmentTypeDescription)

3.4.4.5. Restricciones de las firmas múltiples para lelas

En la generación de firma en formato CAdEs o XAdES, no tiene sentido:

� No pueden existir varios firmantes CAdES-EPES o XAdES-EPES que tengan diferentes políticas, es decir, todas las firmas CAdES-EPES/XAdES-EPES de un objeto firmado deben tener la misma política.

En la generación de firma en formato XMLDSig, no tienen sentido los siguientes tipos de firma:

� Firma múltiple paralela enveloping. La firma múltiple paralela debe ser enveloped.

� Añadir un firmante detached. Cuando se añade un firmante al resultado de una firma anterior, debe ser firma attached, ya que la firma detached en el caso del XMLDSig firma un documento accesible por una URI, y se está firmando una firma anterior, no un documento.

� Añadir un firmante en paralelo al resultado de una firma enveloping anterior.

3.4.4.6. Limitaciones de las firmas múltiples paral elas

En los métodos de firma paralela existen los mismos tipos de función que en los métodos de firma (sign, signFile, signFileOneStep, signFileToFileOneStep y signFileByBlockOneStep) y las limitaciones que sufren estos son las mismas limitaciones que afectan a los métodos de firma (apartados 3.4.1 y 3.4.2 ).

IMPORTANTE: Si se realizan firmas paralelas detached en las cuales los datos originales se hayan modificado y no se verifique la integridad de los mismos, podrían llegarse a realizar firmas erróneas que no se pudieran verificar.






Por este motivo, es responsabilidad de la aplicación que se integra con el componente verificar la integridad de los datos antes de añadir nuevos firmantes a una firma paralela-detached.






4. FAQs

Durante la explotación revise la consola de java, ya que esta da información detallada de lo que esta sucediendo en el Applet.

4.1. Problemas con inputFile

En algunas versiones de IExplorer y Firefox el value retornado por el input de tipo File no contiene el path entero, en su lugar devuelve únicamente el nombre por motivos de seguridad.

Esto puede ocasionar problemas en integraciones que utilicen el inputFile para solicitar al usuario el path y posteriormente utilizar la funcionalidad getFileByPath.

Como evitar este problema:

- En caso de no querer utilizar el path es recomendable el uso de la función getFile() del Applet de WebSigner. Esta función genera un FileDialog equivalente al inputFile evitando el problema.

- En caso de necesitar el path en la integración para mostrarlo o almacenarlo se podría usar un inputFile especial que evite el problema de la pérdida del path. Como orientación se dispone de un ejemplo en el siguiente link

(https://bug143220.bugzilla.mozilla.org/attachment.cgi?id=328849).

4.2. Error en la carga de las librerías del applet

Se ha observado que, en determinadas casuísticas, si se importan las librerías javascript asociadas al componente (WS.js o WS_Full.js) de forma relativa sin especificar el dominio donde se importan, por ejemplo:

<script language="javascript" src="firma/js/WS.js" type="text/javascript"></script>

se producen distintos errores de librerías no encontradas al ejecutar los applet. Es necesario por tanto importar la librería de forma absoluta, especificando el dominio, por ejemplo:

<script language="javascript" src="https://prefirmaelectronica.aragon.es/websigner/js/WS.js" type="text/javascript"></script>

El valor resaltado debe ser configurado a través de un valor en un fichero .properties para facilitar despliegue por entorno. (Ver Manual de Integración General para la URL a aplicar en cada entorno)






4.3. Como aumentar memoria para evitar limitación d e la JRE

Para no tener que realizar estar tareas se recomienda utilizar los métodos ByBlock que están preparados para trabajar con ficheros grandes , en el caso que no se puedan modificar estos métodos para poder firmar documentos de tamaño superior a 4 MB es necesario configurar el PC del usuario de la aplicación que usa el componente, siguiendo las siguientes indicaciones.

4.3.1. Configuración memoria virtual

En la configuración por defecto del plug-in de Java el tamaño máximo de datos a firmar es de 2MB. En caso de querer firmar ficheros más grandes hay que modificar la configuración del plugin para añadir los parámetros “–Xmx” y “–Xms” con los valores elegidos. Los pasos para poder realizar los cambios en la memoria virtual de Java son los siguientes:

Paso 1 : Seleccionamos la consola de Java dentro del panel de control de Windows.

Paso 2: Al ejecutar la consola de Java, nos aparecerá el siguiente panel, donde tenemos que seleccionar la pestaña de Java y pulsar el botón “Ver”






Paso 3 : En la ventana de configuración, tenemos que indicar el tamaño de memoria virtual de java que queramos asignar a la jdk que estemos usando en nuestro proceso. El tamaño se indica en el bloque “Parametros del entorno de ejecución” en función de los valores en la tabla anterior.






NOTA: El valor por defecto de la memoria de la máquina virtual de Java es –Xmx64m. Para poder realizar firmas con documentos de mayor tamaño se debe subir este valor, siendo este dependiente de la memoria física que tenga el equipo. Los parámetros que se indican son –Xmx<valor>m/G, donde ‘m’ son megabytes y G son gigabytes.

Cada vez que se actualice JAVA, será necesario real izar la configuración de memoria desde el panel de control.

servicio de firma electrónica de gobierno de...

Documents