Configuración de la información de firmas mediante la API WSSSignature

Puede proteger los mensajes SOAP, sin utilizar conjuntos de políticas para la configuración, utilizando las API de WSS (Web Services Security). Para configurar la información de firmas para las secciones de enlaces del generador para la solicitud del lado del cliente, utilice la API WSSSignature. La API WSSSignature forma parte del paquete com.ibm.websphere.wssecurity.wssapi.signature.

Antes de empezar

Puede utilizar la API de WSS o puede configurar los conjuntos de políticas utilizando la consola administrativa para habilitar la información de firmas. Para proteger los mensajes SOAP, debe completar las tareas de firma siguientes:

  • Configure la información de firmas.
  • Seleccione los métodos de firma.
  • Añada o cambie partes firmadas, según proceda.

Acerca de esta tarea

WebSphere Application Server utiliza la información de firmas para el generador predeterminado con objeto de firmar partes del mensaje y utiliza la firma digital XML con algoritmos existentes como, por ejemplo, RSA-SHA1 y HMAC-SHA1.

La firma XML define muchos métodos para describir información clave y permite la definición de un nuevo método. A menudo, es necesaria la canonicalización XML (C14N) cuando se utiliza la firma XML. La información se puede representar de varias formas dentro de los documentos XML serializados. El proceso C14N se utiliza para canonicalizar información XML. Seleccione un algoritmo C14N apropiado porque la información que se canonicaliza depende de este algoritmo.

La información de firmas especifica las limitaciones de integridad que se aplican a los mensajes generados. Las limitaciones incluyen especificar qué partes del mensaje generado se deben firmar digitalmente y las partes del mensaje a las que se adjuntan digitalmente los elementos de indicación de fecha y hora y Nonce firmados. Se configuran la firma y la información de parte de firma relacionada siguientes:

Tabla 1. Información de partes de firma. Utilice las partes de firma para proteger los mensajes.
Partes de firma Descripción
palabra clave
Añade una parte de firma utilizando palabras clave. Utilice las palabras clave siguientes para las partes de firma:
  • ADDRESSING_HEADERS
  • BODY
  • TIMESTAMP
Las cabeceras WS-Addressing no se cifran, pero se pueden firmar.
xpath Añade una parte de firma utilizando una expresión XPath.
part Añade un objeto WSSSignPart como un destino de la parte de firma.
timestamp Añade un objeto WSSTimestamp como un destino de la parte de firma. Cuando se especifica, la información de la indicación de fecha y hora también especifica cuando se genera el mensaje y cuando caduca.
cabecera Añade la cabecera, especificada por QName, como un destino de la parte de firma.
securityToken Añade un objeto SecurityToken como un destino de la parte de firma.

Para la información de firmas, se producen determinados comportamientos predeterminados. La forma más sencilla de utilizar la API WSSSignature es utilizar el comportamiento predeterminado (consulte el código de ejemplo). Los valores predeterminados son definidos por la API de WSS para el método de firma, el método de canonicalización, las referencias de la señal de seguridad y las partes de firma.

Tabla 2. Comportamientos de firma predeterminados. De forma predeterminada, hay varios comportamientos de firma configurados.
Decisiones de firma Comportamiento predeterminado
Qué palabras clave se van a utilizar Establece las palabras clave. WebSphere Application Server soporta las siguientes palabras clave de manera predeterminada:
  • ADDRESSING_HEADERS
  • BODY
  • TIMESTAMP
Qué método de firma utilizar Establece el algoritmo de firma. El método de firma predeterminado es RSA SHA1. WebSphere Application Server da soporte a los métodos de firmas preconfigurados siguientes:
  • WSSSignature.RSA_SHA1: http://www.w3.org/2000/09/xmldsig#rsa-sha1
  • WSSSignature.HMAC_SHA1: http://www.w3.org/2000/09/xmldsig#hmac-sha1
El método de firma digital DSA-SHA1 (http://www.w3.org/2000/09/xmldsig#dsa-sha1) no está soportado.
Qué método de canonicalización utilizar Establece el algoritmo de canonicalización. El método de canonicalización predeterminado es EXC C14N. WebSphere Application Server da soporte a los métodos de canonicalización preconfigurados siguientes:
  • WSSSignature.EXC_C14N; http://www.w3.org/2001/10/xml-exc-c14n#
  • WSSSignature.C14N: http://www.w3.org/2001/10/xml-c14n#
Es necesaria la confirmación de firma Establece si es necesaria la confirmación de firma. El valor predeterminado es false. La confirmación de firma se define en la especificación OASIS Web Services Security Versión 1.1. Si es necesario, el valor de la confirmación de firma se almacena con objeto de utilizarlo para validar la confirmación de firma , después de devolver el mensaje que generó la confirmación de firma en el mensaje de respuesta. Este método es para uso del lado del solicitante.
Qué señal de seguridad se va a utilizar

Establece SecurityToken. El tipo de señal especifica qué tipo de señal se va a utilizar para firmar y validar mensajes. La señal X.509 es el tipo de señal predeterminada.

WebSphere Application Server proporciona los siguientes tipos de señal del consumidor preconfigurados:

  • Señal de clave derivada
  • Señales X509

También puede crear tipos de señal personalizados, según sea necesario.

Qué referencia de señal se va a establecer Establece refType. SecurityToken.REF_STR es el valor predeterminado del tipo de la referencia de señal. WebSphere Application Server soporta los siguientes tipos de referencias de señales preconfigurados:
  • SecurityToken.REF_STR
  • SecurityToken.REF_KEYID
  • SecurityToken.REF_EMBEDDED
  • SecurityToken.REF_THUMBPRINT

Si se llama a WSSSignature.requireSignatureConfirmation(), la API WSSSignature espera que el mensaje de respuesta incluirá la confirmación de firma.

Procedimiento

  1. Para configurar la información de firmas en un mensaje SOAP utilizando la API de WSS, en primer lugar, asegúrese de que está instalado el servidor de aplicaciones.
  2. Utilice la API WSSSignature para firmar las partes del mensaje y especificar los algoritmos en un mensaje SOAP. El proceso de la API de WSS para la firma sigue estos pasos de proceso:
    1. Utiliza WSSFactory.getInstance() para obtener la instancia de implementación de la API de WSS.
    2. Crea la instancia WSSGenerationContext desde la instancia WSSFactory. Se debe llamar a WSSGenerationContext en una aplicación cliente de JAX-WS.
    3. Crea SecurityToken desde WSSFactory para configurar la clave para la firma.
    4. Crea WSSSignature desde la instancia WSSFactory utilizando SecurityToken. El comportamiento predeterminado de WSSSignature es firmar estas partes de firma: BODY, ADDRESSING_HEADERS y TIMESTAMP.
    5. Añade la parte que se va a firmar, si la parte predeterminada no es apropiada. Si se cambia el método de conversión o el método de transformación, crea WSSSignPart y la añade a WSSSignature.
    6. Crea WSSSignaturePart en WSSSignature. Llama al método requiredSignatureConfirmation(), si se va a aplicar la confirmación de firma.
    7. Establece el método de canonicalización, si el valor predeterminado no es apropiado.
    8. Establece el método de firma, si el valor predeterminado no es apropiado.
    9. Establece la referencia de la señal, si el valor predeterminado no es apropiado.
    10. Añade WSSSignature a WSSGenerationContext.
    11. Llama a WSSGenerationContext.process() con el SOAPMessageContext.

Resultados

Ha completado los pasos para configurar la firma para la sección del generador de los enlaces. Si existe una condición de error al firmar las partes del mensaje, se proporciona una excepción WSSException. Si es correcto, se llama a WSSGenerationContext.process() y se aplica Web Services Security al mensaje SOAP.

Ejemplo

En el ejemplo siguiente se proporciona código de ejemplo que utiliza métodos que se definen en la API WSSignature.

// Obtener el contexto de mensaje 
   Object msgcontext = getMessageContext();

// Generar la instancia com.ibm.websphere.wssecurity.wssapi.WSSFactory (paso: a)
   WSSFactory factory = com.ibm.websphere.wssecurity.wssapi.WSSFactory.getInstance();

// Generar la instancia WSSGenerationContext (paso: b)
   WSSGenerationContext gencont = factory.newWSSGenerationContext();

// Generar el manejador de retorno de llamada
   X509GenerateCallbackHandler callbackHandler = new 
       X509GenerateCallbackHandler(
       "",
       "dsig-sender.ks",
       "jks", 
       "client".toCharArray(), 
       "soaprequester", 
       "client".toCharArray(), 
       "CN=SOAPRequester, OU=TRL, O=IBM, ST=Kanagawa, C=JP", null);

// Generar la señal de seguridad que se va a utilizar para la firma (paso: c)
   SecurityToken token = factory.newSecurityToken(X509Token.class, 
        callbackHandler);

// Generar la instancia WSSSignature (paso: d)
   WSSSignature sig = factory.newWSSSignature(token);

// Establecer la parte que se va a firmar (paso: e)
// DEFAULT: WSSSignature.BODY, WSSSignature.ADDRESSING_HEADERS, 
//          and WSSSignature.TIMESTAMP.

// Establecer la parte de la cabecera SOAP especificada por QName  (paso: e)
      sig.addSignHeader(new 
                        QName("http://www.w3.org/2005/08/addressing", 
                        "MessageID"));

// Establecer la parte especificada por la palabra clave (paso: e)
      sig.addSignPart(WSSSignature.BODY);

// Establecer la parte especificada por SecurityToken  (paso: e)
   UNTGenerateCallbackHandler untCallbackHandler = new 
      UNTGenerateCallbackHandler("Chris", "sirhC");
      SecurityToken unt = factory.newSecurityToken(UsernameToken.class, 
         untCallbackHandler);
      sig.addSignPart(unt);

// Establecer la parte especificada por WSSSignPart  (paso: e)
   WSSSignPart sigPart = factory.newWSSSignPart();
      sigPart.setSignPart(WSSSignature.TIMESTAMP);
      sigPart.setDigestMethod(WSSSignPart.SHA256);
      sig.addSignPart(sigPart);

// Establecer la parte especificada por WSSTimestamp  (paso: e)
   WSSTimestamp timestamp = factory.newWSSTimestamp();
      sig.addSignPart(timestamp);

// Establecer la parte especificada por la expresión XPath (paso: e) 
   StringBuffer sb = new StringBuffer();
      sb.append("/*[namespace-uri()='http://schemas.xmlsoap.org/soap/envelope/' 
         and local-name()='Envelope']");
      sb.append("/*[namespace-uri()='http://schemas.xmlsoap.org/soap/envelope/' 
         and local-name()='Body']");
      sb.append("/*[namespace-uri()='http://xmlsoap.org/Ping' 
         and local-name()='Ping']");
      sb.append("/*[namespace-uri()='http://xmlsoap.org/Ping' 
         and local-name()='Text']");
      sig.addSignPartByXPath(sb.toString());

// Establecer la aplicación de la confirmación de firma (paso: f)
      sig.requireSignatureConfirmation();

// Establecer el método de canonicalización (paso: g)
// DEFAULT: WSSSignature.EXC_C14N
      sig.setCanonicalizationMethod(WSSSignature.C14N);

// Establecer el método de firma (paso: h)
// DEFAULT: WSSSignature.RSA_SHA1
      sig.setSignatureMethod(WSSSignature.HMAC_SHA1);

// Establecer la referencia de la señal (paso: i)
// DEFAULT: SecurityToken.REF_STR
      sig.setTokenReference(SecurityToken.REF_KEYID);
	
// Añadir WSSSignature a WSSGenerationContext  (paso: j)
   gencont.add(sig);

// Generar la cabecera de WS-Security (paso: k)
gencont.process(msgctx);
Nota: X509GenerationCallbackHandler necesita la contraseña de la clave porque se utiliza la clave privada para la firma.

Qué hacer a continuación

A continuación, seleccione los métodos del algoritmo, si desea un método que es distinto de los valores predeterminados. Si los métodos de algoritmo no necesitan modificarse, utilice la API WSSVerification para verificar la firma y especificar los métodos de algoritmo en la sección del consumidor del enlace. Tenga en cuenta que la API WSSVerification sólo está soportada en el consumidor de respuestas (lado del cliente).


Icon that indicates the type of topic Task topic



Timestamp icon Last updated: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twbs_confsignaturegen
File name: twbs_confsignaturegen.html