Protección de servicios web con una señal X.509

Liberty admite Oasis Web Services Security X.509 Certificate Token Profile 1.1. Se puede utilizar una señal X.509 para proporcionar la integridad de mensajes y la confidencialidad firmando y cifrando los mensajes.

Política WS-Security

Para proteger un mensaje XML con una señal X.509, debe crearse primero un contrato que se especifica en un lenguaje de descripción de servicios web (WSDL). El servicio web debe tener una política WS-Security incluida en el archivo WSDL. La política WS-Security puede contener las aserciones AsymmetricBinding o SymmetricBinding.

El requisito de una señal X.509 se expresa como un tipo de aserción X509Token en la política WS-Security. En el ejemplo siguiente se muestra una aserción X509Token de ejemplo:
<sp:X509Token sp:IncludeToken=
  "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
  <wsp:Policy>
    <sp:WssX509V3Token10 />
  </wsp:Policy>
</sp:X509Token>
En una aserción AsymmetricBinding:
  • Se utiliza el iniciador X509Token para la firma de mensajes desde el solicitante al proveedor y el cifrado de mensajes desde el proveedor al solicitante.
  • El destinatario X509Token se utiliza para la firma de mensajes desde el proveedor al solicitante y el cifrado de mensajes desde el solicitante al proveedor.
En la tabla siguiente se muestra cómo se utilizan las señales de iniciador y de destinatario para cada componente de la cadena de solicitud/respuestas:
Tabla 1. Señal de iniciador y destinatario para cada componente de la cadena de solicitud/respuestas
* Señal de iniciador Señal de destinatario
salida de solicitud (solicitante) sign encrypt
entrada de solicitud (proveedor) verify signature decrypt
salida de respuesta (proveedor) encrypt sign
entrada de respuesta (solicitante) decrypt verify signature
Las claves privadas se utilizan para firmar y descifrar los mensajes. Los certificados públicos se utilizan para cifrar los mensajes y verificar las firmas. Las claves privadas pertenecen al usuario de la clave (el firmante o el descifrador).

En una aserción SymmetricBinding, el iniciador y el destinatario comparten una clave secreta o una clave efímera protegida para una señal X.509. Se utiliza la clave tanto para el cifrado como para el descifrado.

En el ejemplo siguiente se muestra una política WS-Security de muestra con una señal X.509 de una aserción AsymmetricBinding. Esta política permite firmar y cifrar el cuerpo de la solicitud y la respuesta con TimeStamp (indicación de fecha y hora).
<wsp:Policy wsu:Id="SampleAsymmetricX509TokensPolicy">
  <wsp:ExactlyOne>
    <wsp:All>
      <sp:AsymmetricBinding>
        <wsp:Policy>
          <sp:InitiatorToken>
            <wsp:Policy>
              <sp:X509Token sp:IncludeToken=
                "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
                <wsp:Policy>
                  <sp:WssX509V3Token10 />
                </wsp:Policy>
              </sp:X509Token>
            </wsp:Policy>
          </sp:InitiatorToken>
          <sp:RecipientToken>
            <wsp:Policy>
              <sp:X509Token sp:IncludeToken=
                "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/Never">
                <wsp:Policy>
                  <sp:WssX509V3Token10 />
                </wsp:Policy>
              </sp:X509Token>
            </wsp:Policy>
          </sp:RecipientToken>
          <sp:AlgorithmSuite>
            <wsp:Policy>
              <sp:Basic128 />
            </wsp:Policy>
          </sp:AlgorithmSuite>
          <sp:Layout>
            <wsp:Policy>
              <sp:Strict />
            </wsp:Policy>
          </sp:Layout>
          <sp:IncludeTimestamp />
          <sp:ProtectTokens />
          <sp:OnlySignEntireHeadersAndBody />
        </wsp:Policy>
      </sp:AsymmetricBinding>
      <sp:SignedParts>
        <sp:Body />
      </sp:SignedParts>
      <sp:EncryptedParts>
        <sp:Body />
      </sp:EncryptedParts>
      <sp:Wss10>
        <wsp:Policy>
          <sp:MustSupportRefKeyIdentifier />
        </wsp:Policy>
      </sp:Wss10>
    </wsp:All>
  </wsp:ExactlyOne>
</wsp:Policy>
En el ejemplo siguiente se muestra una política WS-Security con una señal X.509 de una aserción SymmetricBinding. Esta política permite firmar el cuerpo de la solicitud y la respuesta con TimeStamp (indicación de fecha y hora).
<wsp:Policy wsu:Id="SampleSymmetricX509TokensPolicy">
  <wsp:ExactlyOne>
    <wsp:All>
      <sp:SymmetricBinding>
        <wsp:Policy>
          <sp:ProtectionToken>
            <wsp:Policy>
              <sp:X509Token sp:IncludeToken=
                "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/Never">
                <wsp:Policy>
                  <sp:WssX509V3Token11 />
                  <sp:RequireThumbprintReference />
                </wsp:Policy>
              </sp:X509Token>
            </wsp:Policy>
          </sp:ProtectionToken>
          <sp:Layout>
            <wsp:Policy>
              <sp:Lax />
            </wsp:Policy>
          </sp:Layout>
          <sp:IncludeTimestamp />
          <sp:OnlySignEntireHeadersAndBody />
          <sp:SignBeforeEncrypting />
          <sp:AlgorithmSuite>
            <wsp:Policy>
              <sp:Basic128 />
            </wsp:Policy>
          </sp:AlgorithmSuite>
        </wsp:Policy>
      </sp:SymmetricBinding>
      <sp:EncryptedParts>
        <sp:Body />
      </sp:EncryptedParts>
      <sp:SignedParts>
        <sp:Body />
      </sp:SignedParts>
    </wsp:All>
  </wsp:ExactlyOne>
</wsp:Policy>

Referencia e inclusión de señales

Una aserción de señal puede transportar un atributo sp:IncludeToken que requiere que la señal se incluya en el mensaje. Varias aserciones de señal admiten mecanismos para hacer referencia a señales además de referencias directas. Si una aserción de señal contiene varias aserciones de referencia, es necesario que las referencias a esa señal contengan todos los tipos de referencia especificados. Por ejemplo, si una aserción de señal lleva un atributo sp:IncludeToken con un valor de ../Always y esa aserción de señal contiene también una aserción sp:RequireIssuerSerialReference anidada, el símbolo debe estar incluido dos veces en el mensaje. Aunque tales combinaciones no son errores, es mejor evitarlas por motivos de eficacia.

La aserción IncludeToken se aplica en Liberty, pero se ignora en el entorno de ejecución de WS-Security de WebSphere Application Server tradicional.

La política WS-Security admite estos mecanismos de referencia de señal:
  • KeyIdentifier: <sp:RequireKeyIdentifierReference... />
  • IssuerSerial: <sp:RequireIssuerSerialReference ... />
  • Thumbprint: <sp:RequireThumbprintReference ... />

Estas referencias se utilizan al generar una señal X.509 en el lado del cliente o generador y no se aplican en el lado del servidor o consumidor.

Configuración de tiempo de ejecución

El módulo ejecutable de la característica WS-Security de Liberty proporciona más opciones de configuración para la protección de mensajes con una señal X.509 que las que abarca la política WS-Security. La configuración de tiempo de ejecución se define en el archivo server.xml. La configuración de tiempo de ejecución incluye propiedades criptográficas como signatureProperties y encryptionProperties, clave y almacenes de claves.

En el ejemplo siguiente se muestra una configuración de cliente para una aserción X509Token:
<wsSecurityClient id="default"
                  ws-security.callback-handler="com.ibm.ws.wssecurity.example.cbh.KeyPasswordCallbackHandler">
  <signatureProperties org.apache.ws.security.crypto.merlin.keystore.type="jks"
                       org.apache.ws.security.crypto.merlin.keystore.password="LibertyX509Client"
                       org.apache.ws.security.crypto.merlin.keystore.alias="x509ClientDefault"
                       org.apache.ws.security.crypto.merlin.file="${server.config.dir}/x509ClientDefault.jks" />
  <encryptionProperties org.apache.ws.security.crypto.merlin.keystore.type="jks"
                        org.apache.ws.security.crypto.merlin.keystore.password="LibertyXClient"
                        org.apache.ws.security.crypto.merlin.keystore.alias="x509DefaultCert"
                        org.apache.ws.security.crypto.merlin.file="${server.config.dir}/x509ClientDefault.jks" />
</wsSecurityClient>
En el ejemplo siguiente se muestra una configuración de servidor para una aserción X509Token:
<wsSecurityProvider id="default"
                    ws-security.callback-handler="com.ibm.ws.wssecurity.example.cbh.KeyPasswordCallbackHandler">
  <signatureProperties org.apache.ws.security.crypto.merlin.keystore.type="jks"
                       org.apache.ws.security.crypto.merlin.keystore.password="LibertyX509Server"
                       org.apache.ws.security.crypto.merlin.keystore.alias="x509ServerDefault"
                       org.apache.ws.security.crypto.merlin.file="${server.config.dir}/x509ServerDefault.jks" />
  <encryptionProperties org.apache.ws.security.crypto.merlin.keystore.type="jks"
                        org.apache.ws.security.crypto.merlin.keystore.password="LibertyX509Server"
                        org.apache.ws.security.crypto.merlin.keystore.alias="x509ServerDefault"
                        org.apache.ws.security.crypto.merlin.file="${server.config.dir}/x509ServerDefault.jks" />
</wsSecurityProvider>

En la configuración de tiempo de ejecución, las propiedades signatureProperties y encryptionProperties son equivalentes a las propiedades criptográficas de la configuración WSS4J. Para obtener más información, consulte Configuración WSS4J. Muchas propiedades criptográficas tienen valores predeterminados válidos de modo que no se tienen que especificar. Pero otras propiedades, como las relacionadas con clave y almacén de claves, se deben especificar.

Para obtener más información sobre estas propiedades, consulte Configuración predeterminada de seguridad de servicios web.

Archivos de almacén de claves, claves y certificados

El cifrado y la firma de mensajes requieren el uso de certificados públicos y claves privadas. Estos certificados públicos y claves privadas se almacenan en los archivos de almacén de claves. Son necesarios los archivos de almacén de claves cuando se utilizan aserciones X509Token. El archivo de almacén de claves del lado del cliente contiene la clave privada del cliente, y una cadena de certificados correspondiente a la clave pública del servidor. El archivo de almacén de claves del lado del servidor contiene la clave privada del servidor, y una cadena de certificados correspondiente a la clave pública del cliente.

Cuando un mensaje SOAP está cifrado y firmado, el entorno de ejecución de WS-Security interpreta las propiedades signatureProperties y encryptionProperties de esta manera:
  • Aserción AsymmetricBinding

    La clave especificada por la propiedad signatureProperties se utiliza como la clave privada para firmar el mensaje de salida y se utiliza también para descifrar el mensaje de entrada.

    La clave especificada por la propiedad encryptionProperties se utiliza como la clave pública para cifrar el mensaje de salida y se utiliza también para verificar la firma del mensaje de entrada.

  • Aserción SymmetricBinding

    Se utiliza la clave especificada por las propiedades encryptionProperties, mientras que se omite la propiedad signatureProperties.

CallbackHandler de contraseña de clave privada

Para acceder a una clave privada de un almacén de claves, debe conocer dos contraseñas distintas. Una contraseña es para el almacén de claves donde se almacena la clave privada. La otra es para la clave privada en sí. Aunque la contraseña del almacén de claves se especifica en una de las propiedades de cifrado, signatureProperties o encryptionProperties, WS-Security normalmente utiliza la clase CallbackHandler para acceder a la clave privada de un almacén de claves. En Liberty, esta clase CallbackHandler se debe empaquetar como una característica de Liberty y se debe especificar su nombre de clase como el valor de la propiedad personalizada ws-security.callback-handler en security.xml.

WS-Security requiere esta clase CallbackHandler para acceder a la clave privada de un almacén de claves.

Para obtener más información sobre la clase CallbackHandler de contraseña, consulte Desarrollo de un manejador de devolución de llamada de contraseña para WS-Security.

Si la clase CallbackHandler no proporciona la contraseña de clave privada, el entorno de ejecución de ws-security intenta primero CallbackHandler así que se debe proporcionar, a continuación se utiliza la contraseña especificada en las propiedades de cifrado como contraseña predeterminada para la clave privada. Esta propiedad se configura como org.apache.ws.security.crypto.merlin.keystore.private.password.

Dado que solo se admite una propiedad personalizada ws-security.callback-handler en cada una de las secciones wsSecurityClient y wsSecurityProvider del archivo security.xml, un único manejador de devolución de llamada de contraseña debe dar soporte a todas las contraseñas necesarias para cada tipo de aplicación (cliente o servidor) que utilice el valor predeterminado. Todas las aplicaciones de proveedor deben utilizar el manejador de devolución de llamada de contraseña predeterminado. Las aplicaciones cliente deben alterar temporalmente el manejador de devolución de llamada predeterminado especificando la propiedad personalizada ws-security.callback-handler en el contexto de solicitud de la invocación de servicio web del cliente.

Si tiene que proporcionar contraseñas para una clave privada X.509 y una UsernameToken para una sola invocación de servicio web, no puede proporcionar manejadores de devolución de llamada aparte para cada uso. En este caso, debe implementar un solo manejador de devolución de llamada que gestione los dos tipos de contraseña. Tal como se ilustra en el ejemplo anterior, debe utilizar el método WSPasswordCallback.getUsage() para determinar qué tipo de contraseña se devuelve. Consulte la documentación de la API WSPasswordCallback para los códigos de uso soportados http://ws.apache.org/wss4j/apidocs/org/apache/wss4j/common/ext/WSPasswordCallback.html.

Lista de revocación de certificados

Una lista de revocación de certificados (CRL) es una lista de números de serie de certificados revocados. Una CRL puede ser un archivo autónomo o puede estar empaquetada en un derivador PKCS#7. Puede utilizar una CRL con un almacén de confianza para controlar el acceso a un servicio.

Se requieren dos pasos para configurar la característica de WS-Security en Liberty para realizar la comprobación de revocación con un archivo CRL. Para habilitar la comprobación de revocación de certificado con un archivo CRL, debe modificar la configuración del tiempo de ejecución de WS-Security en el archivo server.xml.
  1. En el elemento wsSecurityProvider o wsSecurityClient, añada la propiedad siguiente:
    ws-security.enableRevocation="true"
  2. En el elemento signatureProperties, añada la propiedad siguiente y establezca el valor en un archivo CRL:
    org.apache.ws.security.crypto.merlin.x509crl.file
El ejemplo siguiente muestra una configuración del proveedor WS-Security que habilita la comprobación de revocación de certificados con un archivo CRL:
<wsSecurityProvider id="default"
    ws-security.callback-handler="com.acme.example.cbh.CommonPasswordCallback" 
    ws-security.signature.username="x509ServerDefault"
    ws-security.enableRevocation="true">
  <signatureProperties 
      org.apache.ws.security.crypto.merlin.keystore.type="jks"
      org.apache.ws.security.crypto.merlin.keystore.password="LibertyX509Server"
      org.apache.ws.security.crypto.merlin.keystore.alias="x509ServerDefault"
      org.apache.ws.security.crypto.merlin.file="${server.config.dir}/x509ServerDefault.ks"
      org.apache.ws.security.crypto.merlin.truststore.password="LibertyX509Server"
      org.apache.ws.security.crypto.merlin.truststore.file="${server.config.dir}/x509DefaultServer.ks"
      org.apache.ws.security.crypto.merlin.x509crl.file="${server.config.dir}/revokedCerts.crl"/>
</wsSecurityProvider>

Icono que indica el tipo de tema Tema de concepto

Nombre de archivo: cwlp_wssec_x509.html