Manual del integrador del MiniApplet v1.2 del

Transcripción

1 ADMINISTRATIVA, PROCEDIMIENTOS E IMPULSO DE LA ADMINISTRACIÓN ELECTRÓNICA Manual del integradr del MiniApplet v1.2 del

2 Índice de cntenids 1Intrducción Prducts de tercers incluids cn el...3 2Requisits mínims Entrn Cliente Cmpatibilidad cn Windws Cmpatibilidad cn Mac OS X Dispsitivs móviles Entrn Servidr...5 3Funcinalidad prprcinada pr el Frmats de firma sprtads pr el CAdES (CMS Advanced Electrnic Signature) XAdES (XML Advanced Electrnic Signature) FacturaE (Factura electrónica) PAdES (PDF Advanced Electrnic Signature) Frmats de firma n sprtads pr el Us de certificads y claves privadas pr parte del Establecimient manual del almacén de certificads y claves Frzar ruta del almacén de Mzilla Firefx Despliegue del Imprtación de las biblitecas JavaScript Imprtación en páginas Web generadas dinámicamente Carga del MiniApplet Cnfiguración del idima Restricción según desfase hrari cn el servidr Firma del JAR del MiniApplet El prces de firma electrónica Selección del cntenid a firmar La cnversión de dats a Base

3 5.1.2Selección de cntenid desde fichers en disc Selección de bjetiv de las cntrafirmas Selección del certificad y clave privada de firma Firma Recgida de resultads Funcines dispnibles del Us del API desde JavaScript Obtención de resultads Obtención directa de resultads Obtención de resultads mediante Callbacks Firma electrónica Firmas electrónicas múltiples Cfirmas Cntrafirmas Firmas/Multifirmas trifásicas Realizar firma trifásicas cn el 6.5.2Servici de firma trifásica Firmas/Multifirmas masivas Gestión de fichers Guardad de dats en disc Selección de un ficher pr parte del usuari y recuperación de su nmbre y cntenid Selección de múltiples fichers pr parte del usuari y recuperación de sus nmbres y cntenids Utilidad Ec Obtención de ls mensajes de errr Cnversión de una cadena Base64 a text Cnversión de un text a cadena Base Cnfiguración de las peracines Pas de parámetrs adicinales a ls métds de firma, cfirma y cntrafirma

4 7.2Selección autmática de certificads Cnfiguración del filtr de certificads Cnfiguración de la plítica de firma Cnfiguración manual Plítica de firma de la AGE v Plítica de firma de Factura electrónica (Facturae) Gestión de errres Cmpatibilidad cn dispsitivs móviles Arquitectura del sistema Despliegues cmpatibles Servicis auxiliares del móvil Ntificacines al usuari Enlaces de descarga Enlaces Andrid Enlaces ios Limitacines Limitacines de frmat Limitacines funcinales Infrmación específica para firmas CAdES Algritms de firma Parámetrs adicinales Firma y cfirma Cntrafirma Infrmación específica para firmas XAdES Tratamient de las hjas de estil XSL de ls XML a firmar Algritms de firma Parámetrs adicinales Firma y cfirma Cntrafirma Infrmación específica para firma de facturas electrónicas Operacines n sprtadas y ntas de interés Algritms de firma

5 11.3Parámetrs adicinales Infrmación específica para firmas PAdES Operacines n sprtadas y ntas de interés Algritms de firma Parámetrs adicinales Prblemas cncids Errr al firmar fichers mayres de 4 megabytes Cn el navegadr Mzilla Firefx y DNIe (DNI Electrónic) el applet se queda blquead y n muestra el diálg de selección de certificads, desblqueándse si retir el DNIe del lectr N se detecta la inserción/extracción del DNIe en el lectr (u tra tarjeta inteligente) El applet n detecta ningún certificad baj Mzilla / Firefx El MiniApplet n permite la firma de PDF cn cierts certificads

6 1 Intrducción El es una herramienta de firma electrónica que funcina en frma de applet de Java integrad en una página Web mediante JavaScript. El Cliente hace us de ls certificads digitales X.509v3 y de las claves privadas asciadas a ests que estén instalads en el repsitri almacén de claves y certificads (KeyStre) del sistema perativ del navegadr Web (Internet Explrer, Mzilla Firefx, etc.), así cm de ls que estén en dispsitivs (tarjetas inteligentes, dispsitivs USB) cnfigurads en el mism (cm pr ejempl, el DNI Electrónic DNIe). El Cliente de Firma, cm su nmbre indica, es una aplicación que se ejecuta en cliente (en el rdenadr del usuari, n en el servidr Web). Est es así para evitar que la clave privada asciada a un certificad tenga que salir del cntenedr del usuari (tarjeta, dispsitiv USB navegadr) ubicad en su PC. De hech, nunca llega a salir del navegadr, el Cliente le envía ls dats a firmar y éste ls devuelve firmads. El n almacena ningún tip de infrmación persnal del usuari, ni hace us de ckies ni ningún tr mecanism para la gestión de dats de sesión. El es Sftware Libre publicad que se puede usar, a su elección, baj licencia GNU General Public License versión 2 (GPLv2) superir baj licencia Eurpean Sftware License 1.1 (EUPL 1.1) superir. Puede cnsultar la infrmación relativa al pryect dentr del cual se encuentra el y descargar ls fuentes de la aplicación en la siguiente dirección Web: Tant ls binaris cm ls fichers fuente empaquetads pueden descargarse desde: Prducts de tercers incluids cn el El incluye, entre trs, ls siguientes prducts de tercers: JXAdES ( BuncyCastle ( 6

7 Códig derivad de itext v2.1.7 ( Códig derivad de Apache ORO ( Códig derivad de Java Mime Magic Library ( Códig derivad de Juniversalchardet ( Códig derivad de OpenJDK ( 7

8 2 Requisits mínims 2.1 Entrn Cliente Entrn de ejecución de Java: Java SE 6 Update 38 (1.6.0_38) superir, en 32 (x86) Java SE 7 Update 10 (1.7.0_10) superir en 32 (x86) 64 (x64/amd64) bits Sistema perativ: Windws XP SP3, Vista SP2, 7 SP1, 8 superir, en 32 (x86) 64 (x64) bits Windws Server 2003 R2 SP2 superir, en 32 (x86) 64 (x64) bits Linux 2.6 superir (sprte prestad para Ubuntu y Guadalinex), en 32 (x86) 64 (x64/amd64) bits Mac OS X Snw Lepard ( superir), Lin ( superir) Muntain Lin ( superir) Navegadr Web: Mzilla Firefx 4.0 superir En Windws únicamente se sprta Firefx en 32 bits. Ggle Chrme 15 superir Apple Safari 5 superir Micrsft Internet Explrer 7 superir, en bits Nta para usuaris de Firefx 9 superir y Windws XP Windws Server 2003: La carga del almacén de claves y certificads de Firefx 9 superir pr parte del necesita que el sistema tenga instalad el entrn de ejecución redistribuible de Micrsft Visual C Si n cnsigue acceder a sus certificads y claves privadas desde el, necesitará descargarl e instalarl manualmente. Este puede descargarse de: Windws XP y Windws Server 2003 en arquitectura x86: Windws XP y Windws Server 2003 en arquitectura x64: El prces de instalación puede requerir permiss de administradr. 8

9 2.1.1 Cmpatibilidad cn Windws 8 El n es cmpatible cn Internet Explrer 10 y superires en su versión Metr, y debe ser ejecutad cn la versión de escritri de Internet Explrer. Para autmatizar en cierta manera el cambi de Internet Explrer desde Metr hasta el escritri clásic de Windws 8 se debe incluir la siguiente meta-infrmación en la cabecera de la página HTML: <meta http-equiv="x-ua-cmpatible" cntent="requiresactivex=true"/> Puede encntrar más infrmación sbre cmplements de navegadr (plugins) en Internet Explrer sbre Metr en Windws 8 en: x Cmpatibilidad cn Mac OS X Java en versines psterires a la actualización de Apple La actualización de Apple Java para OS X deshabilita pr cmplet la ejecución de applets de Java y aplicacines Java WebStart en navegadres Web, intrduciend una incmpatibilidad ttal cn el Puede slventar este incnveniente de ds frmas alternativas: 1. Vlviend a habilitar manualmente el sprte de applets de Java y aplicacines Java WebStart siguiend las instruccines descritas en la siguiente página Web: 2. Instaland Oracle JRE 7 para Mac OS X a. Es imprtante tener en cuenta que Oracle JRE 7 es incmpatible cn las versines de 32 bits del navegadr Web Ggle Chrme (las únicas actualmente dispnibles) Java en versines psterires a la actualización de Apple Pr defect, tras instalar la actualización de Java de Apple, Mac OS X n permite la ejecución de applets aplicacines Java Web Start, l cual prvca que el n funcine. Para habilitar ls applets de Java y las aplicacines Web Start en Mac OS X es necesari indicarl desde el panel de Preferencias de Java dentr de las Preferencias generales de Mac OS X y marcar la casilla Activar módul de Applet y aplicacines Web Start. 9

10 Cm medida de seguridad, si el usuari n ejecuta applets de Java pr un perid de tiemp prlngad, Mac OS X deshabilita autmáticamente la ejecución de applets y aplicacines Java Web Start, pr l que será necesari cmprbar que esta ejecución está permitida antes de iniciar el MiniApplet independientemente de si esta ejecución ya fue habilitada anterirmente Muntain Lin ( y superires) Mac OS X Muntain Lin intrduce, cm medida de seguridad una restricción a la ejecución de aplicacines descargadas a través de Internet, cm sn ls applets de Java. Pr defect, Mac OS X n permite esta ejecución a mens las aplicacines se hayan descargad a través de la Apple Mac App Stre ( eventualmente que el desarrlladr que firma la aplicación esté autrizad pr la prpia Apple). Para permitir la ejecución del descargad desde una página Web nrmal, es necesari indicarl mediante la pción de Seguridad y Privacidad (dentr de Preferencias) de Mac OS X marcand la pción Permitir aplicacines descargadas de: Cualquier siti. 10

11 2.2 Dispsitivs móviles Ls applets Java, cm el, n puede ejecutarse desde dispsitivs Andrid, ios Windws RT/Phne; sin embarg, el crrect despliegue del MiniApplet hará que sus aplicacines puedan ejecutar las peracines de firma utilizand las aplicacines nativas del para ests sistemas en lugar del MiniApplet. Cnsulte el apartad Cmpatibilidad cn dispsitivs móviles para saber más. 2.3 Entrn Servidr Servidr de aplicacines JEE cmpatible cn Servlets de Java. Apache Tmcat, Oracle GlassFish, RedHat JBss, IBM WebSphere, Oracle Applicatin Server, etc. JRE 1.6 superir (recmendada última versión dispnible de Java 7). Es psible realizar un despliegue del en un sistema servidr que cuente únicamente cn un servidr Web (cm Apache Web Server) cn un servidr de aplicacines n cmpatible cn JEE (cm Micrsft Internet Infrmatin Server, IIS). 11

12 3 Funcinalidad prprcinada pr el El prprcina únicamente funcinalidades de firma electrónica (incluyend multifirmas) sbre un cnjunt select de frmats de firma, per n tras funcinalidades cm sbres digitales cifrads simétrics. Adicinalmente, se prprcina un cnjunt reducid de métds de utilidad y pcines de peración. Si necesita un frmat de firma n sprtad pr el MiniApplet una funcinalidad n sprtada pr este, cnsulte el catálg de para determinar cuál es la más aprpiada para sus necesidades. 3.1 Frmats de firma sprtads pr el CAdES (CMS Advanced Electrnic Signature) Frmat avanzad de firma binaria. Se sprtan las siguientes variantes de CAdES: CAdES-BES CAdES-EPES En cualquier cas, es psible siempre incluir el cntenid firmad en la prpia firma (firma implícita) excluirl (firma explícita). Pr defect, n se incluyen en la firma ni ls dats firmads, ni plítica de firma alguna. Es decir, cuand n se intrduce ninguna cnfiguración, se generan firmas CAdES-BES explícitas. Cnsulte el apartad Infrmación específica para firmas CAdES para más infrmación sbre la cnfiguración de las firmas CAdES XAdES (XML Advanced Electrnic Signature) Se sprtan las siguientes variantes de XAdES: XAdES-BES XAdES-EPES Cn independencia de la variante, es psible realizar las firmas XAdES en tres diferentes mds: Envelping Envelped Internally Detached 12

13 Cnsulte el apartad Infrmación específica para firmas XAdES para más infrmación sbre ls mds de firma XAdES y trs cndicinantes de us. Pr defect, cuand n se indican parámetrs de cnfiguración adicinales, el MiniApplet genera firmas XAdES-BES envelping FacturaE (Factura electrónica) Frmat para la firma de facturas electrónicas cnfrme a la especificación 3.1 del estándar. Al cnfigurar este frmat se establecen tdas sus prpiedades bligatrias, cm la plítica de firma, pr l que n deberán establecerse manualmente. El frmat de factura electrónica n permite cfirma ni cntrafirmar las facturas. Cnsulte el apartad Infrmación específica para firma de facturas electrónicas para más infrmación sbre las pcines de cnfiguración de las facturas electrónicas PAdES (PDF Advanced Electrnic Signature) Frmat de firma avanzada de dcuments PDF. Se sprtan las siguientes variantes de PAdES: PAdES-Simple PAdES-BES Una salvedad en la realización de firmas PAdES cn respect al estándar, es que n se sprta la firma de fichers adjunts emptrads en ls dcuments PDF. Adicinalmente, el impne una limitación en el tamañ de las firmas generadas, pr l que el us cmbinad de cadenas de certificads muy largas y sells de tiemp puede exceder este tamañ límite y prvcar un fall en el prces de firma. Cnsulte el apartad Infrmación específica para firmas PAdES para más infrmación sbre ls mds de firma PAdES y trs cndicinantes de us. Pr defect, el MiniApplet genera firmas PAdES-Simple. 3.2 Frmats de firma n sprtads pr el El n sprta la realización de firmas en frmat CMS/PKCS#7, el frmat XMLDSig (XML Digital Signature), ni ls frmats de ODF y OOXML para la firma de dcuments fimátics. 13

14 Se recmienda sustituir las firmas CMS pr firmas CAdES, ya que este últim prprcina cmpatibilidad hacia atrás cn CMS. Se recmienda sustituir las firmas XMLDSig pr firmas XAdES, ya que este últim prprcina cmpatibilidad hacia atrás cn XMLDSig. Si necesita utilizar firmas CMS XMLDSig de un md en el que el us de sus hmólgs AdES (Advanced Digital Signature) n es psible, puede utilizar el applet cmplet Más infrmación en Us de certificads y claves privadas pr parte del El utiliza un mecanism autmátic para determinar cuál será el almacén de certificads y claves que debe usar en cada cas. La nrma general sigue este simple algritm: 1. Si el navegadr Web es Mzilla Firefx, cn independencia del sistema perativ, se usa el almacén prpi de Mzilla Firefx (NSS, Netscape Security Services) más ls móduls PKCS#11 (Public Key Cryptgraphy Specificatin number 11) que Firefx tuviese cnfigurads, cm tarjetas inteligentes, DNIe (Dcument Nacinal de Identidad electrónic), HSM (Hardware Security Mdule), etc. 2. Si el navegadr es cualquier tr (Internet Explrer, Opera, Chrme Safari), se usa el almacén predeterminad del sistema perativ: a. Windws: CAPI (Cryptgraphy Applicatin Prgramming Interface) b. Mac OS X: Llaver de Mac OS X c. Linux: NSS Adicinalmente, es psible frzar al MiniApplet para que ignre estas reglas y utilizar un almacén fij. En este cas, ls almacenes sprtads sn: PKCS#12 (Public Key Cryptgraphy Specificatin number 12) / PFX (Persnal File Exchange). CAPI (únicamente en sistemas Windws). Llaver de Mac OS X, tant el cmún del sistema cm un llaver independiente en ficher (únicamente en sistemas Mac OS X). NSS (requiere que esté instalad Mzilla Firefx). PKCS11 (Public Key Cryptgraphy Specificatin number 11) Establecimient manual del almacén de certificads y claves Es psible para el integradr seleccinar manualmente el almacén de certificads de usuari que se debe utilizar, independientemente del sistema 14

15 perativ el navegadr que utilice el usuari. Sin embarg, hay que tener en cuenta que si se seleccina un almacén n dispnible en el entrn del usuari, el MiniApplet dará errr al intentar recuperar ls certificads del almacén. La selección manual del almacén de claves se realiza durante la carga del MiniApplet y se mantiene durante tda su ejecución. Una vez cargad, n es psible cambiar de almacén de certificads. Para frzar el us de un almacén de certificads cncret pasarems cm segund parámetr del métd de carga (cargarminiapplet(cdebase, keystre), cnsulte la sección de despliegue del MiniApplet para mayr infrmación sbre este métd ) el tip de almacén que se desea utilizar. El tip se indicará mediante las variables JavaScript dedicadas a tal fin (declaradas en la bibliteca miniapplet.js, dentr del bjet MiniApplet, que debe estar imprtada en las páginas Web en cualquier cas). Estas variables sn: KEYSTORE_WINDOWS Almacén de certificads CAPI. Cmpatible únicamente cn sistemas Micrsft Windws. KEYSTORE_APPLE Llaver de Mac OS X. Cmpatible únicamente cn sistemas Apple Mac OS X. KEYSTORE_FIREFOX Almacén NSS (Mzilla Firefx, Mzilla Thunderbird, etc.). KEYSTORE_PKCS12 Almacén en ficher PKCS#12 / PFX (Persnal File Exchange). KEYSTORE_PKCS11 Almacén de claves cmpatible PKCS#11 (tarjeta inteligentes, aceleradra criptgráfica). Determinads tips de almacén permiten indicar el ficher bibliteca en disc asciad al almacén. Este ficher bibliteca debe indicarse mediante su ruta absluta en el sistema del usuari, cm parte del mism parámetr, a cntinuación del tip de almacén y separads pr sign ds punts ( : ), siguiend el patrón: TIPO_ALMACEN:RUTA_ALMACEN Ls almacenes que permiten indicar el ficher bibliteca que se debe utilizar sn: KEYSTORE_APPLE Permite indicar el llaver en ficher de tip llaver en el que se encuentran ls certificads de firma. Si n se indica ningún ficher se usa el llaver general del sistema. 15

16 KEYSTORE_PKCS12 Permite indicar el almacén en ficher de tip PKCS#12/PFX (nrmalmente cn extensines.p12.pfx) en el que se encuentran ls certificads de firma. Si n se indica ningún ficher el MiniApplet slicitará al usuari que seleccine un mediante un diálg gráfic. KEYSTORE_PKCS11 Permite indicar la bibliteca que se debe utilizar para acceder al dispsitiv que almacena ls certificads de firma. Si n se indica ningún ficher el MiniApplet slicitará al usuari que seleccine un mediante un diálg gráfic. Es imprtante reseñar que la bibliteca PKCS#11 es dependiente del sistema perativ y de su arquitectura, pr l que si se indica, pr ejempl, una bibliteca PKCS#11 cm una DLL (Dynamic Link Library) de 32 bits, n funcinará ni en Linux ni en Mac OS X, per tampc en Windws 64 bits si se usa el MiniApplet desde un navegadr de 64 bits. A cntinuación se listan alguns ejempls de parámetr que se pueden pasar al métd: MiniApplet.KEYSTORE_WINDOWS Cnfigura CAPI (almacén general de claves y certificads de Windws) MiniApplet.KEYSTORE_APPLE Cnfigura el llaver de Mac OS X del sistema MiniApplet.KEYSTORE_APPLE + :/Users/usuari/Library/Keychains/lgin.keychain Cnfigura el llaver /Users/usuari/Library/Keychains/lgin.keychain MiniApplet.KEYSTORE_PKCS12 Cnfigura un almacén PKCS#12 que se slicitará al usuari mediante un diálg gráfic de selección. MiniApplet.KEYSTORE_PKCS12 + :C:\\prueba\\almacen.p12 Cnfigura el almacén PKCS#12 C:\\prueba\\almacen.p12 Así, para cargar el aplicativ MiniApplet indicand manualmente el almacén de certificads que se desea utilizar, utilizaríams sentencias JavaScript del tip: MiniApplet.cargarMiniApplet(cdeBase, MiniApplet.KEYSTORE_WINDOWS); MiniApplet.cargarMiniApplet(cdeBase, MiniApplet.KEYSTORE_FIREFOX); MiniApplet.cargarMiniApplet(cdeBase, MiniApplet.KEYSTORE_PKCS12 + :C:\\prueba\\almacen.p12 ); MiniApplet.cargarMiniApplet(cdeBase, MiniApplet.KEYSTORE_PKCS11 + :C:\\Windws\\System32\\PkcsV2GK.dll ); 16

17 Tenga en cuenta que n tds ls almacenes de certificads están dispnibles en tds ls sistemas. Así pues: CAPI sól está dispnible en sistemas Micrsft Windws. El llaver de Mac OS X sól está dispnible en sistemas Apple Mac OS X. NSS sól está dispnible cuand un prduct Mzilla cmpatible, cm Mzilla Firefx Mzilla ThunderBird, está instalad en el sistema y es de la misma arquitectura (x86, x64, IA64, etc.) que el navegadr que utilice el usuari para acceder al MiniApplet. Si en un almacén se indica un ficher bibliteca asciad, sól estará dispnible si este ficher bibliteca puede encntrarse en la ruta indicada y el usuari dispne de permiss de lectura y ejecución sbre él. Un almacén PKCS#11 cncret sól estará dispnible si el ficher bibliteca puede encntrarse en la ruta indicada, el usuari dispne de permiss de lectura y ejecución sbre él y además es para el mism sistema perativ y arquitectura que la del navegadr que utilice el usuari para acceder al MiniApplet Frzar ruta del almacén de Mzilla Firefx El MiniApplet detecta autmáticamente dónde está instalad Mzilla Firefx y, de esta frma, cóm acceder al almacén de certificads del navegadr y cuál es el almacén crrespndiente al usuari que está usand actualmente el navegadr, ya Firefx permite la existencia de varis perfiles de usuari dentr de la misma cuenta de usuari del sistema perativ. Existen casines muy cncretas en las que n es psible detectar dónde está instalad el navegadr cm, pr ejempl, si se utiliza un navegadr Firefx Prtable si se intenta acceder al almacén de una cuenta cncreta de Firefx sin usar el prpi navegadr. En ests cass, el MiniApplet usará las siguientes variables del sistema para lcalizar ls recurss necesaris: NSS_HOME: Directri cn las biblitecas NSS cmpatibles cn la versión de a la que pertenezca el almacén al que deseams acceder. PROFILE_HOME: Directri cn el perfil de usuari de Firefx al que pertenece el almacén. Si un integradr desease desde un sistema integrad acceder a un almacén de una cuenta cncreta de Firefx, deberá cnfigurar estas variables de entrn. 17

18 4 Despliegue del Para el us del MiniApplet sn necesaris 2 fichers principalmente: miniapplet-full_x.jar Es el archiv Java en el que se encuentra el applet y tda la funcinalidad de la aplicación. X es el númer de versión del applet. miniapplet.js Es la bibliteca JavaScript que permite la integración y us del en una página Web. Para el despliegue del Cliente debe publicar ests fichers en su servidr Web. Una vez desplegads bastará cn imprtar las biblitecas JavaScript en su página web y cargar el applet. 4.1 Imprtación de las biblitecas JavaScript Para pder integrar el MiniApplet en su página Web debe imprtar en ella la bibliteca JavaScript de despliegue: miniapplet.js Su situación depende de la dirección de publicación de su servidr. Puede hacer referencia a ella mediante una URL absluta mediante una URL relativa a partir de la dirección de publicación de su página Web. Una vez determinada la URL de cada una de las biblitecas, las páginas Web que hagan us del deben imprtarlas de frma glbal a tda la página, pr ejempl, incluyend las sentencias JavaScript de imprtación de biblitecas en la sección head del HTML, tal y cm se muestra en el siguiente ejempl: <head> <script type="text/javascript" src=" </script> En este ejempl se han usad las siguientes direccines para cada una de las biblitecas JavaScript: miniapplet.js: 18

19 Si la página Web en la que deseams cargar el Cliente estuviese también en la ruta se pdría hacer referencia a la bibliteca miniapplet.js de frma relativa indicand: <script type="text/javascript" src="miniapplet.js"></script> Cualquier página Web cn esta bibliteca JavaScript imprtada está lista para cargar el e incrprar la lógica de negci (JavaScript) asciada a su us. Las peracines que se desean realizar cn el MiniApplet se ejecutarán a partir del bjet MiniApplet definid en miniapplet.js. Pr ejempl: MiniApplet.sign(); Imprtación en páginas Web generadas dinámicamente En un sistema Web actual, l habitual es que las páginas Web n residan pre-cnstruidas en directris Web, sin que estas se generen dinámicamente ( al vuel ) mediante alguna de las muchas tecnlgías dispnibles de aplicacines Web (JSP, ASP, PHP, etc.). En ests cass es necesari tener en cuenta que debe indicarse la lcalización de la bibliteca JavaScript de despliegue mediante una URL absluta. <script type="text/javascript" src=" </script> 4.2 Carga del MiniApplet Una vez tenems el MiniApplet desplegad y las biblitecas JavaScript imprtadas en la página Web, la carga del MiniApplet se puede realizar mediante una simple sentencia JavaScript: cargarminiapplet(cdebase, keystre) Este métd recibe ds parámetrs: cdebase Debe indicarse la URL de despliegue de la aplicación JEE keystre (pcinal) 19

20 Establece el almacén de claves y certificads alternativ indicand su tip y su ficher asciad si l hubiese. Cnsulte cn la sección Establecimient manual del almacén de certificads y claves para más infrmación sbre su frmat y us. La invcación JavaScript a este métd debe realizarse a través del bjet MiniApplet y atendiend a las siguientes bservacines: Cierts diálgs gráfics (selección de fichers, mensajes, etc.) se mstrarán en pantalla centrads respect a la situación en pantalla de la prpia sentencia JavaScript de carga, pr l que puede ser interesante el us de técnicas HTML y JavaScript para asegurar que la sentencia de carga queda centrada respect a la parte visible en el navegadr de la página HTML, y así garantizar una mejr experiencia de usuari. Desde el mment de la invcación hasta la cmpleta carga del MiniApplet pueden pasar uns segunds, y dependiend del equip del usuari y su cnexión de red, hasta más de un minut. Intente que la llamada a la sentencia de carga se realice de frma temprana respect a la carga del rest de cmpnentes de la página para evitar prblemas de invcacines e innecesarias esperas para ls usuaris. A cntinuación se muestran diferentes ejempls de carga del : Carga el MiniApplet desplegad en la dirección <script type="text/javascript"> MiniApplet.cargarMiniApplet( ); </script> Carga el MiniApplet desde una función JavaScript desplegad en la dirección functin cargar() { MiniApplet.cargarMiniApplet( ); } Carga el MiniApplet desplegad en la dirección per usand siempre el llaver de Mac OS X cm almacén de claves y certificads. <script type="text/javascript"> MiniApplet.cargarMiniApplet( KEYSTORE_APPLE); </script> Carga el MiniApplet desplegad en la dirección per usand siempre el ficher c:\stre.pfx (tip PKCS#12 / PFX) cm 20

21 almacén de claves y certificads. El MiniApplet slicitará psterirmente la cntraseña de este almacén al usuari mediante un diálg gráfic. <script type="text/javascript"> MiniApplet.cargarMiniApplet( KEYSTORE_PKCS12 + :C:\\stre.pfx ); </script> 4.3 Cnfiguración del idima El MiniApplet detecta el idima del sistema del usuari, de tal frma que si se dispne de ls texts traducids a ese idima, ls mstrará traducids a ls usuaris en ls distints diálgs gráfics. Sin embarg, es psible frzar que se utilice un idima cncret de ls que dispne. El idima se puede cnfigurar mediante el métd JavaScript: setlcale(lcale) Este métd debe invcarse a través del bjet MiniApplet y recibe cm parámetr: cdebase Códig del idima que se desea establecer según la ISO 639. Este métd deberá establecerse siempre antes del métd de carga del MiniApplet. Pr ejempl: Cnfiguración del idima galleg: <script type="text/javascript"> MiniApplet.setLcale( gl_es ); MiniApplet.cargarMiniApplet( ); </script> Si n se dispne de ls texts del MiniApplet traducids al idima cnfigurad, se usarán ls texts del idima pr defect (Españl). Actualmente, el MiniApplet dispne de ls texts traducids en ls siguientes idimas: Españl/Castellan (es_es) (Idima pr defect) Galleg (gl_es) 21

22 4.4 Restricción según desfase hrari cn el servidr Al realizar una firma en el equip del usuari, esta registra el mment de la firma (signingtime) usand la hra del prpi equip. En cas de que la hra y/ fecha del equip se encuentre mal cnfigurada, es psible que una validación psterir de la firma prvque errres, sbre td si se trabaja también cn sells de tiemp. El MiniApplet n puede mdificar la hra del sistema del usuari, per si puede advertirle de esta situación para que la crrija, inclus blquear la carga. Para hacer esta cmprbación se puede utilizar el métd JavaScript: checktime(checktype, maxmillis) Este métd debe invcarse a través del bjet MiniApplet y recibe cm parámetrs: checktype Tip de verificación que se desea realizar. Admite ls valres: MiniApplet.CHECKTIME_NO: N realiza ningún tip de cmprbación. MiniApplet.CHECKTIME_RECOMMENDED: Realiza la cmprbación hraria y, en cas de encntrar un desfase, pedirá al usuari que l crrija antes de cntinuar. MiniApplet.CHECKTIME_OBLIGATORY: Realiza la cmprbación hraria y, en cas de encntrar un desfase, blqueará la carga del Applet y pedirá al usuari que l crrija. maxmillis Milisegunds máxims que se permiten de desfase. Se recmienda que se indique un perid mínim de 1 minut ( milisegunds) para facilitar la crrección de la hra en el equip del usuari. 4.5 Firma del JAR del MiniApplet Para la crrecta ejecución de la aplicación es necesari que el JAR del applet publicad esté crrectamente firmad. El Ministeri de Hacienda y Administracines Públicas (MINHAP) distribuye baj acuerd versines firmadas (pr el prpi MINHAP) de cada un de ests fichers, per en cas de n dispner de estas versines firmadas si ha necesitad realizar alguna mdificación en el MiniApplet y empaquetar su prpia versión, deberá firmar usted mism el archiv JAR del MiniApplet. 22

23 Para la firma del ficher JAR se recmienda el us de la herramienta Oracle JAR Signing and Verificatin Tl (jarsigner) según las instruccines descritas en la siguiente página Web: Puede btener esta herramienta de frma gratuita junt al Oracle Java Develpment Kit (JDK): 23

24 5 El prces de firma electrónica Cualquier firma electrónica realizada mediante el MiniApplet sigue un prces simple de 4 pass. 5.1 Selección del cntenid a firmar La cnversión de dats a Base64 L primer que debems saber antes de trabajar cn dats en el es que ests siempre se transfieren en frmat Base64, tant desde el applet al JavaScript de la página Web cm en sentid invers, per el MiniApplet internamente trabaja cn la descdificación binaria de ests dats en Base64. Est significa que ls dats firmads realmente n serán ls que nstrs prprcinems en Base64, sin su descdificación binaria. Así, pr ejempl, si la cadena de text SOY UN TEXTO A FIRMAR tiene cm representación en base64 la cadena U09ZIFVOIFRFWFRPIEEgRklSTUFS, debems establecer cm dats a firmar siempre U09ZIFVOIFRFWFRPIEEgRklSTUFS, per l que se firmará será SOY UN TEXTO A FIRMAR. 24

25 Esta frma de perar permite trabajar sin ambigüedades tant cn texts en diferentes cdificacines (ASCII, UTF-8, ISO , etc.) cm cn dats binaris de cualquier tip. El MiniApplet cuenta cn ds métds de utilidad para cdificar y descdificar dats en Base64, gettextfrmbase64() y getbase64frmtext(). En ambs cass es necesari indicar el jueg de caracteres (cdificación) del text para evitar prblemas en las cnversines. Si descnce prefiere que se detecte autmáticamente la cdificación, utilice algun de ls parámetrs especiales que se definen en ls apartads Cnversión de una cadena Base64 a text y Cnversión de un text a cadena Base Selección de cntenid desde fichers en disc En muchas casines, el cntenid a firmar n es directamente accesible desde JavaScript para ser firmad, y es necesari acceder al disc del usuari para recuperarl desde un ficher. Para estas casines, el permite que en las peracines de firma, cfirma y cntrafirma n se especifiquen ls dats que se quieren firmar las firmas que se quieren multifirmar. Cuand n se indican, el applet permite al usuari cargar un ficher en disc desde el que cargar ests dats. Alternativamente, aunque n se recmendable ya que puede prducir prblemas al cargar fichers grandes, el MiniApplet cuenta cn cierts métds de utilidad que permiten la lectura de un varis fichers (getfilenamecntentbase64() y getmultifilenamecntentbase64()). Ests métds muestran al usuari un diálg de selección cn el que seleccinar ls fichers y devuelven siempre el nmbre y cntenid de ls fichers en Base64, cn independencia del cntenid ests. Cnsulte el apartad de Selección de un ficher pr parte del usuari y recuperación de su nmbre y cntenid para más detalles. El us de ls métds getfilenamecntentbase64() y getmultifilenamecntentbase64() rmpe la cmpatibilidad del despliegue cn el móvil Selección de bjetiv de las cntrafirmas El cas de las cntrafirmas es especial en el sentid que l dats prprcinads n sn realmente l que querems firmar, sin que sn una firma electrónica la cual querems cntrafirmar. En este cas, la firma ha de prprcinarse de igual frma que si se tratase de ls dats reales a firmar (cn las mismas cnsideracines respect a la cdificación Base64). 25

26 Para determinar si debe cntrafirmar td el árbl de firmas sl ls nds hja deben realizarse indicacines mediante parámetrs adicinales. Cnsulte el apartad Selección de ls nds que se desean cntrafirmar para aprender a cnfigurar ls nds bjetiv de la cntrafirma. 5.2 Selección del certificad y clave privada de firma Una vez tenems establecid en JavaScript el cntenid que querems firmar, el siguiente pas es la elección de la clave privada y su certificad asciad cn ls que querems realizar la firma electrónica. Pr mtivs de seguridad, el integradr n puede btener la lista de certificads y claves instaladas en el equip del usuari, y es siempre respnsabilidad es este últim su selección, per l que si puede el integradr es restringir ls psibles certificads a usar en base a una serie de criteris predefinids, en l que el MiniApplet cncreta cm Filtrs de certificads. Una vez se ha aplicad el filtr de certificads, en cas de haberl establecid, se mstrará al usuari el diálg de selección cn el listad filtrad de certificads. También es psible realizar una selección autmática de certificad cuand sól haya un seleccinable. Cnsulte el apartad Selección autmática de certificads para saber el md de cnfigurar esta pción. En el cas de que ningún certificad cumpla cn ls criteris de filtrad se prducirá una situación de excepción. 5.3 Firma El MiniApplet cuenta cn tres métds independientes para cada un de las peracines sprtadas (firma, cfirma y cntrafirma). A ests métds, además de ls dats a firmar y filtrs de certificads cmentads anterirmente es necesari indicar el frmat (PAdES, CAdES, XAdES u FacturaE), el algritm de firma y trs parámetrs adicinales que pudiesen ser necesaris. En el cas de la cfirma y cntrafirma, puede utilizarse el frmat AUTO para indicar que debe realizarse una firma cn el mism frmat que la firma riginal. Ls métds de firma, cfirma y cntrafirma devuelven siempre las firmas cdificadas en Base Recgida de resultads Cuand desde JavaScript se recibe el resultad de la firma en Base64 l más cmún es ptar pr una entre ds pcines: Guardar ls resultads en un archiv en el almacenamient lcal del usuari enviarls a un servidr. En el primer cas el prprcina un métd de utilidad (savedatatfile()) para guardar resultads en disc. En este cas es siempre el 26

27 usuari el que elige nmbre del ficher y directri de destin pr mtivs de seguridad, y debems acrdarns que aunque le prprcinems ls dats en Base64, l que se almacenará en el ficher es la descdificación binaria de ests. Si ptams pr enviarls a un servidr, l más usual es hacerl directamente en Base64 y, psterirmente, mediante una aplicación en servidr independiente del MiniApplet, realizar las transfrmacines y descdificacines pertinentes. 27

28 6 Funcines dispnibles del El expne una serie de funcinalidades a través de JavaScript que permiten realizar la mayría de las accines relativas a las firmas electrónicas en entrns crprativs de administración electrónica. Estas funcinalidades están divididas en distints apartads según su tiplgía: Firma electrónica Firmas electrónicas múltiples Cfirma Cntrafirma Cnfiguración Blque del certificad de firma (para prcess masivs). Gestión de fichers Guardad de dats en disc Selección de un ficher pr parte del usuari y recuperación de su nmbre y cntenid. Selección de múltiples fichers pr parte del usuari y recuperación de sus nmbres y cntenids. Utilidad Obtención de ls mensajes de errr Cnversión de una cadena Base64 a text. Cnversión de un text a una cadena Base Us del API desde JavaScript El API del se expne autmáticamente al entrn JavaScript al imprtar la bibliteca miniapplet.js y está perativ pasads uns segunds desde la invcación al métd de carga. Debid a este liger retras desde la invcación al métd de carga y la finalización de la prpia carga (y pr l tant de la cmpleta peratividad del API), es recmendable que la llamada al métd de carga se realice autmáticamente (cm se ha indicad en el apartad Carga del MiniApplet), per que el inici de la lógica de firma dependa de una interacción del usuari cn la página Web (cm pulsar un btón), así el prpi tiemp de reacción del usuari ante el interfaz gráfic permite cargar pr cmplet el MiniApplet. 6.2 Obtención de resultads Ls métds de peración criptgráfics del Cliente btienen cm resultad la firma/multifirma generada. Esta firma puede btenerse de ds frmas: directamente cm valr de retrn de las funcines mediante funcines callback que establecen el cmprtamient definid para prcesar ese resultad. Ls métds del peración del Cliente sn únics, lueg se usa un mecanism u tr según si se han establecid ls métds de callback (md 28

29 asíncrn) n (md síncrn). Para utilizar el md síncrn (devlución directa del resultad), basta cn establecer ls parámetrs crrespndientes de cada función a null, directamente, mitirls en la llamada Obtención directa de resultads La btención de frma asíncrna de ls resultads es la que se ha utilizad hasta ahra y se hereda del applet Este md simplifica a ls prgramadres rganizar a ejecución de las peracines de una frma secuencial, que viene a ser el md cmún de us, y facilita la migración desde el applet al MiniApplet. Sin embarg, este md n disfruta de las ventajas que se cnsiguen mediante el md de peración asíncrn que se btiene mediante el us de callbacks (véase el apartad Obtención de resultads mediante Callbacks ), que es además el que permite que nuestrs desarrlls sea cmpatibles cn platafrmas móviles. Mientras que este md de us hace que el resultad de la peración se btenga cm valr devuelt pr la función, ls errres pueden detectarse mediante la captura de excepcines. La identificación de ests errres se realizará mediante ls métds geterrrtype() y geterrrmessage(). Un ejempl de peración en el que se btiene de frma síncrna el resultad de las peracines de firma es: // Llamams a la peración de firma var signature; try { signature = MiniApplet.sign(null, SHA512withRSA, PAdES, null); } catch (e) { // Mstrams un mensaje cn el errr btenid dcument.getelementbyid( resultmessage ).innerhtml = Errr + message; } // Guardams la firma en un camp de un frmulari dcument.getelementbyid( result ).value = signature; // Mstrams un mensaje cn el resultad de la peración dcument.getelementbyid( resultmessage ).innerhtml = La firma finalizó crrectamente ; Obtención de resultads mediante Callbacks Ls métds de firma, cfirma y cntrafirma del MiniApplet se ejecutan de frma asíncrna cuand se establece al mens una de las funcines callback para el tratamient de ls resultads. Al hacerl de esta manera, que es la recmendada, se evita que el script quede blquead durante su ejecución y el navegadr l detecte cm un funcinamient anómal e intente blquearl. Así 29

30 mism, el us de este mecanism permite que nuestr despliegue sea cmpatible cn el Cliente de firma móvil. Para pder perar cn este funcinamient asíncrn se ha dispuest el sistema de callbacks. Estas callbacks sn también funcines que definen que se debe hacer cn el resultad de la peración. Pr ejempl: Pdems definir que muestre en un camp de un frmulari un mensaje indicand que la peración ha terminad crrectamente. Pdems guardar la firma en disc mediante el métd prprcinad pr el prpi MiniApplet. Pdems adjuntarla a un camp cult de un frmulari y enviarl. Pdems hacer que se cfirme el resultad de una firma. Etc. Estas callbacks se definen cm funcines nrmales JavaScript y pueden servir para 2 prpósits: Gestinar el resultad de una peración firma, cfirma cntrafirma. Gestinar el errr devuelt pr una peración firma, cfirma cntrafirma. La función que gestina el resultad crrect de las peracines criptgráficas recibe siempre un únic parámetr que será el resultad devuelt pr la peración (la firma, cfirma cntrafirma generada en base64). Esta puede tener la frma: functin successcallback(resultbase64) { } La función que gestina ls cass de errr btendrá siempre 2 parámetrs que definen el tip de errr prducid (la clase de excepción cualificada que prduj el errr) y el mensaje de errr asciad. Esta función puede ser de la frma: functin errrcallback(type, message) { } Para tratar el resultad de las firmas, cfirmas y cntrafirmas mediante estas funcines se les pasará el nmbre de las funcines de gestión del resultad y ls errres cm penúltim y últim parámetr, respectivamente. Pr ejempl: // Función que se ejecutará si la firma termina crrectamente 30

31 functin savesignaturefunctin (signature) { // Guardams la firma en un camp de un frmulari dcument.getelementbyid( result ).value = signature; // Mstrams un mensaje cn el resultad de la peración dcument.getelementbyid( resultmessage ).innerhtml = La firma finalizó crrectamente ; } // Función que se ejecutará si el prces de firma falla functin shwerrrfunctin (type, message) { // Mstrams un mensaje cn el resultad de la peración dcument.getelementbyid( resultmessage ).innerhtml = Errr + message; } // Llamams a la peración de firma MiniApplet.sign(null, SHA512withRSA, PAdES, null, savesignaturefuntin, shwerrrfuntin); 6.3 Firma electrónica Mediante la peración de firma electrónica pdems realizar la firma de ls dats seleccinads pr el integradr y pr el usuari. El resultad de esta peración se debe gestinar asíncrnamente mediante funcines callback. Est garantiza que el JavaScript de nuestra página n se queda blquead durante la peración, evitand mlests mensajes pr parte del navegadr Web. Este us de la función de firma también garantiza la cmpatibilidad del despliegue cn el Cliente Móvil. Para ejecutar la peración de firma se utiliza la función JavaScript: functin sign(datab64, algrithm, frmat, params, successcallback, errrcallback); En esta función: datab64: Dats en frma de cadena en Base64 que deseams firmar. También puede n indicar la firma (usar null) para que se muestre al usuari un diálg de carga de ficher. Si ls dats que necesita firmar sn un text, cárguel y cnviértal a base 64 tal cm se indica en el apartad Cnversión de un text a cadena Base64. algrithm: Algritm de firma. Cnsulte el apartad Algritms de firma para cncer ls algritms dispnibles. frmat: Frmat de firma. Cnsulte el apartad Frmats de firma sprtads pr el para cnsultar aquells dispnibles. params: Parámetrs adicinales para la cnfiguración de la firma. Cnsulte el apartad Pas de parámetrs adicinales a ls métds de firma, cfirma y cntrafirma para saber cóm realizar el pas de parámetrs y el 31

32 apartad de infrmación específica del frmat de firma que desee realizar para saber ls parámetrs sprtads pr el frmat en cuestión. successcallback: Función JavaScript que se ejecutará una vez se btenga el resultad de la peración de firma. Esta función recibirá cm únic parámetr la firma resultad. Si se mite este parámetr, se establece a null, la firma resultad se btendrá cm valr de retrn de la función. errrcallback: Función JavaScript que se ejecutará cuand curra un errr durante la peración de firma. Esta función recibirá ds parámetrs que sn el tip y el mensaje de errr. Si se mite este parámetr, se establece a null, el errr se btendrá en frma de excepción. Cnsulte el apartad 7.5 Gestión de errres. El resultad de esta peración puede btenerse directamente gestinarme mediante las funcines callback. Este resultad se btiene cdificad en base Ejempls: A cntinuación se muestran distints ejempls relacinads cn la función de firma electrónica: Firma electrónica cargand dats desde un ficher: // Funcin que se ejecutara cuand la firma termine crrectamente functin savesignaturefunctin (signature) { MiniApplet.saveDataTFile(signature, Guardar firma, firma.pdf, pdf, Adbe PDF ); } // Funcin que se ejecutara cuand el prces de firma falle functin shwerrrfunctin (type, message) { shwerrr(message); // Funcin creada pr el integradr para mstrar errres } // Llamams a la peracin de firma MiniApplet.sign(null, SHA512withRSA, PAdES, null, savesignaturefuntin, shwerrrfuntin); Firma electrónica de un text: var text = Hla Mund!! ; var datab64 = MiniApplet.getBase64FrmText(text, default ); MiniApplet.sign(dataB64, SHA1withRSA, CAdES, null, successfunctin, errrfuntin); Firma electrónica de un text intrducid pr el usuari: var text = dcument.getelementbyid( usertext ).value; 32

33 var datab64 = MiniApplet.getBase64FrmText(text, aut ); MiniApplet.sign(dataB64, SHA1withRSA, CAdES, null, successfunctin, errrfuntin); <!-- Fragment HTML cn un camp de text en dnde el usuari puede insertar el text que desea firmar --> <frm> <textarea name="usertext" cls="50" rws="5">aquí el usuari puede insertar el text que quiera</textarea> </frm> Firma electrónica permitiend al usuari seleccinar parámetrs de firma: var params = expplicy=firmaage ; var mdes = dcument.getelementsbyname( rbmde ); fr (i = 0; i <mdes.length; i++) { if (mdes[i].checked) { } } params = params + \nmde= + mdes[i].value; break; MiniApplet.sign( datab64, SHA1withRSA, CAdES, params, successfunctin, errrfunctin ); <!-- Fragment HTML cn btnes de radi para la selección del md de firma --> <frm> <input type="radi" name="rbmde" value="explicit" checked="checked" />Explícita <br/> <input type="radi" name="rbmde" value="implicit" />Implícita </frm> 6.4 Firmas electrónicas múltiples En este apartad se englban las peracines que permiten agregar más de una firma electrónica a un dcument. Existen ds tips generales de firmas múltiples: Cfirmas. Permiten que varis individus firmen el mism dcument. Cntrafirmas: Permite que un firmante refrende una firma electrónica. 33

34 6.4.1 Cfirmas Operación mediante la cual ds más firmantes muestran su acuerd cn un dcument dats cncrets. La cfirma cnsiste en agregar la infrmación de firma de un firmante a una firma ya existente. Así, será necesari que una persna firme el dcument generand así la infrmación de firma y, psterirmente, el rest de ls firmantes cfirmen la firma generada. Si la firma generada cntenía ls dats firmads n serán necesaris nuevamente ls dats para la generación de las cfirmas. Un ejempl de us de este tip de firmas es cuand varis individus firman el mism cntrat cm partes cntratante y cntratista, cmpuestas, tal vez, pr varis individus cada una teniend que firmar tds ells. El resultad de esta peración se debe gestinar asíncrnamente mediante funcines callback. Est garantiza que el JavaScript de nuestra página n se queda blquead durante la peración, evitand mlests mensajes pr parte del navegadr Web. Este us de la función de firma también garantiza la cmpatibilidad del despliegue cn el Cliente Móvil. La función JavaScript mediante la cual se realizan las cfirmas es: functin csign(signb64, datab64, algrithm, frmat, params, successcallback, errrcallback); En esta función: signb64: Firma electrónica en frma de cadena en Base64 que deseams cfirmar. Una firma en Base64 es el resultad btenid pr las peracines de firma, cfirma y cntrafirma. También puede n indicar la firma (usar null) para que se muestre al usuari un diálg de carga de ficher. datab64: Dats en frma de cadena en Base64 que firmams riginalmente. Puede ser nul si la firma seleccinada cntiene ls dats firmads riginalmente. Si ls dats utilizads riginalmente para la firma sn un text, cárguel y cnviértal a base 64 tal cm se indica en el apartad Cnversión de un text a cadena Base64. algrithm: Algritm de firma. Cnsulte el apartad Algritms de firma para cncer ls algritms dispnibles. frmat: Frmat de firma. Cnsulte el apartad Frmats de firma sprtads pr el para cnsultar aquells dispnibles. Si n cnce el frmat de firma utilizad para la firma riginal, indique el valr AUTO para especificar que se utilice el mism frmat. Este valr sól reprduce el frmat, n las prpiedades de la firmas riginal. Pr ejempl, si cfirmásems una firma XAdES-EPES, indicand "AUTO" cm 34

35 valr, agregaríams a esta una cfirma XAdES-BES salv que indicásems a través del parámetr params la plítica de firma que querems utilizar. params: Parámetrs adicinales para la cnfiguración de la cfirma. Si se intrduce un nul, se usará la cnfiguración pr defect para el frmat de firma establecid. Cnsulte el apartad Pas de parámetrs adicinales a ls métds de firma, cfirma y cntrafirma para saber cóm realizar el pas de parámetrs y el apartad de infrmación específica del frmat de firma que desee realizar para saber ls parámetrs sprtads pr el frmat en cuestión. successcallback: Función JavaScript que se ejecutará una vez se btenga el resultad de la peración de cfirma. Esta función recibirá cm únic parámetr la cfirma resultad. Esta función recibirá cm únic parámetr la firma resultad. Si se mite este parámetr, se establece a null, la firma resultad se btendrá cm valr de retrn de la función. errrcallback: Función JavaScript que se ejecutará cuand curra un errr durante la peración de cfirma. Esta función recibirá ds parámetrs que sn el tip y el mensaje de errr. Si se mite este parámetr, se establece a null, el errr se btendrá en frma de excepción. Cnsulte el apartad 7.5 Gestión de errres. El resultad de esta peración puede btenerse directamente gestinarme mediante las funcines callback. Este resultad se btiene cdificad en base Ejempls: A cntinuación se muestran distints ejempls relacinads cn la función de cfirma electrónica: Cfirma electrónica cargand una firma desde un ficher sabiend que esta cntiene ls dats firmads riginalmente: MiniApplet.cSign(null, null, SHA1withRSA, CAdES, null, successcallback, errrcallback); Cfirma electrónica del resultad de una firma: // Funcin que realiza la cfirma a partir de ls dats de firma functin csignfunctin (signatureb64) { MiniApplet.cSign( signatureb64, datab64, SHA1withRSA, XAdES, null, savedatafunctin, shwerrr ); } // Función que almacena ls dats generads pr la cfirma en el camp // resultid de un frmulari y l envia functin savedatafunctin (csignb64) { dcument.getelementbyid( resultid ).value = csignb64; dcument.getelementbyid( frmulari ).submmit(); 35

36 } // Función para firmar dats. Si termina crrectamente la peración de firma se // llama a la función csignfunctin cn el resultad de la peración y, si // esta también termina crrectamente, se llama a la función savedatafunctin // cn el resultad de la cfirma. Si falla alguna de estas funcines se llama // al métd shwerrr functin firmar(datab64) { MiniApplet.sign(dataB64, SHA1withRSA, XAdES, frmat=xades Detached, csignfunctin, shwerrr); } Cfirma electrónica de tra peración de multifirma: functin csignactin (signatureb64) { MiniApplet.cSign( multisignatureb64, datab64, SHA1withRSA, XAdES, null, successcallback, errrcallback ); }; MiniApplet.csign(signB64, SHA1withRSA, XAdES, null, csignactin, errrcallback); Cntrafirmas Operación mediante la cual una entidad refrenda la firma de tra. La cntrafirma cnsiste en agregar una firma electrónica sbre tra para revalidarla. Ejempls de us de este tip de firmas sn cuand un ntari cnfirma que las firmas de un más individus sn crrectas y pertenecen realmente a ests, cuand, debid a la caducidad de ls certificads de firma, un usuari desea revalidar una firma realizada cn un certificad antigu cn un algritm de firma actualmente insegur. Para realizar una cntrafirma n es necesari dispner del dcument que se firmó riginalmente. N tds ls frmats de firma permiten la cntrafirma de fichers. Cnsulte el manual del frmat de firma de su interés para cncer si este sprta esta peración. La función JavaScript mediante la cual se realizan las cntrafirmas es: functin cuntersign(signb64, algrithm, frmat, params, successcallback, errrcallback); En esta función: signb64: Firma electrónica en frma de cadena en Base64 que deseams cntrafirmar. Una firma en Base64 es el resultad btenid pr las peracines de firma, cfirma y cntrafirma. También puede n indicar la 36

37 firma (usar null) para que se muestre al usuari un diálg de carga de ficher. algrithm: Algritm de firma. Cnsulte el apartad Algritms de firma para cncer ls algritms dispnibles. frmat: Frmat de firma. Cnsulte el apartad Frmats de firma sprtads pr el para cnsultar aquells dispnibles. Si n cnce el frmat de firma utilizad para la firma riginal, indique el valr AUTO para especificar que se utilice el mism frmat. Pr ejempl, si cntrafirmásems una firma CAdES-EPES, indicand "AUTO" cm valr, agregaríams a esta una cntrafirma CAdES-BES salv que indicásems a través del parámetr params la plítica de firma que querems utilizar. params: Parámetrs adicinales para la cnfiguración de la cntrafirma. Si se intrduce un nul, se usará la cnfiguración pr defect para el frmat de firma establecid. Cnsulte el apartad Pas de parámetrs adicinales a ls métds de firma, cfirma y cntrafirma para saber cóm realizar el pas de parámetrs y el apartad de infrmación específica del frmat de firma que desee realizar para saber ls parámetrs sprtads pr el frmat en cuestión. successcallback: Función JavaScript que se ejecutará una vez se btenga el resultad de la peración de cntrafirma. Esta función recibirá cm únic parámetr la cntrafirma resultad. Esta función recibirá cm únic parámetr la firma resultad. Si se mite este parámetr, se establece a null, la firma resultad se btendrá cm valr de retrn de la función. errrcallback: Función JavaScript que se ejecutará cuand curra un errr durante la peración de cntrafirma. Esta función recibirá ds parámetrs que sn el tip y el mensaje de errr. Si se mite este parámetr, se establece a null, el errr se btendrá en frma de excepción. Cnsulte el apartad 7.5 Gestión de errres. El resultad de esta peración puede btenerse directamente gestinarme mediante las funcines callback. Este resultad se btiene cdificad en base Creación del árbl de firmas La peración de cntrafirma se realiza sbre tra firma. Esta puede ser una firma simple, una cfirma u tra cntrafirma. Estas peracines de firma, cfirma y cntrafirma van agregand firmas a un dcument y, ya que las cntrafirmas se realizan sbre firmas previas, se frma l que se ha dad en llamar un árbl de firmas. Pr ejempl si realizams una firma sbre uns dats btendríams la siguiente estructura: 37

38 Si realizásems una cfirma sbre el resultad de la peración anterir btendríams l siguiente: Tenga en cuenta que una firma y una cfirma están al mism nivel y sn equivalentes. N tiene imprtancia cual fue la primera en realizarse (firma) y cual la siguiente siguientes prque tdas sn cfirmas. Las cfirmas sn firmas sbre ls dats riginales, pr l tant tdas dependen de ests. Así, si agregams una nueva cfirma quedaría de la siguiente frma: Una cntrafirma, en cambi se realiza sbre una firma previa, nunca sbre ls dats. Pr ejempl: Una persna que cntrafirme, puede estar interesada en cntrafirmar más de una firma simultáneamente. Este sería el cas de un ntari que valida cn la suya las firmas de un las ds partes de un cntrat. Est se representa cn una firma sbre cada una de las firmas que se cntrafirmen, que n tienen pr qué ser tdas las del árbl de firmas. Pr ejempl, pdems cntrafirmar la cfirma anterirmente cntrafirmada y tra adicinal, quedand así: 38

39 Ds cntrafirmas situadas a un mism nivel del árbl n sn cfirmas, ni siquiera cuand dependen del mism nd. Simplemente, sn cntrafirmas del mism nd. Siempre es psible seguir creand cfirmas y cntrafirmas al árbl las cfirmas siempre dependerán de ls dats y las cntrafirmas de tr nd de firma. Este nd puede ser así una cntrafirma, generand nuevs niveles en el árbl: Selección de ls nds que se desean cntrafirmar En función de l explicad en el apartad anterir, el permite que las cntrafirmas se realizan sbre ls siguientes bjetivs: Nds hja del árbl (LEAFS): Se firmarán sól las firmas del árbl de ls que n depende ningún tr nd. Td el árbl de firma (TREE): Se firman tds ls nds de firma del árbl. La cnfiguración de qué nds se desean firmar se realiza a través del parámetr params de la función de cntrafirma, al que, además de tda la cnfiguración específica del frmat de firma, el parámetr adicinal target que indica ls nds a cntrafirmar. Si desea cncer cóm utilizar el parámetr params para establecer una cnfiguración, cnsulte el aparatad Pas de parámetrs adicinales a ls métds de firma, cfirma y cntrafirma. La clave target del params puede adptar un de ls siguientes valres: 39

40 leafs: Cntrafirma tdas las firmas que sean nds hja del árbl. Este es el valr pr defect. tree: Cntrafirma tdas las firmas del árbl. Si, pr ejempl, dispnems del siguiente árbl de firmas: Cada una de las cnfiguracines dará el siguiente resultad: target=leafs target=tree Si desea realizar cntrafirmas más cncretas que permitan seleccinar nds firmantes cncrets del árbl de firmas, cnsulte el catálg de para determinar cuál es la más aprpiada para sus necesidades Ejempls: A cntinuación se muestran distints ejempls relacinads cn la función de cntrafirma electrónica: 40

41 Cntrafirma electrónica de una firma seleccinada pr el usuari: var filenamedatab64; try { filenamedatab64 = MiniApplet.getFileNameCntentBase64( Ficher de firma, xsig, Firma XAdES ); } catch (e) { return; } var signatureb64; var separatridx = filenamedatab64.indexof(" "); if ((separatridx + 1) < filenamedatab64.length) { signatureb64 = filenamedatab64.substring(separatridx + 1); } else { /* El ficher n cntenía dats */ return; } MiniApplet.cunterSign( signatureb64, SHA1withRSA, XAdES, null, successcalback, errrcallback ); Cntrafirma electrónica del resultad de una firma: functin cuntersigncallback (signatureb64) { MiniApplet.cunterSign( signatureb64, SHA1withRSA, XAdES, null, successcallback, errrcallback ); } MiniApplet.sign(dataB64, SHA1withRSA, XAdES, null, cuntersigncallback, errrcallback); Cntrafirma electrónica de td el árbl de firmas: MiniApplet.cunterSign( signatureb64, SHA1withRSA, CAdES, target=tree, successcallback, errrcallback ); 6.5 Firmas/Multifirmas trifásicas El, siguiend la perativa nrmal, realiza las firmas electrónicas siguiend ls siguientes pass: 1. Cnstruye la estructura que el usuari debe firmar según el frmat de firma y la cnfiguración seleccinada. 2. Realiza la firma digital de ess dats cn el certificad del usuari. 41

42 3. Finalmente, cmpne la firma en el frmat de firma electrónica cnfigurad. Sin embarg, el MiniApplet también permite que la primera y tercera de las fases mencinadas se realicen de frma externa (en un servidr remt), mientras que la segunda fase, la firma digital cn el certificad del usuari, se realiza internamente. Esta división del prces de firma en 3 fases es l que cmúnmente se llama Firma Trifásica. Esta perativa resulta de much interés en determinads cass: El rigen y/ el destin de la infrmación es un servidr, de tal frma que se pueden pre-prcesar ls dats en servidr (Fase I) y mandar al usuari sól la infrmación mínima necesaria, firmarla el usuari en su sistema (Fase II) y, cn el resultad, cmpner la firma en servidr (Fase III) para seguidamente enviarla a dnde crrespnda. Se necesita firmar dcuments muy grandes. La firma trifásica interesa en este cas prque la mayr carga de prces recaería sbre el servidr y n sbre el sistema del usuari que presuntamente tendrá muchs mens recurss. El us de la firma trifásica en ests cass cnlleva una serie de ventajas y desventajas: Ventajas El dcument n viaja a través de la red. Mayr facilidad para desarrlls multi-dispsitiv y mens prpens a errres debid a que la parte cliente n se vería expuesta a las muchas variables del entrn que pueden afectar a ls distints frmats de firma (versines preinstaladas de biblitecas, cambis en Java,). Las peracines más cmplejas se realizan en servidr, un entrn much más cntrlad. Desventajas: Implica un mayr númer de cnexines de red, aunque el tráfic de red, según el cas, pdría sea menr. Requiere el despliegue de servicis en el servidr Realizar firma trifásicas cn el Para bligar al a generar una firma de frma trifásica es necesari realizar las siguientes accines. Establecer el frmat de firma trifásica Para la firma en ls frmats CAdES, PAdES y XAdES se usará CAdEStri, PAdEStri y XAdEStri, respectivamente, cm identificadr del frmat. 42

43 Cnfigurar parámetr cn la URL del servidr En ls parámetrs extra de la peración se deberá cnfigurar la URL del servici de firma trifásica. Este parámetr se cnfigurará cn la clave serverurl. Para saber más de ls parámetrs extra de cnfiguración cnsulte el apartad Pas de parámetrs adicinales a ls métds de firma, cfirma y cntrafirma Ejempls: A cntinuación se muestran alguns ejempls de peración trifásica: Firma trifásica XAdES: MiniApplet.sign( datab64, SHA1withRSA, XAdEStri, frmat=xades Detached\nserverUrl= successcalback, errrcallback ); Cfirma trifásica CAdES: MiniApplet.cSign( signb64, datab64, SHA512withRSA, CAdEStri, serverurl= successcalback, errrcallback ); Servici de firma trifásica Este servici es el que realiza la primera y tercera fase del prces de firma trifásica. Junt al se distribuye el archiv WAR TriPhaseSignerServer.war que cntiene que despliega un servici web de tip REST cn las funcinalidades de firma trifásica. Este servici n es dependiente de ningún servidr de aplicacines cncret. Cnsulte el manual de su servidr de aplicacines para saber cóm desplegar este ficher WAR. El servici de firma trifásica distribuid junt al MiniApplet sprta ls frmats CAdES, XAdES y PAdES (firmas y multifirmas) y admite las mismas pcines de cnfiguración que las firmas mnfásicas de ests frmats. Advertencia: Se han detectad prblemas cn JBss 7 debid a que incrpra de serie la versión 1.5.X de la bibliteca XMLSec, que intrduce un prblema de cmpatibilidad cn las firmas XAdES. Si está segur de que ninguna de sus aplicacines hace us de esta bibliteca, elimínela para slventar este prblema. 43

44 Es muy recmendable habilitar el servici de firma trifásica cuand se realizan despliegues cmpatibles cn el móvil. Para saber más acerca del móvil cnsulte el apartad Cmpatibilidad cn dispsitivs móviles Cnfiguración del servici de firma trifásica Ta cm se distribuye, el servici de firma trifásica n necesita cnfiguración para permitir generar firmas trifásicas de la frma nrmal del. Est es, cuand el integradr pase cm parámetr ls dats que desea firmar y quiera recibir la firma resultante. Existe la psibilidad, sin embarg, de cnfigurar el servici trifásic, mediante el ficher cnfig.prperties cntenid en el WAR, para establecer un Dcument Manager (Administradr de dcuments) distint que recja ls dats de tra fuente y ls envíe a tr destin. Integrads en el servici trifásic se distribuyen 2 Dcument Manager distints que el integradr del servici puede cnfigurar mediante la clave dcument.manager del ficher de prpiedades: es.gb.afirma.triphase.server.selfishdcumentmanager: Es el Dcument Manager pr defect y emula el cmprtamient de la firma mnfásica del cliente. Es decir, recibe ls dats a firmar y devuelve la firma. es.gb.afirma.triphase.server.filesystemdcumentmanager: En este cas se enviaría, en lugar de ls dats a firmar, el nmbre de un ficher lcalizad en el servidr para que sea el que se firme. La firma resultante se guardará en tr directri del servidr y se devlverá al MiniApplet únicamente la cadena OK para cnfirmar que la peración finalizó crrectamente. Este Dcument Manager permite que ls dats (cuy rigen y destin sea un servidr) n viajen hasta el Cliente reduciend cnsiderablemente el tráfic de red y la fiabilidad y velcidad del prces. Si se cnfigura este Dcument Manager se pueden cnfigurar tras tres prpiedades en el ficher de cnfiguración del servici: indir: Directri del servidr en dnde se encuentran ls dcuments de dats. utdir: Directri del servidr en dnde se almacenan las firmas generadas. verwrite: Cnfigura si se deben sbrescribir ls fichers de firma si ya existe una cn el mism nmbre (true) n (false). 44

45 Un desarrlladr Java pdría crear nuevs Dcument Manager a medida e integrarls en el servici. Para ell deberá implementar la interfaz es.gb.afirma.triphase.server.dcumentmanager. Pr ejempl, se pdría crear un Dcument Manager que recgiese ls dats a firmar de un gestr de cntenids y almacenase la firma resultante en base de dats. 6.6 Firmas/Multifirmas masivas El puede utilizarse para la realización de múltiples firmas de tal frma que un usuari l perciba cm una única peración. Para ell basta que el integradr utilice ls métds de firma, cfirma y cntrafirma sbre tds ls dats que crrespnda. Para psibilitar que el usuari sól deba seleccinar el certificad de firma en una casión y n para peración individual, se deberá dejar prefijad este certificad mediante el métd: functin setstickysignatry (sticky); En esta función: sticky: Es un blean. Si se indica el valr true, el próxim certificad que seleccine el usuari (durante la próxima peración de firma/multifirma) quedará fijad y se utilizará para tdas las peracines psterires. Si se indica el valr false, se libera el certificad y se vlverá a slicitar al usuari en cada una de las siguientes peracines. Este métd n devuelve nada. Adicinalmente, para la generación de multifirmas dentr de un prcedimient masiv es interesante indicar el valr AUTO cm frmat de firma. Al hacerl, las cfirmas y cntrafirmas se realizarán en el mism frmat que la firma sbre la que se pera. 6.7 Gestión de fichers Ests sn métd rientads al guardad carga de fichers en disc Guardad de dats en disc El permite almacenar dats en el equip del usuari. Este métd es útil para almacenar dats generads cm parte de la peración del sistema las prpias firmas generadas pr el MiniApplet. 45

46 El integradr puede seleccinar ls dats que desea almacenar, la prpuesta de nmbre para el ficher y trs parámetrs para el diálg de guardad. Sin embarg, será el usuari el únic que pdrá decidir dnde desea almacenar ls dats y qué nmbre tendrá el ficher. Ls dats guardads sn ls dats indicads en base64 ya descdificads. Es decir, si deseams almacenar el text SOY UN TEXTO A FIRMAR, cnvertirems este text a Base 64 cn l que btendríams la cadena U09ZIFVOIFRFWFRPIEEgRklSTUFS y se la pasaríams al métd de guardad. Si abrims el ficher resultante encntrarems que este cntiene la cadena SOY UN TEXTO A FIRMAR. La función JavaScript para el guardad de dats en disc es: functin savedatatfile(datab64, title, filename, extensin, descriptin); En esta función: datab64: Dats en frma de cadena en Base64 que deseams almacenar. Cmúnmente, est será el resultad de una peración de firma uns dats que se habrán prcesad previamente para cdificarls a este frmat. title: Títul del diálg de guardad. filename: Prpuesta de nmbre de ficher. extensin: Extensión de guardad prpuesta. Ls fichers visibles del diálg se filtrarán para sól visualizar ls que tienen esta extensión mientras esté seleccinada en el diálg. Un ejempl de extrensión es: pdf descriptin: Descripción del tip de ficher que se va a almacenar. Esta descripción aparecerá asciada a la extensión indicada. Esta función devlverá true cuand ls dats queden guardads crrectamente. Si el usuari canceló la peración de guardad devlverá false y si se prduj algún errr durante la peración de guardad se lanzará una excepción Ejempls: A cntinuación se muestran distints ejempls relacinads cn el guardad de dats en disc: Guardad de una firma electrónica generada pr el MiniApplet: functin savedatacallback (datab64) { MiniApplet.saveDataTFile(dataB64, Guardar firma electrónica, firma.csig, csig, Firma binaria ); } 46

47 MiniApplet.cSign(dataB64, SHA1withRSA, CAdES, null, savedatacallback, errrcallback); Guardad de dats insertads pr el usuari: var text = dcument.getelementbyid( usertext ).value; var datab64 = MiniApplet.getBase64FrmText(text, aut ); MiniApplet.saveDataTFile(dataB64, Guardar, ficher.txt, txt, Text plan ); <!-- Fragment HTML cn un camp de text en dnde el usuari puede insertar el text que desea guardar --> <frm> <textarea name="usertext" cls="50" rws="5">aquí el usuari puede insertar el text que desee guardar</textarea> </frm> NOTA: Este métd guarda ls dats descdificads, n en base 64, pr l que en este ejempl se guardaría un ficher de text cn el text en clar insertad pr el usuari Selección de un ficher pr parte del usuari y recuperación de su nmbre y cntenid El permite que el usuari seleccine un ficher de su sistema lcal y recuperar del mism su nmbre y cntenid. Este métd ns permite cargar fichers para firmarls, multifirmarls u perar cn ells de cualquier tr md. La función JavaScript para el guardad de dats en disc es: functin getfilenamecntentbase64(title, extensins, descriptin); En esta función: title: Títul del diálg de selección. extensins: Listad de extensines de ficher permitidas. Estas aparecerán separadas pr una cma (, ) y sin espacis entre ellas. Pr ejempl: pdf,jpg,txt. El diálg sól mstrará ls fichers cn estas extensines, salv que el usuari establezca l cntrari en el diálg. descriptin: Descripción del tip de ficher que se espera cargar. Esta descripción aparecerá asciada a las extensines indicadas. 47

48 Este métd devuelve el nmbre del ficher seleccinad seguid del cntenid del mism en base 64, separads pr el carácter. Si el usuari cancelase el diálg de selección de ficher devlvería null y, en cas de prducirse un errr durante la peración de carga cnversión a base 64, se lanzaría una excepción. Pr ejempl, si se cargase el ficher entrada.txt que cntiene el text SOY UN TEXTO A FIRMAR, ( U09ZIFVOIFRFWFRPIEEgRklSTUFS si l cdificams en base 64) el métd devlvería el text entrada.txt U09ZIFVOIFRFWFRPIEEgRklSTUFS. Advertencia: El us de este métd hace que el despliegue del MiniApplet n sea cmpatible cn el Cliente Móvil. En su lugar, n indique ls dats que desea firma, cfirma cntrafirmar y el MiniApplet permitirá al usuari cargar un ficher de dats/firma sbre el que perar Ejempls: Carga de un ficher y recgida de su nmbre var filenamecntentb64; try { filenamecntentb64 = MiniApplet.getFileNameCntentBase64( Seleccinar ficher, jpg,gif,png, Imagen ); } catch (e) { return; } var filename = filenamecntentb64.substring(0, filenamecntentb64.indexof( )); Carga y firma de un ficher var filenamecntentb64; try { filenamecntentb64 = MiniApplet.getFileNameCntentBase64( Seleccinar ficher, pdf, Adbe PDF ); } catch (e) { return; } var separatridx = filenamecntentb64.indexof( ); var filename = filenamecntentb64.substring(0, separatridx); var datab64; if ((separatridx + 1) < filenamecntentb64.length) { datab64 = filenamecntentb64.substring(separatridx + 1); } else { /* El ficher n cntenía dats */ return; 48

49 } MiniApplet.sign(dataB64, SHA1withRSA, CAdES, null, successcallback, errrcallback); Selección de múltiples fichers pr parte del usuari y recuperación de sus nmbres y cntenids El permite que el usuari seleccine una serie de fichers de su sistema lcal y recuperar el nmbre y cntenid de ls misms. Este métd ns permite cargar fichers para firmarls, multifirmarls u perar cn ells de cualquier tr md. La función JavaScript para el guardad de dats en disc es: functin getmultifilenamecntentbase64(title, extensins, descriptin); En esta función: title: Títul del diálg de selección. extensins: Listad de extensines de ficher permitidas. Estas aparecerán separadas pr una cma (, ) y sin espacis entre ellas. Pr ejempl: pdf,jpg,txt. El diálg sól mstrará ls fichers cn estas extensines, salv que el usuari establezca l cntrari en el diálg. descriptin: Descripción del tip de ficher que se espera cargar. Esta descripción aparecerá asciada a las extensines indicadas. Este métd devuelve una cadena cn el patrón: Nmbre1 Cntenid1 Nmbre2 Cntenid2 NmbreX CntenidX Est es el listad de nmbres y cntenids de ficher cncatenads tds cn el carácter. Un Nmbre X se refiere al nmbre de un de ls fichers seleccinads mientras que el Cntenid X se refiere al cntenid de ese mism ficher. Pr ejempl, si se seleccinasen ls fichers entrada.txt e imagen.jpg, se btendría la cadena de text entrada.txt U09ZIFVOIFRFWFRPIEEgRklSTUFS imagen.jpg A1NSHA1NQW212ASYAN45YMD2MWQEI JHAUHS7SASSNH7DAUDASDA9844, en dnde seguid del text entrada.txt y limitad pr ls caracteres aparece el cntenid de ese ficher cnvertid a base 64 y seguid de l text imagen.jpg y separad pr aparece el cntenid de ese tr ficher. Advertencia: El us de este métd hace que el despliegue del MiniApplet n sea cmpatible cn el Cliente Móvil. En su lugar, n indique ls dats que desea 49

50 firma, cfirma cntrafirmar y el MiniApplet permitirá al usuari cargar un ficher de dats/firma sbre el que perar. N es psible la selección múltiple de fichers mediante este mecanism Ejempls: Carga de fichers y recgida de sus nmbres var filenamecntentb64; try { filenamecntentb64 = MiniApplet.getMultiFileNameCntentBase64( Seleccinar múltiples ficher, jpg,gif,png, Imagen ); } catch (e) { /* Si el errr n se debe a la cancelación pr el usuari, l mstrams. */ if (! es.gb.afirma.cre.aocancelledoperatinexceptin.equals( MiniAppl et.geterrrtype())) { /* Métd del integradr para mstrar lgs */ shwlg(miniapplet.geterrrmessage()); } return; } var i = 0; var separatridx1 = 0; var separatridx2 = -1; var filenames = new Array(); d { separatridx2 = filenamecntentb64.indexof(, separatridx1); filenames[i] = filenamecntentb64.substring(separatridx1, separatridx2); separatridx1 = filenamecntentb64.indexof(, separatridx2 + 1) + 1; i++; } while (separatridx1 > 0); Carga y firma de fichers var filenamecntentb64; try { filenamecntentb64 = MiniApplet.getMultiFileNameCntentBase64( Seleccinar fichers, pdf, Adbe PDF ); } catch (e) { /* Si el errr n se debe a la cancelación pr el usuari, l mstrams. */ if (! es.gb.afirma.cre.aocancelledoperatinexceptin.equals( MiniAppl et.geterrrtype())) { /* Métd del integradr para mstrar lgs */ shwlg(miniapplet.geterrrmessage()); } return; } var separatridx1 = filenamecntentb64.indexof( ) + 1; 50

51 var separatridx2 = 0; var datab64; while (separatridx2 > -1 && separatridx1 > 0 && separatridx1 < filenamecntentb64.length) { separatridx2 = filenamecntentb64.indexof(, separatridx1); if (separatridx2 == -1) { datab64 = filenamecntentb64.substring(separatridx1); } else { datab64 = filenamecntentb64.substring(separatridx1, separatridx2); } MiniApplet.sign(dataB64, SHA1withRSA, CAdES, null, successcallback, errrcallback); if (separatridx2 > -1) { } } separatridx1 = filenamecntentb64.indexof(, separatridx2 + 1) + 1; 6.8 Utilidad Ec El MiniApplet dispne de un métd que devuelve la cadena: Java vendr: JAVA_VENDOR Java versin: JAVA_VERSION Java architecture: JAVA_ARCHITECTURE Esta cadena muestra el fabricante de la máquina virtual, la versión de java que se ejecuta y su arquitectura. Esta misma infrmación se imprime en la cnsla Java al ejecutar el métd precedida pr el mensaje: MiniApplet cargad y en ejecución El principal prpósit de este métd es que ls integradres puedan llamarl para cmprbar si el applet está crrectamente cargad y cmprbar la versión de Java instalada. En cas cntrari, fallará su ejecución. Cuand el métd se invca desde un dispsitiv móvil, en el que n se pueden ejecutar applets, el text devuelt pr la función será: Cliente JavaScript Obtención de ls mensajes de errr Cuand un métd del MiniApplet falla en su ejecución lanza una excepción y almacena el mensaje que describe el errr. El integradr puede acceder a este mensaje e identificar el tip de errr mstrársel al usuari. 51

52 La función JavaScript para recuperar el mensaje de errr prducid pr la aplicación es: functin geterrrmessage(); Este métd devuelve el mensaje de errr antecedid pr el nmbre cualificad de la excepción que l prduj. Para ver ejempls del us de este métd y la gestión de errres del MiniApplet, cnsulte el apartad Gestión de errres Cnversión de una cadena Base64 a text El prprcina un métd para la cnversión de una cadena Base64 a un text plan cn una cdificación cncreta. Este métd permite mstrar al usuari en text plan infrmación que se psea Base64. Cass en ls que puede ser necesari est sn cuand se carga el cntenid de un ficher de text plan desde disc pr medi de algun de ls métds de carga cuand ls dats sn el resultad de una firma XML, pr ejempl. La función JavaScript para recuperar el text plan crrespndiente a la cadena en Base64 es: functin gettextfrmbase64(datab64, charset); En esta función: datab64: Sn ls dats Base64 que se quieren mstrar cm text plan. charset: Es el jueg de caracteres que se debe utilizar para la cnversión. Ls más cmunes sn utf-8, is e is Si se desea utilizar el jueg de caracteres pr defect, indique default pase un valr nul. Si desea que se intente detectar el jueg de caracteres autmáticamente, indique aut. Este métd devuelve una cadena cn el text plan crrespndiente Ejempls Cnversión de una firma XML generada previamente functin shwcallback (signatureb64) { var text = MiniApplet.getTextFrmBase64(xmlSignB64, utf-8 ); alert(text); } MiniApplet.sign(dataB64, SHA1withRSA, XAdES, frmat=xades Envelped, shwtextcallback, errrcallback); 52

53 6.8.4 Cnversión de un text a cadena Base64 El prprcina un métd para la cnversión de un text plan cn una cdificación cncreta a una cadena Base64. Este métd permite pasar al métd de firma un text insertad pr el usuari, pr ejempl. La función JavaScript para cnvertir de text plan a Base64 es: functin getbase64frmtext(plainttext, charset); En esta función: plaintext: Es el text plan que se desea cnvertir a Base64. charset: Es el jueg de caracteres del text plan. Ls más cmunes sn utf-8, is e is Si se desea utilizar el jueg de caracteres pr defect, indique default pase un valr nul. Si desea que se intente detectar el jueg de caracteres autmáticamente, indique aut. Este métd devuelve una cadena Base64 que es la cdificación del text plan indicad Ejempls Firma de un text insertad pr el usuari var text = Hla Mund!! ; var datab64 = MiniApplet.getBase64FrmText(text, utf-8 ); MiniApplet.sign(dataB64, SHA1withRSA, CAdES, null, successcallback, errrcallback); 53

54 7 Cnfiguración de las peracines 7.1 Pas de parámetrs adicinales a ls métds de firma, cfirma y cntrafirma Una peculiaridad del us del API del MiniApplet desde JavaScript es que, para mejrar la fiabilidad, tds ls pass de valres de parámetrs se realizan mediante cadenas de text (ls dats binaris se cdifican en Base64 para pder transmitirls cm texts), per en ls métds de firma, cfirma y cntrafirma se acepta un tip de parámetr (usualmente denminada params) que es una representación textual de una clección de prpiedades Java (Prperties). Las prpiedades establecidas mediante params tienen distintas utilidades según el frmat de firma utilizad (indicar una variante del frmat, especificar una plítica de firma, etc.), per siempre siguen el mism frmat: nmbreparam1=valrparam1 nmbreparam2=valrparam2 Y desde JavaScript deben cncatenarse cada una de las líneas usand el carácter especial de nueva línea (\n) cm separadr: var params= nmbreparam1=valrparam1\nnmbreparam2= valrparam2 ; Es imprtante respetar el nmbre riginal de las prpiedades ya que puede existir diferenciación entre mayúsculas y minúsculas. Cnsulte la dcumentación JavaDc de cada frmat de firma para más infrmación sbre ls parámetrs aceptads pr cada un de ells. 7.2 Selección autmática de certificads Para aquells cass en ls que sól exista un certificad en el almacén de certificads al que se acceda cuand se descarten certificads y sól haya un que es psible seleccinar, es psible indicar al MiniApplet que l seleccine autmáticamente en lugar de mstrar al usuari el diálg de selección cn este únic certificad. Est pdems cnfigurarl mediante la prpiedad headless. Si agregams a la lista de prpiedades que cnfiguran las peracines de firma, cfirma y cntrafirma el parámetr headless cn el valr true, el diálg de selección n se mstrará al usuari cuand sól haya un certificad dispnible. En su lugar, se seleccinará autmáticamente este certificad y se cntinuará 54

55 cn la peración. La línea que debería agregarse a la cnfiguración es, pr tant: headless=true Pr defect, si n se establece la prpiedad headless se indica un valr distint de true, se mstrará el diálg de selección de certificads aun cuand sól haya un certificad para seleccinar. Para saber cóm establecer la prpiedad headless en las peracines de firma cnsulte el apartad Pas de parámetrs adicinales a ls métds de firma, cfirma y cntrafirma. 7.3 Cnfiguración del filtr de certificads El dispne de filtrs de certificads que se pueden aplicar para restringir ls certificads que pdrá seleccinar el usuari para realizar una peración de firma multifirma. Ls filtrs de certificads se pueden establecer cm parámetrs adicinales en las peracines de firma, cfirma y cntrafirma. Las claves que ns permiten establecer filtrs de certificads sn: filter: Esta clave permite establecer un y sól un de ls filtrs de certificads que se listan más adelante en este apartad. Pr ejempl: filter=nnexpired: Certificads n caducads filters: Esta clave permite establecer un más de ls filtrs de certificads listads que se listan más adelante en este apartad. Ls certificads deberán cumplir las cndicines establecidas en tds ls certificads listads, de l cntrari n se mstrarán. Ls distints filtrs se deben separar mediante el carácter punt y cma ( ; ). Ejempls: filters=nnexpired: Certificads n caducads filters=issuer.rfc2254: (O=DIRECCION GENERAL DE LA POLICIA);keyusage.nnrepudiatin:true Certificads de firma del DNIe filters=issuer.rfc2254: (O=DIRECCION GENERAL DE LA POLICIA);keyusage.nnrepudiatin:true;nnexpired: Certificads de firma del DNIe n caducads. 55

56 filters.x: En esta clave X será un enter igual mayr que 1. El MiniApplet leerá la clave filters.1, a cntinuación filters.2 y así hasta que n encuentre una de las claves de la secuencia. Al cntrari que cn la clave filters, basta cn que el certificad cumpla un de ests filtrs para que se muestre. N es necesari cumplirls tds. Cada un de estas claves puede declarar varis filtrs separads pr punt y cma ( ; ) de tal frma que sí se deberán cumplir tds ells para satisfacer ese subfiltr cncret. Ejempl: filters.1=issuer.rfc2254:(o=direccion GENERAL DE LA POLICIA);keyusage.nnrepudiatin:true filters.2=issuer.rfc2254:(o=fnmt) La cnjunción de estas ds claves en una peración de firma hará que sól se muestren al usuari ls certificads CERES y el de firma del DNIe. Estas tres claves de definición de filtrs sn excluyentes y tienen la priridad según la que se listan (filter, filters y filters.x). Es decir, si se establece la prpiedad filter, n se prcesarán las prpiedades filters y filters.1, pr ejempl. Ls filtrs dispnibles en el MiniApplet sn: Filtr DNIe: Filtra ls certificads del almacén para que sól se muestren ls certificads de firma de ls DNIe dispnibles desde ese almacén. Para establecer este filtr de certificads se indicará la prpiedad filter cn el valr dnie: en el parámetr de cnfiguración de la peración de firma, cfirma cntrafirma. Ejempl: filter=dnie: Filtr de certificads de firma: Filtra ls certificads del almacén para que n se muestren ls cnsiderads certificads de autenticación. Esta exclusión n se realiza mediante KeyUsage para evitar que queden excluids certificads mal identificads. Un ejempl de certificad que n se mstrará en el diálg es el de autenticación del DNIe. Para establecer este filtr de certificads se indicará la prpiedad filter cn el valr signingcert: en el parámetr de cnfiguración de la peración de firma, cfirma cntrafirma. Ejempl: filter=signingcert: 56

57 Filtr de certificads de autenticación: Filtra ls certificads del almacén para que n se muestren ls específics para firma avanzada recncida. Esta exclusión n se realiza mediante KeyUsage para evitar que queden excluids certificads mal identificads. Un ejempl de certificad que n se mstrará en el diálg es el de firma del DNIe. Para establecer este filtr de certificads se indicará la prpiedad filter cn el valr authcert: en el parámetr de cnfiguración de la peración de firma, cfirma cntrafirma. Ejempl: filter=authcert: Filtr SSL: Filtra ls certificads del almacén para que sól se muestre aquells cn un númer de serie cncret (cmúnmente sól será un). Existe un cas especial. Si el númer de serie resulta ser de un certificad de autenticación de un DNIe, se mstrará en su lugar el certificad de firma de ese mism DNIe. Para establecer este filtr de certificads se indicará la prpiedad filter cn el valr ssl:, seguid pr el númer de serie del certificad, en el parámetr de cnfiguración de la peración de firma, cfirma cntrafirma. Est es: filter=ssl:nº_serie. El númer de serie se debe indicar en hexadecimal: Ejempls: filter=ssl:45553a61 filter=ssl:03ea Filtr de certificads cualificads de firma: Filtra ls certificads del almacén para que sól se muestre aquells cn un númer de serie cncret (cmúnmente sól será un). En el cas de que este certificad n esté cualificad para firma, se buscará un certificad parej que sí l esté en el almacén. Si se encntrase se seleccinaría este nuev certificad y, si n, se seleccinará el certificad al que crrespnde el númer de serie. Para establecer este filtr de certificads se indicará la prpiedad filter cn el valr qualified:, seguid pr el númer de serie del certificad, en el parámetr de cnfiguración de la peración de firma, cfirma cntrafirma. Est es: filter=qualified:nº_serie. El númer de serie se debe indicar en hexadecimal: Ejempls: filter=qualified:45553a61 filter=qualified:03ea 57

58 Filtr de certificads caducads: Filtra aquells certificads que se encuentran fuera de su perid de validez para que sól se muestren ls certificads vigentes, que sn ls únics que pueden generar una firma válida. Para establecer este filtr se usará la palabra clave nnexpired: Ejempl: filter=nnexpired: Filtr pr huella digital (Thumbprint): Filtra ls certificads de tal frma que sól se mstrará aquel que tenga la huella digital indicada. Hay que tener en cuenta que esta huella digital n debe calcularse en base a un ficher (pr ejempl, un.cer ), sin que es la huella digital de la cdificación del certificad. Para establecer este filtr se usará la palabra clave thumbprint:, seguida del algritm de huella digital utilizad y, separad pr el carácter ds punts ( : ) la huella digital que se busque en hexadecimal. Ejempl: filter=thumbprint:sha1:30 3a bb a fd d7 c5 a2 52 dc a5 54 f4 c5 ee 8a a5 4d Este filtr sól mstrará el certificad cuya huella digital en SHA1 sea la indicada. Filtr RFC2254 en base al Subject del certificad: Filtra ls certificads a partir de una expresión regular creada según la RFC2254 que se aplica sbre el Subject del certificad. Para establecer este filtr se usará el valr subject.rfc2254: seguid de la expresión RFC2254. Puede revisarse la nrmativa RFC 2254 en Ejempl: filter=subject.rfc2254:(cn=* z*) Este filtr mstrará sól aquells certificads en ls que aparezca la cadena z en el CmmnName de su Subject. Filtr RFC2254 en base al Issuer del certificad: Filtra ls certificads a partir de una expresión regular creada según la RFC2254 que se aplica sbre el Issuer del certificad. Para establecer este filtr se usará el valr issuer.rfc2254: seguid de la expresión RFC

59 Puede revisarse la nrmativa RFC 2254 en Ejempl: filter=issuer.rfc2254:( (O=FNMT)(O=DIRECCION GENERAL DE LA POLICIA)) Este filtr mstrará sól aquells certificads cuy Issuer tenga establecid cm rganización FNMT DIRECCION GENERAL DE LA POLICIA, es decir, sól mstrará ls certificads del DNIe y ls de CERES. Filtr de text en base al Subject del certificad: Filtra ls certificads según si cntienen n una cadena de text en el Principal de su Subject. Para establecer este filtr se usará el valr subject.cntains: seguid de la cadena de text que debe cntener. Ejempl: filter=subject.cntains:juan ESPAÑOL ESPAÑOL Este filtr mstrará sól aquells certificads en ls que aparezca la cadena JUAN ESPAÑOL ESPAÑOL en el Subject. Filtr de text en base al Issuer del certificad: Filtra ls certificads según si cntienen n una cadena de text en el Principal de su Issuer. Para establecer este filtr se usará el valr issuer.cntains: seguid de la cadena de text que debe cntener. Ejempl: filter=issuer.cntains:o=empresa Este filtr mstrará sól aquells certificads en ls que el Principal del Issuer muestre el text O=EMPRESA. Filtrs pr us declarad de ls certificads (KeyUsage): Clección de filtrs que permiten filtrar según el us declarad de ls certificads. Para establecer ests filtrs usarems las siguientes claves según ls uss que se quieran cmprbar. Las claves irán seguidas de ls valres true false, según se desee que el us esté habilitad n l esté, respectivamente: keyusage.digitalsignature: keyusage.nnrepudiatin: keyusage.keyencipherment: keyusage.dataencipherment: keyusage.keyagreement: keyusage.keycertsign: 59

60 keyusage.crlsign: keyusage.enciphernly: keyusage.deciphernly: Ls KeyUsages que n se declaren en el filtr n se tendrán en cuenta. Ejempls: filters=keyusage.digitalsignature:true;keyusage. keyencipherment:true Este filtr mstrará sól aquells certificads que tengan establecids a true ls KeyUsage digitalsignature (autenticación) y keyencipherment (sbres electrónics), ignrand el valr del rest de KeyUsages. Este filtr mstrará, pr ejempl, ls certificads de la FNMT. filters=keyusage.nnrepudiatin:true Este filtr mstrará sól aquells certificads que tengan establecids a true el nnrepudiatin (firma avanzada). Este filtr mstrará, pr ejempl, el certificad de firma del DNIe. Se ignrará cualquier valr establecid cm filtr de certificads distint a ls que se han listad. Si ningún certificad cumple ls criteris de filtrad, se lanzará una excepción indicand que n se ha encntrad ningún certificad que cumpla cn ls criteris indicads y se cancelará la peración. Si más de un certificad cumple ls criteris de filtrad, se mstrarán tds ells en el diálg de selección de certificads. Si tan sól un certificad cumple cn las cndicines de ls filtrs establecids y se ha cnfigurad la pción headless en las prpiedades adicinales de la peración, se seleccinará autmáticamente ese certificad sin mstrar el diálg de selección al usuari. Cnsulte el apartad Selección autmática de certificads para cncer cóm cnfigurar la prpiedad headless. Para saber cóm establecer la cnfiguración de ls filtrs de certificads en las peracines de firma cnsulte el apartad Pas de parámetrs adicinales a ls métds de firma, cfirma y cntrafirma. 60

61 7.4 Cnfiguración de la plítica de firma Cnfiguración manual La plítica de firma de una firma electrónica identifica diverss criteris que se han cumplid durante la cnstrucción de esta firma requisits que cumple la prpia firma. Esta plítica de una firma electrónica se identifica mediante varis atributs declarads en la firma. Tds ls frmats avanzads de firma (CAdES y XAdES) tienen una variante EPES (Explicit Pliyc-based Electrnic Signature) que declaran ls atributs crrespndientes a la plítica de firma. El permite la generación de firmas EPES (CAdES-EPES y XAdES-EPES) para l cual es necesari indicar las prpiedades de la plítica en el métd de firma que se vaya a utilizar. Cnsulte el apartad específic de cnfiguración del frmat de firma que desee utilizar para cncer las prpiedades dispnibles para la cnfiguración de la plítica de firma. Para saber cóm establecer estas las prpiedades de firma, cnsulte el apartad Pas de parámetrs adicinales a ls métds de firma, cfirma y cntrafirma. Tenga en cuenta que el que una firma incluya ls atributs crrespndientes a una plítica de firma cncreta n significa que cumpla ls criteris de la plítica. Si desea que sus firmas se ajusten a una plítica de firma lea las restriccines impuestas pr esa plítica y genere firmas acrde a ella antes de cnfigurarla. De esta frma, pdrá asegurarse de que sus firmas sn cmpatibles cn trs sistemas y entrns en ls que se utilicen firmas acrde a la plítica en cuestión Plítica de firma de la AGE v1.8 En el se ha incluid un mecanism para la cnfiguración rápida y sencilla de la plítica de firma de la Administración General del Estad (AGE) v1.8. Para cnfigurar esta plítica cncreta basta cn indicar la siguiente prpiedad en la peración de firma, cfirma cntrafirma, cuand se utilice un frmat avanzad de firma (CAdES y XAdES). expplicy=firmaage Esta prpiedad se expandirá a las necesarias para el cumplimient de la plítica de firma de la AGE, l que equivale a intrducir las prpiedades: CAdES plicyidentifier= plicyidentifierhash=7sxx3erfuh31tvaw9lz70n7p1va= plicyidentifierhashalgrithm=

62 plicyqualifier= cafirma/plitica_firma_age_v1_8.pdf mde=implicit XAdES plicyidentifier=urn:id: plicyidentifierhash=v8lvvngdcpen6velrd1ja8harfk= plicyidentifierhashalgrithm= plicyqualifier= cafirma/plitica_firma_age_v1_8.pdf frmat=xades Detached mde=implicit La prpiedad frmat, sól se aplicará cuand el frmat de firma sea XAdES. La prpiedad mde, sól se aplicará cuand el frmat de firma sea CAdES y ls dats cupen mens de 1 MegaByte. Cn tamañs mayres de dats n se incluirán ests en las firmas. Si se cnfigura para la peración alguna prpiedad individual que cincida cn alguna de las prpiedades a las que se expande la plítica, se ignrará esa prpiedad individual y prevalecerá el valr impuest pr la plítica. Pr ejempl, si se cnfigurasen las prpiedades expplicy=firmaage y frmat=xades Envelping, para una peración de firma cn frmat XAdES, se generaría una firma XAdES Detached cn la plítica de firma de la AGE establecida. Es decir, se ignraría que se estableció la prpiedad frmat=xades Envelping. Para saber cóm cnfigurar prpiedades en las peracines de firma, cnsulte el apartad Pas de parámetrs adicinales a ls métds de firma, cfirma y cntrafirma. Para más infrmación sbre la plítica de firma de la AGE puede cnsultar la guía de implementación de la plítica que está en el área de descargas de la iniciativa Plítica de firma de la AGE en Plítica de firma de Factura electrónica (Facturae) Para la firma de facturas electrónicas se deberá utilizar siempre el frmat FacturaE. Este frmat cnfigura autmáticamente las prpiedades necesarias para la firma de facturas electrónicas, incluida la plítica de firma. Las firmas generadas siempre sn según la especificación 3.1 de factura electrónica. 62

63 Para saber cóm cnfigurar prpiedades en las peracines de firma, cnsulte el apartad Pas de parámetrs adicinales a ls métds de firma, cfirma y cntrafirma. 7.5 Gestión de errres La gestión de errres del MiniApplet se basa en el sistema de captura de excepcines desde JavaScript, prpagadas desde Java. Ls métds del applet lanzan excepcines cuand se prduce algún errr durante su ejecución, y es psible capturar estas excepcines desde JavaScript y ver su tip y descripción gracias a ls métds del MiniApplet. Ests métds sn: geterrrtype(): Devuelve el nmbre cualificad de la clase de excepción. Alguns ejempls sn: java.i.filentfundexceptin: Lanzada cuand n se encuentra el ficher seleccinad pr el usuari. es.gb.afirma.keystres.cmmn.aocertificatesntfundexceptin: Lanzada cuand n hay certificads en el almacén ningun pasa el filtr establecid. es.gb.afirma.cre.aocancelledoperatinexceptin: Cuand el usuari ha cancelad algun de ls diálgs que se le mstró durante la peración (selección de ficher, selección de certificad, inserción de cntraseña). geterrrmessage(): Devuelve el mensaje asciad al errr que se ha prducid. Alguns ejempls sn: El sistema n puede encntrar el archiv especificad El almacen n cntenia entradas validas Operación cancelada pr el usuari Ests mensajes n están internacinalizads (siempre se muestran en castellan) y n cntienen caracteres especiales (cm las tildes españlas). Es recmendable, que el integradr identifique el tip de errres que puede prducir su despliegue y, cuand ls detecte cn geterrrtype() actúe cm crrespnda mstrand un mensaje persnalizad si fuese necesari. A cntinuación se muestra un ejempl simple de gestión de errres en el MiniApplet mediante JavaScript: functin firmar() { var signature; 63

64 } try { sign( Hla, SHA1withRSA, CAdES, null, savedatacallback, errrcallback); } catch(e) { alert( Se prduj un errr al ejecutar la peración de firma ); return; } functin savesignaturecallback (signature) try { MiniApplet.saveDataTFile(signature, Guardar firma, firma.csig, null, null); } catch(e) { alert( Se prduj un errr al ejecutar la peración de firma ); return; } } Una frma de cmpletar el ejempl anterir sería mstrar al usuari más infrmación acerca de la naturaleza del errr, de frma que pueda intentar subsanarl: functin shwerrrcallback (errrtype, errrmessage) { if (errrtype().equals( java.i.filentfundexceptin )) { alert( Errr: N se ha seleccinad un ficher de dats válid ); } else if (errrtype().equals( es.gb.afirma.keystres.cmmn.aocertificatesntfundexceptin ) { alert( Errr: N se ha encntrad ningún certificad de firma válid ); } else { alert( Errr: Se prduj un errr durante la peración de firma ); } } var signature; try { MiniApplet.sign( Hla, SHA1withRSA, CAdES, null, sucesscallback, shwerrrcallback); } catch(e) { shwerrrcallback(miniapplet.geterrrtype(), MiniApplet.getErrrMessage()); } Revise la dcumentación JavaDc de cada métd del MiniApplet para cmprbar que excepcines puede lanzar y el mtiv de las mismas. Cualquier tra excepción n cntemplada en la dcumentación JavaDc se cnsidera un errr prpi de la aplicación. Cuand el cmprtamient de la herramienta difiera según el tip de errr, gestine siempre mediante la cláusula else ls errres n dcumentads. 64

65 8 Cmpatibilidad cn dispsitivs móviles Ls navegadres Web de ls dispsitivs móviles n admiten cmplements capaces de realizar firmas electrónicas (Applets de Java, ActiveX, etc.), pr l que es necesari implementar trs mecanisms para suplir esta carencia. En el cas del, se han desarrllad aplicacines nativas para sistemas móviles que, de frma transparente para el integradr, sustituirán al MiniApplet y realizarán las peracines del firma. Actualmente, existen versines publicadas del Móvil para sistemas Andrid 4 e ios. 8.1 Arquitectura del sistema Dad que ls sistemas móviles impnen limitacines en la cmunicación que puede establecerse entre el navegadr web y una aplicación nativa, ha sid necesari idear una arquitectura de cmunicación que permita el traspas bidireccinal de infrmación entre la aplicación nativa y la página web. La arquitectura es la siguiente: 1. Cuand detecta que está en un dispsitiv móvil, en lugar de cargar el, el navegadr web realiza una llamada pr prtcl a la aplicación nativa (previamente instalada) pasándle ls dats necesaris para ejecutar la peración designada. 65

66 2. La aplicación nativa realiza la peración en base a la cnfiguración prprcinada. 3. La aplicación nativa envía el resultad de la peración a un servidr remt del integradr pr medi de un servici publicad en el mism. Ls dats, sean cuales sean (la firma, mensaje de éxit, mensaje de errr, ), se envían cifrads. 4. La página web descarga y brra el resultad de la peración del servidr pr medi de tr servici web distint al de guardad. La página descifra el cntenid y cntinúa cn el fluj de peración determinad pr el integradr. 8.2 Despliegues cmpatibles Para que nuestrs despliegues del MiniApplet sean cmpatibles cn ls nativs para dispsitivs móviles, de tal frma que las firmas se realicen mediante ests cuand el entrn de ejecución n permita la ejecución de applets, deberems seguir las siguientes pautas: Desplegar el MiniApplet mediante la bibliteca JavaScript miniapplet.js que se distribuye junt a él. Aunque el MiniApplet puede desplegarse cm un Applet nrmal y crriente, tda la lógica que se encarga de ejecutar el móvil cuand n es psible ejecutar applets y prcesa las rdenes al Applet se encuentra en esta bibliteca. El cóm se despliega el MiniApplet cn esta bibliteca se explica en el apartad Despliegue del Establecer las rutas de ls servicis auxiliares del móvil. La falta de un canal de cmunicación bidireccinal entre las el navegadr web y el móvil, al cntrari de l que curre entre el navegadr web y un Applet, bliga a cnstruir una arquitectura de cmunicación basada en 2 servicis encargads de enviar y recger mensajes, respectivamente. Para que el navegadr y el móvil hagan us de este canal se deberán cnfigurar la URL en la que se encuentran ests servicis. La cnfiguración de las URL de ls servicis de cmunicación se realizará mediante el métd: setservlets(urlservletenvi, urlservletrecepcin) La llamada a este métd se deberá realizar inmediatamente después de la sentencia de carga del MiniApplet. 66

67 Esta sentencia es incua para el MiniApplet. Ls servicis sól se usarán en cas de que se cargue el móvil. Un ejempl de us de esta llamada es: <script type="text/javascript"> MiniApplet.cargarMiniApplet( ); MiniApplet.setServlets( ); </script> Simplificar la perativa. El Móvil n implementa tdavía alguns de ls métds y funcinalidades del MiniApplet. Pr l que cnviene n utilizar ests métds si n es necesari y buscar alternativas cmpatibles. Cnsulte el apartad Limitacines funcinales para cncer ls métds que n implementa el móvil. 8.3 Servicis auxiliares del móvil Junt al MiniApplet se distribuyen 2 servlets que permiten el guardad y la recgida de dats en servidr para la cmpatibilidad cn el móvil. Ests servlet sn: SignatureStrageServer: Este servlet permite almacenar dats en un directri del servidr. Ls dats se almacenan cn un identificadr. SignatureRetrieverServer: Este servlet permite recuperar dats de un servidr a partir de un identificadr. Tras devlver ls dats, el servici brra el ficher tempral en dnde se almacenaban. Este servici nunca devlverá dats que se guardasen hace más de un tiemp máxim cnfigurad, devlviend errr tal cm si n hubiese encntrad el ficher de dats. Igualmente, brrará tds aquells fichers del directri tempral que hayan sbrepasad este tiemp máxim desde su creación. Ambs servicis se pueden cnfigurar mediante el ficher de prpiedades cnfiguratin.prperties, cntenid pr ambs. En este ficher pdrems cnfigurar las siguientes variables: tmpdir: Es el directri del servidr en dnde se almacenarán ls dats temprales. Debe cntener el mism valr en ls servicis de guardad y recgida de dats. El administradr del sistema puede determinar que sól ests servicis tengan permis de lectura y escritura en él. Si n se cnfigura esta prpiedad, se usará el directri tempral del servidr. 67

68 exptime: Es el tiemp de caducidad en milisegunds de ls fichers del directri. Esta prpiedad sól se establece para el servici de recuperación de dats. Una vez superad ese tiemp desde la creación del ficher, el servici de recuperación se negará a devlverl y l eliminará. El valr pr defect establecid es (1 minut) Ests servicis de guardad y recuperación se distribuyen en frma de WAR y sn independientes del sftware servidr de aplicacines que se utilice. Cnsulte la dcumentación de su sftware servidr de aplicacines para saber más acerca de cóm desplegarls. El integradr puede sustituir ests servlets pr trs realizads pr él mism siempre y cuand mantenga la interfaz de cmunicación. De esta frma, pr ejempl, pdría crear servlets que almacenasen ls dats en base de dats ls insertase en un bus tempral de dats. 8.4 Ntificacines al usuari Es bligatri que el usuari tenga instalada la aplicación móvil cmpatible cn su dispsitiv antes de realizar el trámite web para el que se haya desplegad el MiniApplet. Pr ell se recmienda a ls integradres que, al detectar el tip de dispsitiv del usuari le adviertan y muestren el enlace a la página de descarga de la aplicación, para que la descarguen e instalen antes de cntinuar. La bibliteca JavaScript que acmpaña al facilita al usuari la detección de ls sistemas perativs móviles cmpatibles mediante las funcines: functin isandrid() Detecta si el usuari accede a la página web desde un dispsitiv Andrid. functin isios() Detecta si el usuari accede a la página web desde un ipd, iphne ipad. Un ejempl del us de estas funcines sería: // Si es un dispsitiv Andrid, mstrams el mensaje de advertencia para Andrid if (MiniApplet.isAndrid()) { dcument.getelementbyid( andridwarning ).style.display = "blck"; } // Si es un dispsitiv ios, mstrams el mensaje de advertencia para ios else if (MiniApplet.isAndrid()) { dcument.getelementbyid( ioswarning ).style.display = "blck"; } 68

69 69

70 8.5 Enlaces de descarga El usuari pdrá encntrar estas aplicacines en la tienda de aplicacines crrespndiente a cada sistema. Ls enlaces dispnibles sn: Enlaces Andrid <a href=" <img alt="andrid app n Ggle Play" src=" </a> <a href=" <img alt="get it n Ggle Play" src=" <a href=" <img alt="andrid app n Ggle Play" src=" </a> <a href=" <img alt="get it n Ggle Play" src=" 70

71 8.5.2 Enlaces ios <a href=" mt=8&u=4" target="itunes_stre" style="display:inline-blck;verflw:hidden;backgrund:url( er.itunes.apple.cm/htmlresurces/assets//images/web/linkmaker/badge_appst re-sm.png) nly screen{backgrund-image:url( es/assets//images/web/linkmaker/badge_appstre-sm.svg);}"></a> <a href=" mt=8&u=4" target="itunes_stre"style="display:inline-blck;verflw:hidden;backgrun d:url( s/web/linkmaker/badge_appstre-lrg.png) nly screen{backgrund-image:url( es/assets/es_es//images/web/linkmaker/badge_appstre-lrg.svg);}"></a> móvil - Ministeri de Hacienda y Administracines Públicas <a href=" mt=8&u=4" móvil - Ministeri de Hacienda y Administracines Públicas</a> 71

72 8.6 Limitacines Debe tenerse en cuenta que las versines actuales de ls distints cliente móviles n implementan tda la funcinalidad dispnible en el MiniApplet, ni es la misma funcinalidad cn la que cuenta cada aplicativ móvil. Las limitacines existentes, ya sea prque aún n se han desarrllad pr la impsibilidad de hacerl para ese sistema cncret, sn las siguientes: Limitacines de frmat N tds ls frmats de firma del MiniApplet están sprtads en su implementación tradicinal mnfásica. Según el sistema móvil, hay frmats que aún n están implementads. Cuand nuestr despliegue utilice un frmat de firma que n esté implementad para el sistema móvil del usuari, se intentará cmpner la firma de frma trifásica, de tal frma que la cnstrucción del frmat de firma se realice en el servidr y sól la peración de firma digital se realice en el dispsitiv del usuari. Para permitir esta cmpatibilidad de frmats el integradr debe desplegar el servici de firma trifásic y cnfigurarl en la web de despliegue del MiniApplet. Puede cnsultar cóm realizar estas tareas en el apartad Firmas/Multifirmas trifásicas. Ls frmats mnfásics sprtads pr cada un de ls sistemas sn: Andrid CAdES PAdES ios CAdES Limitacines funcinales Sistemas Andrid functin getfilenamecntentbase64(title, extensin, descriptin) Ls clientes móviles n dispnen del métd de carga de fichers, ya que est cnllevaría invcar a la aplicación nativa sól para que ns permitiese seleccinar el ficher de dats. En su lugar, cuand se desee permitir al usuari firmar un ficher lcalizad en su dispsitiv, se deberá ejecutar el métd de firma del 72

73 MiniApplet sin indicar ls dats a firmar. De esta frma la aplicación nativa permitirá al usuari seleccinar un ficher y l firmará directamente. functin getmultifilenamecntentbase64(title, extensin, descriptin) Ls clientes móviles n dispnen de un md para cargar múltiples fichers para prcesarls secuencialmente. functin setstickysignatry(stick) Ls clientes móviles n permiten fijar un certificad que el usuari seleccinar durante una peración de firma/multifirma de tal frma que este se reutilice en siguientes peracines Sistemas ios functin savedatatfile() El cliente móvil ios n sprta la peración de guardad en disc, ya que el sistema perativ impide el guardad de dats en un directri cmún y accesible para el usuari, pr l que este n pdría recuperar la firma guardada. functin getfilenamecntentbase64(title, extensin, descriptin) Ls clientes móviles n dispnen del métd de carga de fichers, ya que est cnllevaría invcar a la aplicación nativa sól para que ns permitiese seleccinar el ficher de dats. En su lugar, cuand se desee permitir al usuari firmar un ficher lcalizad en su dispsitiv, se deberá ejecutar el métd de firma del MiniApplet sin indicar ls dats a firmar. De esta frma la aplicación nativa permitirá al usuari seleccinar un ficher y l firmará directamente. functin getmultifilenamecntentbase64(title, extensin, descriptin) Ls clientes móviles n dispnen de un md para cargar múltiples fichers para prcesarls secuencialmente. functin setstickysignatry(stick) Ls clientes móviles n permiten fijar un certificad que el usuari seleccinar durante una peración de firma/multifirma de tal frma que este se reutilice en siguientes peracines. 73

74 9 Infrmación específica para firmas CAdES 9.1 Algritms de firma Las firmas CAdES aceptan ls siguientes algritms de firma (deben escribirse exactamente cm aquí se muestran): SHA1withRSA MD5withRSA MD2withRSA SHA256withRSA SHA384withRSA SHA512withRSA N es recmendable usar ls algritms MD5withRSA y MD2withRSA pr estar bslets y ser vulnerables. Pr la misma razón, es igualmente cnveniente evitar el algritm SHA1withRSA. El algritm más segur, y pr l tant el recmendad para su us es SHA512withRSA. Tenga en cuenta que si el usuari utiliza una versión de Java anterir a la recmendada en el apartad de requisits mínims del Entrn Cliente, es psible que n pueda generar firmas electrónicas cn este algritm desde alguns almacenes de certificads. 9.2 Parámetrs adicinales A cntinuación se detallan ls parámetrs adicinales que aceptan cada una de las frmas de generación de firmas. Es psible que el us de parámetrs n cntemplads en las siguientes tablas prvque trs cambis de funcinamient. N bstante n se dará sprte al aplicativ si se usan parámetrs n dcumentads, asumiend el integradr td el riesg y respnsabilidad derivads del us de parámetrs valres distints de ls aquí descrits Firma y cfirma Nmbre del parámetr Valres Descripción psibles mde explicit La firma resultante n incluirá ls dats firmads. Si n se indica el parámetr mde se cnfigura autmáticamente este cmprtamient. implicit La firma resultante incluirá internamente una cpia de ls 74

75 dats firmads. El us de este valr pdría generar firmas de gran tamañ. cntenttypeoid OID Identificadr del tip de dat firmad. cntentdescriptin [Text] Descripción textual del tip de dats firmad. plicyidentifier [OID URN de tip OID] Identificadr de la plítica de firma, necesari para generar firmas CAdES-EPES. plicyidentifierhash [Valr en Base64] Huella digital de la plítica de firma. Es bligatri indicar este parámetr si de indicó también plicyidentifier, al igual que es bligatri también dar valr al parámetr plicyidentifierhashalgrithm. plicyidentifierhashalgrithm SHA1 Indica que la huella digital plicyqualifier includeonlysignningcertificat e SHA-256 SHA-384 SHA-512 [URL hacia dcumen t] true false indicada en el parámetr plicyidentifierhash se calculó mediante el algritm SHA1. Indica que la huella digital indicada en el parámetr plicyidentifierhash se calculó mediante el algritm SHA-256. Indica que la huella digital indicada en el parámetr plicyidentifierhash se calculó mediante el algritm SHA-284. Indica que la huella digital indicada en el parámetr plicyidentifierhash se calculó mediante el algritm SHA-512. URL (universalmente accesible) hacia el dcument (nrmalmente PDF) que cntiene una descripción textual de la plítica de firma. Este parámetr es pcinal inclus si se desea generar firmas CAdES-EPES. Indica que debe incluirse en la firma únicamente el certificad del firmante. Indica que debe incluirse en la firma tda la cadena de certificación del certificad firmante. Valr pr defect. 75

76 9.2.2 Cntrafirma Nmbre del parámetr plicyidentifier plicyidentifierhash Valres psibles [OID URN de tip OID] [Valr en Base64] Descripción Identificadr de la plítica de firma, necesari para generar firmas CAdES-EPES. Huella digital de la plítica de firma. Es bligatri indicar este parámetr si de indicó también plicyidentifier, al igual que es bligatri también dar valr al parámetr plicyidentifierhashalgrithm. plicyidentifierhashalgrithm SHA1 Indica que la huella digital indicada en el parámetr plicyidentifierhash se calculó mediante el algritm SHA1. plicyqualifier includeonlysignningcertificat e SHA-256 SHA-384 SHA-512 [URL hacia dcumen t] true false Indica que la huella digital indicada en el parámetr plicyidentifierhash se calculó mediante el algritm SHA-256. Indica que la huella digital indicada en el parámetr plicyidentifierhash se calculó mediante el algritm SHA-284. Indica que la huella digital indicada en el parámetr plicyidentifierhash se calculó mediante el algritm SHA-512. URL (universalmente accesible) hacia el dcument (nrmalmente PDF) que cntiene una descripción textual de la plítica de firma. Este parámetr es pcinal inclus si se desea generar firmas CAdES-EPES. Indica que debe incluirse en la firma únicamente el certificad del firmante. Indica que debe incluirse en la firma tda la cadena de certificación del certificad firmante. Valr pr defect. 76

77 10 Infrmación específica para firmas XAdES 10.1 Tratamient de las hjas de estil XSL de ls XML a firmar Cuand se firma cfirma (n aplica a la cntrafirma) un XML que cntiene hjas de estil, estas se firman igualmente (a mens que se indique l cntrari cn el parámetr ignrestylesheets, descrit más adelante), cumpliend las siguientes reglas: Firmas XML Envelped Hja de estil cn ruta relativa N se firma. Hja de estil remta cn ruta absluta Se restaura la declaración de hja de estil tal y cm estaba en el XML riginal Se firma una referencia (cannizada) a esta hja remta Hja de estil emptrada Se restaura la declaración de hja de estil tal y cm estaba en el XML riginal Firmas XML Externally Detached Hja de estil cn ruta relativa N se firma. Hja de estil remta cn ruta absluta Se firma una referencia (cannizada) a esta hja remta Hja de estil emptrada N es necesaria ninguna acción Firmas XML Envelping Hja de estil cn ruta relativa N se firma. 77

78 Hja de estil remta cn ruta absluta Se firma una referencia (cannizada) a esta hja remta Hja de estil emptrada N es necesaria ninguna acción Firmas XML Internally Detached Hja de estil cn ruta relativa N se firma. Hja de estil remta cn ruta absluta Se firma una referencia (cannizada) a esta hja remta Hja de estil emptrada N es necesaria ninguna acción 10.2 Algritms de firma Las firmas XAdES aceptan ls siguientes algritms de firma (deben escribirse exactamente cm aquí se muestran): SHA1withRSA SHA256withRSA SHA384withRSA SHA512withRSA N es recmendable usar el algritm SHA1withRSA pr estar bslet y ser vulnerables. El algritm más segur, y pr l tant el recmendad para su us es SHA512withRSA. Tenga en cuenta que si el usuari utiliza una versión de Java anterir a la recmendada en el apartad de requisits mínims del Entrn Cliente, es psible que n pueda generar firmas electrónicas cn este algritm desde alguns almacenes de certificads Parámetrs adicinales A cntinuación se detallan ls parámetrs adicinales que aceptan cada una de las frmas de generación de firmas. Es psible que el us de parámetrs n cntemplads en las siguientes tablas prvque trs cambis de funcinamient. N bstante n se dará sprte al 78

79 aplicativ si se usan parámetrs n dcumentads, asumiend el integradr td el riesg y respnsabilidad derivads del us de parámetrs valres distints de ls aquí descrits. 79

80 Firma y cfirma Nmbre del parámetr Valres Descripción psibles frmat XAdES Envelping Genera firmas en frmat Envelping. Este es el frmat que se utiliza pr defect cuand n se indica ningun. XAdES Envelped Genera firmas en frmat Envelped. XAdES Detached Genera firmas en frmat includeonlysignningcertificat e true Internally Detached. Indica que debe incluirse en la firma únicamente el certificad del firmante. false Indica que debe incluirse en la firma tda la cadena de certificación del certificad firmante. Valr pr defect. plicyidentifier [URL] Identificadr de la plítica de firma (nrmalmente una URL hacia la plítica en frmat XML prcesable), necesari para generar firmas XAdES-EPES. plicyidentifierhash [Valr en Base64] Huella digital de la plítica de firma. Es bligatri indicar este parámetr si el valr indicad en plicyidentifier n es universalmente accesible. Si se da valr a este parámetr es bligatri también dar valr al parámetr plicyidentifierhashalgrithm. plicyidentifierhashalgrithm SHA1 Indica que la huella digital indicada en el parámetr plicyidentifierhash se calculó mediante el algritm SHA1. SHA-256 SHA-384 SHA-512 Indica que la huella digital indicada en el parámetr plicyidentifierhash se calculó mediante el algritm SHA-256. Indica que la huella digital indicada en el parámetr plicyidentifierhash se calculó mediante el algritm SHA-384. Indica que la huella digital indicada en el parámetr plicyidentifierhash se calculó 80

81 plicyqualifier [URL hacia dcument] mediante el algritm SHA-512. URL (universalmente accesible) hacia el dcument (nrmalmente PDF) que cntiene una descripción textual de la plítica de firma. Este parámetr es pcinal inclus si se desea generar firmas XAdES-EPES. plicydescriptin [Text] Descripción textual de la plítica de firma. En el cas de que se firme un XML, la cdificación del text usad debe adecuarse al XML firmad. Este parámetr es pcinal inclus si se desea generar firmas XAdES-EPES. signerclaimedrle [Text] Agrega a la firma un camp cn el carg atribuid al firmante. En el cas de que se firme un XML, la cdificación del text usad debe adecuarse al XML firmad. signercertifiedrle [Text] Agrega a la firma un camp cn el carg cnfirmad del firmante. En el cas de que se firme un XML, la cdificación del text usad debe adecuarse al XML firmad. signatureprductincity [Text] Agrega a la firma un camp cn la ciudad en la que se realiza la firma. En el cas de que se firme un XML, la cdificación del text usad debe adecuarse al XML firmad. signatureprductinprvince [Text] Agrega a la firma un camp cn la prvincia en la que se realiza la firma. En el cas de que se firme un XML, la cdificación del text usad debe adecuarse al XML firmad. signatureprductinpstalcde [Text] Agrega a la firma un camp cn el códig pstal en dnde se realiza la firma. En el cas de que se firme un 81

82 XML, la cdificación del text usad debe adecuarse al XML firmad. signatureprductincuntry [Text] Agrega a la firma un camp cn el país en el que se realiza la firma. En el cas de que se firme un XML, la cdificación del text usad debe adecuarse al XML firmad. referencesdigestmethd mimetype g/2000/09/xmldsi g#sha1 g/2001/04/xmlenc #sha256 g/2001/04/xmlenc #sha512 g/2001/04/xmlenc #ripemd160 [Text en frmat MIME-Type] Usa el algritm SHA1 para el cálcul de las huellas digitales de las referencias XML firmadas. Usa el algritm SHA-256 para el cálcul de las huellas digitales de las referencias XML firmadas. Este es el valr recmendad. Usa el algritm SHA-512 para el cálcul de las huellas digitales de las referencias XML firmadas. Usa el algritm RIPEMD160 para el cálcul de las huellas digitales de las referencias XML firmadas. MIME-Type de ls dats a firmar. Si n se indica este parámetr el sistema intenta aut-detectar el tip, estableciend el más aprximad (que puede n ser el estrictamente crrect). encding [Text] Cdificación de ls dats a firmar. Un us incrrect de este parámetr puede prvcar la generación de una firma inválida. cntenttypeoid cannicalizatinalgrithm [OID URN de tip OID] g/tr/2001/rec-xm l-c14n g/tr/2001/rec-xm l-c14n # WithCmments Identificadr del tip de dat firmad. Este parámetr es cmplementari (que n excluyente) al parámetr mimetype. Se firma el XML cn cannizad XML 1.0 inclusiv (valr pr defect). Se firma el XML cn cannizad XML 1.0 inclusiv cn cmentaris. 82

83 g/2001/10/xml-ex c-c14n# g/2001/10/xml-ex c-c14n#withcmme Se firma el XML cn cannizad XML 1.0 exclusiv. Se firma el XML cn cannizad XML 1.0 exclusiv cn cmentaris. nts xadesnamespace [URL] URL de definición del espaci de nmbres de XAdES (el us de este parámetr puede cndicinar la declaración de versión de XAdES). ignrestylesheets true Si se firma un XML cn hjas de estil, ignra estas dejándlas sin firmar. false Si se firma un XML cn hjas de estil, firma también las hjas de estil (valr pr defect, cnsultar ntas adicinales sbre firma de hjas de estil). avidbase64transfrms true N declara transfrmacines Base64 inclus si sn necesarias. false Declara las transfrmacines Base64 cuand se han cdificad internamente ls dats a firmar en Base64 (valr pr defect). headless true Evita que se muestren diálgs gráfics adicinales al usuari (cm pr ejempl, para la dereferenciación de hjas de estil enlazadas cn rutas relativas). false Permite que se muestren diálgs gráfics adicinales al usuari. applysystemdate true La firma incluirá un atribut cn la fecha y hra de la firma, btenidas del relj del rdenadr del usuari (valr pr defect). false Se mite la inclusión de la fecha y hra de la firma cm atribut de esta última. xmltransfrms [Númer] Númer de transfrmacines a aplicar al cntenid firmad. Debe indicarse psterirmente igual númer de parámetrs 83

84 xmltransfrmntype g/2000/09/xmldsi g#base64 g/tr/1999/rec-xp ath g/tr/1999/rec-xs lt g/2002/06/xmldsi g-filter2 xmltransfrmntype, sustituyend n pr un rdinal cnsecutiv, cmenzand en 0 (ver ntas adicinales sbre indicación de transfrmacines adicinales). El cntenid se transfrma en Base64 antes de ser firmad. El cntenid se transfrma mediante XPATH antes de ser firmad. Únicamente es aplicable cuand se firma cntenid XML. El cntenid se transfrma mediante XSLT antes de ser firmad. Únicamente es aplicable cuand se firma cntenid XML. El cntenid se transfrma mediante XPATH2 antes de ser firmad. Únicamente es aplicable cuand se firma cntenid XML. xmltransfrmnsubtype [Text] Subtip de la transfrmación n. Ls valres aceptads y sus funcinalidades dependen del valr indicad en xmltransfrmntype. xmltransfrmnbdy [Text] Cuerp de la transfrmación n. Ls valres aceptads y sus funcinalidades dependen del valres indicads en xmltransfrmntype y en xmltransfrmnsubtype. ndetsign [Text] Identificadr del nd (establecid mediante el atribut Id ) que se desea firmar dentr de un XML Indicación de transfrmacines adicinales al cntenid a firmar Respect al us de ls parámetrs xmltransfrmntype, xmltransfrmnsubtype y xmltransfrmnbdy, sus valres van ligads, aceptándse las siguientes cmbinacines: Transfrmación XPATH Tip: 84

85 Subtips: N tiene subtips. Cuerp: Especificad mediante sentencias de tip XPATH. Transfrmación XPATH2 Tip: Subtips: subtract: Resta. intersect: Intersección unin: Unión Cuerp: Especificad mediante sentencias de tip XPATH2. Transfrmación XSLT Tip: Subtips: N tiene subtips. Cuerp: Especificad mediante sentencias de tip XSLT. Transfrmación BASE64 Tip: Subtips: N tiene subtips. Cuerp: N tiene cuerp. N es psible especificar transfrmacines cmplejas que incluyan varias sentencias. En su lugar, puede declararse una sucesión de transfrmacines simples que prduzcan el mism resultad. Cada una de las transfrmacines se aplicará de frma rdenada sbre el resultad de la anterir. El listad de transfrmacines se inicia cn aquella declarada cn el índice 0. Pr ejempl, si se desean insertar 2 transfrmacines adicinales, se deberán establecer ls parámetrs: xmltransfrms=2 xmltransfrm0type= xmltransfrm0subtype= (Opcinal) xmltransfrm0bdy= xmltransfrm1type= xmltransfrm1subtype= (Opcinal) xmltransfrm1bdy= 85

86 Cntrafirma Nmbre del parámetr Valres Descripción psibles plicyidentifier [URL] Identificadr de la plítica de firma (nrmalmente una URL hacia la plítica en frmat XML prcesable), necesari para generar firmas XAdES-EPES. plicyidentifierhash [Valr en Base64] Huella digital de la plítica de firma. Es bligatri indicar este parámetr si el valr indicad en plicyidentifier n es universalmente accesible. Si se da valr a este parámetr es bligatri también dar valr al parámetr plicyidentifierhashalgrithm. plicyidentifierhashalgrithm SHA1 Indica que la huella digital indicada en el parámetr plicyidentifierhash se calculó mediante el algritm SHA1. plicyqualifier SHA-256 SHA-384 SHA-512 [URL hacia dcument] Indica que la huella digital indicada en el parámetr plicyidentifierhash se calculó mediante el algritm SHA-256. Indica que la huella digital indicada en el parámetr plicyidentifierhash se calculó mediante el algritm SHA-384. Indica que la huella digital indicada en el parámetr plicyidentifierhash se calculó mediante el algritm SHA-512. URL (universalmente accesible) hacia el dcument (nrmalmente PDF) que cntiene una descripción textual de la plítica de firma. Este parámetr es pcinal inclus si se desea generar firmas XAdES-EPES. plicydescriptin [Text] Descripción textual de la plítica de firma. En el cas de que se firme un XML, la cdificación del text usad debe adecuarse al XML firmad. Este parámetr es pcinal 86

87 inclus si se desea generar firmas XAdES-EPES. signerclaimedrle [Text] Agrega a la firma un camp cn el carg atribuid al firmante. En el cas de que se firme un XML, la cdificación del text usad debe adecuarse al XML firmad. signercertifiedrle [Text] Agrega a la firma un camp cn el carg cnfirmad del firmante. En el cas de que se firme un XML, la cdificación del text usad debe adecuarse al XML firmad. signatureprductincity [Text] Agrega a la firma un camp cn la ciudad en la que se realiza la firma. En el cas de que se firme un XML, la cdificación del text usad debe adecuarse al XML firmad. signatureprductinprvince [Text] Agrega a la firma un camp cn la prvincia en la que se realiza la firma. En el cas de que se firme un XML, la cdificación del text usad debe adecuarse al XML firmad. signatureprductinpstalcde [Text] Agrega a la firma un camp cn el códig pstal en dnde se realiza la firma. En el cas de que se firme un XML, la cdificación del text usad debe adecuarse al XML firmad. signatureprductincuntry [Text] Agrega a la firma un camp cn el país en el que se realiza la firma. En el cas de que se firme un XML, la cdificación del text usad debe adecuarse al XML cntrafirmad. encding [Text] Fuerza una cdificación para la firma resultante. Un us incrrect de este parámetr puede prvcar la generación de una firma inválida. 87

88 applysystemdate true La firma incluirá un atribut cn la fecha y hra de la firma, btenidas del relj del rdenadr del usuari (valr pr defect). false Se mite la inclusión de la fecha y hra de la firma cm atribut de esta última. 88

89 11 Infrmación específica para firma de facturas electrónicas 11.1 Operacines n sprtadas y ntas de interés Las facturas electrónicas se firman cn el frmat XAdES Envelped per cn unas particularidades cncretas que n es psible replicar mediante el frmat XAdES del Es necesari utilizar el frmat FacturaE para la firma de facturas. El frmat FacturaE sól puede utilizarse sbre facturas electrónicas acrdes al estándar. Las facturas electrónicas n sprtan las peracines de cfirma ni cntrafirma. Si se intenta hacer una peración de cfirma cntrafirma sbre una factura electrónicas se ntificará que n es psible prque ésta ya cuenta cn una firma Algritms de firma Las firmas de FacturaE aceptan ls siguientes algritms de firma (deben escribirse exactamente cm aquí se muestran): SHA1withRSA SHA256withRSA SHA384withRSA SHA512withRSA El algritm más segur, y pr l tant el recmendad para su us es SHA512withRSA. Sin embarg, tenga en cuenta que si el usuari utiliza una versión de Java anterir a la recmendada en el apartad de requisits mínims del Entrn Cliente, es psible que n pueda generar firmas electrónicas cn ls algritms SHA-2 (SHA256, SHA384 y SHA512) desde alguns almacenes de certificads Parámetrs adicinales A cntinuación se detallan ls parámetrs adicinales que acepta el frmat FacturaE para la cnfiguración de la peración y la firma electrónica generada. Es psible que el us de parámetrs n cntemplads en las siguientes tablas prvque trs cambis de funcinamient. N bstante n se dará sprte al aplicativ si se usan parámetrs n dcumentads, asumiend el integradr td el riesg y respnsabilidad derivads del us de parámetrs valres distints de ls aquí descrits. 89

90 Nmbre del parámetr Valres Descripción psibles signercertifiedrle [Text] Agrega a la firma un camp cn el carg cnfirmad del firmante. signatureprductincity [Text] Agrega a la firma un camp cn la ciudad en la que se realiza la firma. signatureprductinprvince [Text] Agrega a la firma un camp cn la prvincia en la que se realiza la firma. signatureprductinpstalcde [Text] Agrega a la firma un camp cn el códig pstal en dnde se realiza la firma. signatureprductincuntry [Text] Agrega a la firma un camp cn el país en el que se realiza la firma. 90

91 12 Infrmación específica para firmas PAdES 12.1 Operacines n sprtadas y ntas de interés Las firmas PAdES n admiten cntrafirmas. Una cfirma PAdES cnsiste en la adición de una firma adicinal al dcument PDF, sin que se establezca ninguna relación de interdependencia cn las firmas existentes. Cfirmar un dcument PDF es cmpletamente equivalente a firmar un dcument PDF ya firmad. Adbe Acrbat/Reader n sprta múltiples firmas cuand hay firmas PAdES-BES. Únicamente es psible usar PAdES para dcuments PDF. N se firman ls psibles adjunts emptrads que pudiese cntener el dcument PDF. N se sprta la firma de PDF cifrads cn certificads cn algritm AES Algritms de firma Las firmas PAdES aceptan ls siguientes algritms de firma (deben escribirse exactamente cm aquí se muestran): SHA1withRSA SHA256withRSA SHA384withRSA SHA512withRSA El estándar PAdES recmienda n usar el algritm SHA1withRSA pr n ser el más segur. El algritm más segur, y pr l tant el recmendad para su us es SHA512withRSA. Sin embarg, tenga en cuenta que si el usuari utiliza una versión de Java anterir a la recmendada en el apartad de requisits mínims del Entrn Cliente, es psible que n pueda generar firmas electrónicas cn ls algritms SHA-2 (SHA256, SHA384 y SHA512) desde alguns almacenes de certificads Parámetrs adicinales A cntinuación se detallan ls parámetrs adicinales que aceptan cada una de las frmas de generación de firmas. Es psible que el us de parámetrs n cntemplads en las siguientes tablas prvque trs cambis de funcinamient. N bstante n se dará sprte al 91

92 aplicativ si se usan parámetrs n dcumentads, asumiend el integradr td el riesg y respnsabilidad derivads del us de parámetrs valres distints de ls aquí descrits. 92

93 Nmbre del parámetr Valres psibles Descripción signaturesubfilter adbe.pkcs7.detache Cnfigura la peración para d generar firmas PAdES Simple. ETSI.CAdES.detache Cnfigura la peración para d generar firmas PAdES-BES. Esta pción puede hacer que al realizar varias firmas sbre un dcument, Adbe Acrbat/Reader indique que plicyidentifier [OID URN de tip OID] las anterires n sn válidas. Identificadr de la plítica de firma, necesari para generar firmas PAdES-EPES. plicyidentifierhash [Valr en Base64] Huella digital de la plítica de firma. Es bligatri indicar este parámetr si de indicó también plicyidentifier, al igual que es bligatri también dar valr al parámetr plicyidentifierhashalgrithm. plicyidentifierhashalgrit hm plicyqualifier SHA1 SHA-256 SHA-384 SHA-512 [URL hacia dcument] Indica que la huella digital indicada en el parámetr plicyidentifierhash se calculó mediante el algritm SHA1. Indica que la huella digital indicada en el parámetr plicyidentifierhash se calculó mediante el algritm SHA-256. Indica que la huella digital indicada en el parámetr plicyidentifierhash se calculó mediante el algritm SHA-284. Indica que la huella digital indicada en el parámetr plicyidentifierhash se calculó mediante el algritm SHA-512. URL (universalmente accesible) hacia el dcument (nrmalmente PDF) que cntiene una descripción textual de la plítica de firma. Este parámetr es pcinal inclus cuand se genera una firma 93

94 EPES. signatureprductincity [Text] Incluye un camp en el diccinari PDF cn la ciudad dnde se ha realizad la firma. signercntact [Text] Incluye un camp en el diccinari PDF cn infrmación de cntact del [Text]firmante (usualmente una dirección de crre electrónic). signfield [Text] Nmbre del camp, pre-cread y vací, del PDF dnde debe insertarse la firma generada. signaturepage [Enter] Númer de página, empezand en 1, en dnde crear el camp de firma visible para la firma. Se puede indicar la última página cn el valr signaturepsitinonpagelwe rleftx signaturepsitinonpagelwe rlefty signaturepsitinonpageuppe rrightx signaturepsitinonpageuppe rrighty [Enter] [Enter] [Enter] [Enter] Crdenada hrizntal inferir izquierda del recuadr visible de la firma desde la esquina inferir izquierda de la página. Crdenada vertical inferir izquierda del recuadr visible de la firma desde la esquina inferir izquierda de la página. Crdenada hrizntal superir derecha del recuadr visible de la firma desde la esquina inferir izquierda de la página. Crdenada vertical superir derecha del recuadr visible de la firma desde la esquina inferir izquierda de la página. signaturerubricimage [Text Base64] Imagen JPG cdificada en base 64 que se desea aparezca en el camp de firma. layer2text [Text] Text que mstrar en el camp visible en dnde se inserta la firma. 94

95 layer2fntfamily 0 Muestra el text del cap de firma cn fuente Curier. 1 Muestra el text del cap de firma cn fuente Helvetica. 2 Muestra el text del cap de firma cn fuente Times Rman. 3 Muestra el text del cap de firma cn fuente Symbl. 4 Muestra el text del cap de firma cn fuente ZapfDingBats. layer2fntsize [Enter] Tamañ de fuente cn el que se muestre el text del camp de firma. layer2fntstyle [Enter] Estil del text del camp de firma. Se expresa cn la suma de ls valres asignads a cada estil: 0 (Nrmal), 1 (Negrita), 2 (Cursiva), 4 (Subrayad) y 8 (Tachad). Pr ejempl: el valr 3 indica text en negrita y cursiva. layer2fntclr [Text] Clr del text del camp de firma. Ls valres sprtads sn: black, white, gray, lightgray, darkgray, red y pink. headless true Evita mstrar diálgs gráfics adicinales al usuari (cm pr ejempl, la slicitud de cntraseñas de ls PDF). false Permite mstrar diálgs gráfics adicinales al usuari (valr pr defect). avidencryptingsignedpdfs true N cifra el PDF firmad aunque el PDF riginal si l estuviese. false Cifra el PDF firmad cuand PDF riginal l estuviese (valr pr defect). wnerpasswrd [Text] Cntraseña del PDF a firmar en el cas de que este estuviera cifrad. allwsigningcertifiedpdfs true Permite la firma de PDF certificads (la firma 95

96 false resultante puede ser inválida) N permite la firma de PDF certificads (valr pr defect). 96

97 13 Prblemas cncids 13.1 Errr al firmar fichers mayres de 4 megabytes El plugin de Java limita en cierta medida ls dats que el cliente es capaz de prcesar, l que suele reducir el tamañ máxim de dats que el MiniApplet puede firmar. Est se ve acmpañad de las psibles limitacines que surjan de la cantidad de memria dispnible en el equip del usuari. En la versión 1.2 del MiniApplet se ha paliad este prblema de tal frma que el límite de tamañ pasa a depender más de ls recurss del equip del usuari y la cnfiguración de la peración de firma. De frma segura, se pueden realizar firmas de dats de un tamañ mínim de 8 megabytes. Pr parte del integradr, es psible evitar parcialmente esta limitación abandnand, siempre que sea psible, el us de ls métds de carga de ficher getfilenamecntentbase64 y getmultifilenamecntentbase64, en favr de la carga de dats realizada al llamar a las peracines criptgráficas sin indicar ls dats a firmar/multifirma. Pr ejempl, en lugar de llamar al métd getfilenamecntentbase64 para cargar un ficher y lueg pasarle ls dats btenids al métd sign, llamarems al métd sign sin dats para que sea el mism el que permita cargar el ficher de dats Cn el navegadr Mzilla Firefx y DNIe (DNI Electrónic) el applet se queda blquead y n muestra el diálg de selección de certificads, desblqueándse si retir el DNIe del lectr El cntrladr PKCS#11 ficial del DNIe n admite que se establezcan varias sesines de frma simultánea, y si pr cualquier razón (sesión SSL, etc.) el prpi navegadr Web Mzilla / Firefx tiene ya establecida una cmunicación cn el DNIe en el mment en el que el también l necesita, este últim se queda blquead esperand a que en navegadr Mzilla / Firefx cierre su sesión. El cierre de la sesión cntra el DNIe pr parte de Mzilla / Firefx puede tardar varis minuts si el usuari n interviene, pr l que cnviene frzar manualmente este cierre: Extraer el DNIe del lectr y vlverl a insertar just en el mment en el que se slicita la cntraseña del Repsitri Central de certificads de Mzilla Firefx (antes de intrducirla). Es psible que Mzilla / Firefx 97

98 reabra la sesión en la reinserción (adelantándse al pr l que quizás necesite repetir la peración. Pdems indicar a Mzilla / Firefx que cierre la sesión pulsand el btón Lg ut teniend el dispsitiv DNIe PKCS#11 Mdule seleccinad en la ventana Dispsitivs de Seguridad del menú Opcines de Mzilla Firefx. Al igual que en el métd anterir, a veces es necesari repetir la peración varias veces, ya que Mzilla / Firefx reabre autmáticamente la cmunicación cn el DNIe sin dar tiemp al a utilizarl. En tras casines, el btón aparece deshabilitad aunque Mzilla / Firefx tenga una sesión abierta cntra el dispsitiv, cn l que n es psible aplicar este métd. Este prblema surge principalmente en sistemas Linux/Slaris. Para ests sistemas se recmienda el us del cntrladr OpenDNIe para DNI electrónic. Puede encntrar este cntrladr en: N se detecta la inserción/extracción del DNIe en el lectr (u tra tarjeta inteligente) A veces puede currir que el navegadr n detecta la extracción intrducción del DNIe (u tra tarjeta inteligente) en el lectr, pr l que si n hems intrducid la tarjeta previamente a que se arranque el cliente de firma, n se encntrará el certificad. Otr psible cas es que una vez cargad el cliente, se extraiga la tarjeta y, al realizar una peración de firma, el navegadr muestre 98