Manual del integrador del MiniApplet v1.5 del y la compatibilidad de sus despliegues con AutoFirma y el mo vil

Transcripción

1 Manual del integradr del MiniApplet v1.5 del y la cmpatibilidad de sus despliegues cn AutFirma y el m vil

2 Índice de cntenids 1 Intrducción Prducts de tercers incluids cn el Requisits mínims Entrn Cliente MiniApplet AutFirma Dispsitivs móviles Entrn Servidr Funcinalidad 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) ODF (Open Dcument Frmat Firmas de dcuments LibreOffice / OpenOffice.rg) OOXML (Office Open XML Firmas de dcuments Micrsft Office) Selección autmática del frmat de firma Frmats de firma n recmendads Us de certificads y claves privadas pr parte del Establecimient manual del almacén de certificads y claves Us de tarjetas inteligentes Us exclusiv de certificads accesibles mediante PKCS#11 en Mzilla Firefx 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 Entrns n cmpatibles cn Applets y prblemas durante la carga Carga directa de AutFirma y ls clientes móviles

3 4.3 Cnfiguración del idima Restricción según desfase hrari cn el servidr Firma del JAR del MiniApplet Despliegue en entrns de Web dinámica y en servidres n estátics El prces de firma electrónica Selección del cntenid a firmar La cnversión de dats a Base Selección de cntenid desde fichers en disc Selección de dats remts Selección de bjetiv de las cntrafirmas Selección del certificad y clave privada de firma Nta técnica: La cadena de cnfianza de un certificad 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 MiniApplet Servici de firma trifásica Firmas/Multifirmas masivas Firma pr ltes predefinids Cnfiguración del servici Creación de ls ltes

4 6.7.3 Respuesta a una ejecución de un lte Descripción del md transaccinal de ejecución de ls ltes Firma/multifirma y guardad del resultad Gestión de fichers Guardad de dats en disc Selección y recuperación de un ficher pr parte del usuari Selección y recuperación de múltiples fichers pr parte del usuari 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 Descarga de dats remts Selección de certificad Cnfiguración de las peracines Pas de parámetrs adicinales a ls métds de firma, cfirma y cntrafirma Parámetrs adicinales n sprtads Selecció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 la AGE v Plítica de firma de Factura electrónica (Facturae) Cnfiguración de parámetrs de la JVM Cnfiguración de la Máquina Virtual de Java para tratamient de fichers grandes Cnfiguración a través de prpiedades del sistema Gestión de errres Cmpatibilidad cn dispsitivs móviles y AutFirma Arquitectura del sistema

5 9.1.1 Entrns de escritri (Windws, Linux y Mac OS X) cn nuevs navegadres Dispsitivs móviles, Internet Explrer 10 e inferires y Micrsft Edge Despliegues cmpatibles Cnfiguración de la invcación a AutFirma Servicis auxiliares del móvil Ntas sbre ls servicis de almacenaje y recuperación Ntificacines al usuari Limitacines Limitacines de frmat Limitacines funcinales Cmpatibilidad del cn aplicacines móviles y AutFirma Enví anónim de estadísticas pr parte del MiniApplet y AutFirma Infrmación específica para firmas CAdES Algritms de firma Firmas CAdES implícitas explícitas 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 Algritms de huella digital para las referencias Situación del nd de firma en XAdES Envelped Us de estructuras Manifest en firmas XAdES Frmats de XAdES cmpatibles cn estructuras Manifest Parámetrs adicinales Firma y cfirma Cntrafirma Firmas XAdES explícitas Infrmación específica para firma de facturas electrónicas

6 12.1 Operacines n sprtadas y ntas de interés Algritms de firma Parámetrs adicinales Infrmación específica para firma de dcuments en frmat ODF Algritms de firma Infrmación específica para firma de dcuments en frmat OOXML Algritms de firma Infrmación específica para firmas PAdES Creación de una firma visible Inserción de una imagen en un dcument PDF antes de ser firmad Operacines n sprtadas y ntas de interés Firma de dcuments PDF cifrads prtegids cn cntraseña Algritms de firma Parámetrs adicinales Prblemas cncids El n funcina adecuadamente cn las versines de Firefx de la 42.0 a la N se puede acceder al almacén de claves de Firefx 49.0 y superires Us de cierts algritms cn Windws XP Diálgs de advertencia al usuari en Java 7u55 y psterires (incluyend Java 8) Errr El cnjunt de claves n existe al firmar cn el almacén de claves de Windws 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 El servici de firma trifásica genera un errr al realizar firmas XAdES en servidres JBss Las firmas cn DNIe requieren que se intrduzca el PIN del DNIe pr cada peración de firma N aparecen ls certificads de las tarjetas de la FNMT al ejecutar el desde Firefx Errr en la firma cn tarjetas de la FNMT desde Firefx

7 1 Intrducción El MiniApplet (también referid en este manual cm MiniApplet simplemente Cliente ) es una herramienta de firma electrónica que funcina en frma de Applet de Java integrad en una página Web mediante JavaScript. El MiniApplet puede integrarse en trámites web pr medi del JavaScript de despliegue que l acmpaña. De esta frma, permite que se ejecuten peracines de firma en ests trámites usand ls certificads del ciudadan. En cas de n pder ejecutarse el MiniApplet pr prblemas de cmpatibilidad de entrn, raznes cnfianza permiss restringids, el JavaScript de despliegue derivará las tareas de firma en una aplicación de nativa instalada en el sistema (AutFirma y móvil). Estas aplicacines deberán estar instaladas previamente en el sistema. Las instruccines y explicacines detalladas en el presente dcument se refieren pr nrma al MiniApplet, per afectan igualmente a AutFirma y ls móviles salv en ls aspects detallads en el apartad Cmpatibilidad cn dispsitivs móviles y AutFirma. El MiniApplet 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 MiniApplet le envía ls dats a firmar y éste ls devuelve firmads. El MiniApplet 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 MiniApplet sí almacena el lg de su última ejecución a efects de frecer sprte al usuari si se encntrase algún errr durante la ejecución del Applet. Sól se almacena el lg de la última ejecución del MiniApplet, este n cntiene ningún tip de infrmación persnal y el integradr n tiene acces al mism. Es el usuari quien debe remitirl. El MiniApplet 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 AutFirma y descargar el códig fuente y ls binaris de la aplicación en la siguiente dirección Web: 7

8 1.1 Prducts de tercers incluids cn el El incluye, entre trs, ls siguientes prducts de tercers: JXAdES ( BuncyCastle ( 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 ( 8

9 2 Requisits mínims 2.1 Entrn Cliente MiniApplet Entrn de ejecución de Java: Java SE 6 Update 38 (1.6.0_38) superir, en 32 bits (x86). Se recmienda adptar Java 8 si n fuese psible usar al mens Java 6u45 7u76. En Apple OS X n se sprta (pr bslescencia) la versión 6 del JRE de Apple, siend necesari usar las versines 7 u 8 del JRE de Oracle. Java SE 7 Update 10 (1.7.0_10) superir. Se recmienda adptar Java 8 si n fuese psible usar al mens Java 7u76. En 32 (x86) 64 (x64/amd64) bits según la arquitectura del navegadr Web. En Internet Explrer se recmienda siempre usar versines de 32 bits. Java SE 8 Se recmienda usar al mens la versión 8u51. En 32 (x86) 64 (x64/amd64) bits según la arquitectura del navegadr Web. En Internet Explrer se recmienda siempre usar versines de 32 bits. Sistema perativ: Windws XP SP3, Vista SP2, 7 SP1, 8 y 10, en 32 (x86) 64 (x64) bits. Se recmienda abandnar Windws XP en favr de Windws 7 superir. 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. Se recmienda al mens un Linux basad en la versión 3 superir del núcle (Linux Kernel). Apple OS X Ysemite ( superir) El Capitán ( ). Navegadr Web: Mzilla Firefx 4.0 superir Mzilla Firefx, entre sus versines 40 y 47, sufre un prblema que dificulta el us de applets. Se recmienda el us de la versión 49 superir. En cas de querer utilizar el almacén de claves de Firefx independientemente del navegadr que utilice el usuari, se recmienda utilizar un Firefx de 32 bits en cas de que el sistema perativ bjetiv sea Wndws y un Firefx de 64 bits en cas de OS X. De esta frma, la arquitectura del navegadr pr defect del sistema y la de Firefx será la misma y la JVM cargada pr el Java Plugin pdrá acceder al almacén del sistema y al de Firefx. 9

10 Ggle Chrme versines de la 15 a la 41. A partir de, Chrme 41, es necesari tener previamente instalad el prgrama AutFirma en el sistema del usuari. Apple Safari 6.2 superir (sprte prestad únicamente para la versión OS X). Micrsft Internet Explrer 8 superir (se recmienda usar siempre versines de 32 bits). Las versines 8 y 9 de 64bits de Internet Explrer requieren que se tenga una versión de Java de 64 bits. Sin embarg, Internet Explrer 10 y superires, independientemente de la arquitectura del navegadr, siempre utilizan Java 32 bits. Micrsft Edge 20 superir. Es necesari tener previamente instalad el prgrama AutFirma en el sistema del usuari. 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 ls entrns de ejecución redistribuibles de Micrsft Visual C y Si n cnsigue acceder a sus certificads y claves privadas desde el necesitará descargarls e instalarls manualmente. Ests pueden descargarse de: Visual Studi 2013 (una vez en el enlace, seleccine el idima y la arquitectura adecuada para su Sistema perativ). Visual Studi 2005 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. Nta para usuaris de Firefx 49 superir y Windws: La carga del almacén de claves y certificads de Firefx 49 superir pr parte del necesita que el sistema tenga instalad ls entrns de ejecución redistribuibles de Micrsft Visual C Si n cnsigue acceder a sus certificads y claves privadas desde el, necesitará descargarls e instalarls manualmente. Ests pueden descargarse de: Visual Studi 2015 (una vez en el enlace, seleccine el idima y la arquitectura adecuada para su Sistema perativ) El prces de instalación puede requerir permiss de administradr. Nta para usuaris de Micrsft Edge: Micrsft Edge n sprta la ejecución de Applets de Java, pr l que ls usuaris necesitarán tener preinstalad AutFirma para ejecutar las peracines de firma desde este navegadr. Adicinalmente, n se sprta la cmunicación a través de sckets 10

11 entre AutFirma y Micrsft Edge, pr l que ls despliegues del MiniApplet deberán cnfigurar un servidr intermedi para dar sprte a este navegadr Habilitación de Applets de Java en navegadr Web (cualquier entrn perativ) En cualquier entrn perativ actual, y debid a ls riesgs de seguridad que ell implica, es necesari habilitar ls Applets de Java en ls navegadres Web. Para ell, es necesari seguir un prces que es diferente según el navegadr Web, y que puede variar según el sistema perativ. Cnsulte la dcumentación del navegadr Web para btener instruccines sbre cóm habilitar ls Applets de Java, y siga atentamente las indicacines de Oracle para este prces, que puede encntrar en: Cmpatibilidad cn Windws 8 y superires 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: 11

12 Cmpatibilidad cn Apple OS X Ls Applets de Java en OS X cn Safari tienen restringid pr defect el acces al sistema de fichers, l cual puede causar cierta cnfusión cn el MiniApplet en OS X, prque da la impresión de funcinar aprpiadamente, per cuand se slicita abrir guardar un ficher, n es psible. En particular, l que el usuari aprecia al intentar abrir un ficher es que el diálg de selección se abre, per n muestra ningún archiv: Para cnseguir que el MiniApplet tenga acces n restringid al sistema de fichers del usuari es necesari que este cnfigure Safari para habilitar el Md Insegur para el siti Web en cncret que publique el MiniApplet. Para ell, siga las indicacines de Apple, que puede encntrar aquí: 12

13 2.1.2 AutFirma Para cncer ls mds de instalación de AutFirma y ls requisits del sistema, cnsulte el dcument AF_manual_instalacin_y_gestin_ES. 2.2 Dispsitivs móviles Ls Applets Java, cm el, n puede ejecutarse desde dispsitivs móviles cm Ggle Andrid Apple ios; sin embarg, el crrect despliegue del MiniApplet hará que sus aplicacines puedan ejecutar las peracines de firma utilizand las aplicacines nativas del pryect para ests sistemas en lugar del MiniApplet. Cnsulte el apartad Cmpatibilidad cn dispsitivs móviles y AutFirma 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) cn JEE 5 cm mínim. 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). 13

14 3 Funcinalidad prprcinada pr el El prprcina únicamente funcinalidades de firma electrónica (incluyend firmas múltiples) sbre un cnjunt de frmats de firma, per n tras funcinalidades cm sbres digitales cifrads simétrics, cm hacía el Applet Adicinalmente, se prprcina un cnjunt de métds de utilidad y pcines de peración. Si necesita una funcinalidad n sprtada pr el MiniApplet, cnsulte el catálg de para determinar cuál es la más aprpiada para sus necesidades. AutFirma y ls clientes móviles n sprtan tdas las peracines del. Para cnsultar las funcinalidades dispnibles en cada una de estas peracines, cnsulte el apartad Cmpatibilidad cn dispsitivs móviles y AutFirma. 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 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. 14

15 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 sl puede utilizarse sbre facturas electrónicas y sbre ellas sól es psible realizar la peración de firma. N permite cfirmarlas ni cntrafirmarlas. 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-Básic (pr defect) PAdES-BES PAdES-EPES 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. 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-Básic a mens que se indique una plítica de firma AGE 1.9 superir (en cuy cas, pr adecuación, se pasa a generar PAdES-BES) se indique explícitamente mediante un parámetr adicinal que se desea usar PAdES-BES ODF (Open Dcument Frmat Firmas de dcuments LibreOffice / OpenOffice.rg) El MiniApplet es capaz de realizar firmas ODF, de frma acrde a la siguiente tabla de cmpatibilidad: Impress (Presentacines) OpenOffice.rg 3.2 / 3.3 Calc (Hjas de Writer (Texts) Cálcul) Es imprtante reseñar que las firmas ODF n sn acrdes al Esquema Nacinal de Interperabilidad (ENI). 15

16 Algritm de firma para dcuments ODF El frmat ODF únicamente admite el algritm de firma SHA1withRSA, pr l que siempre se usará ese algritm cn independencia del valr que se indique cm algritm en la invcación (aunque se indique un valr distint a SHA1withRSA, se usará siempre SHA1withRSA) OOXML (Office Open XML Firmas de dcuments Micrsft Office) Es psible firmar dcuments OOXML en frmats recncids pr Micrsft Office. El sprte de las firmas realizadas cn el MiniApplet en cuant a versines y prgramas de Micrsft Office es la siguiente: Office 2007 Office 2008 Office 2010 Office 2011 Office 2013 Office 2016 Wrd (dcx) NO N/A SÍ N/A SÍ NO Excel (xlsx) NO N/A SÍ N/A SÍ NO PwerPint (pptx) NO N/A SÍ N/A SÍ NO Prject NO NO NO NO NO NO OneNte NO NO NO NO NO NO Visi NO NA NO NO NO NO XPS NO NO NO NO NO NO SÍ = Cmpatible, NO = N cmpatible, N/A = N aplica (estas versines de Office para OS X n permiten mstrar cmprbar las firmas OOXML). Tengase en cuenta que las firmas generadas pr el n sn cmpatibles actualmente cn Micrsft Office Es imprtante reseñar que las firmas OOXML n sn acrdes al Esquema Nacinal de Interperabilidad (ENI) Versines de Java cmpatibles cn las firmas OOXML Pr errres cncids de la máquina virtual de Java en su versión 6, únicamente es psible realizar este tip de firmas cn Java 7 y superires, recmendándse el us de Java 8u51 cm mínim. 3.2 Selección autmática del frmat de firma El permite que se indique la palabra clave AUTO cm frmat de firma. En este cas, el cmprtamient variará según la peración de firma que se intente realizar: En una peración de firma simple, se realizará la firma usand cm frmat aquel predefinid para el tip de dat de entrada: Si ls dats sn un dcument PDF, se utilizará el frmat de firma PAdES. Si ls dats sn una factura electrónica, se utilizará el frmat de firma FacturaE. Si ls dats sn XML, se utilizará el frmat de firma XAdES. Si ls dats sn un dcument ODF, se utilizará el frmat de firma ODF. 16

17 Si ls dats sn un dcument OOXML, se utilizará el frmat de firma OOXML. En cualquier tr cas, se utilizará el frmat de firma CAdES. ADVERTENCIA: El us del valr AUTO cm frmat en las peracines de firma se encuentra dispnible a partir de la versión 1.4 del MiniApplet. N se recmienda el us de este valr cuand el bjet de la firma sea el registr de dcumentación del usuari pr parte de la entidad mtiv similar que permita que implique el registr de las firmas del usuari pr parte de la entidad y sea susceptible de que se firmen dcuments en diverss frmats, ya que se dificultaría la gestión de las firmas. En una peración de cfirma cntrafirma, se realizará esta cfirma cntrafirma en el frmat que estuviese la firma electrónica de entrada. 3.3 Frmats de firma n recmendads El sprta, además de ls mencinads, la realización de firmas en ls frmats CMS/PKCS#7 y XMLDSig (XML Digital Signature). Sin embarg, se recmienda que n se haga us de ests frmats pr estar bslets. 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. Ls frmats CMS y XMLDSig se incluyen en el cn el únic bjetiv de prprcinar cmpatibilidad cn aplicacines que hiciesen us de ests frmats. Su us está ttalmente desacnsejad y n se prprcina sprte sbre ests frmats. 3.4 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 17

18 c. Linux: Almacén central 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). Almacén NSS de Mzilla (requiere que esté instalad Mzilla Firefx). PKCS11 (Public Key Cryptgraphy Specificatin number 11). Cn independencia del almacén que use el MiniApplet el navegadr puede cmbinar el us de uns u trs almacenes para tareas relacinadas cn las cnexines SSL, aspect que n influye en estas reglas de selección. Así, pr ejempl Mzilla Firefx hará us del almacén NSS para las cnexines de Red, per utilizará el de Java a la hra de cargar Applets desde sitis Web cn SSL 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 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 puede realizar durante la carga del MiniApplet/AutFirma en tiemp de ejecución. Para cnfigurar el us de un almacén durante el prces de carga pasarems el tip de almacén cm segund parámetr del métd utilizad: cargarminiapplet(string, String) cargarappafirma(string, String). Cnsulte la sección de despliegue del MiniApplet para mayr infrmación sbre ests métds. Para cnfigurar el us de un almacén durante la ejecución del Applet AutFirma se utilizará el métd setkeystre(string). En cas de ser AutFirma el cliente en ejecución y estar usándse la cmunicación pr sckets, se reiniciará la cmunicación para asegurar que las siguientes peracines usan el almacén prprcinad. El tip de almacén 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 18

19 Llaver de Mac OS X. Cmpatible únicamente cn sistemas Apple Mac OS X. KEYSTORE_SHARED_NSS Almacén NSS del sistema. Cmpatible únicamente cn sistemas Linux. KEYSTORE_MOZILLA Almacén NSS de Mzilla (Mzilla Firefx, Mzilla Thunderbird, etc.). KEYSTORE_PKCS12 Almacén en ficher PKCS#12 / PFX (Persnal File Exchange). KEYSTORE_JAVA Almacén en ficher JKS (Java KeyStre). KEYSTORE_JCEKS Almacén en ficher JCEKS (Java Cryptgraphy Extensin KeyStre). KEYSTORE_JAVACE Almacén en ficher de tip CaseExactJKS (Case Exact Java KeyStre). 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 un 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. 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 19

20 ni en Mac OS X, per tampc en Windws 64 bits si se usa el MiniApplet desde un navegadr de 64 bits. ADVERTENCIA: Ls almacenes que hacen us de un ficher bibliteca requieren una cntraseña de acces. Esta cntraseña se preguntará directamente al usuari cuand se requiera el acces al almacén. ADVERTENCIA: El acces al almacén de Mzilla desde Windws, cuand n se realiza desde el prpi navegadr, puede requerir la instalación de algún entrn de ejecución de Visual C++. Si se quiere trabajar cn este cas de us, cnsulte ls requisits de Mzilla Firefx en el apartad MiniApplet 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_MOZILLA); MiniApplet.cargarMiniApplet(cdeBase, MiniApplet.KEYSTORE_PKCS12 + :C:\\prueba\\almacen.p12 ); MiniApplet.cargarMiniApplet(cdeBase, MiniApplet.KEYSTORE_PKCS11 + :C:\\Windws\\System32\\PkcsV2GK.dll ); 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. 20

21 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 Us de tarjetas inteligentes El MiniApplet tiene acces a las claves de las tarjetas inteligentes a partir de sus cntrladres cuand están instalads en el sistema. Para utilizar ls certificads en tarjeta en las peracines de firma, se puede acceder a ells desde un almacén PKCS#11 cnfigurad desde cualquiera de ls almacenes de sistema dispnibles: KEYSTORE_WINDOWS: El almacén de Windws carga autmáticamente tdas las tarjetas insertadas para las que se haya instalad su cntrladr CSP el MiniDriver crrespndiente de Windws Update. En cas de detectarse un DNIe insertad una tarjeta CERES, se hará us de ls misms a partir de un cntrladr intern de la aplicación para crregir prblemas detectads cn Java en ls cntrladres ficiales. KEYSTORE_MOZILLA/ KEYSTORE_SHARED_NSS: Ls almacenes de Mzilla se cmpnen de un almacén intern y el cnjunt de cntrladres PKCS#11 de las tarjetas instaladas en el sistema. El MiniApplet cargará autmáticamente el almacén intern y tds ls dispsitivs detectads. Debid a prblemas detectads cn Java y ls cntrladres ficiales de DNIe y tarjetas CERES, en cas de detectarse insertada cualquiera de estas tarjetas se utilizará un cntrladr intern de la aplicación, ignrándse ls PKCS#11 cnfigurads en el almacén de Mzilla. En cas de detectar alguna de estas tarjetas también se ignrarán el rest de dispsitivs insertads para evitar prblemas entre ls distints cntrladres. KEYSTORE_APPLE: El llaver de OS X se cmpne de un almacén interns y el cnjunt de cntrladres de las tarjetas insertadas. Debid a prblemas detectads cn Java y ls cntrladres ficiales de DNIe y tarjetas CERES, en cas de detectarse insertada cualquiera de estas tarjetas se utilizará un cntrladr intern de la aplicación. Pr regla general, se cnsidera que sól debería haber una tarjeta inteligente insertada en el mment de firmar. En cas de encntrarse varias, se dará priridad al DNIe y las tarjetas CERES. En dichs cass, es psible que ls certificads del rest de tarjetas n aparezcan dispnibles para firmar den errr durante la firma Us exclusiv de certificads accesibles mediante PKCS#11 en Mzilla Firefx Estableciend a true la prpiedad del sistema es.gb.afirma.keystres.mzilla.ladsscdonly (debe hacerse antes de la carga del 21

22 MiniApplet) se activa un md especial de funcinamient que prvca que se ignren ls certificads y claves del almacén central de certificads de Mzilla Firefx (NSS) y se usen exclusivamente ls accesibles mediante móduls de seguridad PKCS#11 adicinales. Esta funcinalidad puede resultar útil para frzar el us de tarjetas inteligentes dispsitivs de almacén USB y descartar ls certificads aljads en el almacén sftware del navegadr. Cnsulte el apartad Cnfiguración a través de prpiedades del sistema para saber cóm establecer prpiedades de sistema Frzar ruta del almacén de Mzilla Firefx El MiniApplet detecta de frma autmática dónde está instalad el navegadr Mzilla Firefx y, de esta frma, cóm acceder al su almacén de certificads y cuál es el almacén crrespndiente al usuari actual, si hubiese varis usuaris definids dentr de la misma cuenta del sistema perativ. Si n se encntrase ningún activ el perfil de ningún usuari de entre ls definids, se cargaría el perfil pr defect. 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 mdificad (cm una edición Prtable) si se intenta acceder al almacén de una cuenta cncreta de Firefx sin usar el prpi navegadr. En ests cass, el integradr pdrá usar las siguientes prpiedades del sistema para lcalizar ls recurss necesaris para indicar al MiniApplet dnde encntrarl: es.gb.afirma.keystres.mzilla.useenvirnmentvariables Establezca esta variable a true para indicar que deben leerse alguna de las ds variables que se describen a cntinuación. AFIRMA_NSS_HOME Directri cn las biblitecas NSS cmpatibles cn la versión de a la que pertenezca el almacén al que deseams acceder. AFIRMA_PROFILES_INI Ruta cmpleta (incluyend el nmbre de archiv) hacia el ficher prfiles.ini que cntiene la infrmación de perfiles de usuari de Firefx. Pr ejempl: AFIRMA_PROFILES_INI=c:\Tmas\prfiles.ini Si el ficher referenciad en esta variable de entrn n existe n se tienen permiss de lectura sbre él, se ignra, pasándse entnces a usar el ficher de perfiles pr defect de Firefx. 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. 22

23 Cnsulte el apartad Cnfiguración a través de prpiedades del sistema para saber cóm establecer prpiedades de sistema Aclaracines sbre la cnfiguración de perfiles de Mzilla Firefx La funcinalidad descrita anterirmente debe aplicarse únicamente cuand se está segur de la lcalización de ls directris de Mzilla Firefx y esta n es la nrmal para ells, l cual se suele dar únicamente en despliegues interns muy cntrlads de versines alteradas de Mzilla Firefx, cm las versines que se denminan Prtables. El ficher de cnfiguración prfiles.ini de Firefx cntiene infrmación sbre ls perfiles de usuari instalads en un entrn de ejecución cncret de Firefx. Un ejempl de este ficher pdría ser el siguiente: [General] StartWithLastPrfile=1 [Prfile0] Name=default IsRelative=1 Path=Prfiles/ir5ad1g.default Default=1 [Prfile1] Name=default IsRelative=1 Path=Prfiles/ir5ad1g.default [Prfile2] Name=default IsRelative=1 Path=Prfiles/ir5ad1g.default En este ficher se puede bservar que hay cnfigurads tres perfiles de usuari, siend el perfil pr defect el primer (el númer cer). N bstante, el que esté declarad cm pr defect únicamente quiere decir que este será el usad en Firefx si el usuari n indica l cntrari. Dad que el MiniApplet se inicia estand 23

24 ya un perfil activ (puest que se inicia desde un Firefx cuand ya hay un perfil cargad), es el estad de activ n activ el factr que se usa para seleccinar el perfil a usar. Un perfil se cnsidera activ cuand su directri (que en este ejempl, y para el primer perfil sería Prfiles/ir5ad1g.default ) cntiene un ficher llamad parent.lck lck. Adicinalmente, es imprtante recalcar que en una exprtación cpia de perfiles (tant si se hace de frma manual cm si se usan las herramientas para tal fin de Firefx) pueden quedarse varis perfiles cm activs simultáneamente (varis perfiles cntendrán un ficher llamad parent.lck lck, aunque sl debería cntenerl un entre tds ls perfiles). En ests cass, el MiniApplet seleccinará el primer perfil activ que encuentre (siguiend el rden establecid en prfiles.ini), y si se desea alterar este cmprtamient será necesari subsanar el prblema eliminand tds ls fichers parent.lck lck de tds ls directris de perfil estand Firefx detenid. 24

25 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 MiniApplet 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: Si la página Web en la que deseams cargar el MiniApplet estuviese también en la ruta se pdría hacer referencia a la bibliteca miniapplet.js de frma relativa indicand: 25

26 <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) 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: 26

27 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 almacén de claves y certificads. ElMiniApplet 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> Entrns n cmpatibles cn Applets y prblemas durante la carga Tant si se slicita la carga del MiniApplet desde un entrn n cmpatible (entrns móviles, Ggle Chrme versión 42 superir, Micrsft Edge, etc.), cm cuand n es psible cargar el Applet (falta 27

28 de permiss, Java n instalad,), el JavaScript de despliegue trata de delegar las peracines que debía ejecutar el MiniApplet en una aplicación nativa de firma. En el cas de entrns de escritri, si el usuari tiene instalad AutFirma, esta aplicación será lanzada para ejecutar las peracines de firma que crrespndan. En el cas de un dispsitiv Andrid ios, se utilizará la aplicación móvil crrespndiente a ese sistema. Puede encntrar el listad de funcinalidades del MiniApplet cmpatibles cn AutFirma y ls clientes móviles en el apartad Cmpatibilidad cn dispsitivs móviles y AutFirma. Tenga en cuenta también que ls clientes móviles y determinads entrns que ejecuten AutFirma necesitan de servicis externs que psibiliten la cmunicación entre la página Web y el cliente de firma. Puede encntrar infrmación detallada sbre este punt en el apartad Servicis auxiliares del móvil Carga directa de AutFirma y ls clientes móviles Es psible que un integradr decida desechar directamente el, de tal frma que se deriven tdas las peracines de firma en AutFirma y ls móviles. Para cargar directamente estas aplicacines, utilice en lugar del métd de carga descrit del MiniApplet el siguiente métd de carga: cargarappafirma(cdebase, keystre) Ls parámetrs cdebase y keystre sn exactamente iguales a ls del métd de carga del MiniApplet. Cnsulte ls ejempls anterires para cncer su utilidad y md de us. Un ejempl del us de este métd es: <script type="text/javascript"> MiniApplet.cargarAppAfirma( ); </script> El parámetr keystre tendrá efect cuand se cargue AutFirma cm herramienta para la realización de la firma, n cuand se utilice el móvil. Para cncer más detalles de la funcinalidad y us de AutFirma y ls móviles, cnsulte el apartad Cmpatibilidad cn dispsitivs móviles y AutFirma. La cmunicación entre la aplicación de firma y la página del trámite web se realizará cuand sea psible a través de un scket (entrns cn AutFirma y navegadres web que l sprten) y si n a través de servicis externs. Es psible, sin embarg, que un integradr deseche el us de la cmunicación vía scket en pr de la cmunicación mediante servidr intermedi, para así mantener la cmpatibilidad de versines de AutFirma que n la sprtasen, pr ejempl. En ese cas, puede 28

29 cnfigurar el md de cmunicación mediante el servici intermedi llamand al métd setfrcewsmde(blean) antes de invcar al métd de carga. Pr ejempl: <script type="text/javascript"> MiniApplet.setFrceWSMde(true); MiniApplet.cargarMiniApplet( ); </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á invcarse siempre antes del métd de carga del MiniApplet y del métd checktime, en cas de usarse. 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) Ls siguientes métds JavaScript permiten al integradr establecer explícitamente mensajes y texts que aparecerán al usuari en ls distints diálgs gráfics del Applet. Es respnsabilidad del integradr establecer ests texts en el idima que crrespnda en el mment de invcar a ests métds: 29

30 savedatatfile (datab64, title, filename, extensin, descriptin, successcallback, errrcallback) getfilenamecntentbase64 (title, extensins, descriptin, filepath) getmultifilenamecntentbase64 (title, extensins, descriptin, filepath) Cnsulte la dcumentación de ests métds para cncer la descripción de cada un de ls parámetrs cnfigurables. 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, checkurl) 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. checkurl URL cntra la que se realizara la petición para btener la hra del servidr. Si n se indica este parámetr, se usará una página web aleatria dentr del prpi dmini. Según la cnfiguración de su servidr web, es psible que n se pueda determinar la hra a través de las peticines realizadas. De ser así, n se mstrará nada al usuari para n perjudicar la realización del trámite. También es psible que su servidr sól transmita la hra en la primera carga de la página 30

31 y n cuand esta se refresca. Si ese fuese el cas, sól se advertiría de la diferencia hraria en la primera carga de la página y n sí el usuari le da a refrescar la página desde su navegadr. Téngase en cuenta también que el desfase hrari se calcula en el mment de invcar al métd checktime. Así pues, si el usuari mdificase la hra de su sistema después de cmprbación de invcar a este métd, pdría realizar peracines de firma sin que se le mstrasen advertencias. En cas de que desee blquear de frma cmpleta la firma de dats cn una hra de sistema incrrecta, asegúrese de que el servidr de la página web de cmprbación de hra siempre envía la hra en las respuestas de sus peticines y llame al métd checktime antes de cada peración de firma. 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. 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): Es preferible en cualquier cas utilizar certificads apts para firma de aplicacines que estén recncids pr Oracle cm de cnfianza. 4.6 Despliegue en entrns de Web dinámica y en servidres n estátics El MiniApplet necesita que tds sus recurss (JAR de Java, fichers JavaScript y página HTML de despliegue) se encuentren en el mism directri (misma ruta Web). Cuand se despliega este en servidres Web n estátics (cm un servidr de Prtlets, un servidr de páginas activas de Micrsft, etc.), es respnsabilidad del integradr hacer que ls recurss puedan ser referenciads tal y cm si estuviesen en un servidr estátic bien mdificar tant HTML cm JavaScript para intrducir referencias abslutas dnde pudiese ser necesari. Cm nrma general, n se prprcina sprte técnic para prblemas de despliegue en entrns Web cn servidres n estátics, cm pueden ser: 31

32 Servidres de aplicacines usand páginas dinámicas (JSP, JSF, ASP, etc.). Mapes virtuales de ls directris que puedan afectar a ls recurss del MiniApplet. Servidres de Prtlets. Etc. 32

33 Ja v a S c r i p t SECRETARÍA GENERAL DE ADMINISTRACIÓN DIGITAL 5 El prces de firma electrónica Selección de cntenid a firmar Selección de certificad de firma Firma Recgida de resultad 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. Base64 M i n i A p p l e i r m a Binari 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. 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 33

34 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. Si se desea restringir el tip de ficher a firmar, es psible indicar a ls distints métds de firma un listad de extensines de ficher. En cas de hacerl, al usuari sól le aparecerán pr defect en el diálg de selección ls fichers cuya extensión esté entre las indicadas. Para cnfigurar este cmprtamient se utilizará el parámetr extra filenameexts y se le pasará cm parámetr el listad de extensines separadas pr el carácter cma (, ). Pr ejempl: filenameexts=pdf Sól mstrará pr defect ls fichers cn extensión.pdf. filenameexts=pdf,swf Sól mstrará pr defect ls fichers que tengan la extensión.pdf.swf Inclus si se ha indicad este parámetr, el usuari pdrá vlver a ver tds ls archivs seleccinar según si el diálg de carga de fichers su sistema perativ dispne de esta capacidad. Para saber más acerca de la cnfiguración de parámetrs adicinales de cnfiguración, cnsulte el apartad Pas de parámetrs adicinales a ls métds de firma, cfirma y cntrafirma. Alternativamente, aunque n es 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 de ests. Cnsulte el apartad de Selección y recuperación de un ficher pr parte del usuari para más detalles. El us de ls métds getfilenamecntentbase64() y getmultifilenamecntentbase64() rmpe la cmpatibilidad del despliegue cn el móvil. 34

35 5.1.3 Selección de dats remts El MiniApplet dispne de un métd JavaScript para la descarga de dats remts. Cuand ls dats que se desean prcesar se encuentran en una URL (HTTP HTTPS), es psible hacer us de este métd de descarga para btener ess dats cdificads en Base64. De esta frma, pueden indicarse nrmalmente ls dats descargads cm entrada del métd de firma del MiniApplet cualquier tr dat que se reciba en Base64. Este métd tendrá las mismas restriccines de acces que el JavaScript del navegadr, l cual, en cndicines nrmales, bliga a que ls dats estén en el mism dmini que la página Web que alja el MiniApplet, y debe ser accesible pr el mism prtcl (HTTP HTTPS). El métd en cuestión es dwnladremtedata. Cnsulte el apartad Descarga de dats remts para más detalles Selección de bjetiv de las cntrafirmas El cas de las cntrafirmas es especial, ya que ls 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). 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 de 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. 35

36 5.2.1 Nta técnica: La cadena de cnfianza de un certificad Ls certificads frman nrmalmente parte de una cadena de cnfianza, en el que el certificad cuy titular es usuari final ha sid a su vez firmad pr tr certificad, el de una Autridad de Certificación intermedia (CA), y este a su vez pr una Autridad de Certificación raíz (la autridad intermedia puede n existir y que el certificad del usuari haya sid firmad directamente pr la CA raíz que haya varias autridades intermedias encadenadas, ese aspect depende de la arquitectura seleccinada pr el emisr de ls certificads). Pr ejempl, un certificad de DNIe, usualmente tiene esta cadena: CA Raíz DNIe. CA Intermedia DNIe. Certificad DNIe de ciudadan. Tant el MiniApplet cm la aplicación AutFirma incluyen en la firma, siempre que sea psible y n se indique l cntrari, la cadena cmpleta de cnfianza del certificad usad para firmar, siguiend de esta manera las recmendacines en este sentid Algritms de huella digital para la firma de certificads y su relación cn la cadena de cnfianza Cm se ha cmentad anterirmente, ls certificads van firmads pr su antecesr en la cadena de cnfianza (except el certificad raíz, que es aut-firmad), y estas firmas, cm cualquier tra firma, tienen sus algritms de huella digital. Muchs certificads de CA Raíz CA intermedias que riginalmente fuern firmads mediante el algritm de huella digital SHA-1, han debid migrarse a SHA-2 (usualmente a SHA-256) debid a la bslescencia e inseguridad de SHA-1, y en la mayría de ls cass se ha ptad pr refirmar exactamente el mism certificad (cn las mismas claves, pública y privada) sl que cn distint algritm de huella, en vez de sustituirl pr un certificad nuev (cn claves nuevas). En ests cass, al tener un certificad raíz ( raíz intermedia) SHA-2 las mismas claves que su hmólg SHA-1, ambs frman una cadena de certificación crrecta, per sl un de ells puede aparecer en la cadena. El usa la cadena de certificads que devuelve el subsistema de gestión de claves del equip del firmante (NSS en Firefx, MS-CAPI en Windws, etc.), pr l que n es psible frzar el us de certificads SHA-2 en la cadena ni determinar cuál de ls ds se usará en el cas de que ambs estén imprtads en este subsistema. Cnsulte cn su fabricante (Mzilla en el Cas de Firefx, Micrsft en el cas de tr navegadr en Windws, Apple en el cas de tr navegadr en OS X, etc.) para btener más infrmación sbre las reglas de cnfrmación de cadenas de cnfianza cuand hay dispnibles varis certificads equivalentes per cn distinta algritmia de huella digital. 36

37 Cnviene resaltar un cas especial, que es el us de tarjetas inteligentes en Mzilla Firefx (en cualquier sistema perativ). En este cas, la cnfrmación de la cadena de cnfianza se delega en el cntrladr PKCS#11 (habitualmente suministrad pr el fabricante de la tarjeta, per puede ser de un fabricante independiente), y su crrección y cntenid depende tant de las funcinalidades de este cm de si la prpia tarjeta cntiene n la cadena cmpleta de certificads para cada una de sus entradas. Cnsulte en este cas cn el fabricante de su módul PKCS#11 (FNMT-RCM para tarjetas CERES, Cuerp Nacinal de Plicía en el cas de DNIe, etc.) para btener más infrmació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 firma, puede indicarse el frmat AUTO para indicar que se realice la firma cn un frmat acrde al tip de dats prprcinads. Cnsulte el apartad Selección autmática del frmat de firma para más infrmación. 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 de estas 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 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. En la llamada a savedatatfile() pueden indicarse ls texts que debe mstrar el diálg, pr l que debe tener la precaución, pr cherencia, de usar el mism idima que ha cnfigurad para el MiniApplet. Una alternativa a invcar la función de firma y psterirmente a la de guardad, es llamar al métd signandsavetfile(), cn el que se ejecutará la peración deseada y psterirmente se dará la pción al usuari de guardar el ficher. El resultad de la peración es el mism que el que devlvería la llamada a la peración de firma crrespndiente, inclus si el usuari decide n guardar ls dats a disc. 37

38 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. 38

39 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 Firmas/Multifirmas masivas Firma de ltes Firma/multifirma y guardad 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 MiniApplet btienen cm resultad la firma/multifirma generada. Esta firma puede btenerse de ds frmas: directamente cm valr de retrn de las 39

40 funcines mediante funcines callback que establecen el cmprtamient definid para prcesar ese resultad. ADVERTENCIA: Su despliegue sól será cmpatible cn AutFirma y ls clientes móviles si utiliza el md asíncrn para la btención de resultads. Para cncer más detalles acerca de la cmpatibilidad de ls despliegues del MiniApplet cn las aplicacines nativas, cnsulte el apartad Cmpatibilidad cn dispsitivs móviles y AutFirma. Ls métds de peración del MiniApplet sn únics, lueg se usa un mecanism u tr según si se han establecid ls métds de callback (md 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 sí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 AutFirma y 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 var message = MiniApplet.getErrrMessage(); 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 ; 40

41 6.2.2 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í mism, el us de este mecanism permite que nuestr despliegue sea cmpatible cn AutFirma y 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 qué 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 de firma, cfirma cntrafirma. Gestinar el errr devuelt pr una peración de firma, cfirma cntrafirma. La función que gestina el resultad crrect de las peracines criptgráficas recibe ds parámetrs que serán el resultad devuelt pr la peración (la firma, cfirma cntrafirma generada en base64) y el certificad utilizad para firmar (cdificad en base64). Esta puede tener la frma: functin successcallback(signaturebase64, certificateb64) { } 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) { } 41

42 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 functin savesignaturefunctin (signatureb64) { // Guardams la firma en un camp de un frmulari dcument.getelementbyid( result ).value = signatureb64; // 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 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. 42

43 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 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 parámetrs la firma resultante y el certificad utilizad en la peración. 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 Gestión de errres para btener más infrmación. El resultad de esta peración puede btenerse directamente gestinarse 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. // Advertencia: Esta peración n se puede ejecutar en AutFirma desde Chrme // prque n sprta 2 llamadas al applet sin interacción cn el usuari. functin savesignaturefunctin (signatureb64, certificateb64) { MiniApplet.saveDataTFile(signatureB64, 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); 43

44 Firma electrónica de un text intrducid pr el usuari: var text = dcument.getelementbyid( usertext ).value; 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. 44

45 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 en cfirmas y cntrafirmas. Este valr sól reprduce el frmat, n las prpiedades de las firmas riginales. Pr ejempl, si cfirmásems una firma XAdES-EPES, indicand "AUTO" cm 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 45

46 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 parámetrs la cfirma resultante y el certificad utilizad en la peración. 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 Gestión de errres para más infrmación. 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, certificateb64) { dcument.getelementbyid( resultid ).value = csignb64; dcument.getelementbyid( firmante ).value = certificateb64; dcument.getelementbyid( frmulari ).submmit(); } // 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 // ésta 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) { 46

47 } 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 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 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 en cfirmas y cntrafirmas. 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 47

48 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 parámetrs la cntrafirma resultante y el certificad utilizad en la peración. 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 Gestión de errres para más infrmación. 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: 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: 48

49 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 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í: 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: 49

50 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: 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 50

51 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: 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( 51

52 ); signatureb64, SHA1withRSA, XAdES, null, successcalback, errrcallback Cntrafirma electrónica del resultad de una firma: // Advertencia: Esta peración n cn AutFirma ejecutad desde Chrme sin // que el usuari intervinese entre ambas peracines 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. 3. Finalmente, cmpne la firma en el frmat de firma electrónica cnfigurad. Sin embarg, el MiniApplet y AutFirma también permiten 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 preprcesar 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. 52

53 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 sbre dispsitivs móviles 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. Cm nta imprtante, debe recalcarse que el prcedimient de firma trifásic es útil únicamente cuand ls fichers residen en servidr y se implementan las clases adecuadas para su btención y almacenamient. Cuand el dcument a firmar reside en cliente, n sl se prduce un innecesari tráfic de red, sin que se aumenta la psibilidad de fall y se incrementan las necesidades de memria del MiniApplet Realizar firma trifásicas cn el MiniApplet Para bligar al AutFirma 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, FacturaEtri, PAdEStri y XAdEStri, respectivamente, cm identificadr del frmat. 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: 53

54 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 afirma-server-triphase-signer.war 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, FacturaE y PAdES (firmas y multifirmas) y admite las mismas pcines de cnfiguración que las firmas mnfásicas de ests frmats. 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. Advertencia: Alguns servidres de aplicacines y entrns incrpran biblitecas que se cargan autmáticamente en cualquier despliegue realizad, l que puede cnllevar a prblemas de cmpatibilidad cn el servici de firma trifásica, en especial cn la firma XAdES. Un de ests servidres es JBss en sus versines 7 y EAP 6. Puede cnsultar cm slventar este prblema en el apartad El servici de firma trifásica genera un errr al realizar firmas XAdES en servidres JBss Cnfiguración del servici de firma trifásica Tal y 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. Desde este ficher es psible cnfigurar las siguientes prpiedades: 54

55 Access-Cntrl-Allw-Origin Permite establecer el rigen permitid de las peticines. El servici de firma trifásica agregará el valr de esta prpiedad en las respuestas del servici. Si se establece cm valr un asterisc ( * ), se indica que se pueden realizar peticines desde cualquier dmini. Valr pr defect: * alternative.xmldsig Permite habilitar el md de cmpatibilidad cn biblitecas de firma XML que puedan encntrarse en el classpath del servidr de aplicacines. Este tip de biblitecas pueden interferir cn las que incluye el prpi Oracle Java e impedir realizar firmas XAdES. Ejempls de biblitecas que prvcan ests errres sn XERCES/XALAN. Al indicar el valr true, se habilitará el md de cmpatibilidad cn estas biblitecas, l que bligará al servici a buscar diverss paquetes de clases para encntrar un md de cmpletar las firmas. N se garantiza la cmpatibilidad cn tdas las versines de estas biblitecas. Valr pr defect: false dcument.manager Clase que se encargará de gestinar ls dcuments que se deben firmar y las firmas generadas. El Dcument Manager pr defect imita un prces de firma mnfásica. Cnsulte el apartad Cnfiguración del Dcument Manager del servici para más detalles Cnfiguración del Dcument Manager del servici Integrads en el servici trifásic se distribuyen, a md de ejempl, ds 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 lad cliente reduciend cnsiderablemente el tráfic de red y la fiabilidad y velcidad del prces. 55

56 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). El Dcument Manager es.gb.afirma.triphase.server.filesystemdcumentmanager se prprcina únicamente a md de ejempl de cóm puede implementarse el servici usand un simple sistema de fichers, per n es un desarrll preparad para llevarse a prducción (pr mtivs de seguridad, escalabilidad, etc.). El Dcument Manager es.gb.afirma.triphase.server.selfishdcumentmanager, es necesari que esté dispnible en el sistema para las funcinalidades de firma móvil en ls cass dnde n existe una funcinalidad mnfásica per esta se requiere pr cmpatibilidad, cm pr ejempl: Andrid: XAdES. ios: XAdES, CAdES y PAdES. En ests cass las aplicacines móviles seleccinan autmáticamente el md trifásic y es.gb.afirma.triphase.server.selfishdcumentmanager cm Dcument Manager, n siend necesaria ninguna acción ni cnfiguración pr parte del integradr. Así, si se dispne de este Dcument Manager en servidr, sería psible que un mism siti Web cnfigurad para firmas mnfásicas cn el MiniApplet AutFirma, funcinase sin prblemas cn dispsitivs móviles. En cualquier tr cas, el us de las firmas trifásicas emuland firmas mnfásicas está desacnsejad, ya que se hace un mal us de ls recurss de red. 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. 56

57 Ntas específicas para cnfiguración del ejempl FileSystemDcumentManager Parámetrs de us y descripción del funcinamient FileSystemDcumentManager es un simple simuladr de repsitri de cntenids que funcina sbre un sistema de fichers, dnde el identificadr del dcument es realmente el nmbre del ficher, tant en la entrada (ficher a firmar) cm en la salida (ficher cn la firma hecha). En él, ls nmbres de fichers se indican cdificads en Base64, para evitar prblemas de cdificación, teniend pr ejempl: dcument.pdf se indicaría cm ZG9jdW1lbnRvLnBkZg== firma.xsig se indicaría cm ZmlybWEueHNpZw== El servici devuelve también, cdificad en Base64, el nmbre del ficher (sin ruta, supniend que esta es siempre utdir) en el cual se ha almacenad la firma resultante. Ests fichers se leen y escriben siempre tmand cm base ls directris indicads (utdir e indir), per pr tratarse de un ejempl, n se cntrla que se usen rutas relativas para acceder a partes privadas del sistema perativ (pr ejempl, indicand../../../../../etc/passwrd ), siend respnsabilidad del integradr, implementar las medidas de seguridad aprpiadas. Es imprtante tener en cuenta que ls nmbres de ficher utilizads deben cumplir las restriccines del sistema de fichers dnde residan utdir e indir. Así, pr ejempl, en un sistema de fichers NTFS n deberíams nunca indicar un nmbre de fichers que cntuviese el carácter ds punts ( : ) Cnfiguración en alta dispnibilidad cn varis nds Ls directris cnfigurads para el despliegue del servici trifásic (utdir e indir) deben ser siempre directris visibles y cmpartids pr tdas las instancias en ejecución. Este aspect es especialmente imprtante en cnfiguracines de servidres de aplicacines en alta dispnibilidad, dnde puede haber varis nds que presten el servici trifásic, cada un de ells en un sistema de fichers diferente, dnde sí se especifica una ruta lcal, puede que esta apunte a un directri distint en cada nd (distint servidr, disc diferente, tr sistema de fichers, etc.). El que tds ls nds accedan al mism directri referenciad en la cnfiguración se puede lgrar fácilmente usand un almacenamient cmpartid entre tds ells (cn el mism punt de mntaje), mediante enlaces simbólics, etc. Es imprtante también asegurarse de que tds ls nds tienen ls permiss adecuads sbre ls directris cnfigurads. 57

58 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. El valr AUTO n es válid para firmas simples. 6.7 Firma pr ltes predefinids El MiniApplet y AutFirma incrpran una funcinalidad de firma de ltes de dats. Gracias a esta característica es psible definir externamente un lte de firma mediante un ficher XML. Las peracines de firma definidas en el lte se ejecutarán de frma desatendida pr el cliente una vez se seleccine el certificad de firma, cn la cncurrencia de ls móduls servidres, y devlviéndse el resultad glbal de la ejecución del lte. La función de firma de ltes es: functin signbatch (batchb64, batchpresignerurl, batchpstsignerurl, params, successcallback, errrcallback); En esta función: batch64: Es el ficher de lte cdificad en base 64. Para saber cóm cnstruir el ficher de lte cnsulte el apartad Creación de ls ltes. batchpresignerurl: URL del servici de prefirma de ltes. Este servici se despliega junt cn el servici de firma trifásica. batchpstsignerurl: URL del servici de prefirma de ltes. Este servici se despliega junt cn el servici de firma trifásica. 58

59 params: Parámetrs para la cnfiguración glbal de la peración. Permite definir ls filtrs para determinar qué certificads de firma pueden utilizarse. 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 específic Cnfiguración del filtr de certificads para cncer ls parámetrs que se pueden establecer. successcallback: Función JavaScript que se debe ejecutar en cas de que la firma del lte finalice crrectamente. Esta función recibirá cm parámetr el XML resultad, en base64, cn ls resultads parciales de la peración. errrcallback: Función JavaScript que se debe ejecutar en cas de que la firma del lte finalice cn errres. Esta función recibirá ds parámetrs: el tip de errr prducid y un text descriptiv del errr. Para hacer us de esta funcinalidad será necesari desplegar el servici de firma trifásica. Cnsulte el apartad Servici de firma trifásica para más infrmación Cnfiguración del servici Para la firma pr ltes, además de la cnfiguración del ficher del servici de firma trifásica, requiere la cnfiguración de un ficher adicinal en servidr llamad signbatch.prperties. Este ficher es bligatri y debe estar situad en la raíz del CLASSPATH. En cas de n encntrarl, el sistema fallará en fase de despliegue (de la aplicación WAR JEE). Este ficher se lee una única vez durante el despliegue de la aplicación, pr l que en cas de cambiar ls valres, debe redesplegarse td el servici. El ficher debe cntar cn las siguientes prpiedades de cnfiguración: allwedsurces Debe cntener, separadas pr punt y cma ( ; ), ls rígenes de dats permitids. Puede usarse un asterisc ( * ) cm cmdín, per únicamente al final de cada fuente de dats indicada. El nmbre especial de rigen base64 indica que se aceptarán directamente ls misms dats a firmar cm Base64, explicitads cm el nmbre de su fuente de dats. Este parámetr es bligatri, si n se indica n se aceptará ninguna fuente de dats, y pr l tant n se pdrá realizar ninguna firma. Se admiten las siguientes fuentes de dats: Base64: Indicada cm base64. HTTP (cm el acces l inicia el servidr, debe tenerse cuidad de n trgar permiss a dminis dats interns n deseads): 59

60 Pr ejempl: etc. HTTPS (cm el acces l inicia el servidr, debe tenerse cuidad de n trgar permiss a dminis dats interns n deseads): Pr ejempl: etc. FTP (cm el acces l inicia el servidr, debe tenerse cuidad de n trgar permiss a dminis dats interns n deseads): Pr ejempl: ftp://*, ftp://ftp.ats.net/*, ftp://ftp.ats.net/dc.pdf, etc. Ficher en disc (debe tenerse much cuidad de n trgar permiss sbre fichers de sistema cnfidenciales): Pr ejempl: file://c:\files\*, file://c:\files\dc.pdf, etc. cncurrentmde Es un valr pcinal, puede tener ds valres: true Indica que se permite el prces en paralel de las entradas del lte. false El lte se prcesará secuencialmente, sl un prces simultáne. maxcurrentsigns Debe cntener, en el cas de que se haya indicad el valr true para el parámetr cncurrentmde, el númer máxim de firmas a prcesar cncurrentemente. tmpdir Directri a usar para ls fichers temprales. Si se indica se usará el del sistema. Un ejempl de ficher de cnfiguración pdría ser: maxcurrentsigns=10 tmpdir=c:/salida/temp # Operacin cncurrente en serie cncurrentmde=true # Fuentes de dats permitidas, separadas pr allwedsurces=base64;file://*; Creación de ls ltes Ls integradres que deseen usar esta funcinalidad deben crear (externamente, el MiniApplet n tiene ninguna función expresa para est) el XML de definición del lte de firma, que debe seguir este esquema: 60

61 <xs:schema attributefrmdefault="unqualified" elementfrmdefault="qualified" xmlns:xs=" <xs:element name="signbatch"> <xs:cmplextype> <xs:sequence> <xs:element name="singlesign" maxoccurs="unbunded" minoccurs="1"> <xs:cmplextype> <xs:sequence> <xs:element type="xs:string" name="datasurce"/> <xs:element name="frmat"> <xs:simpletype> <xs:restrictin base="xs:string"> <xs:enumeratin value="xades"/> <xs:enumeratin value="cades"/> <xs:enumeratin value="pades"/> <xs:enumeratin value="facturae"/> </xs:restrictin> </xs:simpletype> </xs:element> <xs:element name="subperatin"> <xs:simpletype> <xs:restrictin base="xs:string"> <xs:enumeratin value="sign"/> <xs:enumeratin value="csign"/> <xs:enumeratin value="cuntersign"/> </xs:restrictin> </xs:simpletype> </xs:element> <xs:element name="extraparams"> <xs:simpletype> <xs:restrictin base="xs:base64binary" /> </xs:simpletype> </xs:element> <xs:element name="signsaver"> <xs:cmplextype> <xs:sequence> <xs:element type="xs:string" name="class"/> <xs:element name="cnfig"> <xs:simpletype> <xs:restrictin base="xs:base64binary" /> </xs:simpletype> </xs:element> </xs:sequence> </xs:cmplextype> </xs:element> </xs:sequence> <xs:attribute type="xs:string" name="id" use="required"/> </xs:cmplextype> </xs:element> </xs:sequence> <xs:attribute type="xs:integer" name="cncurrenttimeut" use="ptinal"/> <xs:attribute name="stpnerrr" use="ptinal"> <xs:simpletype> <xs:restrictin base="xs:string"> <xs:enumeratin value="true"/> <xs:enumeratin value="false"/> </xs:restrictin> </xs:simpletype> </xs:attribute> <xs:attribute name="algrithm" use="required"> <xs:simpletype> <xs:restrictin base="xs:string"> <xs:enumeratin value="sha1withrsa"/> <xs:enumeratin value="sha256withrsa"/> <xs:enumeratin value="sha384withrsa"/> <xs:enumeratin value="sha512withrsa"/> 61

62 </xs:restrictin> </xs:simpletype> </xs:attribute> </xs:cmplextype> </xs:element> </xs:schema> Un psible ejempl de XML cread siguiend este esquema pdría ser el siguiente: <?xml versin="1.0" encding="utf-8"?> <signbatch stpnerrr="false" algrithm="sha256withrsa" cncurrenttimeut=" "> <singlesign Id=" e-728d-4a33-9db9-3a4efea4cead"> <datasurce> <frmat>xades</frmat> <subperatin>sign</subperatin> <extraparams> Iw0KI1N1biBBdWcgMjMgMTM6NDU6NDAgQ0VTVCAyMDE1DQpTaWduYXR1cmVJZD03NzI1Mzc0ZS03M jhkltrhmzmtowrios0zytrlzmvhngnlywqncg== </extraparams> <signsaver> <class>es.gb.afirma.signers.batch.signsaverfile</class> <cnfig> Iw0KI1N1biBBdWcgMjMgMTM6NDU6NDAgQ0VTVCAyMDE1DQpGaWxlTmFtZT1DXDpcXFVzZXJ zxfx0b21hc1xcqxbwrgf0yvxctg9jywxcxfrlbxbcxezjuk1bms54bwwncg== </cnfig> </signsaver> </singlesign> <singlesign Id="93d1531c-cd32-4c8e-8cc8-1f1cfe66f64a"> <datasurce>sg9sysbndw5kbw==</datasurce> <frmat>cades</frmat> <subperatin>sign</subperatin> <extraparams> Iw0KI1N1biBBdWcgMjMgMTM6NDU6NDAgQ0VTVCAyMDE1DQpTaWduYXR1cmVJZD05M2QxNTMxYy1jZ DMyLTRjOGUtOGNjOC0xZjFjZmU2NmY2NGENCg== </extraparams> <signsaver> <class>es.gb.afirma.signers.batch.signsaverfile</class> <cnfig> Iw0KI1N1biBBdWcgMjMgMTM6NDU6NDAgQ0VTVCAyMDE1DQpGaWxlTmFtZT1DXDpcXFVzZXJ zxfx0b21hc1xcqxbwrgf0yvxctg9jywxcxfrlbxbcxezjuk1bmi54bwwncg== </cnfig> </signsaver> </singlesign> </signbatch> Cmpnentes de un lte Cabecera de definición de lte En el ejempl, es la línea <signbatch stpnerrr="false" algrithm="sha256withrsa">. Cntiene ds atributs cnfigurables pr el integradr: 1. stpnerrr Cuand se establece a false se indica que el prces debe cntinuar inclus si alguna de las firmas del lte n puede cmpletarse, y cuand se establece a true el prces se para en el mment en el que se prduce el primer errr. Pr defect, se cnsidera que el valr es true, se parará la ejecución tras el primer errr. 62

63 2. algrithm Indica el algritm de firma a usar para td el lte, y puede tener ls siguientes valres: SHA1withRSA (N se recmienda su us pr bslet) SHA256withRSA SHA384withRSA SHA512withRSA Definición de cada firma dentr del lte Dentr del element de definición de lte debems incluir un varis elements de tip singlesign (pr cada firma que querams incluir en el lte debems incluir un element de este tip), que debe incluir en su rigen un identificadr únic. Pdems bservar que en el ejempl tenems ds cabeceras de definición de firma, ya que el lte cntiene ds firmas. Observems la cabecera de la primera firma: <singlesign id=" e-728d-4a33-9db9-3a4efea4cead">, que indica que es una firma dentr del lte identificada pr la cadena e-728d-4a33-9db9-3a4efea4cead. Cada una de las firmas dentr del lte puede ser cnfigurada individualmente cn ls siguientes parámetrs: Origen de ls dats a firmar El rigen de ls dats debe indicarse dentr del element datasurce del XML, pr ejempl: <datasurce> El rigen de ls dats a firmar puede indicarse (siempre que cumpla ls permiss indicads en el ficher de cnfiguración descrit en la sección Cnfiguración del servici ): Cn una URL. En este cas el servidr (nunca el cliente) descargará directamente ls dats a firmar. Se admite HTTP, HTTPS y FTP. Si se usa SSL cn certificad cliente es necesari que el certificad cliente esté instalad en el almacén de certificads persnales del Entrn de Ejecución de Java (JRE). En este cas, la URL debe devlver ls dats finales a firmar, sin ninguna cdificación intermedia. Así, pr ejempl, para firmar un PDF que esté dispnible en una URL debems indicar directamente la URL que apunte a ese PDF, cm: av5p0_anexo_psc.pdf Si la URL apunta a una huella digital (para ls mds de firma que l sprten), esta debe estar igualmente en binari, cm: 63

64 En el ejempl, puede bservarse que en la primera firma se indica que el rigen de ls dats es la URL Indicand directamente ls dats a firmar cdificads en Base64. En este cas el servidr descdificará el Base64 para btener ls dats a firmar. Puede usarse también para indicar directamente una huella (en ls mds de firma que l sprten), teniéndse en este cas que indicar en Base64. En el ejempl, puede bservarse que en la primera firma se indica que el rigen de ls dats es el Base64 SG9sYSBNdW5kbw==, que descdificad equivale a la cadena de text Hla Mund Frmat de firma El frmat de firma a utilizar debe indicarse dentr del element frmat del XML, pr ejempl <frmat>xades</frmat>. Se admiten ls siguientes frmats: XAdES : XAdES CAdES: CAdES PAdES: PAdES Cn este frmat sl se pueden firmar y cfirmar dcuments PDF. N se permiten cntrafirmas. FacturaE: FacturaE Cn este frmat sl se permite la firma de facturas electrónicas. Ni cfirmas, ni cntrafirmas Operación de firma La peración cncreta de firma a realizar debe indicarse dentr del element subperatin del XML, pr ejempl <subperatin>sign</subperatin>. Se admiten las siguientes peracines: Firma: sign Cfirma: csign Cntrafirma: cuntersign Parámetrs adicinales para la firma Ls parámetrs adicinales para el frmat y la peración cncreta de firma deben indicarse dentr del element extraparams del XML, pr ejempl <extraparams>bw9kzt1pbxbsawnpda0kc2lnbmf0dxjluhjvzhvjdglvbknpdhk9twfkcmlk</extraparams>. Ests parámetrs adicinales deben indicarse cdificand su representación textual cm Base64. Así, las siguientes prpiedades (indicand cada parámetr en una línea de text cn el frmat nmbre_parámetr=valr): 64

65 mde=implicit signatureprductincity=madrid Para una representación visible del carácter intr se utilizará la partícula \n. Así, ls parámetrs anterires quedaría cm: mde=implicit\nsignatureprductincity=madrid Al cdificar cadena a Base64, btendríams: bw9kzt1pbxbsawnpda0kc2lnbmf0dxjluhjvzhvjdglvbknpdhk9twfkcmlk Si n se desea establecer parámetrs adicinales debe dejarse el nd vací Cnfiguración del guardad de la firma El guardad de la firma una vez esta se cmpleta es una tarea que realiza igualmente el servidr, utilizand para ell clases especiales de guardad que el integradr debe cdificar según sus necesidades. Las clases deben situarse en el CLASSPATH de la aplicación Web en el lad servidr (nrmalmente dentr de un ficher JAR). Cnsulte la dcumentación de su servidr de aplicacines para realizar esta tarea. Una frma muy cómda de hacerl es editand el WAR (es un ficher ZIP cn la extensión cambiada) antes de desplegarl, y añadiend el JAR cn las nuevas clases en el directri WEB-INF/lib. Hay que tener cuidad de n alterar el rest de cntenids ni la estructura de carpetas antes de vlver a cmprimir el WAR (cm ZIP). Estas clases deben implementar el interfaz SignSaver, que tiene la siguiente frma: package es.gb.afirma.signers.batch; imprt java.i.ioexceptin; imprt java.util.prperties; /** Interfaz para el guardad, almacenaje enví de firmas una vez realizadas. Tmás García-Merás. */ public interface SignSaver { /** Guarda una firma electrónica. sign Definición de la firma que se hiz. datatsave Dats a guardar, resultad de la firma electrónica. IOExceptin Si hay prblemas durante el prces. */ vid savesign(final SingleSign sign, final byte[] datatsave) thrws IOExceptin; /** Deshace un guardad previ (para ls mds transaccinales). sign Identificadr de la firma a deshacer. */ vid rllback(final SingleSign sign); /** Cnfigura cóm ha de guardarse la firma electrónica. * cada implementación requerirá unas prpiedades distintas dentr del * bjet de prpiedades. cnfig Prpiedades de cnfiguración. */ vid init(final Prperties cnfig); 65

66 /** Obtiene las prpiedades de cnfiguración. Prpiedades de cnfiguración. */ Prperties getcnfig(); } Cm se puede bservar, el bjet de guardad recibe sus parámetrs de funcinamient y cnfiguración en un ficher de prpiedades de Java en el métd init, que es invcad siempre inmediatamente después de ser instanciad. La frma de indicar qué clase de guardad a usar y cn qué cnfiguración es mediante el nd signsaver, que cntiene a su vez ds nds: class, cn el nmbre cualificad de la clase a usar. cnfig, cn las prpiedades de cnfiguración cdificadas en Base64. Así, en el ejempl tenems el siguiente nd: <signsaver> <class>es.gb.afirma.signers.batch.signsaverfile</class> <cnfig> Iw0KI1RdSBBdWcgMjAgMTI6MTM6NDEgQ0VTVCAyMDE1DQpGaWxlTmFtZT1DXDpcXFVzZXJzXFx0b21hc1xcQXBwRGF0Y VxcTG9jYWxcXFRlbXBcXEZJUk1BMi54bWwNCg== </cnfig> </signsaver> Este indica que debe usarse la clase de guardad es.gb.afirma.signers.batch.signsaverfile cn la cnfiguración Iw0KI1RdSBBdWcgMjAgMTI6MTM6NDEgQ0VTVCAyMDE1DQpGaWxlTmFtZT1DXDpcXFVzZXJzXFx0b21hc1xcQXBwRGF0YVxcTG9j YWxcXFRlbXBcXEZJUk1BMi54bWwNCg==, que si la descdificams vems que cntiene: FileName=C:\\Users\\tmas\\AppData\\Lcal\\Temp\\FIRMA2.xml Que es la cnfiguración que necesita para guardar la firma (esta clase simplemente guarda la firma en el ficher que se le indique en la cnfiguración. Se incluyen cn la implementación ds ejempls de clases de guardad: Guardad a ficher: Clase: es.gb.afirma.signers.batch.signsaverfile Parámetrs de cnfiguración: FileName: Indica el ficher dnde debe guardarse la firma (n crea directris, ests deben existir y deben tenerse ls permiss adecuads). Esta clase es un simple ejempl, y n debe usarse directamente en prducción, ya que presenta prblemas de seguridad (pdrían indicarse que se sbrescriba un ficher de sistema). Ver Ntas sbre el ejempl SignSaverFile. Enví a una dirección HTTP POST: 66

67 Clase: es.gb.afirma.signers.batch.signsaverhttppst Parámetrs de cnfiguración: PstUrl: URL a la que enviar ls dats vía HTTP POST. Puede ser tant HTTP cm HTTPS PstParamName Indica el parámetr de la petición POST dnde deben adjuntarse ls dats. Ests se adjuntarán siempre en Base64 cn alfabet URL SAFE. Esta clase realiza una llamada HTTP POST a la dirección indicada, enviand cm dats del POST un parámetr cn el nmbre indicad cuy valr será la cdificación Base64 del resultad de la firma. Es necesari entnces que el integradr prvea este servici HTTP POST para recibir y tratar la firma enviada (habitualmente un servici Web). La URL indicada debe ser accesible desde el servidr (que es quien realiza el enví) Ntas sbre el ejempl SignSaverFile La clase es.gb.afirma.signers.batch.signsaverfile, es, cm se ha cmentad anterirmente, únicamente un ejempl de implementación el del interfaz es.gb.afirma.signers.batch.signsaver que puede resultar de utilidad para depuración, per que n debe ser utilizada nunca en entrns reales. Para evitar su expsición accidental, se distribuye cn la escritura a disc deshabilitada mediante una variable final: /** El guardad real está deshabilitad pr defect, habilitar para usar esta clase * para depuración. N debe usarse para entrns reales, ya que n hay cmprbacines de * qué fichers pueden sbrescribirse. */ private static final blean DISABLED = true; Si desea usarla para pruebas cn escrituras reales en disc, debe habilitarla cambiand el valr de dicha variable: private static final blean DISABLED = false; Respuesta a una ejecución de un lte Cuand se termina de prcesar un lte de firma, el cliente recibe cm respuesta un XML cdificad en Bas64 que describe cm ha resultad el prces. Este XML es acrde al siguiente esquema: <xs:schema attributefrmdefault="unqualified" elementfrmdefault="qualified" xmlns:xs=" <xs:element name="signs"> <xs:cmplextype> <xs:sequence> 67

68 <xs:element name="signresult" maxoccurs="unbunded" minoccurs="0"> <xs:cmplextype> <xs:simplecntent> <xs:extensin base="xs:string"> <xs:attribute type="xs:string" name="id" use="required"/> <xs:attribute type="xs:string" name="result" use="required"/> <xs:attribute type="xs:string" name="descriptin" use="ptinal"/> </xs:extensin> </xs:simplecntent> </xs:cmplextype> </xs:element> </xs:sequence> </xs:cmplextype> </xs:element> </xs:schema> Un ejempl de XML devuelt pdría ser el siguiente: <?xml versin="1.0" encding="utf-8"?> <signs> <signresult id="001-xades" result="done_and_saved" descriptin=""/> <signresult id="002-cades" result="done_and_saved" descriptin=""/> <signresult id="003-cades" result="done_and_saved" descriptin=""/> <signresult id="004-cades" result="done_and_saved" descriptin=""/> </signs> En él distinguims un nd signresult pr cada una de las firmas del lte, cn su crrespndiente identificadr. Este puede tener tres atributs: id : Identificadr de la firma. result : Resultad del prces. descriptin : Descripción del resultad del prces (pcinal) Descripción del md transaccinal de ejecución de ls ltes Cuand se indica que un lte debe pararse en cas de errr (cn el atribut stpnerrr="true" en la cabecera del XML de definición), se activa un md transaccinal, que sigue el siguiente prces: Las firmas sn generadas íntegramente en servidr, per n se guardan hasta que n se realizan tdas las del lte. Si una generación fallase se interrumpe td el prces y se da pr perdid. Una vez están generadas, se cmienza el prces de guardad de firmas (el rden del lte n es relevante, el prgrama puede guardarlas en un rden distint). Si un guardad falla, se deshacen ls guardads que sí se hubiesen cmpletad adecuadamente, llamand para ell al métd rllback(final SingleSign sign) de la clase de guardad (SignSaver) definida en el lte para cada firma. Es respnsabilidad del integradr implementar adecuadamente este métd rllback(final SingleSign sign) en su clase de guardad. En ls ejempls prvists de implementacines de SignSaver, si se usa salvad en un archiv del sistema de fichers, el rllback simplemente 68

69 brra el ficher cread, per si se usa el ejempl de HTTP POST, el rllback n deshace la peración (realmente n hace nada, ya que n hay frma de deshacer una llamada HTTP) Tamañ máxim del XML de definición de lte El XML de definición de lte n puede exceder en tamañ de 1.024KB. Si necesitase cmpner trabajs mayres, ests deberán fraccinarse en varis ltes. Recuerde que puede establecer cm dats a firmar una URL, accesible desde el servidr de firma, desde la que btener ls dats. 6.8 Firma/multifirma y guardad del resultad El integradr del sistema puede rdenar al MiniApplet y AutFirma que ejecute una peración de firma, cfirma cntrafirma y a cntinuación frezca al usuari guardar la firma recién generada. Para llevar a cab esta peración el integradr deberá prprcinar ls misms parámetrs que en la peración de firma, además del tip de peración (firma, cfirma cntrafirma) y una sugerencia para el nmbre del ficher que se guardará. La función JavaScript para el guardad de dats en disc es: functin signandsavetfile (peratin, datab64, algrithm, frmat, params, filename, successcallback, errrcallback); En esta función: peratin: Operación criptgráfica que se slicita realizar. Esta puede ser sign, csign cuntersign (firma, cfirma cntrafirma, respectivamente). datab64: Dats firma electrónica en frma de cadena en Base64 sbre la que deseams perar. También se puede n indicar este parámetr (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 se desea cfirmar cntrafirmas una firma y 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 69

70 frmat de firma que desee realizar para saber ls parámetrs sprtads pr el frmat en cuestión. filename: Nmbre prpuest para el ficher generad. El usuari pdrá cambiar este nmbre, ya que tan sól aparecerá cm nmbre pr defect en el diálg de guardad de dats. Puede n indicarse un valr (usar null), en cuy cas se usará el nmbre Firma seguid de la extensión que crrespnda al frmat en cuestión. successcallback: Función JavaScript que se ejecutará una vez se btenga el resultad de la peración. Esta función recibirá cm parámetrs la firma, cfirma cntrafirma resultante y el certificad utilizad en la peración. 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. 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 Gestión de errres para más infrmación. El resultad de esta peración puede btenerse directamente gestinarme mediante las funcines callback. Este resultad se btiene cdificad en base64. El resultad que se btendrá será el de la peración de firma ignrándse en cualquier cas el resultad del guardad de ls dats Ejempls: A cntinuación se muestran distints ejempls relacinads cn el guardad de dats en disc: Cfirma de una firma, guardad del resultad en disc y anexión del mism a un frmulari: functin addtfrmcallback (signb64, certb64) { dcument.getelementbyid( signature ).value = signb64; } MiniApplet.signAndSaveTFile ( csign, signb64, SHA1withRSA, CAdES, null, MiCfirma.csig, addtfrmcallback, errrcallback); <!-- Fragment HTML cn un camp de text en dnde el usuari puede insertar el text que desea guardar --> <frm> <input name="sign" id="signature" type="hidden" /> </frm> Firma y guardad de un dcument: 70

71 MiniApplet.signAndSaveTFile( sign, null, SHA1withRSA, XAdES, frmat=xades Envelping, null, addtfrmcallback, errrcallback); <!-- 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: Al n indicarse dats de entrada se permitirá cargar un ficher de disc y cuand aparezca el diálg de guardad, al n haberse establecid un nmbre de ficher pr defect, se prpndrá el mism nmbre del ficher cargad al que se le agrega la extensión del frmat de firma. 6.9 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. 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, successcallback, errrcallback); 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. 71

72 filename: Prpuesta de nmbre de ficher. extensin: Extensión de ficher que se prpne para el guardad. 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 extensió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. sucesscallback: Nmbre de la función callback javascript que se ejecutará en cas de que el guardad de dats finalice crrectamente. Esta función n recibe parámetrs. Si se mite este parámetr, se establece a null, n se ejecutara ninguna función al terminar la peración. errrcallback: Nmbre de la función callback javascript que se ejecutará en cas de que el guardad de dats finalice cn errres. Esta función recibe 2 parámetrs: el tip de errr y el mensaje de errr. Si se mite este parámetr, se establece a null, n se ejecutara ninguna función al terminar la peración. 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 ); } 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> 72

73 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 y recuperación de un ficher pr parte del usuari 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, filepath); 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. filepath: Opcinal. Ruta absluta del ficher que se debería seleccinar pr defect sól el nmbre de ficher sugerid. 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 firmar, cfirmar 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 73

74 ); } 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; } MiniApplet.sign(dataB64, SHA1withRSA, CAdES, null, successcallback, errrcallback); Carga de un ficher cn ruta preseleccinada var filenamecntentb64; try { filenamecntentb64 = MiniApplet.getFileNameCntentBase64( Seleccinar ficher, jpg,gif,png, Imagen, C:/pruebas/Entrada.png ); } catch (e) { return; } var filename = filenamecntentb64.substring(0, filenamecntentb64.indexof( )); Selección y recuperación de múltiples fichers pr parte del usuari 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, filepath); 74

75 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. filepath: Opcinal. Ruta absluta de un de ls fichers que se debería seleccinar pr defect sól el nmbre sugerid de un de ls fichers. Este métd devuelve un array de elements en dnde cada un de ells sigue el patrón: Nmbre Cntenid Est es, el nmbre del ficher y su cntenid en base 64 separads pr el carácter. Pr ejempl, si se seleccinasen ls fichers entrada.txt e imagen.jpg, se btendría un array cn ls elements: entrada.txt U09ZIFVOIFRFWFRPIEEgRklSTUFS imagen.jpg A1NSHA1NQW212ASYAN45YMD2MWQEI Seguid del text entrada.txt y separad pr el carácter aparece el cntenid de ese ficher cnvertid a base 64 y seguid del 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 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 filenamecntentb64array; try { filenamecntentb64array = 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( MiniApplet.getErrrType())) { 75

76 } } return; /* Métd del integradr para mstrar lgs */ shwlg(miniapplet.geterrrmessage()); var filenames = new Array(); fr (var i = 0; i < filenamecntentb64array.lenght; i++) { var separatridx = filenamecntentb64array[i].indexof( ); filenames[i] = filenamecntentb64array[i].substring(0, separatridx); } 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( MiniApplet.getErrrType())) { /* Métd del integradr para mstrar lgs */ shwlg(miniapplet.geterrrmessage()); } return; } var separatridx1 = filenamecntentb64.indexof( ) + 1; 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.10 Utilidad Ec El MiniApplet dispne del métd ech() que devuelve la cadena: Java vendr: JAVA_VENDOR 76

77 Java versin: JAVA_VERSION Java architecture: JAVA_ARCHITECTURE Llamarems a este métd de la frma: MiniApplet.ech(); La cadena devuelta pr el métd ech() cuand el MiniApplet se encuentra cargad 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 entrn en el que n se pueden ejecutar applets, cm en un dispsitiv móvil, cuand n se hayan cncedid ls permiss para la ejecución del applet, 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. 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 Gestión de errres apartad para más infrmación 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: 77

78 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. Este valr pr defect es dependiente del entrn perativ (sistema perativ y navegadr Web), pr l que n se recmienda su us. 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); 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. Este valr pr defect es dependiente del entrn perativ (sistema perativ y navegadr Web), pr l que n se recmienda su us. 78

79 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); Descarga de dats remts El prprcina un métd para la descarga de dats remts. Este métd accede a una URL establecida pr el integradr, descarga el cntenid que en ella se encuentra e invca a un métd callback al que le prprcina ls dats descargads en Base64. La descarga de ls dats se realiza desde JavaScript y sufre las limitacines que aplican ls navegadres a este tip de descargar. Pr nrma, sól pdrán descargarse dats accesibles desde una URL situada en el mism dmini y mism esquema (HTTP HTTPS) que la web que integra el JavaScript de despliegue. La descarga de ls dats se realiza pr medi del métd GET de HTTP y se realiza de frma asíncrna. Es decir, se descargan ls dats en hil de ejecución distint al prces principal. Una vez termina el prces de descarga, se invca a un métd callback establecid pr el integradr, de tal frma que así recuperar el cntrl de la peración. La función JavaScript para descarga de dats remts es: functin dwnladremtedata(url, successcallback, errrcallback); En esta función: url: URL de acces a ls dats a descargar. successcallback: Nmbre de la función que se invcará en cas de finalizar crrectamente la descarga de ls dats. Esta función recibirá cm únic parámetr ls dats descargads en Base64. errrcallback: Nmbre de la función que se invcará en cas de finalizar cn errres la descarga de ls dats. Esta función recibirá cm únic parámetr el errr que riginó el prblema. Este métd devuelve n devuelve nada y su ejecución es asíncrna. 79

80 Ejempls Descarga de dats y psterir firma var mstrarerrr = functin(e) { alert( Errr en la descarga de ls dats: + e); } var iniciarfirma = functin(datsb64) { MiniApplet.sign( datsb64, algrithm, frmat, null, successcallback, errrcallback); } var url = ; MiniApplet.dwnladRemteData (url, iniciarfirma, mstrarerrr); Selección de certificad El MiniApplet puede permitir al usuari seleccinar un certificad sin necesidad de realizar una peración de firma. Para est, se utiliza el mism diálg de selección que en las peracines de firma tradicinales. La utilidad de este métd es cncer de anteman el certificad que el usuari quiere seleccinar para la firma, de tal frma que puede realizar validacines previas sbre el certificad y/ mstrar infrmación de este en su aplicación web. La función JavaScript para permitir seleccinar un certificad de usuari es: functin selectcertificate(params, successcallback, errrcallback); En esta función: params: Parámetrs de cnfiguración de la peración que afecten a la selección de certificads. Más cncretamente, se pueden cnfigurar filtrs de certificads, cm se indica en el apartad Cnfiguración del filtr de certificads, y la selección autmática de certificad, cm se describe en el apartad Selección autmática de certificads. successcallback: Nmbre de la función que se invcará en cas de finalizar crrectamente la selección de certificad. Esta función recibirá cm únic parámetr el certificad seleccinad en Base64. errrcallback: Nmbre de la función que se invcará en cas de finalizar cn errres la descarga de ls dats. Esta función recibirá cm parámetrs, el tip de errr que se prduj y el mensaje de errr asciad. 80

81 Este métd permite recuperar directamente el certificad seleccinad cm resultad de la función recuperarl a través de las funcines callback, si se establecen. Para mantener la cmpatibilidad cn las aplicacines nativas será necesari hacerl siempre a través de las funcines callback. Este métd también es cmpatible cn la función setstickysignatry(blean) (véase el apartad Firmas/Multifirmas masivas) cn la cual es psible fijar el certificad seleccinad pr el usuari. De esta frma se utilizará el mism certificad durante las siguientes peracines de firma selección Ejempls Selección de certificad y enví a servidr para su análisis var mstrarerrr = functin(errrtype, errrmessage) { alert( Errr en la descarga de ls dats: + errrmessage); } var enviarcertificad = functin(certb64) { dcument.getelementbyid( cert ).value = certb64; fcument.getelementbyid( frmulari ).submit(); } var extraparams = filters.0=issuer.cntains:fnmt\n + filters.1=issuer.cntains:plicia ; MiniApplet.selectCertificate (extraparams, enviarcertificad, mstrarerrr); 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 81

82 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 Parámetrs adicinales n sprtads Revise cn cuidad ls parámetrs admitids en cada un de ls frmats de firma y en cada una de las peracines. Si se cnfigura un parámetr n sprtad simplemente será ignrad sin ningún mensaje de errr en registr. 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á 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, cntrafirma y selección de certificads. Las claves que ns permiten establecer filtrs de certificads sn: 82

83 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 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. 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 sub-filtr 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. 83

84 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: filters=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: filters=signingcert: 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: filters=authcert: Filtr de certificads SSCD: Filtra ls certificads del almacén para que se muestren sól aquells emitids pr medi de un dispsitiv SSCD (dispsitiv segur de creación de firma), cm es el cas de ls certificads del DNIe. Hay que tener en cuenta que el filtrad se realiza a partir de un atribut QCStatement declarad en el prpi certificad. Si la autridad de certificación n incluye este atribut, n será psible realizar la distinción. Para establecer este filtr de certificads se indicará la prpiedad filter cn el valr sscd: en el parámetr de cnfiguración de la peración de firma, cfirma cntrafirma. Ejempl: filters=sscd: 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. 84

85 Advertencia: Se acnseja el us del filtr de certificads cualificads ( qualified: ), que actúa de igual manera per distingue entre ls certificads de autenticación y firma de un mayr númer de certificads. 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: filters=ssl:45553a61 filters=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: filters=qualified:45553a61 filters=qualified:03ea 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: filters=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: filters=thumbprint:sha1:30 3a bb a fd d7 c5 a2 52 dc a5 54 f4 c5 ee 8a a5 4d 85

86 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: filters=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 RFC2254. Puede revisarse la nrmativa RFC 2254 en Ejempl: filters=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. Este filtr puede aplicarse de frma recursiva, de tal frma que permitirá el us del certificad si cualquier de ls certificads de la cadena de certificación pr encima de él mism cumple cn la expresión indicada. Para utilizar recursivamente este filtr se usará el valr issuer.rfc2254.recurse: seguid de la expresión RFC2254. Ejempl: filters=issuer.rfc2254.recurse:(cn=*fnmt*) Este filtr mstrará sól aquells certificads en ls que algun de ls certificads de su cadena de certificación tenga la partícula FNMT en el nmbre cmún 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: filters=subject.cntains:juan ESPAÑOL ESPAÑOL 86

87 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: filters=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: keyusage.crlsign: keyusage.enciphernly: keyusage.deciphernly: Ls KeyUsages que n se declaren en el filtr n se tendrán en cuenta. Ejempls: filterss=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. Filtr pr identificadr de directiva: Filtra ls certificads pr aquells que pseen un identificadr de directiva cncret. Est es útil para mstrar sól determinad tip de certificads de una autridad de certificación. 87

88 Para establecer este filtr se usará el valr plicyid: seguid pr listad de OIDs, separads pr cmas (, ), pr ls que se quieran filtrar. Ejempl: filters=plicyid: Este filtr mstrará sól aquells certificads cn el identificadr de directiva Filtr de seudónim: Filtra ls certificads, listand únicamente ls certificads de pseudónim y aquells que n tienen un certificad de seudónim asciad. Así, quedan cults ls certificads que tienen un certificad equivalente de seudónim, l que evita que aparezca su nmbre real en ls dats de firma. Para establecer este filtr se usará la palabra clave pseudnym: Ejempl: filters=pseudnym: Filtr de almacenes externs: Permite deshabilitar el btón de carga de almacenes PKCS#12 en el diálg de selección de certificads. De esta frma sól pdrán usarse ls certificads del almacén seleccinad pr el integradr ls pr defect del navegadr en cas de que el integradr ni especificase ningún almacén. Para establecer este filtr se usará la palabra clave disablepeningexternalstres Ejempl: filters=disablepeningexternalstres 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. 88

89 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, PAdES 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, PAdES-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 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.9 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.9. 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, XAdES PAdES). 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 manualmente. Ls parámetrs de esta plítica sn ls siguientes: CAdES XAdES plicyidentifier= plicyidentifierhash= G7rucf600+f03r/0bAOQ6WAs0= plicyidentifierhashalgrithm= plicyqualifier= mde=implicit 89

90 PAdES plicyidentifier=urn:id: plicyidentifierhash=g7rucf600+f03r/0baoq6was0= plicyidentifierhashalgrithm= plicyqualifier= frmat=xades Detached plicyidentifier= plicyidentifierhash= G7rucf600+f03r/0bAOQ6WAs0= plicyidentifierhashalgrithm= plicyqualifier= 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 MB. Ls dats n se incluirán en la firma cuand su tamañ sea mayr, siguiend, de frma general, la especificación establecida pr la plítica de firma de la AGE: En el cas de que, debid al tamañ de ls dats a firmar, n resulte técnicamente psible acnsejable realizar las firmas cn el frmat anterirmente descrit (que la firma cntenga ls dats firmads), se generará la estructura de firma detached, que incluye el hash del dcument riginal en la firma. Debid a la generalidad de la especificación, se permite al integradr definir qué tamañs de dats pueden incluirse dentr de la firma y cuáles n para su aplicación, pr l que, en cas de haberse indicad expresamente un md de firma (parámetr mde), se utilizará el valr establecid pr el integradr. Si se cnfigura para la peración alguna prpiedad individual que entre en cnflict cn la plítica indicada (pr ejempl, indicand un frmat prhibid pr esta), 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 la AGE v1.8 En el se ha incluid también el mecanism para usar la plítica de firma versión 1.8 de la AGE. Este mecanism actúa exactamente igual que el de la plítica 1.9 salv prque: La plítica de firma 1.8 de la AGE n está preparada para el frmat de firma PAdES. 90

91 El parámetr a cnfigurar es: expplicy=firmaage18 Esta prpiedad se expandirá a las necesarias para el cumplimient de la plítica de firma de la AGE según la plítica 1.8. Ls parámetrs de esta plítica sn ls siguientes: CAdES plicyidentifier= plicyidentifierhash=7sxx3erfuh31tvaw9lz70n7p1va= plicyidentifierhashalgrithm= plicyqualifier= cafirma/plitica_firma_age_v1_8.pdf mde= ** Ver nta ** Nta: Respect al md en CAdES (implícit explícit, dad que la plítica indica que la firma debe ser implícita siempre que el tamañ del dcument sea raznable. Cm n se especifica exactamente qué tamañ es raznable, si el integradr especifica directamente un md mediante el parámetr, este se respeta, mientras que si n indica ningún md, se generarán firma implícitas para tamañs inferires a 1MB, y explícitas tamañs mayres del cntenid a firmar. XAdES plicyidentifier=urn:id: plicyidentifierhash=v8lvvngdcpen6velrd1ja8harfk= plicyidentifierhashalgrithm= plicyqualifier= cafirma/plitica_firma_age_v1_8.pdf frmat=xades Detached mde=implicit Debe evitarse en la medida de l psible el us de versines de la plítica de la AGE anterires a la 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. 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 Cnfiguración de parámetrs de la JVM El JavaScript de despliegue permite establecer prpiedades que se le prprcinarán directamente a la máquina virtual para su cnfiguración. Est se hará mediante la prpiedad: 91

92 MiniApplet.JAVA_ARGUMENTS Actualmente, esta variable está cnfigurada cn ls valres -Xms512M -Xmx512M que gestinan la memria reservada para la JVM. Ests valres se pueden suprimir estableciend trs, anexar nuevs valres: // Se pisan ls valres existentes cn nuevas prpiedades para la JVM MiniApplet.JAVA_ARGUMENTS = "-XX:ErrrFile=./hs_err_pid%p.lg ";... // Se agregan nuevas prpiedades para la JVM MiniApplet.JAVA_ARGUMENTS += "-Xms512M -Xmx1024M "; Para evitar que las variables se cncatenen erróneamente, debe dejarse un espaci al final de la cadena Cnfiguración de la Máquina Virtual de Java para tratamient de fichers grandes Hay casines en las que el MiniApplet n puede tratar fichers de gran tamañ pr escasez de memria dispnible para la máquina virtual. Para paliar esta situación pdems indicar a la JVM que dispnga de una mayr cantidad máxima de memria usand la pción -Xmx de Java. Pr ejempl, para que Java dispnga de 2GB de memria debems indicar: MiniApplet.JAVA_ARGUMENTS += "-Xms512M Xmx2048M "; N bstante, debems tener mucha precaución al usar estas pcines, ya que si el equip n dispne de la memria que slicitams cm máxim, el MiniApplet n funcinará en abslut, pr l que debems usarl únicamente en entrns dnde estems segurs de que ls equips dispndrán de una de una determinada cantidad de memria libre. Puede encntrar más infrmación sbre las pcines de cnfiguración de memria de la JVM en: Tenga en cuenta que esta cnfiguración n se traslada a AutFirma en cas de que sean ests ls que realicen la firma. AutFirma tiene prefijada la reserva máxima de 1GB de memria en el cas de su versión de 32bits y 8Gb de memria máxims en el cas de la versión de 64bits (en este cas, n se prduce errr si el equip cliente n cuenta cn tanta memria). En pruebas realizadas, esta cnfiguración permite realizar firmas de hasta 130 MB en el cas de la versión de 32bits y hasta 400MB (sin llegar al límite máxim de memria reservada) en el cas de AutFirma de 64bits. 92

93 7.6 Cnfiguración a través de prpiedades del sistema El JavaScript de despliegue del MiniApplet permite establecer una serie de variables que serán usadas cm prpiedades del sistema en tiemp de ejecución. Estas variables permiten cnfigurar cmprtamients específics del MiniApplet. Para establecer estas variables, las asignarems separadas pr espacis a la prpiedad: MiniApplet.SYSTEM_PROPERTIES El nmbre de las variables deben ir antecedid pr -D y tener la frma clave=valr. Pr ejempl: MiniApplet.SYSTEM_PROPERTIES = "-DAFIRMA_NSS_HOME=C:/Prgram Files/Mzilla Firefx "; Estas variables sl tienen efect si se establecen antes de la carga del MiniApplet, si sn establecidas cn psteriridad se ignran pr cmplet. 93

94 8 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; 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 { 94

95 } 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. 95

96 9 Cmpatibilidad cn dispsitivs móviles y AutFirma Cuand el entrn del ciudadan firmante n puede realizar la carga del MiniApplet, el JavaScript de despliegue deriva las tareas de firma a aplicacines nativas capaces de realizarlas, sin necesidad de que el integradr deba gestinar pr su parte esta delegación de tareas. De esta frma pueden cmpletarse trámites electrónics aún en entrns en ls que n es psible ejecutar Applets. Entrns en ls que n es psible ejecutar Applets sn ls navegadres Web de ls dispsitivs móviles, que n admiten cmplements capaces de realizar firmas electrónicas (Applets de Java, ActiveX, etc.). También curre cn alguns navegadres de escritri, cm Ggle Chrme, Micrsft Edge baj tras situacines en las que n es psible ejecutar el MiniApplet: Java n está instalad en el sistema. El usuari n cncedió permiss para la ejecución del Applet. La cnfiguración de seguridad del equip n permitió la ejecución del Applet. Etc. Las aplicacines nativas que sprtan la ejecución de estas tareas de firma sn: AutFirma, para entrns Windws, Linux y Mac OS X; el Andrid, para entrns Andrid; y el ios, para entrns ios. Ns referirems a ests ds últims de frma general cm móviles. Para cncer ls requisits del sistema de AutFirma y ls clientes móviles, lea el apartad functin signandsavetfile(peratinid, datab64, algrithm, frmat, params, utputfilename, successcallback, errrcallback) functin setkeystre(kstype) functin selectcertificate(params, successcallback, errrcallback) Cmpatibilidad del cn aplicacines móviles y AutFirma. Aunque estas aplicacines nativas pueden ejecutar las peracines de firma en lugar del MiniApplet, existen limitacines en cuant al rest de peracines, así cm una serie de criteris y buenas prácticas que deberá seguir el integradr para garantizar la cmpatibilidad cn ambas herramientas. Para que AutFirma y ls móviles puedan asumir cualquier peración de firma, es necesari que estén instaladas en el equip lcal antes de iniciar el trámite de firma. Es respnsabilidad del integradr, alertar de este hech cuand sea susceptible que ls usuaris n tengan instalada la aplicación, ya que n es psible para el navegadr determinar si el usuari la tiene instalada n. Cnsulte el manual AF_manual_instalacin_y_gestin_ES para cncer más detalles acerca de la instalación y cnfiguración de AutFirma y las aplicacines móviles. 96

97 Si se desease delegar en AutFirma y ls móviles las tareas de firma en tds ls cass, se pdría hacer tal cm se describe en el apartad Carga directa de AutFirma y ls clientes móviles. 9.1 Arquitectura del sistema A pesar de que es el JavaScript de despliegue el que gestina la delegación de tareas en la aplicación nativa crrespndiente a cada entrn, deben cumplirse una serie de requisits para que est sea psible. Alguns de ests requisits están rientads únicamente a la cmpatibilidad del despliegue cn un entrn cncret, mientras que trs afectan a tds ells. Est, según la arquitectura de cada slución Entrns de escritri (Windws, Linux y Mac OS X) cn nuevs navegadres AutFirma es una herramienta nativa que puede instalarse en Windws, Linux y Mac OS X cm herramienta independiente de firma de dats lcales. Sin embarg, al instalarse en el sistema también registran el prtcl afirma, mediante l cual atienden a las llamadas realizadas a este prtcl. La llamada pr prtcl es un mecanism de invcación de aplicacines (si acas la prpia aplicación que realiza la llamada n puede atender a este prtcl) mediante el que puede pasarse una cantidad limitada de infrmación a md de parámetrs. Sin embarg, este prtcl sól permite la cmunicación en un sentid ya que la aplicación invcada n puede hacer referencia a la instancia de aquella que la invcó. Es pr est que para permitir la cmunicación bidireccinal, Autfirma establece 2 mecanisms distints: La cmunicación mediante un servidr intermedi, utilizad en dispsitivs móviles e Internet Explrer 10 e inferires (además de Internet Explrer 11 cn el md de cmpatibilidad activad). Este md se explica en el apartad Dispsitivs móviles, Internet Explrer 10 e inferires. La cmunicación mediante scket, utilizad en el rest de navegadres. En la cmunicación pr scket, AutFirma abre un scket de cmunicación cifrad a través del cual pder establecer una canal de cmunicación bidireccinal. La arquitectura de cmunicación seguida en este prces se describe a cntinuación: firmar(dats) invcarprprt cl(id, puerts) firmar(dats) Firma Firma Página Web miniapplet.js AutFirma 97

98 Primeramente, el trámite rdena la peración de firma pr medi del JavaScript de despliegue del MiniApplet. Al detectar este que n es psible ejecutar el MiniApplet, lanzará AutFirma mediante una invcación pr prtcl en el que se le prprcinarán una serie de puerts aleatris (dentr del rang determinad para el us de aplicacines de tercers) a través de ls cuales se deberá intentar la apertura del scket y un identificadr de sesión aleatri que deberán presentar tdas las peticines realizadas a través del mism. La aplicación AutFirma abrirá este scket cifrand el canal mediante un certificad SSL generad en el mment de la instalación (cnsulte el dcument AF_manual_instalacin_y_gestin_ES para más detalles) y el JavaScript enviará la rden de firma a través del mism. El scket se abrirá en un de ls puerts enviads en la invcación, así que el JavaScript de despliegue deberá previamente cmprbar cuál de ells es el que se ha utilizad finalmente antes de realizar la petición. AutFirma devlverá el resultad de la peración a través del prpi scket. Cualquier petición de firma psterir, se realizará a través del mism scket, sin necesidad de relanzar la aplicación. Pasad un tiemp determinad después de la última peración realizada, AutFirma se cerrará, de tal frma que la siguiente peración sí deberá relanzarla, prprcinand nuevs puerts y un nuev identificadr de sesión. El tiemp de espera pr defect que tardará la aplicación en cerrarse después de la última peración realizada es de 1 minut. Puede cnsultar la dirección de descarga de AutFirma y su prces de instalación en el dcument AF_manual_instalacin_y_gestin_ES Dispsitivs móviles, Internet Explrer 10 e inferires y Micrsft Edge Dad que ls sistemas móviles impnen limitacines en cuant a la creación de servicis que puedan ejecutarse en paralel cn tras aplicacines ha sid necesari idear tr tip de canal de cmunicación bidireccinal entre la página web que integra el trámite y la aplicación de firma. La arquitectura de cmunicación que integran cn la que funcinan ls móviles es la siguiente: 98

99 1. Cuand detecta que está en un dispsitiv móvil n se puede cargar el, en lugar de cargar el Applet, 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. 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. Existe tr cas de us de este medi de cmunicación, en el cual ls dats de entrada para la aplicación móvil n se pueden transmitir mediante la llamada pr prtcl debid a su tamañ. En ese cas, la página web primeramente ls sube al servidr intermedi y a cntinuación realiza la invcación pr prtcl a la aplicación para que esta ls descargue y cntinúe nrmalmente cn el prces. La instalación de ls móviles se realiza desde la tienda de aplicacines de Andrid e ios. Puede cnsultar ls enlaces de descarga en el dcument AF_manual_instalacin_y_gestin_ES. 99

100 9.2 Despliegues cmpatibles Para que nuestrs despliegues del MiniApplet sean cmpatibles cn tds ls nativs, 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, 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 100

101 Despliegue del. Establecer las rutas de ls servicis auxiliares. La falta de un canal de cmunicación bidireccinal entre el navegadr web y el móvil AutFirma, 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. Esta sentencia es incua para el MiniApplet. Ls servicis sól se usarán en cas de que se cargue la aplicación nativa. Pr mtivs seguridad, este métd n admite direccines URL lcales ( / lcalhst). Si se desea hacer pruebas en lcal, establezca la dirección IP cnfigurada en el equip. Un ejempl de us de esta llamada es: <script type="text/javascript"> MiniApplet.cargarMiniApplet( ); MiniApplet.setServlets( ) ; </script> Obtención de resultads mediante callbacks El MiniApplet permite btener ls resultads de las peracines de frma inmediata mediante la definición de funcines callback. Sin embarg, para que nuestr despliegue sea cmpatible cn ls clientes nativs se debe usar siempre el md de btención de resultads mediante callbacks. Cnsulte el apartad Obtención de resultads mediante Callbacks para más detalle de cóm usar este md. Evitar el us iterativ de las llamadas a ls métds del MiniApplet (pr ejempl, múltiples llamadas en bucle al métd de firma) 101

102 Las llamadas a las aplicacines nativas se realizan de frma asíncrna e implican que una instancia de la aplicación las atienda. Sin embarg, sól se admite que haya una instancia de la aplicación levantada, así que sól se atenderá una de las peticines lanzadas. Para el permitir la cmpatibilidad cn las aplicacines móviles n debems slicitar que la aplicación realice una peración hasta que n haya finalizad la peración anterir. Est l harems invcand a la siguiente peración desde ls métds successcallback y/ errrcallback definids para la peración anterir. Pr ejempl: Un ejempl de us de este cmprtamient es: var indice; var dats = new Array(); dats[0] = ; dats[1] = ; functin prcesarfirma(signatureb64, certb64) { enviar(signatureb64); MiniApplet.sign( dats[++indice], algritm, frmat, params, prcesarfirma, errrfirma); } functin firmar() { indice = 0; MiniApplet.sign( dats[indice], algritm, frmat, params, prcesarfirma, errrfirma); } ADVERTENCIA: Ggle Chrme n permite más de una llamada externa al navegadr (cm las llamadas a la aplicación nativa) pr cada interacción del usuari. En el cas de la cmunicación pr sckets de AutFirma est n supne un prblema per, en el cas de la cmunicación a través de un servidr intermedi de AutFirma y ls clientes móviles, est supne que sól se atenderá la primera peración slicitada. 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 implementan ls clientes nativs 9.3 Cnfiguración de la invcación a AutFirma Tras la invcación pr prtcl a AutFirma, el JavaScript de despliegue realiza varis intents de cnexión a través de ls distints puerts generads. Si n cnsigue cnectar cn la aplicación en ese tiemp, lanza un errr indicand que n se ha pdid cnectar cn la aplicación. El tiemp de espera ttal viene determinad aprximadamente pr el númer de intents de cnexión que realiza y el 102

103 tiemp de espera que se prduce entre cada un de ells. Este tiemp rnda pr defect ls 25 segunds. Dad que la invcación pr prtcl a AutFirma puede n tener una respuesta inmediata, debid a que implica levantar una máquina virtual Java, levantar la aplicación y abrir el puert, más que puede ser necesari que el usuari dé su cnsentimient para la ejecución de la aplicación, puede darse el cas de ser crt en la primera ejecución. Es pr es que el JavaScript de despliegue permite la cnfiguración de este valr mediante un par de variables. Estas sn: AUTOFIRMA_LAUNCHING_TIME: Tiemp de espera en milisegunds entre intents de cnexión cn AutFirma. Pr defect, 2000 milisegunds. AUTOFIRMA_CONNECTION_RETRIES: Númer de reintents de cnexión que se intentarán antes de determinar que n es psible cnectar cn la AutFirma. Pr defect, 10 reintents. La cnfiguración de estas variables se realizará pr medi del bjet MiniApplet. Pr ejempl: <script type="text/javascript"> // Se realizarán 15 reintents de cnexión cn AutFirma en cas // de ser necesaris MiniApplet.AUTOFIRMA_CONNECTION_RETRIES = 15; MiniApplet.cargarMiniApplet( ); </script> 9.4 Servicis auxiliares del móvil Junt al MiniApplet se distribuyen 2 Servlets de Java 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 103

104 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. 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 Ntas sbre ls servicis de almacenaje y recuperación La cnexión entre ls servicis de almacenaje (SignatureStrageServer) y ls de recuperación (SignatureRetrieverServer) se hace mediante sistema de fichers, cmpartiend una simple carpeta tempral, definida en ambs mediante la variable tmpdir, variable que debe siempre apuntar a directris visibles y cmpartids pr tdas las instancias en ejecución. Este aspect es especialmente imprtante en cnfiguracines de servidres de aplicacines en alta dispnibilidad, dnde puede haber varis nds que presten el servici trifásic, cada un de ells en un sistema de fichers diferente, dnde sí se especifica una ruta lcal, puede que esta apunte a un directri distint en cada nd (distint servidr, disc diferente, tr sistema de fichers, etc.). El que tds ls nds accedan al mism directri referenciad en la cnfiguración se puede lgrar fácilmente usand un almacenamient cmpartid entre tds ells (cn el mism punt de mntaje), mediante enlaces simbólics, etc. Es imprtante también asegurarse de que tds ls nds tienen ls permiss adecuads sbre ls directris cnfigurads Cnsideracines de seguridad Un psible ataque de denegación de servici sbre este sistema de almacenaje tempral es simplemente hacer muchas peticines de almacenaje hasta que se alcance la capacidad ttal del sistema de fichers. Ls servicis prprcinads n incrpran ninguna medida cntra ests ataques, pr l que debe ser el integradr el que las implemente. Algunas de estas medidas pdrían ser: Establecer cutas de disc para el directri cnfigurad en tmpdir. Detectar (y prevenir) múltiples llamadas al servici de almacenamient desde una misma dirección sin estar acmpañadas de las respectivas llamadas de recuperación. 104

105 Detectar (y prevenir) múltiples llamadas al servici de almacenamient en una frecuencia inusualmente alta. Limitar el tamañ de ls fichers que acepta el servici. Etc. 9.5 Ntificacines al usuari Es bligatri que el usuari tenga instalad AutFirma el móvil, según crrespnda, 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"; } El integradr sería el respnsable de preparar ess mensajes de advertencia. Puede cnsultar ls enlaces de descarga de AutFirma y ls móvil en el dcument AF_manual_instalacin_y_gestin_ES. 9.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 en las aplicacines móviles (AutFirma sí sprta tds ls frmats). Según el sistema 105

106 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 Una limitación cmún a tdas las aplicacines es que tdas utilizan siempre el almacén de certificads del sistema ( el prpi de la aplicación en el cas de ios). Se ignra tant el almacén cnfigurad en el métd de carga del applet cm el navegadr utilizad para ejecutar las funcines de firma Sistemas Andrid functin getfilenamecntentbase64(title, extensin, descriptin) Ls clientes nativs n dispnen del métd de carga de fichers, ya que est cnllevaría invcar a la aplicación 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. 106

107 functin signbatch(batchb64, batchpresignerurl, batchpstsignerurl, params, successcallback, errrcallback) Ls clientes móviles n permiten realizar peracines de firma pr ltes Sistemas ios functin savedatatfile(datab64, title, filename, extensin, descriptin, successcallback, errrcallback) 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 nativs n dispnen del métd de carga de fichers, ya que est cnllevaría invcar a la aplicación sól para que ns permitiese seleccinar el ficher de dats. En el cas cncret de ios, la prpia aplicación n tiene acces a fichers, pr l que sól se pdrán firmar dats prprcinads desde la prpia web. 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. functin signbatch(batchb64, batchpresignerurl, batchpstsignerurl, params, successcallback, errrcallback) Ls clientes móviles n permiten realizar peracines de firma pr ltes AutFirma functin getfilenamecntentbase64(title, extensin, descriptin) Ls clientes nativs n dispnen del métd de carga de fichers, ya que est cnllevaría invcar a la aplicación 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 permitirá al usuari seleccinar un ficher y l firmará directamente. functin getmultifilenamecntentbase64(title, extensin, descriptin) 107

108 AutFirma n sprta la carga de múltiples fichers simultáneamente. functin setstickysignatry(stick) AutFirma n permite fijar un certificad que el usuari seleccinar durante una peración de firma/multifirma de tal frma que este se reutilice en siguientes peracines. Se puede emular el funcinamient del métd setstickysignatry mediante el us de filtrs de certificads y el parámetr extra headless. Para ell, al terminar la primera peración de firma ( si se utiliza el métd selectcertificate) se puede tmar el certificad de firma y (mediante JavaScript un prces en servidr) se definirá un filtr de certificads que l seleccine sól a él. Al establecer este filtr y el parámetr headless=true en las siguientes firmas, se seleccinará autmáticamente ese certificad. ADVERTENCIA: AutFirma y n sn cmpatibles cn las funcines incrpradas en versines psterires del MiniApplet. Estas sn: functin signandsavetfile(peratinid, datab64, algrithm, frmat, params, utputfilename, successcallback, errrcallback) functin setkeystre(kstype) functin selectcertificate(params, successcallback, errrcallback) 9.7 Cmpatibilidad del cn aplicacines móviles y AutFirma El 1.5 es cmpatible cn: AutFirma v1.4.2 y superires Cmpatible cn sistemas Windws 7 y superires; sistemas Linux; MacOS 8 y superires. móvil Andrid v1.4 y superires Puede ver ls requisits de cmpatibilidad en la Play Stre. móvil ios v1.4 y superires Puede ver ls requisits de cmpatibilidad en la Apple Stre Enví anónim de estadísticas pr parte del MiniApplet y AutFirma Para pder mejrar la calidad del servici, tant el MiniApplet cm AutFirma envían infrmación anónima de us al servici Ggle Analytics. Esta infrmación cntiene la dirección IP de la máquina que ejecuta la aplicación de firma. 108

109 Para evitar este enví de infrmación, el integradr debe cnfigurar cm prpiedad de sistema la variable es.gb.afirma.dntsendanalytics cn el valr true. Puede cnsultar cm usar prpiedades de sistema en el MiniApplet en la sección Cnfiguración a través de prpiedades del sistema de este mism dcument. Adicinalmente, si el usuari cnfigura una variable de entrn cn mism nmbre y valr en su sistema perativ, tampc se enviarán estas estadísticas de us. 10 Infrmación específica para firmas CAdES 10.1 Algritms de firma Las firmas CAdES aceptan ls siguientes algritms de firma (deben escribirse exactamente cm aquí se muestran): SHA1withRSA 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 Firmas CAdES implícitas explícitas Las firmas y cfirmas CAdES pueden incluir internamente una cpia de ls dats firmads (firmas implícitas) n incluirls (firmas explícitas detached ). El MiniApplet pr defect genera firmas explícitas, más pequeñas en tamañ. Si desea generar firmas implícitas, debe indicar el siguiente parámetr adicinal: mde=implicit Cnsulte la sección Parámetrs adicinales para mayr infrmación Parámetrs adicinales A cntinuación se detallan ls parámetrs adicinales que aceptan cada una de las frmas de generación de firmas. 109

110 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 psibles Descripción 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 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 plicyidentifierhash [OID URN de tip OID] [Valr en Base64] 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. SHA-256 Indica que la huella digital indicada en el parámetr plicyidentifierhash se calculó mediante el algritm SHA-256. SHA-384 Indica que la huella digital indicada en el parámetr plicyidentifierhash se calculó mediante el algritm SHA-284. SHA-512 Indica que la huella digital indicada en el parámetr plicyidentifierhash se calculó mediante el algritm SHA-512. plicyqualifier [URL hacia URL (universalmente accesible) hacia el dcument 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. includeonlysignningcertificate true 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. 110

111 signatureprductincity [Text] Agrega a la firma un camp cn la ciudad en la que se realiza la firma. La cdificación debe ser UTF-8. signatureprductinpstalcde [Text] Agrega a la firma un camp cn el códig pstal en dnde se realiza la firma. La cdificación debe ser UTF-8. signatureprductincuntry [Text] Agrega a la firma un camp cn el país en la que se realiza la firma. La cdificación debe ser UTF-8. cmmitmenttypeindicatins [Enter] Indica el númer de CmmitmentTypeIndicatins que se van a declarar. Ests sn ls mtivs que se declaran para la firma. Ls valres cncrets se especifican cn cmmitmenttypeindicatinniden tifier y cmmitmenttypeindicatinndesc riptin, dnde n va desde 0 hasta el valr indicad en esta prpiedad mens 1. cmmitmenttypeindicatinnidentifier cmmitmenttypeindicatinncmmitmenttypeq ualifiers 1 Establece que el CmmitmentTypeIndicatins númer n (cntand desde cer) es Prueba de rigen. 2 Establece que el CmmitmentTypeIndicatins númer n (cntand desde cer) es Prueba de recepción. 3 Establece que el CmmitmentTypeIndicatins númer n (cntand desde cer) es Prueba de entrega. 4 Establece que el CmmitmentTypeIndicatins númer n (cntand desde cer) es Prueba de enví. 5 Establece que el CmmitmentTypeIndicatins númer n (cntand desde cer) es Prueba de aprbación. 6 Establece que el CmmitmentTypeIndicatins númer n (cntand desde cer) es Prueba de [Text] creación. Lista de indicadres textuales separads pr el carácter ' ' que se aprtan cm calificadres adicinales del CmmitmentTypeIndicatin númer n (atribut pcinal). Nrmalmente sn OID. Ls elements de la lista n pueden cntener el carácter ' ' (ya que este se usa cm separadr). signingcertificatev2 [Blean] Si se indica a true se utilizará SigningCertificateV2, si se indica cualquier 111

112 tra csa SigningCertificateV1. Si n se indica nada, se utilizará V1 para las firmas SHA1 y V2 para el rest Cntrafirma plicyidentifier plicyidentifierhash Nmbre del parámetr 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 SHA- 256 SHA- 384 SHA- 512 [URL hacia dcumen t] 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. includeonlysignningcertificate true 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. signatureprductincity [Text] Agrega a la firma un camp cn la ciudad en la que se realiza la firma. La cdificación debe ser UTF-8. signatureprductinpstalcde [Text] Agrega a la firma un camp cn el códig pstal en dnde se realiza la firma. La cdificación debe ser UTF-8. signatureprductincuntry [Text] Agrega a la firma un camp cn el país en la que se realiza la firma. La cdificación debe ser UTF-8. cmmitmenttypeindicatins [Enter Indica el númer de ] CmmitmentTypeIndicatins que se van a declarar. Ests sn ls mtivs que se declaran para la firma. Ls valres cncrets 112

113 cmmitmenttypeindicatinnidentifier cmmitmenttypeindicatinncmmitmenttype Qualifiers se especifican cn cmmitmenttypeindicatinniden tifier y cmmitmenttypeindicatinndesc riptin, dnde n va desde 0 hasta el valr mens 1 indicad en esta prpiedad. 1 Establece que el CmmitmentTypeIndicatin númer n es Prueba de rigen. 2 Establece que el CmmitmentTypeIndicatin númer n es Prueba de recepción. 3 Establece que el CmmitmentTypeIndicatin númer n es Prueba de entrega. 4 Establece que el CmmitmentTypeIndicatin númer n es Prueba de enví. 5 Establece que el CmmitmentTypeIndicatin númer n es Prueba de aprbación. 6 Establece que el [OID] CmmitmentTypeIndicatin númer n es Prueba de creación. Lista de OID separads pr el caracter ' ' que se aprtan cm calificadres adicinales del CmmitmentTypeIndicatin númer n (atribut pcinal). 11 Infrmación específica para firmas XAdES 11.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 113

114 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. 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 11.2 Algritms de firma Las firmas XAdES aceptan ls siguientes algritms de firma (deben escribirse exactamente cm aquí se muestran): SHA1withRSA SHA256withRSA SHA384withRSA SHA512withRSA 114

115 N es recmendable usar el algritm SHA1withRSA pr estar bslet y ser vulnerable. 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 Algritms de huella digital para las referencias XAdES hace cálculs de huella digital para cada una de las referencias firmadas. El algritm pr defect para estas huellas es SHA-512. Este puede cambiarse mediante el parámetr adicinal referencesdigestmethd. Cnsulte la sección 11.6 para más infrmación Situación del nd de firma en XAdES Envelped Pr defect, el MiniApplet sitúa la firma electrónica en su nd Signature directamente cm hij de la raíz del XML. N bstante, hay situacines en las que puede interesar situar este nd de firma en una situación arbitraria del XML. Para ell, puede usarse el parámetr adicinal insertenvelpedsignatureonndebyxpath, en el que, mediante una expresión XPath v1, pdems indicar el nd en el que querems se inserte la firma (el nd Signature pasará a ser el primer hij de este). Si la expresión XPath reslviese varis nds, se usará el primer de ells. Pr ejempl, en el siguiente XML: <?xml versin="1.0" encding="utf-8"?> <bkstre> <bk categry="cooking"> <title lang="en">everyday Italian</title> <authr>giada De Laurentiis</authr> <year>2005</year> <price>30.00</price> </bk> <bk categry="children"> <title lang="en">harry Ptter</title> <authr>j K. Rwling</authr> <year>2005</year> <price>29.99</price> 115

116 </bk> </bkstre> Si indicams el parámetr cn este valr: insertenvelpedsignatureonndebyxpath = /bkstre/bk[1]/title La firma se insertara cm nd hij del títul del primer libr: <?xml versin="1.0" encding="utf-8"?> <bkstre> <bk categry="cooking"> <title lang="en"> Everyday Italian <ds:signature xmlns:ds=" Id="S1"> </ds:signature> </title> <authr>giada De Laurentiis</authr> <year>2005</year> <price>30.00</price> </bk> <bk categry="children"> <title lang="en">harry Ptter</title> <authr>j K. Rwling</authr> <year>2005</year> <price>29.99</price> </bk> </bkstre> Si en la expresión XPath desea referenciar nds dentr de un espaci de nmbres, debe usar funcines XPath cm namespace-uri() lcal-name(). Pr ejempl, para seleccinar el primer nd dentr del espaci de nmbres de factura electrónica pdríams usar la expresión: 116

117 //*[namespace-uri()=' Us de estructuras Manifest en firmas XAdES Es psible crear firmas XAdES en las que, siguiend el punt 2.3 de la especificación XMLDSig ( las referencias XML n se firmen directamente, sin que se firme una estructura de tip Manifest que a su vez cntenga las referencias a firmar. De esta frma, tal y cm indica la nrmativa, la reslución de las referencias incluidas dentr de una estructura Manifest es una respnsabilidad del validadr, y de cara a la prpia firma n se resuelven para calcular las huellas digitales (l que permite hacer firmas XML explícitas). Cnsulte la especificación XMLDSig para mayr infrmación. Para crear firmas XAdES cn estructuras Manifest debe especificarse el siguiente parámetr adicinal: usemanifest=true Un ejempl muy simplificad de la estructura de una firma cn Manifest sería: <ds:signature Id="Signature-02553"> <ds:signedinf> <ds:reference Id="Reference-894bfd39 " Type=" URI="#Manifest- 36e2de7b"> </ds:reference> </ds:signedinf> <ds:object Id="ManifestObject-ffd54e53"> <ds:manifest Id="Manifest-36e2de7b"> <ds:reference Id="Reference-894bfd39" URI="myscheme://path/file"> <ds:digestmethd Algrithm=" <ds:digestvalue></ds:digestvalue> </ds:reference> </ds:manifest> </ds:object> 117

118 </ds:signature> En este ejempl el cntenid firmad es myscheme://path/file, per al firmar n se ha intentad acceder a ese ficher, y se ha dad pr buena la huella digital indicada Frmats de XAdES cmpatibles cn estructuras Manifest Las firmas XAdES cn Manifest sn cmpatibles cn el frmat Envelping y cualquier md del frmat Detached, per n cn el frmat Envelped. Dad que el sentid del us del Manifest es desligar la referencia de la firma cn la referencia a ls dats firmads, n tiene sentid esta separación cuand la firma cmparte estructura cn ls dats firmads, cm curre en el frmat XAdES Envelped 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 psibles Descripción [Text (expresión XPath v1)] insertenvelpedsignatureonndeb yxpath Indica, mediante una expresión XPath (v1), el nd baj el cual debe insertarse el nd de firma en el cas de una firma Envelped. Si la expresión devuelve más de un nd, se usa sl el primer. Si la expresión n devuelve nds está mal cnstruida se lanzará una excepción. Este parámetr sl tiene efect en firmas Envelped. usemanifest true Usa un Manifest de XMLDSig cn las referencias de firma en vez de firmar directamente estas referencias. Est permite que sea pcinal la cmprbación del destin y huellas digitales de las referencias. false Genera las firmas nrmalmente, sin Manifest (cmprtamient pr defect) addkeyinfkeyvalue true Incluye el nd KeyValue dentr de KeyInf de XAdES (cmprtamient pr defect). false N incluye el nd KeyValue dentr de KeyInf de XAdES. addkeyinfkeyname true Incluye el nd KeyName dentr de KeyInf de XAdES. 118

119 false N incluye el nd KeyName dentr de KeyInf de XAdES (cmprtamient pr defect). avidxpathextratransfrmsonenve lped true Evita la inclusión de la transfrmación XPATH2 que nrmalmente se añade para psibilitar las cfirmas y que elimina tdas las firmas del dcument para dejar únicamente el cntenid. ADVERTENCIA: La cfirma de un dcument en el que al mens una de las firmas n incluye la transfrmación XPATH, dará lugar a un dcument de firma que ptencialmente será validad incrrectamente pr ls validadres de firma. Pr este mtiv, sól se permite el us de este parámetr en la peración de firma (n en la de cfirma). false Incluye la transfrmación XPATH2 psibilita las cfirmas eliminand tdas las firmas del dcument para dejar únicamente el cntenid (cmprtamient pr defect). 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 Internally Detached. includeonlysignningcertificate true 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 Indica que la huella digital indicada en el parámetr plicyidentifierhash se calculó mediante el algritm SHA-256. SHA-384 Indica que la huella digital indicada en el parámetr plicyidentifierhash se calculó mediante el algritm SHA-384. SHA-512 Indica que la huella digital indicada en el parámetr plicyidentifierhash se calculó mediante el algritm SHA-512. plicyqualifier [URL hacia URL (universalmente accesible) hacia el dcument] 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. 119

120 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. signerclaimedrles [Text] Agrega a la firma camps cn ls cargs atribuids al firmante. Deben separarse ls cargs cn el carácter (y este n puede estar en el prpi text de ningún carg). 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 firmad. referencesdigestmethd mimetype rg/2000/09/xmld sig#sha1 rg/2001/04/xmle nc#sha256 rg/2001/04/xmle nc#sha512 [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. 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 [URI] Cdificación de ls dats a firmar (ver la dcumentación del element Object de XMLDSig para más infrmación). Un us incrrect de este parámetr puede prvcar la generación de una firma inválida. Si se prprcinan dats a firmar previamente cdificads en Base64 per se desea sean cnsiderads cm su frma descdificada, debe establecerse este valr a #base64 y especificarse el tip real en el parámetr mimetype. Pr ejempl, para firmar una imagen PNG haciend que la firma se refiera a su frma binaria directa, puede prprcinarse la imagen directamente cdificada en Base64 indicand el 120

121 encding cm #base64 y el mimetype cm image/png. El valr debe ser siempre una URI. utputxmlencding [Text] Cdificación del XML de salida. Si n se indica este valr se intenta aut-detectar a partir del XML de entrada (si ls dats a firmar sn un XML). cntenttypeoid [OID URN de tip Identificadr del tip de dat firmad. Este OID] parámetr es cmplementari (que n cannicalizatinalgrithm rg/tr/2001/rec- xml-c14n rg/tr/2001/rec- xml-c14n #WithC mments rg/2001/10/xmlexc-c14n# rg/2001/10/xmlexcc14n#withcmmen 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. Se firma el XML cn cannizad XML 1.0 exclusiv. Se firma el XML cn cannizad XML 1.0 exclusiv cn cmentaris. ts 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). Si se establece este parámetr es psible que se necesite establecer también el parámetr signedprpertiestypeurl para evitar incherencias en la versión de XAdES. signedprpertiestypeurl [URL] URL de definición del tip de las prpiedades firmadas (Signed Prperties) de XAdES. Si se establece este parámetr es psible que se necesite establecer también el parámetr xadesnamespace para evitar incherencias en la versión de XAdES. Si n se establece se usa el valr pr defect: rperties. ignrestylesheets true Si se firma un XML cn hjas de estil, ignra éstas 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 121

122 dereferenciación de hjas de estil enlazadas cn rutas relativas). false Permite que se muestren diálgs gráfics adicinales al usuari. xmltransfrms [Númer] Númer de transfrmacines a aplicar al cntenid firmad. Debe indicarse psterirmente igual númer de parámetrs xmltransfrmntype, sustituyend n pr un rdinal cnsecutiv, cmenzand en 0 (ver ntas adicinales sbre indicación de transfrmacines adicinales). xmltransfrmntype Indica que ls dats que se prprcinan para rg/2000/09/xmld firmar ya están cdificads en base64 y se debe sig#base64 declarar esta transfrmación adicinal para que se decdifiquen antes de firmarls. Esta transfrmación base64 es adicinal a la transfrmación necesaria para pasar ls dats a rg/tr/1999/recxpath rg/2002/06/xmld sig-filter2 través de ls métds de firma del cliente. El cntenid se debe prcesar mediante esta transfrmación XPATH antes de ser firmad. Únicamente es aplicable cuand se firma cntenid XML. El cntenid se debe prcesar mediante esta transfrmación 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. cmmitmenttypeindicatins [Enter] Indica el númer de CmmitmentTypeIndicatins que se van a declarar. Ests sn ls mtivs que se declaran para la firma. Ls valres cncrets se especifican cn cmmitmenttypeindicatinnident ifier cmmitmenttypeindicatinnidentif ier y cmmitmenttypeindicatinndescrip tin, dnde n va desde 0 hasta el valr mens 1 indicad en esta prpiedad. 1 Establece que el CmmitmentTypeIndicatins númer n es Prueba de rigen. 2 Establece que el CmmitmentTypeIndicatins númer n es Prueba de recepción. 3 Establece que el CmmitmentTypeIndicatins númer n es Prueba de entrega. 122

123 cmmitmenttypeindicatinndescr iptin cmmitmenttypeindicatinndcum entatinreferences cmmitmenttypeindicatinncmmi tmenttypequalifiers 4 Establece que el CmmitmentTypeIndicatins númer n es Prueba de enví. 5 Establece que el CmmitmentTypeIndicatins númer n es Prueba de aprbación. 6 Establece que el CmmitmentTypeIndicatins númer n es Prueba de creación. [Text] Establece la descripción del [Text] [Text] CmmitmentTypeIndicatins númer n.. Este atribut es pcinal. Lista de URL separadas pr el carácter ' ' que se aprtan cm referencias dcumentales del CmmitmentTypeIndicatin númer n (atribut pcinal). Las URL de la lista n pueden cntener el carácter ' ' (ya que este se usa cm separadr). Lista de indicadres textuales separads pr el carácter ' ' que se aprtan cm calificadres adicinales del CmmitmentTypeIndicatin númer n (atribut pcinal). Nrmalmente sn OID. Ls elements de la lista n pueden cntener el carácter ' ' (ya que este se usa cm separadr) 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 Subtips: N tiene subtips. Cuerp: Especificad mediante sentencias de tip XPATH. Tip: Transfrmación XPATH2 Tip: Subtips: subtract: Resta. intersect: Intersección unin: Unión Cuerp: Especificad mediante sentencias de tip XPATH2. Transfrmación BASE64. La transfrmación es inversa, es decir, ls dats se descdifican desde Base64 antes de firmarse, pr l que ests deben estar previamente cdificads en Base64 e indicarse mediante el parámetr adicinal encdign=base64. Tip: Subtips: N tiene subtips. Cuerp: N tiene cuerp. 123

124 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= 124

125 Cntrafirma Nmbre del parámetr Valres psibles Descripción addkeyinfkeyvalue true Incluye el nd KeyValue dentr de KeyInf de XAdES (cmprtamient pr defect). false N incluye el nd KeyValue dentr de KeyInf de XAdES. addkeyinfkeyname true Incluye el nd KeyName dentr de KeyInf de XAdES. false N incluye el nd KeyName dentr de KeyInf de XAdES (cmprtamient 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] plicyidentifierhashalgrithm SHA1 plicyqualifier SHA-256 SHA-384 SHA-512 [URL hacia dcument] 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. 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-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 inclus si se desea generar firmas XAdES-EPES. signerclaimedrles [Text] Agrega a la firma camps cn ls cargs atribuids al firmante. Deben separarse ls cargs cn el carácter (y este n puede estar en el prpi text de ningún carg). 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. 125

126 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. cmmitmenttypeindicatins [Enter] Indica el númer de CmmitmentTypeIndicatins que se van a declarar. Ests sn ls mtivs que se declaran para cmmitmenttypeindicatinnide ntifier cmmitmenttypeindicatinndes criptin cmmitmenttypeindicatinndc umentatinreferences cmmitmenttypeindicatinncm mitmenttypequalifiers la firma. Ls valres cncrets se especifican cn cmmitmenttypeindicatinnidentifier y cmmitmenttypeindicatinndescriptin, dnde n va desde 0 hasta el valr mens 1 indicad en esta prpiedad. 1 Establece que el CmmitmentTypeIndicatins númer n es Prueba de rigen. 2 Establece que el CmmitmentTypeIndicatins númer n es Prueba de recepción. 3 Establece que el CmmitmentTypeIndicatins númer n es Prueba de entrega. 4 Establece que el CmmitmentTypeIndicatins númer n es Prueba de enví. 5 Establece que el CmmitmentTypeIndicatins númer n es Prueba de aprbación. 6 Establece que el CmmitmentTypeIndicatins númer n [Text] [Text] [Text] mde implicit / explicit es Prueba de creación. Establece la descripción del CmmitmentTypeIndicatins númer n. Este atribut es pcinal. Lista de URL separadas pr el carácter ' ' que se aprtan cm referencias dcumentales del CmmitmentTypeIndicatin númer n (atribut pcinal). Las URL de la lista n pueden cntener el carácter ' ' (ya que este se usa cm separadr). Lista de indicadres textuales separads pr el carácter ' ' que se aprtan cm calificadres adicinales del CmmitmentTypeIndicatin númer n (atribut pcinal). Nrmalmente sn OID. Ls elements de la lista n pueden cntener el carácter ' ' (ya que este se usa cm separadr). Permite que se realicen firmas explícitas en lugar de implícitas (pr defect). 126

127 11.7 Firmas XAdES explícitas El MiniApplet cnsidera, pr cmpatibilidad cn el un tip de firmas XAdES llamadas XAdES explícitas, en las que n se firman ls dats, sin la huella digital de ests. Las firmas XAdES explícitas están deprecadas en el MiniApplet y AutFirma, y serán eliminadas en próximas versines de estas herramientas. Este tip de firmas n sn cnfrmes cn ningún tip de nrmativa ni estándar, y deben ser sustituidas pr firmas cn estructuras MANIFEST (sección 11.5) ya que en un futur próxim se extinguirá el us del tip explícit en las firmas XAdES. Para cnfigurar el md explícit cn las firmas XAdES se utiliza el parámetr de cnfiguración mde cn el valr explicit : mde=explicit Este parámetrs sl tienen efect actualmente en AutFirma y en el MiniApplet N se sprtan firmas explícitas XAdES en ls nuevs mds de peración: Firmas pr ltes predefinids. Firmas desde ls clientes móviles (Andrid e ios). Dad que el md explícit se sprta cn la única finalidad de dar sprte a instalacines bsletas que l estuviesen usand (cn Applet MiniApplet ningún prgrama funcinalidad añadida recientemente sprtará este md, recmendándse el Us de estructuras Manifest en firmas XAdES cm alternativa. El us de esta cnfiguración n sprtada en las nuevas características del cliente puede dar lugar a resultads inesperads y la firma puede ser generada de frma explícita n, sin necesidad de que siga siend así en el futur. Si algún rganism n pudiese migrar al Us de estructuras Manifest en firmas XAdES, y necesitase algun de ls nuevs mds de peración marcads cm n cmpatibles cn firmas XAdES explícitas, deberá implementar pr sí mism y de frma externa al ests mecanisms. Est implicaría: Utilizar en la métd de la peración a realizar (firma, cfirma firma pr lte), la huella digital SHA-1 de ls dats a firmar en lugar de ls prpis dats. Cnfigurar cm parámetr adicinal de la peración la prpiedad mimetype, estableciend cm valr hash/sha1. Estas peracines pueden realizarse desde JavaScript just antes de la invcación de la peración de firma. Una vez hech est, n se debe cnfigurar el parámetr adicinal mde. 127

128 Para cncer cóm establecer parámetrs adicinales en sus peracines de firma, cnsulte el apartad Pas de parámetrs adicinales a ls métds de firma, cfirma y cntrafirma. 12 Infrmación específica para firma de facturas electrónicas 12.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 MiniApplet 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. Nmbre del parámetr Valres psibles Descripción signatureprductincity [Text] Agrega a la firma un camp cn la ciudad en la que se realiza la firma. 128

129 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. 13 Infrmación específica para firma de dcuments en frmat ODF 13.1 Algritms de firma El frmat de firma ODF, relativ a dcuments LibreOffice y OpenOffice, sl sprta el algritm SHA1withRSA. El prgrama ignrará cualquier valr indicad cm algritm de firma, utilizándse siempre SHA1withRSA. La peración de cntrafirma n está sprtada pr el estándar ODF ni pr el 14 Infrmación específica para firma de dcuments en frmat OOXML 14.1 Algritms de firma La peración de cntrafirma n está sprtada pr el estándar OOXML ni pr el 129

130 15 Infrmación específica para firmas PAdES 15.1 Creación de una firma visible El MiniApplet permite la creación de firmas visibles dentr de un dcument PDF, que sn l sn tant en pantalla (pr ejempl, usand Adbe Reader) cm en papel una vez impres el dcument. Para ell debems indicar, mediante parámetrs adicinales, la página en dnde situar la visualización de la firma (sl puede haber una, en una única página) y sus crdenadas dentr de esta. Las crdenadas de la visualización se indican partiend de la esquina inferir izquierda, según el siguiente diagrama: 130

131 signaturepsitinonpageupperrightx signaturepsitinonpagelwerleftx signaturepsitinonpageupperrighty signaturepsitinonpagelwerlefty Estas crdenadas, así cm la página de inserción se establecen usand ls parámetrs adicinales, pr ejempl: signaturepsitinonpagelwerleftx = 100 signaturepsitinonpagelwerlefty = 100 signaturepsitinonpageupperrightx = 200 signaturepsitinonpageupperrighty = 200 signaturepage = 1 Ls dcuments PDF cmienzan su numeración de páginas desde un (1). Si se indica -1 cm página se usa la última página del dcument. Dentr del recuadr marcad pr las crdenadas indicadas, es psible mstrar distints elements: Una imagen: En este cas debe indicarse qué imagen a usar aprtand el binari en frmat JPEG cdificad en Base64. signaturerubricimage = AGFGSFH 131

132 La imagen de defrma para adaptarse a las dimensines del recuadr marcad pr las crdenadas, pr l que es imprtante que ambs tengan la misma relación de aspect. Text (que puede cmbinarse cn una imagen) Es necesari indicar n sl el text a sbreimprimir en el cuadr visible, sin también indicacines sbre su frmat (tip de letra y su tamañ, clr, etc.). El text intrduce de frma autmática ls retrns de carr necesaris para adaptarse al recuadr. El text aparece siempre sbre la imagen indicada, si se indicó alguna. Ls parámetrs para indicar el frmat sn: layer2text Text a escribir dentr de la firma visible. Este text se escribe únicamente si n se ha especificad una imagen de rúbrica, y necesita que se indique la página y la situación dónde mstrar el recuadr de firma mediante ls parámetrs signaturepsitinonpagelwerleftx, signaturepsitinonpagelwerlefty, signaturepsitinonpageupperrightx, signaturepsitinonpageupperrighty y signaturepage. layer2fntfamily Tip de letra a usar en el text de la firma visible. Este parámetr requiere que se haya establecid también el parámetr layer2text. Ls valres admitids sn: 0 = Curier (tip pr defect) 1 = Helvética 2 = Times Rman 3 = Symbl 4 = ZapfDingBats 132

133 layer2fntsize Tamañ de letra a usar en el text de la firma visible. Este parámetr requiere que se haya establecid también el parámetr layer2text. Ls valres admitids sn numérics (y el valr pr defect es 12). layer2fntstyle Estil del tip de letra a usar en el text de la firma visible. Este parámetr requiere que se haya establecid también el parámetr layer2text. Ls valres admitids sn numérics, crrespndiend: 0 = Nrmal (estil pr defect) 1 = Negrita 2 = Cursiva 3 = Negrita y cursiva 4 = Subrayad 8 = Tachad Es psible cmbinar estils aplicand la peración lógica sbre ls valres numérics a cmbinar. layer2fntclr Clr del text de la firma visible. Este parámetr requiere que se haya establecid también el parámetr layer2text. Ls valres admitids sn textuales (se ignra entre mayúsculas y minúsculas), sprtándse: black = Negr (clr pr defect) white = Blanc gray = Gris lightgray = Gris clar darkgray = Gris scur red = Rj pink = Rsa 133

134 15.2 Inserción de una imagen en un dcument PDF antes de ser firmad Cm ayuda principalmente a la inserción de Códigs Segurs de Validación (CSV), existe la capacidad de insertar una imagen en un dcument PDF just antes de que se prduzca la firma. Para ell, debems indicar primer una página y una zna dentr de esta para insertar la imagen, usand para ell el mism sistema de crdenadas descrit en la sección 15.1, es decir, a partir de la esquina inferir izquierda. La imagen debe prprcinarse en frmat JPEG cdificad en Base64. Para indicar la página, pdems usar su númer (empezand a cntar desde un cm primera página), usar -1 para referirns a la última página del dcument 0 (cer) para insertar la imagen en tdas las páginas. Es imprtante recalcar que la imagen se defrma para adaptarse al recuadr marcad pr las crdenadas, siend útil para evitar este efect que ambs tengan la misma relación de aspect. Igualmente, n se prprcinan funcinalidades de rtad, pr l que si se quiere insertar una imagen de lad (pr ejempl, en el margen de la página, esta debe venir rtada en rigen. Ls parámetrs adicinales a usar para la inserción de imágenes sn: image Imagen que se desea insertar en el PDF antes de que este sea firmad. La imagen debe prprcinarse en frmat JPEG cdificad en Base64. Si el dcument ya cntiene firmas es psible que se invaliden, pr l que cnviene usarl únicamente en dcuments sin firmas previas. imagepage Página dnde desea insertarse la imagen indicada mediante el parámetr image. La numeración de las páginas cmienza en un. Si se indica -1 cm númer de página se inserta la imagen en la última página del dcument. Si se indica 0 cm númer de página se inserta la imagen en tdas las páginas del dcument. Este parámetr es bligatri, si n se indica una página válida n se insertará la imagen. imagepsitinonpagelwerleftx Crdenada hrizntal inferir izquierda de la psición de la imagen (indicada mediante el parámetr image) dentr de la página. 134

135 Es necesari indicar el rest de crdenadas de la imagen mediante ls parámetrs imagepsitinonpagelwerlefty, imagepsitinonpageupperrightx e imagepsitinonpageupperrighty. Es necesari indicar también una página de inserción en el parámetr imagepage. imagepsitinonpagelwerlefty Crdenada vertical inferir izquierda de la psición de la imagen (indicada mediante el parámetr image) dentr de la página. Es necesari indicar el rest de crdenadas de la imagen mediante ls parámetrs imagepsitinonpagelwerleftx, imagepsitinonpageupperrightx e imagepsitinonpageupperrighty. Es necesari indicar también una página de inserción en el parámetr imagepage. imagepsitinonpageupperrightx Crdenada hrizntal superir derecha de la psición de la imagen (indicada mediante el parámetr image) dentr de la página. Es necesari indicar el rest de crdenadas de la imagen mediante ls parámetrs imagepsitinonpagelwerleftx, imagepsitinonpagelwerlefty e imagepsitinonpageupperrighty. Es necesari indicar también una página de inserción en el parámetr imagepage. imagepsitinonpageupperrighty Crdenada vertical superir derecha de la psición de la imagen (indicada mediante el parámetr image) dentr de la página. Es necesari indicar el rest de crdenadas de la imagen mediante ls parámetrs imagepsitinonpagelwerleftx, imagepsitinonpagelwerlefty e imagepsitinonpageupperrightx. Es necesari indicar también una página de inserción en el parámetr imagepage 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. 135

136 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 Firma de dcuments PDF cifrads prtegids cn cntraseña Si bien es psible firmar dcuments PDF cifrads prtegids cn cntraseña, deben tenerse en cuenta las siguientes limitacines: N se sprta la firma de PDF cifrads cn certificads cn algritm AES256. Puede que n sea psible, en tds ls cass, validar u btener justificantes de validación de dcuments PDF cifrads prtegids pr cntraseña usand la platafrma de validación VALIDE del Gbiern de España 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 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. includeonlysignningcertificate (prpiedad cmpartida cn XAdES y CAdES) 136

137 Si se establece a true se incluye en la firma únicamente el certificad del firmante (y n la cadena de certificación cmpleta). Si n se establece se establece a false se incluirá tda la cadena de certificación. alwayscreaterevisin image imagepage Si se establece a true siempre crea una revisión del PDF inclus cuand el dcument n cntiene ninguna firma previa. Est requiere que ls dcuments de entrada cumplan estrictamente la especificación PDF 1.7 (ISO :2008), y puede crear incmpatibilidades cn dcuments PDF acrdes a la especificación 1.3 creads cn biblitecas antiguas, cm pr ejempl QPDF. Si se establece a false, n crea revisines en dcuments que n cntengan firmas previas y sí las crea en dcuments que ya cntengan alguna firma. Imagen que se desea insertar en el PDF antes de que este sea firmad. La imagen debe prprcinarse en frmat JPEG cdificad en Base64. Si el dcument ya cntiene firmas es psible que se invaliden, pr l que cnviene usarl únicamente en dcuments sin firmas previas. Página dnde desea insertarse la imagen indicada mediante el parámetr image. La numeración de las páginas cmienza en un. Si se indica -1 cm númer de página se inserta la imagen en la última página del dcument. Si se indica 0 cm númer de página se inserta la imagen en tdas las páginas del dcument. Este parámetr es bligatri, si n se indica una página válida n se insertará la imagen. imagepsitinonpagelwerleftx Crdenada hrizntal inferir izquierda de la psición de la imagen (indicada mediante el parámetr image) dentr de la página. Es necesari indicar el rest de crdenadas de la imagen mediante ls parámetrs imagepsitinonpagelwerlefty, imagepsitinonpageupperrightx e imagepsitinonpageupperrighty. Es necesari indicar también una página de inserción en el parámetr imagepage. imagepsitinonpagelwerlefty Crdenada vertical inferir izquierda de la psición de la imagen (indicada mediante el parámetr image) dentr de la página. Es necesari indicar el rest de crdenadas de la imagen mediante ls parámetrs 137

138 imagepsitinonpagelwerleftx, imagepsitinonpageupperrightx e imagepsitinonpageupperrighty. Es necesari indicar también una página de inserción en el parámetr imagepage. imagepsitinonpageupperrightx Crdenada hrizntal superir derecha de la psición de la imagen (indicada mediante el parámetr image) dentr de la página. Es necesari indicar el rest de crdenadas de la imagen mediante ls parámetrs imagepsitinonpagelwerleftx, imagepsitinonpagelwerlefty e imagepsitinonpageupperrighty. Es necesari indicar también una página de inserción en el parámetr imagepage. imagepsitinonpageupperrighty attach Crdenada vertical superir derecha de la psición de la imagen (indicada mediante el parámetr image) dentr de la página. Es necesari indicar el rest de crdenadas de la imagen mediante ls parámetrs imagepsitinonpagelwerleftx, imagepsitinonpagelwerlefty e imagepsitinonpageupperrightx. Es necesari indicar también una página de inserción en el parámetr imagepage. Cntenid a añadir cm adjunt al PDF, en frmat Base64 (el adjunt será el binari decdificad). Este parámetr requiere que se haya establecid también el parámetr attachfilename. attachfilename Nmbre de ficher para adjuntar el cntenid binari indicad mediante attach. Este parámetr requiere que se haya establecid también el parámetr attach. attachdescriptin Descripción del cntenid binari indicad mediante attach. certificatinlevel Nivel de certificación de la firma PDF. Ls valres admitids sn numérics, crrespndiend: 0 = Firma rdinaria n certificada (pr defect) 1 = Firma de autr. N se permite ningún cambi psterir en el dcument 138

139 2 = Firma de autr certificada para frmularis. Se permite únicamente el rellen psterir de ls camps del frmulari 3 = Firma certificada. Se permite únicamente el rellen psterir de ls camps del frmulari el añadid de firmas de aprbación cmpresspdf Si se establece a true n se indica, se cmprime el PDF resultante (firmad) para que cupe mens tamañ. Si se establece a false, el PDF n se cmprime. Esta prpiedad sól se aplica si se trata de un PDF v4 superir. Igualmente, esta prpiedad n tiene efect en ls PDF-A1, este tip de PDF nunca se cmprime al guardarse. pdfversin Versión de PDF que se declarará en el dcument de salida. Ls valres que pueden declararse y la versión de PDF asciada a cada un de ells sn ls siguientes: 2: PDF 1.2 3: PDF 1.3 4: PDF 1.4 5: PDF 1.5 6: PDF 1.6 7: PDF 1.7 signaturesubfilter Nmbre del sub-filtr en el diccinari PDF para indicar el tip de la firma. Si n se indica este parámetr pr defect se usa adbe.pkcs7.detached (firma PAdES básica). Es psible indicar ETSI.CAdES.detached para generar una firma PAdES-BES, si bien el hacerl puede causar que al añadir firmas adicinales al PDF se invaliden las ya existentes. signaturefield signaturepage Nmbre del camp en dnde insertar la firma. Si el dcument PDF tiene ya un camp de firma pre-cread es psible utilizarl para insertar la firma generada, referenciándl pr su nmbre. Si se indica un nmbre de camp de firma que n exista en el dcument PDF prprcinad, se generará una excepción. Página del dcument PDF dnde insertar la firma. Puede usarse la cnstante LAST_PAGE para referirse a la última página del dcument PDF si se descnce el númer ttal de páginas de este. 139

140 Este parámetr se ignra si se ha establecid valr al parámetr signaturefield, y necesita que se establezcan valres válids a ls parámetrs signaturepsitinonpagelwerleftx, signaturepsitinonpagelwerlefty, signaturepsitinonpageupperrightx y signaturepsitinonpageupperrighty. signaturepsitinonpagelwerleftx Crdenada hrizntal inferir izquierda de la psición del recuadr visible de la firma dentr de la página. Es necesari indicar el rest de crdenadas del recuadr mediante ls parámetrs signaturepsitinonpagelwerlefty, signaturepsitinonpageupperrightx y signaturepsitinonpageupperrighty. Si n se indica una página en el parámetr signaturepage la firma se inserta en la última página del dcument. signaturepsitinonpagelwerlefty Crdenada vertical inferir izquierda de la psición del recuadr visible de la firma dentr de la página. Es necesari indicar el rest de crdenadas del recuadr mediante ls parámetrs signaturepsitinonpagelwerleftx, signaturepsitinonpageupperrightx y signaturepsitinonpageupperrighty. Si n se indica una página en el parámetr signaturepage la firma se inserta en la última página del dcument. signaturepsitinonpageupperrightx Crdenada hrizntal superir derecha de la psición del recuadr visible de la firma dentr de la página. Es necesari indicar el rest de crdenadas del recuadr mediante ls parámetrs signaturepsitinonpagelwerleftx, signaturepsitinonpagelwerlefty y signaturepsitinonpageupperrighty. Si n se indica una página en el parámetr signaturepage la firma se inserta en la última página del dcument. signaturepsitinonpageupperrighty Crdenada vertical superir derecha de la psición del recuadr visible de la firma dentr de la página. Es necesari indicar el rest de crdenadas del recuadr mediante ls parámetrs signaturepsitinonpagelwerleftx, signaturepsitinonpagelwerlefty y signaturepsitinonpageupperrightx. 140

141 Si n se indica una página en el parámetr signaturepage la firma se inserta en la última página del dcument. signaturerubricimage layer2text Imagen JPEG cdificada en Base64 de la rúbrica de la firma manuscrita que se desea aparezca cm firma visible en el PDF. Text a escribir dentr de la "capa 2" de la firma visible. Este text se escribe únicamente si n se ha especificad una imagen de rúbrica, y necesita que se indique la página y la situación dónde mstrar el recuadr de firma mediante ls parámetrs signaturepsitinonpagelwerleftx, signaturepsitinonpagelwerlefty, signaturepsitinonpageupperrightx, signaturepsitinonpageupperrighty y signaturepage. Este text puede incluir una serie de palabras clave que serán sustituidas pr ls texts aprpiads del titular emisr del certificad de firma: $$SUBJECTCN$$ Nmbre cmún (CN, Cmmn Name) dentr del X.500 Principal del titular del certificad de firma. $$ISSUERCN$$ Nmbre cmún (CN, Cmmn Name) dentr del X.500 Principal del emisr del certificad de firma. $$CERTSERIAL$$ Númer de serie del certificad de firma. $$SIGNDATE=PATRÓN$$ Fecha de la firma, dnde PATRÓN debe indicar el frmat en el que debe mstrarse la fecha, siguiend el esquema definid pr Oracle para la clase SimpleDateFrmat. Así, pr ejempl, el text "Firmad pr $$SUBJECTCN$$ el día $$SIGNDATE=dd/MM/yyyy$$." resultará finalmente en el PDF cm "Firmad pr Tmás García-Merás el día 04/01/2016." supniend que el CN del titular del certificad de firma es Tmás García-Merás y que la firma se realiza el 04/01/2016. layer2fntfamily Tip de letra a usar en el text de la "capa 2" de la firma visible. Este parámetr requiere que se haya establecid también el parámetr layer2text. Ls valres admitids sn numérics, crrespndiend: 0 = Curier (tip pr defect) 1 = Helvética 2 = Times Rman 141

142 3 = Symbl 4 = ZapfDingBats layer2fntsize Tamañ de letra a usar en el text de la "capa 2" de la firma visible. Este parámetr requiere que se haya establecid también el parámetr layer2text. Ls valres admitids sn numérics (y el valr pr defect es 12). layer2fntstyle Estil del tip de letra a usar en el text de la "capa 2" de la firma visible. Este parámetr requiere que se haya establecid también el parámetr layer2text. Ls valres admitids sn numérics, crrespndiend: 0 = Nrmal (estil pr defect) 1 = Negrita 2 = Cursiva 3 = Negrita y cursiva 4 = Subrayad 8 = Tachad Es psible cmbinar estils aplicand la peración lógica sbre ls valres numérics a cmbinar. layer2fntclr Clr del text de la "capa 2" de la firma visible. Este parámetr requiere que se haya establecid también el parámetr layer2text. Ls valres admitids sn textuales (se ignra entre mayúsculas y minúsculas), sprtándse: black = Negr (clr pr defect) white = Blanc gray = Gris lightgray = Gris clar darkgray = Gris scur red = Rj pink = Rsa signreasn Razón pr la que se realiza la firma (este dat se añade al diccinari PDF, y n a la prpia firma). signatureprductincity (prpiedad cmpartida cn XAdES y CAdES) 142

143 signercntact Ciudad en la que se realiza la firma (este dat se añade al diccinari PDF, y n a la prpia firma). Cntact del firmante, usualmente una dirección de crre electrónic (este dat se añade al diccinari PDF, y n a la prpia firma). plicyidentifier (prpiedad cmpartida cn XAdES y CAdES) Identificadr de la plítica de firma. Debe ser un OID ( una URN de tip OID) que identifique unívcamente la plítica en frmat ASN.1 prcesable. plicyidentifierhash (prpiedad cmpartida cn XAdES y CAdES) Huella digital del dcument de plítica de firma (nrmalmente del mism ficher en frmat ASN.1 prcesable). Si n se indica una huella digital y el parámetr plicyidentifier n es una URL accesible universalmente se prvcará un errr, mientras que si n se indica una huella digital per el parámetr plicyidentifier es una URL accesible universalmente, se descargara el ficher apuntad pr la URL para calcular la huella digital al vuel. plicyidentifierhashalgrithm (prpiedad cmpartida cn XAdES y CAdES) Algritm usad para el cálcul de la huella digital indicada en el parámetr plicyidentifierhash. Es bligatri indicarl cuand se prprcina una huella digital distinta de 0. plicyqualifier (prpiedad cmpartida cn XAdES y CAdES) URL que apunta al dcument descriptiv de la plítica de firma (nrmalmente un dcument PDF cn una descripción textual). wnerpasswrd headless Cntraseña de apertura del PDF (cntraseña del prpietari) si este estaba cifrad. N se sprta la firma de dcuments PDF cifrads cn certificads cn algritm AES256. Evita cualquier interacción cn el usuari si se establece a true, si n se establece se establece a false actúa nrmalmente (puede mstrar diálgs, pr ejempl, para slicitar las cntraseñas de ls PDF cifrads). Útil para ls prcess desatendids y pr ltes. allwsigningcertifiedpdfs 143

144 Si se establece a true permite la firma cfirma de PDF certificads sin cnsultarl al usuari, si se establece a false cualquier tr valr se lanza una excepción en cas de intentar firmar cfirmar un PDF certificad y si n se establece se mstrará un diálg al usuari para que cnfirme que desea realizar la firma a pesar de que el resultad serán una firma n válida. Si el parámetr headless está establecid a true, n pdrá mstrar el diálg de cnfirmación así que llegads a este punt se lanzará una excepción. N se sprta el cifrad de dcuments PDF cn certificads cn algritm AES256. signingcertificatev2 Si se indica a true se utilizará SigningCertificateV2, si se indica cualquier tra csa SigningCertificateV1. Si n se indica nada, se utilizará V1 para las firmas SHA1 y V2 para el rest. 144

145 16 Prblemas cncids 16.1 El n funcina adecuadamente cn las versines de Firefx de la 42.0 a la 47.0 Firefx 42.0 y superires sufren de un prblema de cmpatibilidad cn el entrn de ejecución de Applets de Java (Java Plugin). Este errr es cncid y se encuentra dcumentad pr Mzilla: Para slventar este errr, actualice a la última versión de Mzilla Firefx. Tenga en cuenta que a partir de Mzilla Firefx 49.0 es psible que se tenga que instalar ls entrns de ejecución redistribuibles de Micrsft Visual C Si n le es psible instalar una versión actualizada de Mzilla Firefx, deshabilite pr cmplet el sprte de Applets de Java en Firefx (cnsulte la dcumentación de Mzilla para ell) e instale AutFirma para realizar las firmas prescindiend del MiniApplet 16.2 N se puede acceder al almacén de claves de Firefx 49.0 y superires La carga del almacén de claves y certificads de Firefx 49 y superires pr parte del necesita que el sistema tenga instalad ls entrns de ejecución redistribuibles de Micrsft Visual C Si n cnsigue acceder a sus certificads y claves privadas desde el necesitará descargar este sftware e instalarl manualmente. El entrn de ejecución redistribuible de Micrsft Visual C puede descargarse desde: Una vez en el enlace, seleccine el idima y la arquitectura adecuada para su sistema perativ. El prces de instalación puede requerir permiss de administradr Us de cierts algritms cn Windws XP Cuand se realizan firmas sbre Windws XP, en ciertas cnfiguracines (Service Pack, versión de Java, arquitectura x86 x64, cntrladres de tarjeta inteligente), n es psible usar RSA cn SHA-2 cm algritm de firma. Actualice siempre que sea psible a una versión actual de su sistema perativ, y si n es psible, use SHA-256 cm alternativa a SHA-512 SHA-384 cuand ests ds últims n funcinen, y SHA-1 cuand n funcine ningún algritm de la familia SHA-2 (SHA-224, SHA-256, SHA-384 y SHA-512), si bien en este últim cas debe tener siempre en cuenta que SHA-1 es actualmente un algritm bslet y vulnerable. 145

146 16.4 Diálgs de advertencia al usuari en Java 7u55 y psterires (incluyend Java 8) Dad que el MiniApplet se distribuye cm un Applet de Java genéric susceptible de ser usad en cualquier siti Web, n incrpra restriccines en este sentid. Java, a partir de la versión 7u55 bliga a ls Applets a indicar el siti Web ( al mens su dmini) en el que se van a publicar, mstrand un diálg de advertencia a ls usuaris finales si n se hace así. Para evitar ests diálgs, es necesari un prces pr parte del integradr cnsistente en ls siguientes pass: 1. Mdificación del JAR del MiniApplet para indicar el siti Web de publicación. a. Abra el JAR cm si de un ZIP se tratase (puede cambiar tempralmente la extensión de JAR a ZIP para mayr cmdidad). b. Mdifique el ficher META-INF/MANIFEST.MF, y dentr de este indique en el atribut Caller-Allwable-Cdebase el siti Web dnde va a publicar el MiniApplet, siguiend las instruccines publicadas en: nifest.html#caller_allwable c. Empaquete de nuev el JAR, para l cual puede usar una herramienta nrmal de cmpresión ZIP la prpia de empaquetad JAR de Java: 2. Refirma del MiniApplet. a. Dad que la mdificación del MANIFEST.MF invalidará la firma riginal del MiniApplet, debe refirmarl cn un certificad prpi, para ell puede usar la herramienta JarSigner de Java: html b. Es imprtante que utilice un certificad de firma de códig emitid pr una autridad de certificación recncida cm de cnfianza pr Oracle. Puede encntrar la lista de entidades recncidas en el Panel de Cntrl de Java, dentr del btón Gestinar Certificads de la pestaña Seguridad, y dentr de la ventana en la sección Autridades de Certificación de firmantes del Sistema (esta lista se actualiza cn relativa frecuencia, cnsulte siempre cn la versión más reciente de Java): 146

147 De frma general, puede encntrar infrmación sbre cm mdificar el MANIFEST.MF de un prgrama Java en: Puede encntrar más infrmación sbre este asunt en: En cualquier cas, actualice siempre el entrn de ejecución de Java de ls clientes de firma a la última versión dispnible Errr El cnjunt de claves n existe al firmar cn el almacén de claves de Windws En ciertas casines, y especialmente cuand se usan tarjetas inteligentes, etc.), al firmar en un entrn perativ Windws, la peración finaliza cn errr y se muestra en cnsla el mensaje El cnjunt de claves n existe ( Keyset des nt exist si se tiene un Windws en inglés). Este prblema, que si bien puede darse en cualquier versión de Windws es más cmún en Windws XP, n tiene slución, y se debe a una incmpatibilidad de Java cn ls cntrladres CAPI (CSP, MiniDriver, etc.) de Windws instalads en el sistema del usuari. 147