Configuring CICS for Web Services Security

To configure CICS for Web Services Security (WSS), you must add a WSS handler to your pipeline configuration files.

Before performing this task, you must identify or create the pipeline configuration files to which you will add configuration information for WSS.
  1. Add a <wsse_handler> element to your pipeline. Start of changeThe handler must be included in the <service_handler_list> element in a service provider or requester pipeline.End of change Code the following elements:
    <wsse_handler>
      <dfhwsse_configuration version="1">
    
      </dfhwsse_configuration>
    </wsse_handler> 
    The <dfhwsse_configuration> element is a container for the other elements in the configuration file.
  2. Optional: Code an <authentication> element.
    • In a service requester pipeline, the <authentication> element specifies that CICS should add an X.509 certificate to the security header in outbound SOAP messages.
    • In a service provider pipeline, the element specifies whether CICS should use the security tokens in an inbound SOAP message to determine the user ID under which work will be processed.
    1. Code the trust attribute to specify whether asserted identity is used, and the nature of the trust relationship between service provider and requester. For details of the trust attribute, see The <authentication> element.
    2. Optional: If you specified trust=none, code the mode attribute to specify how credentials found in the message are processed. For details of the mode attribute, see The <authentication> element.
    3. Within the <authentication> element, code the following:
      1. An optional <certificate_label> element that specifies the label associated with an X.509 digital certificate installed in RACF®. If this element is specified in a service requester pipeline, and the <suppress> element is not specified, the certificate is added to the security header in the SOAP message. If you do not specify a <certificate_label> element, CICS® uses the default certificate in the RACF key ring. The certificate label should not contain any of the following characters:
        < > : ! =

        This element is ignored in a service provider pipeline.

      2. An optional, empty <suppress/> element.

        If this element is specified in a service provider pipeline, the handler will not attempt to use any security tokens in the message to determine under which user ID the work will run.

        If this element is specified in a service requester pipeline, the handler will not attempt to add to the outbound SOAP message any of the security tokens that are required for authentication.

      3. Start of changeAn <algorithm> element that specifies the URI of the algorithm used to sign the body of the SOAP message.
        You can specify the following algorithms:
        Algorithm URI
        Digital Signature Algorithm with Secure Hash Algorithm 1 (DSA with SHA1) http://www.w3.org/2000/09/xmldsig#dsa-sha1
        Rivest-Shamir-Adleman algorithm with Secure Hash Algorithm 1 (RSA with SHA1) http://www.w3.org/2000/09/xmldsig#rsa-sha1

        The DSA with SHA1 signature algorithm is supported on inbound SOAP messages only. If you are using basic authentication on inbound SOAP messages, you must still specify the <algorithm> element.

        End of change
  3. Optional: If you require inbound SOAP messages to be digitally signed, code an empty <expect_signed_body/> element.

    The <expect_signed_body/> element indicates that the <body> of the inbound message must be signed. If the body of an inbound message is not correctly signed, CICS rejects the message with a security fault.

  4. Optional: If you require inbound SOAP messages to be encrypted, code an empty <expect_encrypted_body/> element.

    The <expect_encrypted_body/> element indicates that the <body> of the inbound message must be encrypted. If the body of an inbound message is not correctly encrypted, CICS rejects the message with a security fault.

  5. Optional: If you require outbound SOAP messages to be signed, code a <sign_body> element.
    1. Within the <sign_body> element, code an <algorithm> element.
    2. Following the <algorithm> element, code a <certificate_label> element.
    This is an example of a completed <sign_body> element:
    <sign_body>
      <algorithm>http://www.w3.org/2000/09/xmldsig#rsa-sha1</algorithm>
      <certificate_label>SIGCERT01</certificate_label>
    </sign_body>
  6. Optional: If you require outbound SOAP messages to be encrypted, code an <encrypt_body> element.
    1. Within the <encrypt_body> element, code an <algorithm> element.
    2. Following the <algorithm> element, code a <certificate_label> element.
    This is an example of a completed <encrypt_body> element:
    <encrypt_body>
      <algorithm>http://www.w3.org/2001/04/xmlenc#tripledes-cbc</algorithm>
      <certificate_label>ENCCERT02</certificate_label>
    </encrypt_body>

Example

The following example shows a completed <wsse_handler> in which all the optional elements are present:Start of change
<wsse_handler>
    <dfhwsse_configuration version="1">
      <authentication trust="signature" mode="basic">
        <certificate_label>AUTHCERT03</certificate_label>
        <suppress/>
      </authentication>
      <expect_signed_body/>
      <expect_encrypted_body/>
      <sign_body>
        <algorithm>http://www.w3.org/2000/09/xmldsig#rsa-sha1</algorithm>
        <certificate_label>SIGCERT01</certificate_label>
      </sign_body> 
      <encrypt_body> 
        <algorithm>http://www.w3.org/2001/04/xmlenc#tripledes-cbc</algorithm>
        <certificate_label>ENCCERT02</certificate_label>
      </encrypt_body>		
    </dfhwsse_configuration>
</wsse_handler> 
End of change