ALTAS MANUAL DE USUARIO DEL SERVICIO DE CRIPTOGRAFIA

Transcripción

1 ALTAS MANUAL DE USUARIO DEL SERVICIO DE CRIPTOGRAFIA Versión 1.8 Área de Aplicaciones Especiales y Arquitectura de Software

2 Hoja de Control Título Documento de Referencia Responsable Manual de Usuario del NORMATIVA ATLAS Área de Aplicaciones Especiales y Arquitectura de Software Versión 1.8 Fecha Versión 19/09/2013 Registro de Cambios Versión Causa del Cambio Responsable del Cambio Fecha del Cambio 1.0 Versión inicial del documento En ATLAS la implementación del Servicio se ha modificado por lo tanto este documento ha sido ampliamente modificado. Modificación de apartados y para reflejar cambios en nomenclatura de variable app.id.asf Añadido enlace a aplicación de ejemplo en portal ATLAS Actualización a ASF 5. Eliminado apartado 3.1.3, los ficheros de configuración de ASF ya no necesitan residir en la aplicación. Apartado 3.2.1, eliminados parámetros no necesarios. Apartado 3.2.2, nuevas variables de configuración para ASF Se modifica el nombre del área Modificado apartado para configurar SSL en Weblogic Modificado apartado para configurar SSL en Weblogic Añadido punto 4.7 para indicar operaciones no estándar en ASF Añadidos múltiples ejemplos de nuevas funcionalidades añadidas. Apartado 3.1.3, añadida clase de servicio para inyectar servicio ASF. Añadido apartado 4.7 de firma Pades. Añadido apartado 4.13 de verificación Pades. Área de Integración y Arquitectura de Aplicaciones Área de Integración y Arquitectura de Aplicaciones Area de Integración y Arquitectura de Aplicaciones Area de Integración y Arquitectura de Aplicaciones Área de Aplicaciones Especiales y Arquitectura de Software Área de Aplicaciones Especiales y Arquitectura de Software Área de Aplicaciones Especiales y Arquitectura de Software Área de Aplicaciones Especiales y Arquitectura de Software 27/01/ /10/ /02/ /05/ /06/ /08/ /10/ /11/ de 46

3 Framework Atlas Versión Causa del Cambio Responsable del Cambio Fecha del Cambio Modificados apartados 4.14 y Añadida app.name en el ejemplo de environment.properties, sacado de application.properties - Cambiadas referencias a asfservice por cryptservice Se cambia el nombre a Servicio de Criptografía Modificados apartados 4.7 y 4.8 para ejemplos de métodos tienefirmapdf y tienefirmaxml. Modificado apartado 4.6 Área de Aplicaciones Especiales y Arquitectura de Software Área de Aplicaciones Especiales y Arquitectura de Software Área de Aplicaciones Especiales y Arquitectura de Software 21/12/ //02/ /09/ de 46

4 Índice 1. INTRODUCCIÓN AUDIENCIA OBJETIVO CONOCIMIENTOS PREVIOS DESCRIPCIÓN INSTALACIÓN Y CONFIGURACIÓN INSTALACIÓN Paso 1: Añadir la dependencia al módulo de Seguridad Paso 2: Incluir la ruta de definición del servicio cryptservice Paso 3: Inyectar el Servicio en las clases que lo requieran CONFIGURACIÓN Configuración básica Configuración avanzada Configuración del plugin de Jetty para trabajar como servidor seguro Configuración de Weblogic para trabajar como servidor seguro USO OBTENCIÓN DE DATOS DE UN CERTIFICADO DIGITAL COMPROBACIÓN DE ACCESO DE UN CERTIFICADO CIFRADO Y DESCIFRADO DE DATOS CON CLAVE CIFRADO Y DESCIFRADO DE DATOS CON CERTIFICADO FIRMA ELECTRÓNICA EN SERVIDOR FIRMA DE PDF FIRMA PADES FIRMA DE FICHEROS XML FIRMA XADES VALIDACIÓN DE FIRMAS ELECTRÓNICAS VERIFICACIÓN DE UN CERTIFICADO DIGITAL VERIFICACIÓN DE FIRMA PDF VERIFICACIÓN DE FIRMA PADES VALIDACIÓN DE FIRMA XMLDSIG VALIDACIÓN DE FIRMA XADES EXTRACCIÓN DE INFORMACIÓN DE FIRMA DE UN DOCUMENTO XML INDICAR OPERACIÓN NO ESTÁNDAR DE ASF APLICACIÓN DE EJEMPLO ENLACES RELACIONADOS de 46

5 Contenido 1. INTRODUCCIÓN Este documento contiene el manual de uso del servicio de criptografía del módulo de seguridad del framework Atlas. En él se incluye información sobre cómo utilizar dicho componente en una aplicación, así como información acerca de la configuración de los parámetros fundamentales del componente Audiencia objetivo El lector objetivo de este documento es toda aquella persona que esté desarrollando una aplicación basada en el framework Atlas y desee acceder a la plataforma ASF Conocimientos Previos Para un completo entendimiento del documento, el lector deberá tener conocimientos previos sobre las siguientes tecnologías: - Lenguaje Java - Spring Framework - Conocimientos básicos de ASF y certificados digitales X.509 Para saber más sobre dichas tecnologías, consultar los accesos referenciados en el apartado 5 de este documento, Enlaces Relacionados. 5 de 46

6 2. DESCRIPCIÓN El servicio de Spring cryptservice que incluye el módulo de seguridad de Atlas, provee las siguientes funcionalidades: Obtención de datos de un certificado Cifrado y descifrado de datos simétrico con clave Cifrado y descifrado asimétrico con certificado Firma electrónica en servidor Firma electrónica en cliente (en documento aparte) Verificación de firmas electrónicas Validación de certificados digitales 6 de 46

7 3. INSTALACIÓN Y CONFIGURACIÓN 3.1. INSTALACIÓN El viene incluido en el módulo de seguridad de atlas que, a su vez, viene incluido en el arquetipo web. Para poder utilizarlo, bastará con incluir la dependencia de este módulo en el fichero pom.xml del proyecto, añadir la ruta correspondiente al fichero xml de Spring en la variable configlocations, y definir en el contexto de Spring la configuración del servicio para la aplicación Paso 1: Añadir la dependencia al módulo de Seguridad Atención Este paso no es necesario si el proyecto se ha generado a partir del arquetipo web, servicioweb o documentumweb de Atlas. Para añadir la dependencia al módulo de seguridad dentro de nuestro proyecto maven hay que añadir una entrada dependency en la sección dependencies del fichero pom.xml del proyecto, como se puede ver en el siguiente ejemplo: pom.xml <dependencies> [...] <dependency> <groupid>atlasfrm</groupid> <artifactid>atlasfrm-seguridad-lib</artifactid> <version>${atlasfrm-seguridad-lib}</version> </dependency> [...] </dependencies> 7 de 46

8 Paso 2: Incluir la ruta de definición del servicio cryptservice La librería de seguridad ya contiene una definición del servicio cryptservice dentro del contexto de Spring. Bastará con incluir la siguiente ruta dentro de la configuración de los configlocations (usualmente en el fichero web.xml): classpath:/conf/applicationcontext-crypt.xml A continuación se muestra un ejemplo de configlocations en el fichero web.xml: web.xml <context-param> <description> Este parámetro indica la localización exacta de los ficheros de configuración de SPRING </description> <param-name>contextconfiglocation</param-name> <param-value> classpath:/conf/applicationcontext-security.xml; classpath:/conf/applicationcontext-security-hostpolitica.xml; classpath:/conf/applicationcontext-componentes.xml; classpath:/conf/atlas-trazas-application-context.xml; classpath:/conf/applicationcontext-crypt.xml; classpath:/conf/applicationcontext-general.xml; classpath:/conf/applicationcontext-database.xml; </param-value> </context-param> Paso 3: Inyectar el Servicio en las clases que lo requieran Para inyectar el Servicio previamente definido, se pasa como property al bean que lo vaya a usar, que debe tener el método set correspondiente. Para más información sobre cómo inyectar referencias, se puede consultar la documentación de Spring. applicationcontext-services.xml <bean id="miservice" class="xxxx.services.miserviceimpl" p:cryptservice-ref="cryptservice"/> xxxx.services.miserviceimpl.java public class MiServiceImpl implements MiService { private CryptService cryptservice; } public void setcryptservice(cryptservice cryptservice) { this.cryptservice = cryptservice; }... 8 de 46

9 3.2. CONFIGURACIÓN Configuración básica En el modo básico de configuración, esto es, tomando todos los valores por defecto (ver tabla de apartado 3.2.2) solo será necesario configurar los valores del fichero environment.properties, principalmente el parámetro asf.cipherkey que establece la clave de cifrado simétrico para la aplicación (siempre que se use esta funcionalidad). environment.properties ###################################################### # Fichero de variables de configuración específicas # # para el entorno LOCAL # ###################################################### [...] # Recursos de ASF asf.clientjsurl= asf.cipherkey=************* El resto de parámetros ya están configurados para funcionar correctamente en el entorno local de desarrollo. También será necesario configurar el parámetro app.id.asf en el fichero environment.properties con el valor dado de alta para la aplicación en el servidor de ASF. environment.properties ###################################################### # Fichero de propiedades donde se configuran todos # # los parametros de la aplicación que no necesitan # # una configuración diferente para cada entorno (su # # valor es el mismo en el entorno de desarrollo # # local, validación y producción) # ###################################################### [...] # Ids de aplicacion # Identificador de la aplicacion utilizado para las tablas de USU (intranet) app.name=xxxx # Identificador de la aplicacion utilizado para tablas de USUI (internet) app.id.certificate=xxxx # Identificador de la aplicacion utilizado en ASF app.id.asf=apl_demo 9 de 46

10 Configuración avanzada Si se necesita cambiar la configuración por defecto del servicio de ASF será necesario redefinir el bean asfconfiguration en el contexto de Spring. Las propiedades de configuración se pueden definir en el mismo fichero de Spring o en un fichero aparte. El siguiente ejemplo, además de los parámetros de configuración básica, se cambia el valor por defecto de la propiedad signencoding (las variables asf.clientjsurl, asf.cipherkey y app.id.asf son tomadas por maven del fichero environment.properties): applicationcontext-services.xml <!-- Dependencia de servicio de ASF --> <bean id="asfconfiguration" class="atlas.core.seguridad.asf.domain.asfconfiguration"> <property name="applicationidforalloperations" value="${app.id.asf}" /> <property name="clientjsurl" value="${asf.clientjsurl}" /> <property name="cipherkey" value="${asf.cipherkey}" /> <property name="signencoding" value="utf-8" /> </bean> En este ejemplo, la propiedad applicationidforalloperations realiza un set del valor en las propiedades invokingapp, signapplicationid y verifysignatureapplicationid. Esto es así para simplificar la configuración. Los valores de las propiedades clientjsurl y cipherkey hacen referencia a las propiedades asf.clientjsurl y asf.cipherkey del fichero environment.properties (reemplazadas por sus valores en la ejecución de maven). Si cualquier otra variable de configuración es susceptible de cambio con el entorno, deben definirse de esta forma. En el siguiente ejemplo se utiliza un fichero de propiedades como base de configuración: applicationcontext-services.xml <!-- Dependencia de servicio de ASF --> <bean id="cryptconfiguration" class="atlas.core.seguridad.asf.domain.asfconfiguration" /> <bean class="org.springframework.beans.factory.config.propertyoverrideconfigurer"> <property name="location" value="classpath:/conf/asf.properties" /> </bean> src/main/resources/conf/asf.properties 10 de 46

11 ########################################################## # Variables de configuración de la aplicación para ASF # ########################################################## # Configuracion general de ASF asfconfiguration.invokingapp = ${app.id.asf} asfconfiguration.signencoding = iso # Configuración de la firma asfconfiguration.signapplicationid = ${app.id.asf} asfconfiguration.signregisterrevocation = false asfconfiguration.signignoreverificationcaches = false asfconfiguration.signsequential = true asfconfiguration.signtimestamp = false # Configuración de la validación asfconfiguration.verifysignatureapplicationid = ${app.id.asf} asfconfiguration.verifyregisternorepudiation = false asfconfiguration.verifysignaturecheckrevocation = false asfconfiguration.verifyignoreverificationcaches = true asfconfiguration.verifyaddsignature = false # Configuración de la validación de certificados asfconfiguration.verifycheckcertificaterevocation = true asfconfiguration.verifycheckcertificatevalidity = true # Configuración para la firma en cliente asfconfiguration.clientjsurl = ${asf.clientjsurl} # Configuración para cifrado/descifrado sin certificado asfconfiguration.cipherkey = ${asf.cipherkey} asfconfiguration.ciphermode = CBC asfconfiguration.cipheralgorithm = 3DES asfconfiguration.cipheroperationtypeen = 3 asfconfiguration.cipheroperationtypede = 4 asfconfiguration.cipherpadding = PKCS5Padding A continuación se muestra una tabla con todos los atributos configurables de la clase AsfConfiguration: Atributo Descipción Obligatorio Valor por defecto invokingapp Id de la aplicación en ASF. La aplicación debe SI Sin valor por estar dada de alta en ASF defecto verifysignatureapplicationid Id de la aplicación en ASF usado en operaciones de SI Valor de verificación de firmas. invokingapp signapplicationid Id de la aplicación en ASF para operaciones de SI Valor de firma. invokingapp signregisterrevocation Registrar (o no) las revocaciones. NO false 11 de 46

12 signignoreverificationcaches Ignorar (o no) la caché de verificaciones en firma. NO false signencoding Codificación de caracteres en firma NO iso signsequential Firma secuencial NO true signtimestamp Incluír (o no) sellos de tiempo en la firmas. NO false verifyregisternorepudiation Almacenar (o no) la información necesaria para NO false garantizar el no repudio. verifysignaturecheckrevocati Comprobar (o no) el estado de revocación del NO false on cerificado firmante. verifyaddsignature verifyaddsignature NO false verifyignoreverificationcache s Ignorar (o no) la caché de verificaciones. NO true verifycheckcertificaterevocat Verificar (o no) el estado de revocación del NO true ion cerificado al validar los certificados. verifycheckcertificatevalidity Verificar (o no) el estado de validez (caducidad) del NO true cerificado al comprobar el cetificado. cipheralgorithm Algoritmo de cifrado simétrico con clave NO 3DES cipherkey Clave de cifrado simétrico SI Sin valor por defecto ciphermode Modo de cifrado simétrico NO CBC cipherpadding Padding de cifrado NO PKCS5Padding clientjsurl URL del Javascript de firma en cliente SI Sin valor por defecto ficherolog Ruta y nombre de los ficheros de log de ASF NO Sin valor por defecto nivellog Nivel de trazas de ASF, puede ser 10, 20 o hace que se muestren todas las trazas NO Sin valor por defecto securecall Si vale true las llamadas al servidor de ASF se NO false realizarán de forma segura 12 de 46

13 keystoretype Tipo de almacén de claves para comunicación NO Sin valor por segura defecto keystorefile Ruta al almacén de claves para comunicación NO Sin valor por segura defecto keystorepass Clave de acceso al almacén de claves para NO Sin valor por comunicación segura defecto keystorekeyalias Alias de la clave a utilizar para comunicación segura NO Sin valor por defecto searchinapplication Si el servicio de ASF no puede localizar en el NO true sistema los ficheros de propiedades, este parámetro indica si deben buscarse en el classpath de aplicación y en sus librerías Configuración del plugin de Jetty para trabajar como servidor seguro Atención Este paso no es necesario si el proyecto se ha generado a partir del arquetipo web, servicioweb o documentumweb de Atlas. Para poder probar la aplicación con un servidor seguro, es necesario configurar el plugin de Jetty para maven. Serán necesarios los siguientes elementos: Almacén de certificados con las CAs cuyos certificados se admitirán. Para la fase de pruebas bastará con la CA de desarrollo de ICM. El almacén debe terminar en.keystore. Este fichero se llamará truststore.keystore. Almacen de certificados con el certificado de servidor y toda su cadena de certificación. Para la fase de pruebas se podrá utilizar uno de los certificados de la CA de pruebas de ICM disponible. El almacen deberá terminar en.keystore. El fichero se llamará keystore.keystore. Ambos almacenes de certificados se almacenarán en la ruta /src/test/resources/ssl del proyecto web. 13 de 46

14 A continuación se reconfigurará el plugin de Jetty para la ejecución SSL: WantClientAuth: si es true se pedirá certificado en la conexión SSL, aunque será opcional. De esta forma si no se aporta certificado, se mostrará el login tradicional. NeedClientAuth: si es true el certificado de cliente en la conexión será necesario y no se pasará del punto inicial sin aportar uno. Pom.xml del proyecto web 14 de 46

15 <!-- Redefinicion de plugin de Jetty para añadir un conector https --> <plugin> <groupid>org.mortbay.jetty</groupid> <artifactid>jetty-maven-plugin</artifactid> <version>${jetty-maven-plugin.version}</version> <configuration> [...] <connectors> <connector implementation="org.eclipse.jetty.server.nio.selectchannelconnector"> <port>9080</port> <maxidletime>60000</maxidletime> </connector> <connector implementation="org.eclipse.jetty.server.ssl.sslsocketconnector"> <port>9443</port> <maxidletime>60000</maxidletime> <keystore>${project.build.testoutputdirectory}/ssl/keystore.keystore</keystore> <password>desarrollo</password> <keypassword>desarrollo</keypassword> <truststore>${project.build.testoutputdirectory}/ssl/truststore.keystore</truststore> <trustpassword>desarrollo</trustpassword> <wantclientauth>true</wantclientauth> <!-- certificado opcional --> <needclientauth>false</needclientauth> <!-- certificado obligatorio --> </connector> </connectors> </configuration> <dependencies> <dependency> <groupid>commons-dbcp</groupid> <artifactid>commons-dbcp</artifactid> <version>${padre.commons.dbcp.version}</version> </dependency> <dependency> <groupid>com.oracle</groupid> <artifactid>ojdbc14</artifactid> <version>${padre.oracle.version}</version> </dependency> </dependencies> </plugin> Configuración de Weblogic para trabajar como servidor seguro Para poder probar la aplicación con un servidor seguro, es necesario configurar el servidor Weblogic. No se podrán hacer pruebas de la aplicación directamente con un servidor jetty. Los pasos a seguir para configurar el servidor como seguro, utilizando los certificados de prueba de icm, son: Paso 1: Activar el SSL en Weblogic: Acceder a la consola de Weblogic, que normalmente está en la URL En la consola, en Entorno->Servidores, pinchar en el servidor AdminServer para acceder a su configuración: 15 de 46

16 En la pestaña Configuración-> General, activar la casilla Puerto de recepción de SSL activado : 16 de 46

17 Salvar los cambios y en la pestaña Configuracion->SSL->Advanzadas establecer el parámetro Comportamiento de Certificado de Cliente Bidireccional a Certificados de Cliente Solicitados Pero No Aplicados. Salvar los cambios. Paso 2: Configurar los almacenes de certificados en Weblogic: Los certificados SSL para weblogic pueden descargarse del sitio web de ArquitecturaSW. También pueden obtenerse de un arquetipo web en la ruta src/test/resources/ssl. El contenido del paquete son dos ficheros: keystore.jks y truststore.jks. Estos almacenes ya están preconfigurados para el uso en un servidor de aplicaciones. Deben dejarse estos ficheros en una ruta conocida del disco duro para su posterior referencia. En adelante, se asumirá que están en la ruta: D:\Oracle\Middleware\ssl. En la consola de Weblogic, en Entorno->Servidores seleccionar el servidor AdminServer: 17 de 46

18 En la pestaña Configuración -> Almacenes de Claves, en el parámetro Almacenes de Claves pulsar el botón Cambiar: 18 de 46

19 Seleccionar Identidad Personalizada y Protección Personalizada y guardar cambios. 19 de 46

20 Configurar los siguientes parámetros: Identidad: o Almacén de Claves de Identidad Personalizado: ruta a keystore.jks (D:\Oracle\Middleware\ssl\keystore.jks). o Tipo de Almacén de Claves de Identidad Personalizado: jks o Contraseña de Almacén de Claves de Identidad Personalizado: desarrollo o Confirmar Contraseña de Almacén de Claves de Identidad Personalizado: desarrollo Protección: o Almacén de Claves de Protección Personalizado: ruta a truststore.jks (D:\Oracle\Middleware\ssl\truststore.jks). o Tipo de Almacén de Claves de Protección Personalizado: jks o Contraseña de Almacén de Claves de Protección Personalizado: desarrollo o Confirmar Contraseña de Almacén de Claves de Protección Personalizado: desarrollo Guardar cambios. El servidor está ahora listo para su uso. Paso 3: Crear variable de entorno para weblogic. o Establecer la variable JAVA_OPTIONS=-Dweblogic.security.SSL.allowSmallRSAExponent=true 20 de 46

21 Paso 4: Importar el certificado cliente en el navegador. Una vez realizados estos pasos, ya estamos listos para probar aplicaciones con SSL instaladas en el servidor Weblogic. El puerto por defecto SSL de Weblogic es el Los certificados de pruebas de la CA de Icm pueden descargarse en la ruta: 21 de 46

22 4. USO Una vez configurado el entorno para el uso del componente, puede procederse a su utilización Obtención de datos de un certificado digital Para obtener los datos de un certificado digital, se utiliza el método getdatoscertificado, que recibe el certificado X509 en base64 o en una instancia X509Certificate cuyos datos se quieren obtener. El método devuelve un objeto atlas.core.seguridad.asf.domain.datoscertificado. En el siguiente ejemplo, se muestra un método de un ManagedBean de JSF que recoge los datos de un certificado para pintarlos en pantalla. AsfBean.java * Obtiene los datos de un certificado para pintar su contenido id de página public String obtenerdatoscertificado() { try { this.datoscertificado = this.cryptservice.getdatoscertificado(strcertificado); } catch (ServiceException e) { log.error("error obteniendo datos de certificado.", e); AtlasFacesUtils.addErrorMessage(e.getMessage()); } } return NavigationResults.SUCCESS; * Obtención de los datos de certificado de login de usuario DatosCertificado con los datos del certificado de login ServiceException si hubo algún problema private DatosCertificado getdatoscertificadologin() throws ServiceException { // Obtenemos el certificado de login del request X509Certificate[] chain = (X509Certificate[]) FacesContext. getcurrentinstance().getexternalcontext().getrequestmap(). get("javax.servlet.request.x509certificate"); if (chain == null chain.length == 0) { log.warn("no se ha detectado certificado de autenticacion"); return null; } } // Llamar al servicio de ASF para obtener los datos del certificado return this.cryptservice.getdatoscertificado(chain[0]); 22 de 46

23 4.2. Comprobación de acceso de un certificado En aplicaciones donde el acceso de los usuarios se realice mediante certificado, es posible restringir los tipos de certificado a un subconjunto de los admitidos por ICM. En ASF se realiza la configuración de certificados admitidos en una operación y posteriormente, en la aplicación se consulta si el certificado aportado por el usuario está dentro de este conjunto. CryptService.java * Obtiene información de acceso del certificado pasado, sobre la operación de * verificacion en ASF datoscert objeto con la información del certificado a comprobar true si el certificado tiene acceso; false en caso contrario ServiceException si hubo problemas en la comprobacion boolean comprobaracceso(datoscertificado datoscert) throws ServiceException; * Obtiene información de acceso del certificado pasado, sobre la operación de * verificacion en ASF cert objeto con la información del certificado a comprobar true si el certificado tiene acceso; false en caso contrario ServiceException si hubo problemas en la comprobacion boolean comprobaracceso(x509certificate cert) throws ServiceException; Atención Estos métodos solo podrán utilizarse en la creación de políticas de seguridad propias de la aplicación según la normativa de ATLAS. A continuación se muestra un ejemplo de uso de esta funcionalidad: Ejemplo de uso DatosCertificado datoscert = this.cryptservice.getdatoscertificadodealias("2w"); boolean ok = this.cryptservice.comprobaracceso(datoscert); log.info("el certificado '2w' tiene acceso a la aplicación: " + ok); 23 de 46

24 4.3. Cifrado y descifrado de datos con clave Para el cifrado de datos con clave se utiliza el método cifrar. Su correspondiente método de descifrado es descifrar. A continuación se muestra un extracto de la interfaz de servicio: CryptService.java * Cifrar texto con clave simétrica texto texto a cifrar mensaje cifrado ServiceException si hubo algún problema String cifrar(string texto) throws ServiceException; * Descifrar texto con clave simétrica texto texto a descifrar texto descifrado ServiceException si hubo algún problema String descifrar(string texto) throws ServiceException; La clave de cifrado a usar se establece en el objeto de configuración del servicio cryptconfiguration, parámetro cypherkey. El siguiente ejemplo de uso muestra una operación de cifrado y descifrado obteniendo así el texto original. Ejemplo de uso String texto = "Ejemplo de cifrado/descifrado"; log.info("texto original: '" + texto + "'"); // Cifrar texto con clave String cifrado = null; try { cifrado = this.cryptservice.cifrar(texto); } catch (ServiceException e) { log.error("error cifrando datos.", e); } log.info("texto cifrado: '" + cifrado + "'"); // Descifrar texto con clave String descifrado = null; try { descifrado = this.cryptservice.descifrar(cifrado); } catch (ServiceException e) { log.error("error descifrando datos.", e); } log.info("texto descifrado: '" + descifrado + "'"); 24 de 46

25 4.4. Cifrado y descifrado de datos con certificado Para el cifrado de datos con clave se utiliza también el método cifrar, aunque los parámetros a pasar son diferentes de los del apartado anterior. Su correspondiente método de descifrado es descifrar. A continuación se muestra un extracto de la interfaz de servicio: CryptService.java * Cifrar texto con certificado texto texto a cifrar aliascertificado alias del certificado de firma en plataforma ASF texto cifrado ServiceException si ha habido problemas en el firmado String cifrar(string texto, String aliascertificado) throws ServiceException; * Descifrar texto con certificado texto texto a descifrar aliascertificado alias del certificado de firma en plataforma ASF texto descifrado ServiceException si ha habido problemas en el descifrado String descifrar(string texto, String aliascertificado) throws ServiceException; El certificado cuyo alias se pasa en los métodos de cifrado y descifrado deberá estar dado de alta en la plataforma ASF para el id de aplicación configurado. El siguiente ejemplo de uso muestra una operación de cifrado y descifrado obteniendo así el texto original. Ejemplo de uso String texto = "Texto de ejemplo"; String aliascertificado = "2w"; // Certificado instalado en ASF log.info("texto original: '" + texto + "'"); // Cifrar texto con certificado String cifrado = null; try { cifrado = this.cryptservice.cifrar(texto, aliascertificado); } catch (ServiceException e) { log.error("error cifrando datos.", e); } log.info("texto cifrado: '" + cifrado + "'"); // Descifrar texto con certificado String descifrado = null; try { descifrado = this.cryptservice.descifrar(cifrado, aliascertificado); } catch (ServiceException e) { log.error("error descifrando datos.", e); } log.info("texto descifrado: '" + descifrado + "'"); 25 de 46

26 4.5. Firma electrónica en servidor La firma electrónica de unos datos permite garantizar su integridad (que no ha sido modificada desde que se firmó) y el no repudio (no se puede negar haber firmado los datos); opcionalmente también permite garantizar que los datos fueron firmados en un momento determinado. Para realizar una firma electrónica en servidor, ser utiliza el método firmar, que recibe dos parámetros: un array de bytes con los datos a firmar y una cadena con el alias del certificado con el que se quieren firmar (tiene que estar definido previamente en ASF para la aplicación). El método devuelve una cadena con la firma codificada en base 64. Este tipo de firma sirve para textos y datos binarios. CryptService.java * Realiza una firma digital de los datos pasados con el certificado identificado * por el alias datos datos para realizar la firma digital alias alias del certificado en la plataforma ASF firma digital ServiceException si hubo algún problema String firmar(byte[] datos, String alias) throws ServiceException; A continuación se muestra un ejemplo de uso de firmado con certificado: Ejemplo de uso String texto = "Texto de ejemplo"; String aliascertificado = "1r"; // Tiene que estar dado de alta en ASF log.info("texto original: '" + texto + "'"); // Firmado String firma = null; try { firma = this.cryptservice.firmar(texto.getbytes(), aliascertificado); } catch (ServiceException e) { log.error("error realizando firma.", e); } log.info("firma: '" + firma + "'"); 4.6. Firma de Pdf La firma PDF en servidor puede realizarse llamando al siguiente método del servicio: CryptService.java 26 de 46

27 * Realiza una firma digital para ficheros Pdf. alias alias del certificado de firma en la plataforma ASF inpdf documento PDF a firmar documento PDF firmado ServiceException si hubo algún problema byte[] firmarpdf(string alias, byte[] inpdf) throws ServiceException; Como parámetros han de pasarse el alias del certificado en la plataforma ASF y el contenido del fichero PDF a firmar. El resultado será el contenido del fichero PDF ya firmado. Para ejecutar esta operación debe haberse solicitado previamente el alta de la aplicación en ASF, así como de una operación de firma y un certificado asociado a esta operación (cuyo alias será el que habrá que pasar al método). A continuación se muestra un ejemplo de uso de este método: Ejemplo de uso // leer pdf de pruebas de disco File f = new File("pdfSignTest.pdf"); byte[] pdf =... Realizar lectura de fichero... // firmar pdf byte[] signed = this.cryptservice.firmarpdf("2w", pdf); // Grabar fichero firmado File fout = new File("pdf_signed.pdf"); out = new FileOutputStream(fout); out.write(signed); out.close(); Se pueden personalizar algunos aspectos de la firma del fichero PDF a través de la clase atlas.core.seguridad.asf. domain.pdfsignappearance. Los valores personalizables son: Coordenadas x,y de la caja de firma. Altura y anchura de la caja de firma. Página donde se ubicará la parte visible de la firma. Visibilidad de la caja de firma. A continuación se muestra un ejemplo donde la caja de firma se ubicará en la página 3 del documento pdf: CryptService.java 27 de 46

28 * Realiza una firma digital para ficheros Pdf. alias alias del certificado de firma en la plataforma ASF inpdf documento PDF a firmar usartsa usar sello de tiempo? apariencia información de la visualización de la firma documento PDF firmado ServiceException si hubo algún problema byte[] firmarpdf(string alias, byte[] inpdf, boolean usartsa, PdfSignAppearance apariencia) throws ServiceException; Este método permite también incluir un sello de tiempo (usartsa) en la firma Pdf. Ejemplo de uso // leer pdf de pruebas de disco File f = new File("pdfSignTest.pdf"); byte[] pdf =... Realizar lectura de fichero... // firmar pdf pagina 3 PdfSignAppearance apariencia = new PdfSignAppearance(); apariencia.setpage(3); signed = this.cryptservice.firmarpdf("2w", pdf, false, apariencia); // Grabar fichero firmado File fout = new File("pdf_signed.pdf"); out = new FileOutputStream(fout); out.write(signed); out.close(); Si el número de página es negativo, se contará desde el final del documento para posicionar la caja de firma en lugar de contar desde el principio. De esta forma, un valor de -1 establecerá la caja de firma en la última página del documento, -2 lo hará en la penúltima, etc Firma PAdES La firma PAdES en servidor puede realizarse llamando al siguiente método del servicio: CryptService.java * Realiza una firma digital para ficheros Pdf en formato PADES. alias alias del certificado de firma en la plataforma ASF inpdf documento PDF a firmar documento PDF firmado ServiceException si hubo algún problema byte[] firmarpades(string alias, byte[] inpdf) throws ServiceException; 28 de 46

29 Como parámetros han de pasarse el alias del certificado en la plataforma ASF y el contenido del fichero PDF a firmar. El resultado será el contenido del fichero PDF ya firmado. Para ejecutar esta operación debe haberse solicitado previamente el alta de la aplicación en ASF, así como de una operación de firma y un certificado asociado a esta operación (cuyo alias será el que habrá que pasar al método). A continuación se muestra un ejemplo de uso de este método: Ejemplo de uso // leer pdf de pruebas de disco File f = new File("pdfSignTest.pdf"); byte[] pdf =... Realizar lectura de fichero... // firmar pdf byte[] signed = this.cryptservice.firmarpades("2w", pdf); // Grabar fichero firmado File fout = new File("pdf_signed.pdf"); out = new FileOutputStream(fout); out.write(signed); out.close(); Se pueden personalizar algunos aspectos de la firma del fichero PDF a través de la clase atlas.core.seguridad.asf. domain.pdfsignappearance. Los valores personalizables son: Coordenadas x,y de la caja de firma. Altura y anchura de la caja de firma. Página donde se ubicará la parte visible de la firma. Visibilidad de la caja de firma. A continuación se muestra un ejemplo donde la caja de firma se ubicará en la página 3 del documento pdf: CryptService.java * Realiza una firma digital para ficheros Pdf en formato PADES. alias alias del certificado de firma en la plataforma ASF inpdf documento PDF a firmar usartsa usar sello de tiempo? apariencia información de la visualización de la firma documento PDF firmado ServiceException si hubo algún problema byte[] firmarpades(string alias, byte[] inpdf, boolean usartsa, PdfSignAppearance apariencia) throws ServiceException; 29 de 46

30 Este método permite también incluir un sello de tiempo (usartsa) en la firma Pdf. Ejemplo de uso // leer pdf de pruebas de disco File f = new File("pdfSignTest.pdf"); byte[] pdf =... Realizar lectura de fichero... // firmar pdf pagina 3 PdfSignAppearance apariencia = new PdfSignAppearance(); apariencia.setpage(3); signed = this.cryptservice.firmarpades("2w", pdf, false, apariencia); // Grabar fichero firmado File fout = new File("pdf_signed.pdf"); out = new FileOutputStream(fout); out.write(signed); out.close(); También puede comprobarse si un documento Pdf ya está firmado a través del método tienefirmapdf: Ejemplo de uso byte[] pdf =...; byte[] signed = this.cryptservice.firmarpdf("2w", pdf); boolean tienefirma = this.cryptservice.tienefirmapdf(signed); 4.8. Firma de ficheros XML La firma XML se realiza en formato XMLDsig. En el siguiente apartado se mostrará la firma XAdES (también para ficheros XML). En la firma XMLDsig básica se ejecuta una firma de tipo Enveloping en el documento xml completo. En este tipo de firma, el tag raíz del documento XML será el tag de firma, y el documento original quedará englobado dentro de la estructura de la firma. CryptService.java * Realiza una firma digital para ficheros XML en formato XMLDsig enveloping * (el tag de firma es la raiz del Xml original que queda embebido dentro). * La firma digital se realiza sobre todo el documento Xml de entrada * (se firma el tag raiz). alias alias del certificado en la plataforma ASF xml fichero XML a firmar xml firmado ServiceException si hubo algún problema String firmarxml(string alias, byte[] xml) throws ServiceException; 30 de 46

31 Solo será necesario indicar el alias del certificado en la plataforma ASF y el documento XML a firmar. Ejemplo de uso String xml = "<root><head></head><body id=\"idbody\">" + "<content>test de firmado XML</content></body></root>"; // Firma enveloping de todo el XML String envelopingfull = this.cryptservice.firmarxml("2w", xml.getbytes()); En el siguiente ejemplo, la firma seguirá siendo de tipo Enveloping, pero se indica el Id del tag a firmar. No se firmará el documento completo, solo el bloque del tag cuyo Id se ha indicado. CryptService.java * Realiza una firma digital para ficheros XML en formato XMLDsig enveloping * (el tag de firma es la raiz del Xml original que queda embebido dentro). * La firma digital se realiza sobre el tag cuyo ID se indica en el parámetro * idtosign. Es obligatorio que el tag a firmar tenga un atributo de nombre * 'id' y un valor que identifique univocamente al nodo dentro del documento Xml. alias alias del certificado en la plataforma ASF xml fichero XML a firmar idtosign id del tag a firmar. Ej.: "idbody" xml firmado ServiceException si hubo algún problema String firmarxml(string alias, byte[] xml, String idtosign) throws ServiceException; Ejemplo de uso String xml = "<root><head></head><body id=\"idbody\">" + "<content>test de firmado XML</content></body></root>"; // Firma enveloping de parte del XML String envelopingpart = this.cryptservice.firmarxml("2w", xml.getbytes(), "idbody"); En este ejemplo, en lugar de firmarse el tag <root> como en el caso anterior, solo se firmará el tag <body id= idbody >. En el siguiente ejemplo, la firma será de tipo Enveloped, es decir, la estructura del documento original no se alterará. El tag de firma se insertará como hijo del tag indicado. CryptService.java 31 de 46

32 * Realiza una firma digital para ficheros XML en formato XMLDsig. Si se indica * el parámetro insertsigntagname, la firma se realizará en formato * 'enveloped' (el tag de firma se inserta como hijo del nodo cuyo nombre * se ha especificado en el parámetro); en caso contrario, la firma será de * tipo enveloping. alias alias del certificado en la plataforma ASF xml fichero XML a firmar idtosign id del tag a firmar. Ej.: "idbody" insertsigntagname nombre del tag debajo del cual colocar la firma. * Ej.: "head" xml firmado ServiceException si hubo algún problema String firmarxml(string alias, byte[] xml, String idtosign, String insertsigntagname) throws ServiceException; Ejemplo de uso String xml = "<root><head></head><body id=\"idbody\">" + "<content>test de firmado XML</content></body></root>"; // Firma enveloped String enveloped = this.cryptservice.firmarxml("2w", xml.getbytes(), "idbody", "head"); En este ejemplo, el tag raíz del documento XML seguirá siendo <root>. Se firmará el tag <body id= idbody > y el elemento <ds:signature> de la firma se insertará como hijo del tag <head>. También puede comprobarse si un documento Xml ya está firmado a través del método tienefirmaxml: Ejemplo de uso String xml = "...; log.info("ejecutando firma..."); String xmlfirmado = this.cryptservice.firmarxadesbes("2w", xml.getbytes()); boolean tienefirma = this.cryptservice.tienefirmaxml(xml.getbytes()); 32 de 46

33 4.9. Firma XAdES La firma XAdES es otro formato de firma XML. Es una extensión de la firma XMLDsig y presenta una estructura de tipo Enveloped. Existen tres tipo de firma XAdES soportada por ATLAS: XAdES BES: firma de tipo básico, la más simple de todas. XAdES T: firma básica con sello de tiempo. XAdES XL: añade los propios certificados y listas de revocación a los documentos firmados para permitir la verificación en el futuro incluso si las fuentes originales (de consulta de certificados o de las listas de revocación) no estuvieran ya disponibles. Los servicios disponibles para esta firma son los siguientes: CryptService.java * Realiza una firma digital para ficheros XML en formato XAdES (Basico). La firma * digital se realiza sobre todo el documento Xml de entrada (se firma el tag raiz). alias alias del certificado en la plataforma ASF xml fichero XML a firmar xml firmado ServiceException si hubo algún problema String firmarxadesbes(string alias, byte[] xml) throws ServiceException; CryptService.java * Realiza una firma digital para ficheros XML en formato XAdES-T * (Basico + timestamp). La firma digital se realiza sobre todo el documento Xml) * de entrada (se firma el tag raíz. alias alias del certificado en la plataforma ASF xml fichero XML a firmar xml firmado ServiceException si hubo algún problema String firmarxadest(string alias, byte[] xml) throws ServiceException; CryptService.java 33 de 46

34 * Realiza una firma digital para ficheros XML en formato XAdES-XL * (Basico + extended long-term). La * firma digital se realiza sobre todo el documento Xml de entrada (se firma el tag * raiz). alias alias del certificado en la plataforma ASF xml fichero XML a firmar xml firmado ServiceException si hubo algún problema String firmarxadesxl(string alias, byte[] xml) throws ServiceException; A continuación un ejemplo de uso: Ejemplo de uso String xml = "<root><head></head><body id=\"idbody\">" + "<content>test de firmado XML</content></body></root>"; log.info("ejecutando firma..."); String xmlfirmado = this.cryptservice.firmarxadesbes("2w", xml.getbytes()); Validación de firmas electrónicas La validación de la firma electrónica de unos datos permite comprobar su integridad (que no ha sido modificada desde que se firmó) y el no repudio (no se puede negar haber firmado los datos); opcionalmente también permite garantizar que los datos fueron firmados en un momento determinado. Para validar una firma electrónica, ser utiliza el método validar, que recibe dos parámetros: un array de bytes con los datos originales y una cadena con la firma codificada en base 64. El método devuelve una enumeración de tipo SignatureStatus. CryptService.java * Realiza una validación de la firma digital pasada respecto al texto signeddata datos de firma digital firma texto original con el que se ha realizado la firma SignatureEstatus con el estado de la firma ServiceException si hubo algún problema SignatureStatus validarfirma(byte[] signeddata, String firma) throws ServiceException; 34 de 46

35 Ejemplo de uso // Validación de firma String texto = "Texto de ejemplo"; String firma = "[...]"; // firma del texto en formato Base64 try { // La firma será correcta, el resultado será SignatureStatus.OK SignatureStatus estado = this.cryptservice.validarfirma(texto.getbytes(), firma); log.info("estado para texto: " + estado); // El texto firmado ha sido modificado (touppercase()), el resultado será // SignatureStatus.NOT_VALID estado = this.cryptservice.validarfirma(texto.touppercase().getbytes(), firma); log.info("estado para texto modificado: " + estado); } catch (ServiceException e) { log.error("error verificando firma.", e); } Verificación de un certificado digital La verificación de un certificado digital permite comprobar que es válido (que no está caducado, que no ha sido revocado, que se confía en su emisor, que no ha sido modificado desde su emisión ). Para verificar un certificado electrónico, ser utiliza el método getestadocertificado. Este método acepta instancias de X509Certificate y representaciones en base64 de un certificado (formato PEM). El resultado de este método es un objeto de tipo CertificateStatus. Test de ejemplo de comprobación de estado de certificado 35 de 46

36 String aliasrevocado = "4g"; String aliascorrecto = "2w"; String pemcertificate = // certificado '2w' "-----BEGIN CERTIFICATE-----\n" + "MIID1jCCAz+gAwIBAgIBcDANBgkqhkiG9w0BAQUFADCBnzELMAkGA1UEBhMCRVMx\n" + "[...]" + "e2tbpsz7/w7hxnfdci0epxdeqtsys6movfy=\n" + "-----END CERTIFICATE-----\n"; try { CertificateStatus status = this.cryptservice.getestadocertificado( getcertificate(aliasrevocado)); assertequals(status, CertificateStatus.REVOKED); status = this.cryptservice.getestadocertificado(getcertificate(aliascorrecto)); assertequals(status, CertificateStatus.OK); // Certificado en formato PEM status = this.cryptservice.getestadocertificado(pemcertificate); assertequals(status, CertificateStatus.OK); } catch (ServiceException e) { fail("error de certificado: " + e.getmessage()); } Aunque con getestadocertificado se puede comprobar si el certificado ha sido revocado, se ha creado un método específico para hacer esta comprobación. El método es comprobarrevocacion que devuelve un booleano indicando si el certificado está revocado (true) o no (false). Este método, también admite el certificado a comprobar en base64 o en X509Certificate Verificación de firma Pdf Para realizar una verificación de un documento pdf firmado, se usará el siguiente método: CryptService.java * Realiza una validación de la firma digital de un documento PDF inpdf datos del pdf firmado a validar SignatureEstatus con el estado de la firma ServiceException si hubo algún problema SignatureStatus validarfirmapdf(byte[] inpdf) throws ServiceException; Ejemplo de uso 36 de 46

37 // leer pdf de pruebas de disco File f = new File("pdfSignTest.pdf"); byte[] pdf =... Realizar lectura de fichero... // firmar pdf pagina 3 PdfSignAppearance apariencia = new PdfSignAppearance(); apariencia.setpage(3); signed = this.cryptservice.firmarpdf("2w", pdf, false, apariencia); // Validar firma de PDF SignatureStatus status = this.cryptservice.validarfirmapdf(signed); log.info("resultado de la verificacion: " + status); Verificación de firma PAdES Para realizar una verificación de un documento pdf firmado en formato PAdES, se usará el siguiente método: CryptService.java * Realiza una validación de la firma digital PADES de un documento PDF inpdf datos del pdf firmado a validar SignatureEstatus con el estado de la firma ServiceException si hubo algún problema SignatureStatus validarfirmapades(byte[] inpdf) throws ServiceException; Ejemplo de uso // leer pdf de pruebas de disco File f = new File("pdfSignTest.pdf"); byte[] pdf =... Realizar lectura de fichero... // firmar pdf pagina 3 PdfSignAppearance apariencia = new PdfSignAppearance(); apariencia.setpage(3); signed = this.cryptservice.firmarpades("2w", pdf, false, apariencia); // Validar firma de PDF SignatureStatus status = this.cryptservice.validarfirmapades(signed); log.info("resultado de la verificacion: " + status); Validación de firma XMLDsig Para realizar la validación de un documento XML firmado, se usará el siguiente método: CryptService.java 37 de 46

38 * Realiza una validación de la firma digital del documento XML pasado signedxml datos del xml firmado SignatureEstatus con el estado de la firma ServiceException si hubo algún problema SignatureStatus validarfirmaxml(byte[] signedxml) throws ServiceException; Ejemplo de uso String xml = "<root><head></head><body id=\"idbody\">" + "<content>test de firmado XML</content></body></root>"; // Firma enveloped String enveloped = this.cryptservice.firmarxml("2w", xml.getbytes(), "idbody", "head"); // Validar firma SignatureStatus status = this.cryptservice.validarfirmaxml(enveloped.getbytes()); log.info("firma OK: " + (SignatureStatus.OK.getId() == status.getid())); El método validarfirmaxml es útil cuando solo se quiere comprobar la validez de la firma. Si además se quieren recuperar los datos de la firma, el método a utilizar es getdatosfirmaxml. CryptService.java * Realiza una validación de la firma y devuelve el resultado junto con * información de la firma. signedxml datos del xml firmado DatosFirma con información de la firma y del firmante ServiceException si hubo algun problema DatosFirma getdatosfirmaxml(byte[] signedxml) throws ServiceException; Ejemplo de uso String xml = "<root><head></head><body id=\"idbody\">" + "<content>test de firmado XML</content></body></root>"; // Firma enveloped String enveloped = this.cryptservice.firmarxml("2w", xml.getbytes(), "idbody", "head"); // Validar firma DatosFirma datosfirma = this.cryptservice.getdatosfirmaxml(enveloped.getbytes()); SignatureStatus status = datosfirma.getestadofirma(); DatosCertificado datoscert = datosfirma.getfirmante(); log.info("firma OK: " + status); log.info("firmante: " + datoscert); 38 de 46

39 4.15. Validación de firma XAdES Para realizar la validación de un documento XML firmado con firma XAdES, se usará el siguiente método: CryptService.java * Realiza una validación de la firma digital XAdES del documento XML pasado signedxml datos del xml firmado SignatureEstatus con el estado de la firma ServiceException si hubo algún problema SignatureStatus validarfirmaxades(byte[] signedxml) throws ServiceException; Ejemplo de uso String xml = "<root><head></head><body id=\"idbody\">" + "<content>test de firmado XML</content></body></root>"; log.info("ejecutando firma..."); String xmlfirmado = this.cryptservice.firmarxadesbes("2w", xml.getbytes()); // Validar firma log.info("ejecutando validacion..."); SignatureStatus status = this.cryptservice.validarfirmaxades(xmlfirmado.getbytes()); log.info("resultado de la validacion: " + status); El método validarfirmaxades es útil cuando solo se quiere comprobar la validez de la firma. Si además se quieren recuperar los datos de la firma, el método a utilizar es getdatosfirmaxades. CryptService.java * Realiza una validación de la firma y devuelve el resultado junto con * información de la firma. signedxml datos del xml firmado DatosFirma con información de la firma y del firmante ServiceException si hubo algun problema DatosFirma getdatosfirmaxades(byte[] signedxml) throws ServiceException; Ejemplo de uso 39 de 46