Configuring a policy set and bindings for Asymmetric XML Digital Signature or XML Encryption with client and provider general bindings

You can configure the message-level WS-Security policy set and bindings to sign and encrypt a SOAP message by using asymmetric XML Digital Signature and Encryption and general bindings. As part of this procedure, you must specify whether you sign and encrypts or sign or encrypt both the request and response messages.

Before you begin

This task assumes that the service provider and client that you are configuring are in the JaxWSServicesSamples application. For more information about obtaining and install this application, see Accessing Samples.

You use the following trace specification on your server. Use these specifications to debug any future configuration problems that might occur.
*=info:com.ibm.wsspi.wssecurity.*=all:com.ibm.ws.webservices.wssecurity.*=all: 
com.ibm.ws.wssecurity.*=all: com.ibm.xml.soapsec.*=all: com.ibm.ws.webservices.trace.*=all: 
com.ibm.ws.websvcs.trace.*=all:com.ibm.ws.wssecurity.platform.audit.*=off:

About this task

This procedure explains the actions that you need to complete to configure a WS-Security policy set to use the asymmetric XML-Digital Signature and Encryption WS-Security constraints. This procedure also explains how to create new client and provider general bindings and update them to contain your own keystores and keys for asymmetric XML Digital Signature and Encryption.

Because of the nature of JaxWSServicesSamples to apply the policy set and bindings to this application, in the administrative console click Applications > Application types > WebSphere enterprise applications > JaxWSServicesSamples. When you use your own applications, you can use the following paths as an alternative way to access the provider and client for attachment of the policy set and bindings:

* Services > Service Providers > (AppName)
* Services > Service clients > (AppName)

Procedure

  1. Create the custom policy set.
    1. In the administrative console, click Services > Policy sets > Application Policy sets.
    2. Click New.
    3. Specify Name=AsignEncPolicy.
    4. Click Apply.
    5. Under Policies, click Add > WS-Security.
  2. Edit the custom policy set.
    1. In the administrative console, click WS-Security > Main Policy.
      By default, the policy now has the following configuration:
      • Timestamp sent in outbound messages
      • Timestamp required in inbound messages
      • Sign the request and the response (Body, WS-Addressing header, and Timestamp)
      • Encrypt the request and the response (Body and Signature element in SOAP Security header)

      If this is the configuration that you want, click Apply, then Save, and continue to the next step.

      If you want to change this configuration, complete one or more of the following substeps.

    2. Optional: Remove Timestamp from both request and response. You cannot do one-way Timestamp.

      To remove Timestamp from both request and response, clear the Include timestamp in security header setting, and then click Apply.

    3. Optional: Remove signature or encryption from request message.
      1. Under Message level protection, click Request message part protection.
      2. To remove the request encryption, click app_encparts, and then click Delete.
      3. To remove the request signature, click app_signparts, and then click Delete.
      4. Click Done.
    4. Optional: Remove signature or encryption from response message.
      1. Under Message level protection, click Response message part protection.
      2. To remove the response encryption, click app_encparts, and then click Delete.
      3. To remove the response signature, click app_signparts, and then click Delete.
      4. Click Done.
    5. Optional: View or change parts that are being signed or encrypted in the request.
      1. Under Message level protection, click Request message part protection.
      2. To view or change the request encrypted part, click app_encparts, and then click Edit.

        The Elements in Part page displays with the parts that are encrypted in the request message. You can update the settings on this page to add, change, or remove elements to encrypt. By default, the Body and an XPath expression to the Signature are configured. There are two XPath expressions to the Signature element to handle both SOAP 1.1 and SOAP 2.0.

        If you would like to add encryption of a UsernameToken, SAML Assertion, or other elements, see Building XPath expressions for WS-Security.

        When you finish making your changes, click OK.

      3. To view or change the request signed part, click app_signparts, and then click Edit.

        The Elements in Part page displays with the parts that are signed in the request message. You can update the settings on this page to add, change, or remove elements to sign. By default, the Body, the QNames for the WS-Addressing header, and XPath expressions to the Timestamp are configured.

        If you are using the STR Dereference Transform (STR-Transform) to sign a security token, add the following XPath expression:
        /*[namespace-uri()='http://schemas.xmlsoap.org/soap/envelope/' and local-name()='Envelope']
/*[namespace-uri()='http://schemas.xmlsoap.org/soap/envelope/' and local-name()='Header']
/*[namespace-uri()='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd' and local-name()='Security']
/*[namespace-uri()='https://www.w3.org/2000/09/xmldsig#' and local-name()='Signature']
/*[namespace-uri()='https://www.w3.org/2000/09/xmldsig#' and local-name()='KeyInfo']
/*[namespace-uri()='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd' and local-name()='SecurityTokenReference']

        If you would like to sign other elements, such as a BinarySecurityToken, see Building XPath expressions for WS-Security.

        When you finish making your changes, click OK.

      4. Click Done.
    6. Optional: View or change parts that are being signed or encrypted in the response.
      1. Under Message level protection, click Response message part protection.
      2. To view or change the response encrypted part, click app_encparts, and then click Edit.

        The Elements in Part page displays with the parts that are encrypted in the response message. You can update the settings on this page to add, change, or remove elements to encrypt. By default, the Body and an XPath expression to the Signature are configured.

        When you finish making your changes, click OK.

      3. To view or change the response signed part, click app_signparts, and then click Edit.

        The Elements in Part page displays with the parts that are signed in the response message. You can update the settings on this page to add, change, or remove elements to sign. By default, the Body, the QNames for the WS-Addressing header, and XPath expressions to the Timestamp are configured.

        When you finish making your changes, click OK.

      4. Click Done.
    7. Click Apply.
    8. Save the configuration.
  3. Create the client general binding.
    1. In the administrative console, click Services > Policy Sets > General client policy set bindings.
    2. Check Client sample.
    3. Click Copy....
    4. Specify name

      name: MyClientGeneralBinding

    5. Click OK.
  4. Edit the new client general binding to contain your own keystores and keys.
    1. Select MyClientGeneralBinding > WS-Security > Authentication and protection.
    2. Optional: Configure the client's outbound encrypting public certificate for the request message. This certificate must match the private key that the provider uses to decrypt the message.
      1. Under Protection tokens, select gen_encx509token.
      2. Select Callback handler.
      3. Do one of the following actions:

        If you are using a public encrypting certificate from a named keystore, perform the following operations:

        1. Under keystore, click Custom keystore configuration.
        2. Under keystore, enter the full path to your keystore, its type, and password.
        3. Under Key, enter the Name and Alias public encrypting certificate.
        4. Click OK, OK, OK.

        If you are using a public encrypting certificate from a centralized keystore perform the following operations:

        1. Under keystore, select the name of the keystore to use.
        2. Under key, select the name of the public encrypting certificate.
        3. Click OK, OK.
    3. Optional: Configure the client's outbound private signing key for the request message.
      1. Under Protection tokens, select gen_signx509token.
      2. Select Callback handler.
      3. Do one of the following actions:

        If you are using a private signing key from a named keystore, perform the following operations:

        1. Under keystore, click Custom keystore configuration.
        2. Under keystore, enter the full path to your keystore, its type, and password.
        3. Under Key, enter the Name, Alias, and password for your private signing key.
        4. Click OK, OK, OK.

        If you are using a private signing key from a centralized keystore perform the following operations:

        1. Under keystore, select the name of the keystore to use.
        2. Under key, select the name of the private signing key to use.
        3. Enter the password for the signing key.
        4. Click OK, OK.
    4. Optional: Configure the client's inbound private decrypting key for the response message. This private key must match the public certificate that the provider used to encrypt the message.
      1. Under Protection tokens, select con_encx509token.
      2. Select Callback handler.
      3. Do one of the following actions:

        If you are using a private decrypting key from a named keystore, perform the following operations:

        1. Under keystore, click Custom keystore configuration.
        2. Under keystore, enter the full path to your keystore, its type, and password.
        3. Under Key, enter the Name, Alias, and password for your private decrypting key.
        4. Click OK, OK, OK.

        If you are using a private decrypting key from a centralized keystore perform the following operations:

        1. Under keystore, select the name of the keystore to use.
        2. Under key, select the name of the private decrypting key to use.
        3. Enter the password for the decrypting key.
        4. Click OK, OK.
    5. Optional: Configure the client's inbound signature truststore and certificate store for processing the response message.
      1. Under Protection tokens, select con_signx509token.
      2. Select Callback handler.
      3. Do one of the following actions:

        If you want to trust all certificates, perform the following operations. This is the most common configuration option for clients.

        1. Under Certificates, select Trust any certificate.
        2. Click OK, OK.

        If you want to only trust requests signed by specific signing certificates, do the following actions:

        1. Next to Trusted anchor store, click New and then specify Name=MyTrustAnchor
        2. Either select a centrally managed keystore or under External keystore, enter the full path to your truststore, its type, and password.
        3. Click OK.
        4. Next to Trusted anchor store, select MyTrustAnchor.
        5. Click Apply.
        6. Do one of the following actions:

          If you do not need to configure intermediate certificates or Certificate Revocation Lists (CRLs), perform the following actions:

          1. Next to Certificate Store, select none.
          2. Click OK, OK.

          If you need to configure intermediate certificates or Certificate Revocation Lists (CRLs), perform the following actions:

          1. Next to Certificate store, click New and then specify name=MyCertStore
          2. For each CRL that you need to configure, enter it under Revoked certificates.
          3. For each intermediate certificate that you need to configure, enter it under Intermediate X.509 certificates.
          4. Click OK.
          5. Next to Certificate store, select MyCertStore.
          6. Click OK, OK.
  5. Create the provider general binding.
    1. In the administrative console, click Services > Policy sets > General provider policy set bindings.
    2. Check Provider sample.
    3. Click Copy....
    4. Specify Name=MyProviderGeneralBinding.
    5. Click OK.
  6. Edit the new provider general binding to contain your own keystores and keys.
    1. Select MyProviderGeneralBinding > WS-Security > Authentication and protection.
    2. Optional: Configure the provider's outbound encrypting public certificate for the response message. This certificate must match the private key that the client uses to decrypt the message.
      1. Under Protection tokens, select gen_encx509token.
      2. Select Callback handler.
      3. Do one of the following actions:

        If you are using a public encrypting certificate from a named keystore, perform the following operations:

        1. Under keystore, click Custom keystore configuration.
        2. Under keystore, enter the full path to your keystore, its type, and password.
        3. Under Key, enter the Name and Alias public encrypting certificate.
        4. Click OK, OK, OK.

        If you are using a public encrypting certificate from a centralized keystore perform the following operations:

        1. Under keystore, select the name of the keystore to use.
        2. Under key, select the name of the public encrypting certificate.
        3. Click OK, OK.
    3. Optional: Configure the provider's outbound private signing key for the response message.
      1. Under Protection tokens, select gen_signx509token.
      2. Select Callback handler.
      3. Do one of the following actions:

        If you are using a private signing key from a named keystore, perform the following operations:

        1. Under keystore, click Custom keystore configuration.
        2. Under keystore, enter the full path to your keystore, its type, and password.
        3. Under Key, enter the Name, Alias, and password for your private signing key.
        4. Click OK, OK, OK.

        If you are using a private signing key from a centralized keystore perform the following operations:

        1. Under keystore, select the name of the keystore to use.
        2. Under key, select the name of the private signing key to use.
        3. Enter the password for the signing key.
        4. Click OK, OK.
    4. Optional: Configure the provider's inbound private decrypting key for the request message. This private key must match the public certificate that the client used to encrypt the message.
      1. Under Protection tokens, select con_encx509token.
      2. Select Callback handler.
      3. Do one of the following actions:

        If you are using a private decrypting key from a named keystore, perform the following operations:

        1. Under keystore, click Custom keystore configuration.
        2. Under keystore, enter the full path to your keystore, its type, and password.
        3. Under Key, enter the Name, Alias, and password for your private decrypting key.
        4. Click OK, OK, OK.

        If you are using a private decrypting key from a centralized keystore perform the following operations:

        1. Under keystore, select the name of the keystore to use.
        2. Under key, select the name of the private decrypting key to use.
        3. Enter the password for the decrypting key.
        4. Click OK, OK.
    5. Optional: Configure the provider's inbound signature truststore and certificate store for processing the request message.
      1. Under Protection tokens, select con_signx509token.
      2. Select Callback handler.
      3. Do one of the following actions:

        If you want to trust all certificates, perform the following operations. This is the most common configuration option for clients.

        1. Under Certificates, select Trust any certificate.
        2. Click OK, OK.

        If you want to only trust requests signed by specific signing certificates, do the following actions:

        1. Next to Trusted anchor store, click New and then specify Name=MyTrustAnchor
        2. Either select a Centrally managed keystore, or under External keystore, enter the full path to your truststore, its type, and password.
        3. Click OK.
        4. Next to Trusted anchor store, select MyTrustAnchor.
        5. Click Apply.
        6. Do one of the following actions:

          If you do not need to configure intermediate certificates or Certificate Revocation Lists (CRLs), perform the following actions:

          1. Next to Certificate Store, select none.
          2. Click OK, OK.

          If you need to configure intermediate certificates or Certificate Revocation Lists (CRLs), perform the following actions:

          1. Next to Certificate store, click New and then specify name=MyCertStore
          2. For each CRL that you need to configure, enter it under Revoked certificates.
          3. For each intermediate certificate that you need to configure, enter it under Intermediate X.509 certificates.
          4. Click OK.
          5. Next to Certificate store, select MyCertStore.
          6. Click OK, OK.
  7. Configure the client to use the AsignEncPolicy policy set.
    1. In the administrative console, click Applications > Application types > WebSphere enterprise applications > JaxWSServicesSamples > Service client policy sets and bindings.
    2. Select the web services client resource (JaxWSServicesSamples).
    3. Click Attach Policy Set.
    4. Select AsignEncPolicy.
  8. Configure the client to use the MyClientGeneralBinding client general binding
    1. Select the web services resource again.
    2. Click Assign Binding, then select MyClientGeneralBinding.
  9. Configure the provider to use the AsignEncPolicy policy set.
    1. In the administrative console, click Applications > Application types > WebSphere enterprise applications > JaxWSServicesSamples > Service provider policy sets and bindings.
    2. Select the web services provider resource (JaxWSServicesSamples).
    3. Click Attach Policy Set.
    4. Select AsignEncPolicy.
  10. Configure the provider to use the MyProviderGeneralBinding provider general binding
    1. Select the web services resource again.
    2. Click Assign Binding, then select MyProviderGeneralBinding.
  11. Click Save to save your configuration changes.
  12. Restart the client and provider.
    1. Stop the client and the provider.
    2. Restart the client and the provider.
  13. Test the Service.
    1. Point your web browser at the JaxWSServicesSamples:
      http://localhost:9080/wssamplesei/demo
      Avoid trouble: Make sure that you provide the correct host name and port if your profile is not on the same machine, or the port is not 9080.
    2. Select Message Type Synchronous Echo.
    3. Make sure Use SOAP 1.2 is not selected.
    4. Enter a message and click Send Message.
    The sample application reply is JAXWS==>Message.

Results

The JaxWSServicesSamples web services application is configured to use asymmetrical XML Digital Signature and Encryption to protect your SOAP requests and responses by using client and provider named general bindings.