Configuring a policy set and bindings for Asymmetric XML Digital Signature or XML Encryption by using application-specific bindings

This procedure describes how to configure the message-level WS-Security policy set and bindings to sign and encrypt a SOAP message using asymmetric XML Digital Signature and Encryption with application specific bindings. As part of this procedure you must specify whether you will sign and/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 this application, see Obtaining the JAX-WS Web Services samples.

You should use the following trace specification on your server. These specifications enable you 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 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 the actions you need to complete to configure asymmetric XML Digital Signature and Encryption application specific custom bindings for a client and provider.

The keystores that are used in this procedure are provided with WebSphere® Application Server and are installed in every profile that is created. You can use the ${USER_INSTALL_ROOT} variable directly in the configuration to conveniently point to the keystore locations without using a fully qualified path. ${USER_INSTALL_ROOT} resolves to a path such as c:/WebSphere/AppServer/profiles/AppSrv01.

${USER_INSTALL_ROOT}/etc/ws-security/samples/dsig-sender.ks
${USER_INSTALL_ROOT}/etc/ws-security/samples/dsig-receiver.ks
${USER_INSTALL_ROOT}/etc/ws-security/samples/enc-sender.jceks
${USER_INSTALL_ROOT}/etc/ws-security/samples/enc-receiver.jceks

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 using 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 > (App Name)
Services > Service Clients > (App Name)

Avoid trouble: Pay close attention to the names of the token consumers and generators in the administrative console. The Initiator and recipient might not be what you think they should be for the tokens. The usage column in the table specifies whether a token is a consumer token or a generator token.

Procedure

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.
Edit the custom policy set.
1. In the administrative console, click WS-Security > Main Policy.
  By default, the policy will now have 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, unselect the Include timestamp in security header setting, and then click Apply.
3. Optional: Remove request message parts.
  1. Under Message level protection, click Request message part protection.
  2. To remove the request encrypted part, click app_encparts, and then click Delete.
  3. To remove the request signed part, click app_signparts, and then click Delete.
  4. Click Done.
4. Optional: Remove response message parts.
  1. Under Message level protection, click Response message part protection.
  2. To remove the response encrypted part, click app_encparts, and then click Delete.
  3. To remove the response signed part, 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 will be 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.
    
    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 will be 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 will be 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()='http://www.w3.org/2000/09/xmldsig#' and local-name()='Signature'] /*[namespace-uri()='http://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 will be 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 will be 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.
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.
Create a custom binding for the client.
1. Select the web services resource again.
2. Click Assign Binding.
3. Click New Application Specific Binding to create an application-specific binding.
4. Specify the bindings configuration name.
  
  name: signEncClientBinding
5. Click Add > WS-Security.
6. If the Main Message Security Policy Bindings panel does not display, select WS-Security.
Configure the client's custom bindings.
1. Configure a Certificate Store.
  1. Click Keys and Certificates.
  2. Under Certificate store, click New Inbound... .
  3. Specify name=clientCertStore.
  4. Specify Intermediate X.509 certificate=${USER_INSTALL_ROOT}/etc/ws-security/samples/intca2.cer
  5. Click OK.
2. Configure a Trust Anchor.
  1. Under Trust anchor, click New...
  2. Specify name=clientTrustAnchor
  3. Click External Keystore .
  4. Specify Full path=${USER_INSTALL_ROOT}/etc/ws-security/samples/dsig-sender.ks.
  5. Specify Password=client.
  6. Click OK.
  7. Click WS-Security in the navigation for this page.
3. Optional: If Signing the request message, complete the following actions.
  1. Configure the Signature Generator.
    1. Click Authentication and protection > AsymmetricBindingInitiatorSignatureToken0 (signature generator), and then click Apply.
    2. Click Callback handler
    3. Specify Keystore=custom.
    4. Click Custom keystore configuration, and then specify
      
      Full path==${USER_INSTALL_ROOT}/etc/ws-security/samples/dsig-sender.ks
      
      Keystore password=client
      
      Name=client
      
      Alias=soaprequester
      
      Password=client
    5. Click OK, OK, and OK.
  2. Configure the request Signing Information.
    1. Click request:app_signparts, and specify Name=clientReqSignInfo.
    2. Under Signing Key Information, click New , and then specify:
      
      Name=clientReqSignKeyInfo
      
      Type=Security Token reference
      
      Token generator or consumer name=AsymmetricBindingInitiatorSignatureToken0
    3. Click OK, and then click Apply.
    4. Under Message part reference, select request:app_signparts .
    5. Click Edit.
    6. Under Transform algorithms, click New
    7. Specify URL=http://www.w3.org/2001/10/xml-exc-c14n#.
    8. Click OK, OK, and OK.
4. Optional: If Signing the response message, complete the following actions.
  1. Configure the Signature Consumer.
    1. Click AsymmetricBindingRecipientSignatureToken0 (signature consumer), and then click Apply.
    2. Click Callback handler
    3. Under Certificates, click the Certificate store radio button, and specify:
      
      Certificate store=clientCertStore
      
      Trusted anchor store=clientTrustAnchor
    4. Click OK and OK.
  2. Configure the response Signing Information.
    1. Click response:app_signparts, and specify Name=clientRspSignInfo.
    2. Click Apply.
    3. Under Signing Key Information, click New, and then specify:
      
      Name=clientReqSignKeyInfo
      
      Token generator or consumer name=AsymmetricBindingInitiatorSignatureToken0
    4. Click OK.
    5. Under Signing Key Information, click clientRspSignKeyinfo, and then click Add.
    6. Under Message part reference, select response:app_signparts .
    7. Click Edit.
    8. Under Transform algorithms, click New
    9. Specify URL=http://www.w3.org/2001/10/xml-exc-c14n#.
    10. Click OK, OK, and OK.
5. Optional: If Encrypting the request message, complete the following actions.
  1. Configure the Encryption Generator.
    1. Click AsymmetricBindingRecipientEncryptionToken0 (encryption generator), and then click Apply.
    2. Click Callback handler, and specify Keystore=custom.
    3. Click Custom keystore configuration, and then specify
      
      Full path==${USER_INSTALL_ROOT}/etc/ws-security/samples/enc-sender.jceks
      
      Type=JCEKS
      
      Keystore password=storepass
      
      Key Name=bob
      
      Key Alias=bob
    4. Click OK, OK, and OK.
  2. Configure the request Encryption Information.
    Avoid trouble: The setting for Usage of key information references must be set to Key encryption, which is the default value. Data encryption is used for Symmetric encryption.
    1. Click request:app_encparts, and specify Name=clientReqEncInfo.
    2. Click Apply.
    3. Under Key Information, click New, and then specify
      
      Name=clientReqEncKeyInfo
      
      Type=Key_identifier
      
      Token generator or consumer name=AsymmetricBindingRecipientEncryptionToken0
    4. Click OK.
    5. Under Key Information, select clientReqEncKeyInfo, and then click OK.
6. Optional: If Encrypting the response message, complete the following actions.
  1. Configure the Encryption Consumer.
    1. Click AsymmetricBindingInitiatorEncryptionToken0 (encryption consumer), and then click Apply.
    2. Click Callback handler, and specify Keystore=custom.
    3. Click Custom keystore configuration, and then specify
      
      Full path==${USER_INSTALL_ROOT}/etc/ws-security/samples/enc-sender.jceks
      
      Type=JCEKS
      
      Keystore password=storepass
      
      Key Name=alice
      
      Key Alias=alice
      
      Key password=keypass
    4. Click OK and OK.
  2. Configure the response Encryption Information.
    Avoid trouble: The setting for Usage of key Information references must be set to Key encryption, which is the default value. Data encryption is used for Symmetric encryption.
    1. Click response:app_encparts, and specify Name=clientRspEncInfo.
    2. Click Apply.
    3. Under Key Information, click New, and then specify
      
      Name=clientRspEncKeyInfo
      
      Token generator or consumer name=AsymmetricBindingRecipientEncryptionToken0
    4. Click OK.
    5. Under Key Information, select clientRspEncKeyInfo.
    6. Click Add, and then click OK.
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.
Create a custom binding for the provider.
1. Select the web services provider resource again.
2. Click Assign Binding.
3. Click New Application Specific Binding to create an application-specific binding.
4. Specify Bindings configuration name: signEncProviderBinding.
5. Click Add > WS-Security.
6. If the Main Message Security Policy Bindings panel does not display, select WS-Security.
Configure the custom bindings for the provider.
1. Configure a Certificate Store.
  1. Click Keys and Certificates.
  2. Under Certificate store, click New Inbound....
  3. Specify:
    - Name=providerCertStore
    - Intermediate X.509 certificate=${USER_INSTALL_ROOT}/etc/ws-security/samples/intca2.cer
  4. Click OK.
2. Configure a Trust Anchor.
  1. Under Trust anchor, click New...
  2. Specify, Name=providerTrustAnchor.
  3. Click External Keystore, and specify:
    - Full path=${USER_INSTALL_ROOT}/etc/ws-security/samples/dsig-receiver.ks
    - Password=server
  4. Click OK, and then click WS-Security in the navigation for this page, and then click Authentication and protection.
3. Optional: If Signing the request message, complete the following actions.
  1. Configure the Signature consumer.
    1. Click AsymmetricBindingInitiatorSignatureToken0 (signature consumer), and then click Apply.
    2. Click Callback handler.
    3. Under Certificates, click the Certificate store radio button, and specify:
      
      Certificate store=providerCertStore
      
      Trusted anchor store=providerTrustAnchor
    4. Click OK.
    5. Click Authentication and protection in the navigation for this page.
  2. Configure the request Signing Information.
    1. Click request:app_signparts, and specify Name=reqSignInfo.
    2. Click Apply.
    3. Under Signing Key Information, click New, and specify:
      
      Name=reqSignKeyInfo
      
      Token generator or consumer
      
      name=AsymmetricBindingInitiatorSignatureToken0
    4. Click OK.
    5. Under Signing Key Information, click reqSignKeyinfo, and then click Add.
    6. Under Message part reference, select request:app_signparts.
    7. Click Edit.
    8. Under Transform algorithms, click New, and then specify URL=http://www.w3.org/2001/10/xml-exc-c14n#.
    9. Click OK, OK, and OK.
4. Optional: If Signing the response message, complete the following actions.
  1. Configure the Signature Generator.
    1. Click AsymmetricBindingRecipientSignatureToken0 (signature generator), and then click Apply.
    2. Click Callback handler > Custom keystore configuration, and specify:
      
      Full path=${USER_INSTALL_ROOT}/etc/ws-security/samples/dsig-receiver.ks
      
      Keystore password=server
      
      Name=server
      
      Alias=soapprovider
      
      Password=server
    3. Click OK, OK, and OK.
  2. Configure the response Signing Information.
    1. Click response:app_signparts, and specify Name=rspSignInfo.
    2. Under Signing Key Information, click New, and specify:
      
      Name=rspSignKeyInfo
      
      Type=Security Token reference
      
      Token generator or consumer
      
      name=AsymmetricBindingRecipientSignatureToken0
    3. Click OK, and then click Apply.
    4. Under Message part reference, select response:app_signparts.
    5. Click Edit.
    6. Under Transform algorithms, click New, and then specify URL=http://www.w3.org/2001/10/xml-exc-c14n#.
    7. Click OK, OK, and OK.
5. Optional: If Encrypting the request message, complete the following actions.
  1. Configure the Encryption Consumer.
    1. Click AsymmetricBindingRecipientEncryptionToken0 (encryption consumer), and then click Apply.
    2. Click Callback handler, and specify Keystore=custom
    3. Click Custom keystore configuration, and specify:
      
      Full path==${USER_INSTALL_ROOT}/etc/ws-security/samples/enc-receiver.jceks
      
      Type=JCEKS
      
      Keystore password=storepass
      
      Key Name=bob
      
      Key Alias=bob
      
      Key password=keypass
    4. Click OK, OK, and OK.
  2. Configure the request Encryption Information.
    Avoid trouble: The setting for Usage of key information references must be set to Key encryption, which is the default value. Data encryption is used for Symmetric encryption.
    1. Click request:app_encparts, and specify Name=reqEncInfo.
    2. Click APPLY
    3. Under Key Information, click New, and specify:
      
      Name=reqEncKeyInfo
      
      Type=Key identifier
      
      Token generator or consumer
      
      name=AsymmetricBindingRecipientEncryptionToken0
    4. Click OK.
    5. Under Key Information, select reqEncKeyInfo.
    6. Click Add, and then click OK.
6. Optional: If Encrypting the response message, complete the following actions.
  1. Configure the Encryption Generator.
    1. Click AsymmetricBindingInitiatorEncryptionToken0 (encryption generator), and then click Apply.
    2. Click Callback handler, and specify Keystore=custom
    3. Click Custom keystore configuration, and specify:
      
      Full path==${USER_INSTALL_ROOT}/etc/ws-security/samples/enc-receiver.jceks
      
      Type=JCEKS
      
      Keystore password=storepass
      
      Key Name=alice
      
      Key Alias=alicee
    4. Click OK, OK, and OK.
  2. Configure the request Encryption Information.
    Avoid trouble: The setting for Usage of key information references must be set to Key encryption, which is the default value. Data encryption is used for Symmetric encryption.
    1. Click response:app_encparts, and specify Name=rspEncInfo.
    2. Click APPLY
    3. Under Key Information, click New, and specify:
      
      Name=rspEncKeyInfo
      
      Token generator or consumer
      
      name=AsymmetricBindingInitiatorEncryptionToken0
    4. Click OK.
    5. Under Key Information, select rspEncKeyInfo.
    6. Click OK.
Click Save to save your configuration changes.
Restart the client and provider.
1. Stop the client and the provider.
2. Restart the client and the provider.
Test the Service.
1. Point your web browser at the JaxWSServicesSamples:
  http://localhost:9080/wssamplesei/demo
  Avoid trouble: Make sure you provide the correct hostname 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 should reply with 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.