ALTAS
MANUAL DE USUARIO
DEL SERVICIO DE CERTIFICADOS
Versión 1.0
Hoja de Control
Título Manual de Usuario del Servicio de Certificados Documento de
Referencia NORMATIVA ATLAS
Responsable Á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
1.0 Versión inicial del documento
Área de Integración y Arquitectura de
Í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
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”.
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
3. INSTALACIÓN Y CONFIGURACIÓN
3.1. INSTALACIÓN
El Servicio de Certificados 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:
pom.xml
<dependencies>
[...]
<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á “
applicationContext-services.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"
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"
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 Descipción
invokingApp Id de la aplicación en ASF.
Obligatorio.
NOTA: La aplicación debe estar dada de alta en ASF
verifySignatureApplicationId 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
signApplicationId 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
cipherOperationId Id de la operación de cifrado. Opcional, por defecto, "CIFRADO".
NOTA: La operación tiene que existir para la aplicación en ASF
decipherOperationId Id de la operación de descifrado. Opcional, por defecto, "DESCIFRADO".
NOTA: La operación tiene que existir para la aplicación en ASF
signedDataFormat Formato de la firma, según se especifican en Constants. Opcional, por defecto PKCS7_FORMAT
(ver “com.tbsolutions.asf.util.Constants”).
cipheredDataFormat Formato de los datos cifrados, según se especifican en Constants. Opcional, por defecto PKCS7_FORMAT
(ver “com.tbsolutions.asf.util.Constants”).
cipherAlgorithm Algoritmo de cifrado, según se especifican en Constants. Opcional, por defecto TRIPLE_DES_SYMMETRIC_ALGORITHM
keyCipherAlgorithm Algoritmo de cifrado de la clave, según se especifican en Constants. Opcional, por defecto RSA_ASYMMETRIC_ALGORITHM
(ver “com.tbsolutions.asf.util.Constants”).
signatureCheckRevocation Comprobar (o no) el estado de revocación del cerificado firmante. Opcional, por defecto, false.
registroNoRepudio Almacenar (o no) la información necesaria para garantizar el no repudio. Opcional, por defecto, false.
ignoreVerificationCaches Ignorar (o no) la caché de verificaciones. Opcional, por defecto, false.
verifyRevocation Verificar (o no) el estado de revocación del cerificado al validar los certificados.
Opcional, por defecto, true.
verifyValidity Verificar (o no) el estado de validez (caducidad) del cerificado al comprobar el cetificado.
Opcional, por defecto, true.
verifySignatureOperationId 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
digestAlgorithm Algoritmo de hash, según se especifican en Constants. Opcional, por defecto, SHA_DIGEST_ALGORITHM
(ver “com.tbsolutions.asf.util.Constants”).
verifySigningCerts Verificación de los certificados al validar las firmas. Opcional, por defecto, SIGNING_CERT_NO_VERIFY (ver “com.tbsolutions.asf.signatureserver.util.Constants”).
signatureAlgorithm Algoritmo de firma, según se especifican en Constants. Opcional, por defecto, RSA_ASYMMETRIC_ALGORITHM
(ver “com.tbsolutions.asf.util.Constants”).
includeTimeStamp Incluír (o no) sellos de tiempo en la firmas. Opcional, por defecto, false.
signOperationId Identificador de la operación de firma para la aplicación en ASF. Opcional, por defecto, "FIRMA_SIMPLE".
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:
Salvar los cambios y en la pestaña Configuration->SSL->Advanced cambiar el valor de “Two way Client Cert Behavior”
Salvar los cambios.
• Paso 2: Importar el certificado raiz de ICM como certificado de confianza:
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:
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.
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
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);
[...]
}
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);
[...]
}
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); } [...] } [...]
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); } [...] } [...]
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); [...] } [...]
5. ENLACES RELACIONADOS
Producto URL
Spring http://www.springframework.org/
ASF http://gestiona.madrid.org/soja_int/html/web/ASF.htm Certificados digitales http://java.sun.com/j2se/1.5.0/docs/guide/security/cert3.html