Configure a policy set and bindings for Asymmetric XML Digital Signature and/or XML Encryption

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 specify whether you will sign and/or encrypt both the request and response messages.

This task assumes that the service provider and client that we are configuring are in the JaxWSServicesSamples application. Refer to the topic Access Samples for more information on how to obtain and install this application.

You should use the following trace specification on the server. These specifications allow us 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:

This procedure explains the actions we 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 we need to complete to configure asymmetric XML Digital Signature and Encryption application specific custom bindings for a client and provider.

The keystores used in this procedure are provided with WebSphere Application Server and are installed in every profile created. 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 console click Applications > Application types > WebSphere enterprise applications > JaxWSServicesSamples. When using our own applications, we 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 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.gotcha

1. Create the custom policy set.

   1. In the 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 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 you want, click Apply, then Save, and continue to the next step.

      To change this configuration, complete one or more of the following substeps.

   2. Optional: Remove Timestamp from both request and response. We 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. We 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 we would like to add encryption of a UsernameToken, SAML Assertion, or other elements, see Build XPath expressions for WS-Security.

         When we finish making the 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. We 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 we 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 we would like to sign other elements, such as a BinarySecurityToken, see Build XPath expressions for WS-Security.

         When we finish making the 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. We 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 we finish making the 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. We 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 we finish making the changes, click OK.

      4. Click Done.

   7. Click Apply.

   8. Save the configuration.

3. Configure the client to use the AsignEncPolicy policy set.

   1. In the 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.

4. 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.

5. 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...

      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...

      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...

      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.

         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. gotcha

         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...

      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.

         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. gotcha

         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.

6. Configure the provider to use the AsignEncPolicy policy set.

   1. In the 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.

7. 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.

8. 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...

      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...

      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...

      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.

         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. gotcha

         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...

      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.

         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. gotcha

         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.

9. Click Save to save the configuration changes.

10. Restart the client and provider.

    1. Stop the client and the provider.

    2. Restart the client and the provider.

11. Test the Service.

    1. Point the web browser at the JaxWSServicesSamples: http://localhost:9080/wssamplesei/demo

       Avoid trouble: Make sure we provide the correct hostname and port if the profile is not on the same machine, or the port is not 9080.gotcha

    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.

Related concepts

Access the samples

Related tasks

Secure web services using policy sets

Build XPath expressions for WS-Security