ALTAS MANUAL DE USUARIO DEL SERVICIO DE CERTIFICADOS Versión 1.0 Área de Integración y Arquitectura de Aplicaciones
Hoja de Control Título Documento de Referencia Responsable Manual de Usuario del NORMATIVA ATLAS Área de Integración y Arquitectura de Aplicaciones Versión 1.0 Fecha Versión 27/05/2010 Registro de Cambios Versión Causa del Cambio Responsable del Cambio Fecha del Cambio Área de Integración y Arquitectura de 1.0 Versión inicial del documento Aplicaciones 27/01/2010 2 de 22
Índice 1. INTRODUCCIÓN... 4 1.1. AUDIENCIA OBJETIVO... 4 1.2. CONOCIMIENTOS PREVIOS... 4 2. DESCRIPCIÓN... 5 3. INSTALACIÓN Y CONFIGURACIÓN... 6 3.1. INSTALACIÓN... 6 3.1.1. Paso 1: Añadir la dependencia al módulo de Seguridad... 6 3.1.2. Paso 2: Definir una instancia del Servicio en el contexto de Spring... 6 3.1.3. Paso : Inyectar el Servicio en las clases que lo requieran... 7 3.2. CONFIGURACIÓN... 8 3.2.1. Atributos del Servicio... 8 3.2.2. Configuración de Weblogic para trabajar como servidor seguro... 10 SALVAR LOS CAMBIOS... 12 4. USO... 16 4.1. CIFRADO Y DESCIFRADO DE DATOS...16 4.2. FIRMA ELECTRÓNICA EN SERVIDOR... 18 4.3. VALIDACIÓN DE FIRMAS ELECTRÓNICAS... 19 4.4. VERIFICACIÓN DE UN CERTIFICADO DIGITAL... 20 4.5. OBTENCIÓN DE DATOS DE UN CERTIFICADO DIGITAL... 21 5. ENLACES RELACIONADOS... 22 3 de 22
Contenido 1. INTRODUCCIÓN Este documento contiene el manual de uso del servicio de certificados 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. 1.1. 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 usar el servicio AsfSistemasService del módulo de seguridad. 1.2. 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. 4 de 22
2. DESCRIPCIÓN El servicio de Spring AsfService que incluye el módulo de seguridad de Atlas, provee las siguientes funcionalidades: Cifrado y descifrado de datos Firma electrónica en servidor Verificación de firmas electrónicas Validación de certificados digitales Obtención de datos de un certificado 5 de 22
3. INSTALACIÓN Y CONFIGURACIÓN 3.1. INSTALACIÓN El para ASF 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 definir una instancia del servicio en el contexto de Spring e inyectarla en las clases que vayan a usarlo. 3.1.1. Paso 1: Añadir la dependencia al módulo de Seguridad 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: <dependencies> pom.xml <dependency> <groupid>atlasfrm</groupid> <artifactid>atlasfrm-seguridad-lib</artifactid> <version>${atlasfrm-seguridad-lib}</version> </dependency> </dependencies> NOTA: Este paso no es necesario si el proyecto se ha generado a partir del arquetipo web de Atlas. 3.1.2. Paso 2: Definir una instancia del Servicio en el contexto de Spring Para definir una instancia, hay que añadir el bean del servicio en el contexto de aplicación de Spring (generalmente application-context.xml ; si se ha partido de un arquetipo web, el fichero será applicationcontextservices.xml ). El tipo de la interfaz del Servicio es atlas.core.seguridad.service.asfservice y la clase que lo implementa es atlas.core.seguridad.asf.service.impl.asfserviceimpl. Las propiedades de éste bean se pueden ver en el apartado Configuración del presente manual. applicationcontext-services.xml <bean id="service" class="atlas.core.seguridad.asf.service.impl.asfserviceimpl" p:invokingapp="apl_demo"/> 6 de 22
3.1.3. Paso : 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 setter correspondiente. Para más información sobre cómo inyectar referencias, se puede consultar la documentación de Spring. applicationcontext-services.xml <bean id="service" class="atlas.core.seguridad.asf.service.impl.asfserviceimpl" p:invokingapp="apl_demo"/> <bean id="mibean" class="xxxx.miclase" p:servicioasf-ref="service "/> 7 de 22
3.2. CONFIGURACIÓN La configuración del Servicio se realiza mediante los atributos ( properties ) que se inyectan a la instancia del mismo. 3.2.1. Atributos del Servicio A continuación se muestra una tabla con todos los atributos configurables del servicio: Atributo invokingapp verifysignatureapplicationid signapplicationid cipheroperationid decipheroperationid signeddataformat ciphereddataformat cipheralgorithm Descipción Id de la aplicación en ASF. Obligatorio. NOTA: La aplicación debe estar dada de alta en ASF Id de la aplicación en ASF usado en operaciones de verificación de firmas. Opcional, por defecto el valor asignado a "invokingapp". NOTA: La aplicación debe estar dada de alta en ASF Id de la aplicación en ASF para operaciones de firma. Opcional, por defecto el valor asignado a "invokingapp". NOTA: La aplicación debe estar dada de alta en ASF Id de la operación de cifrado. Opcional, por defecto, "CIFRADO". NOTA: La operación tiene que existir para la aplicación en ASF Id de la operación de descifrado. Opcional, por defecto, "DESCIFRADO". NOTA: La operación tiene que existir para la aplicación en ASF Formato de la firma, según se especifican en Constants. Opcional, por defecto PKCS7_FORMAT (ver com.tbsolutions.asf.util.constants ). Formato de los datos cifrados, según se especifican en Constants. Opcional, por defecto PKCS7_FORMAT (ver com.tbsolutions.asf.util.constants ). Algoritmo de cifrado, según se especifican en Constants. Opcional, por defecto TRIPLE_DES_SYMMETRIC_ALGORITHM (ver com.tbsolutions.asf.util.constants ). 8 de 22
keycipheralgorithm signaturecheckrevocation registronorepudio ignoreverificationcaches verifyrevocation verifyvalidity verifysignatureoperationid digestalgorithm verifysigningcerts signaturealgorithm includetimestamp signoperationid Algoritmo de cifrado de la clave, según se especifican en Constants. Opcional, por defecto RSA_ASYMMETRIC_ALGORITHM (ver com.tbsolutions.asf.util.constants ). Comprobar (o no) el estado de revocación del cerificado firmante. Opcional, por defecto, false. Almacenar (o no) la información necesaria para garantizar el no repudio. Opcional, por defecto, false. Ignorar (o no) la caché de verificaciones. Opcional, por defecto, false. Verificar (o no) el estado de revocación del cerificado al validar los certificados. Opcional, por defecto, true. Verificar (o no) el estado de validez (caducidad) del cerificado al comprobar el cetificado. Opcional, por defecto, true. Identificador de la operación de firma para la aplicación. Opcional, por defecto, "VERIFICACION". NOTA: La operación tiene que existir para la aplicación en ASF Algoritmo de hash, según se especifican en Constants. Opcional, por defecto, SHA_DIGEST_ALGORITHM (ver com.tbsolutions.asf.util.constants ). Verificación de los certificados al validar las firmas. Opcional, por defecto, SIGNING_CERT_NO_VERIFY (ver com.tbsolutions.asf.signatureserver.util.constants ). Algoritmo de firma, según se especifican en Constants. Opcional, por defecto, RSA_ASYMMETRIC_ALGORITHM (ver com.tbsolutions.asf.util.constants ). Incluír (o no) sellos de tiempo en la firmas. Opcional, por defecto, false. Identificador de la operación de firma para la aplicación en ASF. Opcional, por defecto, "FIRMA_SIMPLE". NOTA: La operación tiene que existir para la aplicación en ASF 9 de 22
registerrevocation Registrar (o no) las revocaciones. Opcional, por defecto, false. 3.2.2. 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: En la consola de Weblogic, en Environment->Server Elegir un Server: En la pestaña Configuración-> General, activar la casilla SSL Listen Port Enabled : 10 de 22
Salvar los cambios y en la pestaña Configuration->SSL->Advanced cambiar el valor de Two way Client Cert Behavior 11 de 22
Salvar los cambios. Paso 2: Importar el certificado raiz de ICM como certificado de confianza: En la consola de Weblogic, en Environment->Server Elegir un Server: 12 de 22
En la pestaña Configuration->Keystores anotar la ruta Demo Trust Keysore : 13 de 22
Conectarse al servidor e importar el certificado raiz de ICM (icm.cer) en el keystore de confianza. Esto se hace utilizando la herramienta Keytool. A continuación se muestra un ejemplo de importación: 14 de 22
Ejemplo de uso de KeyTool D:\Producto\bea\WEBLOG~1\server\lib>keytool -importcert -file c:\borrar\icm.cer - keypass CERT -keystore DemoTrust.jks -storepass DemoTrustKeyStorePassPhrase Propietario: EMAILADDRESS=fhumanes@comadrid.es, CN=CA Pruebas ICM Desarrollo, OU=ICM Desarrollo, O=ICM, L=Madrid, ST=Madrid, C=ES Emisor: EMAILADDRESS=fhumanes@comadrid.es, CN=CA Pruebas ICM Desarrollo, OU=ICM Desarrollo, O=ICM, L=Madrid, ST=Madrid, C=ES Número de serie: 0 Válido desde: Mon Dec 03 20:39:11 CET 2001 hasta: Thu Dec 01 20:39:11 CET 2011 Huellas digitales del certificado: MD5: A9:EF:03:2B:D9:5B:36:07:01:EB:05:A6:EE:9F:FE:35 SHA1: E1:E1:D9:5B:65:BE:7D:4A:D7:BA:54:1D:6D:C0:40:91:12:36:77:1A Confiar en este certificado? [no]: si Se ha añadido el certificado al almacén de claves Después de este paso, reiniciar el servidor Weblogic. Paso 3: 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 7002. 15 de 22
4. USO Una vez configurado el entorno para el uso del componente, puede procederse a su utilización. 4.1. Cifrado y descifrado de datos Para el cifrado de datos se usa el método cifrar del Servicio. Éste método recibe un array de bytes con los datos a cifrar y el alias del certificado con el que se quiere cifrar (tiene que estar definido previamente en ASF para la aplicación). El método devuelve una cadena (String) con los datos cifrados y codificados en base 64. Si se quiere cifrar un texto, es buena práctica especificar una codificación concreta a la hora de obtener el array de bytes, como se puede ver en el siguiente ejemplo: ClaseEjemplo.java import atlas.core.exceptions.serviceexception; import atlas.core.seguridad.services.asfservice; public class MiClase { private AsfService service; public void mifuncion() throws ServiceException{ } byte[] data= texto.getbytes(encoding); String textocifrado= service.cifrar(data, cipheralias); log.info(textocifrado); Para el descifrado de datos se usa el método descifrar del Servicio. Éste método recibe una cadena con los datos a cifrados y codificados en base 64 y el alias del certificado con el que se quiere cifrar (tiene que estar definido previamente en ASF para la aplicación). El método devuelve un array de bytes con los datos originales (descifrados). Para que la operación de descifrado sea correcta, el certificado con el que se descifre tiene que ser el mismo con el que se cifró. Si se quiere descifrar un texto, es buena práctica especificar una codificación concreta a la hora de construír la cadena a partir del array de bytes devuelto, como se puede ver en el siguiente ejemplo. Para que la cadena se reconstruya correctamente, la codificación tiene que ser la misma que se usó al cifrar. 16 de 22
ClaseEjemplo.java import atlas.core.exceptions.serviceexception; import atlas.core.seguridad.services.asfservice; public class MiClase { private AsfService service; public void mifuncion() throws ServiceException{ } byte[] datosoriginales; datosoriginales= service.descifrar(textocifrado, cipheralias); String textodescifrado= new String(datosOriginales, encoding); log.info(textodescifrado); 17 de 22
4.2. 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 firmaservidor, 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. Si se quiere firmar un texto, es buena práctica especificar una codificación concreta a la hora de obtener el array de bytes, como se puede ver en el siguiente ejemplo: ClaseEjemplo.java import atlas.core.exceptions.serviceexception; import atlas.core.seguridad.services.asfservice; public class MiClase { private AsfService service; public void mifuncion() throws ServiceException{ } byte[] data= texto.getbytes(encoding); String signeddata= service.firmaservidor(data, signalias); 18 de 22
4.3. 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 validarfirma, que recibe tres parámetros: un array de bytes con los datos originales, una cadena con la firma codificada en base 64 y, opcionalmente, el certificado con el que se firmó; si se pasa un valor nulo, no se comprueba que los datos se hayan firmado con dicho certificado. El método devuelve un objeto Result. Si se quiere verificar la firma de un texto, es buena práctica especificar una codificación concreta a la construir la cadena a partir del array de bytes, como se puede ver en el siguiente ejemplo: ClaseEjemplo.java import atlas.core.exceptions.serviceexception; import atlas.core.seguridad.services.asfservice; import atlas.core.seguridad.asf.domain.result; public class MiClase { private AsfService service; public void mifuncion() throws ServiceException{ } byte[] datos= texto.getbytes(encoding); Result result; result= service.validarfirma(datos, signeddata, null); logger.info(result); if(result.ok){ /* Firma correcta */ } else { /* Firma incorrecta */ logger.error(result.message); } 19 de 22
4.4. 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 comprobarcertificado, que recibe el certificado X509 a comprobar. El método devuelve un objeto Result. ClaseEjemplo.java import atlas.core.exceptions.serviceexception; import atlas.core.seguridad.services.asfservice; import atlas.core.seguridad.asf.domain.result; import java.security.cert.x509certificate; public class MiClase { private AsfService service; public void mifuncion(x509certificate cert) throws ServiceException{ } Result result= service.comprobarcertificado(cert); logger.info(result); if(result.ok){ /* Certificado válido } else { } */ /* Certificado inválido */ logger.error(result.message); 20 de 22
4.5. Obtención de datos de un certificado digital Para obtener los datos de un certificado digital, se utiliza el método obtenerdatoscertificado, que recibe el certificado X509 cuyos datos se quieren obtener. El método devuelve un objeto DatosCertificado. ClaseEjemplo.java import atlas.core.exceptions.serviceexception; import atlas.core.seguridad.services.asfservice; import atlas.core.seguridad.asf.domain.datoscertificado; import java.security.cert.x509certificate; public class MiClase { private AsfService service; public void mifuncion(x509certificate cert) throws ServiceException{ } DatosCertificado datoscertificado; datoscertificado= service.obtenerdatoscertificado(cert); logger.info(datoscertificado.nombre); logger.info(datoscertificado.apellidos); logger.info(datoscertificado.phisnif); 21 de 22
5. ENLACES RELACIONADOS Producto Spring ASF Certificados digitales URL http://www.springframework.org/ http://gestiona.madrid.org/soja_int/html/web/asf.htm http://java.sun.com/j2se/1.5.0/docs/guide/security/cert3.html 22 de 22