Start of change

The options for securing SOAP messages

CICS supports both signing and encrypting SOAP messages, so you can select the level of security that is most appropriate for the data that you are sending or receiving in the SOAP message.

The options that you can choose from are:

Basic authentication
In service provider mode, CICS can accept a username token in the SOAP message header for authentication on inbound SOAP messages. This is a type of security token that is comprised of a user name and password. CICS verifies the user name token using an external security manager such as RACF. If successful, the user name is placed in container DFHWS-USERID and the SOAP message is processed in the pipeline. If CICS is unable to verify the username token, a SOAP fault message is returned to the service requester.

Username tokens are not supported in service requester mode or on outbound SOAP messages.

Signing with X.509 certificates
In service provider and service requester mode, you can provide an X.509 certificate in the SOAP message header to sign the body of the SOAP message for authentication. This is a type of security token that is known as a binary security token. To accept binary security tokens from inbound SOAP messages, the public key associated with the certificate must be imported into an external security manager, such as RACF, and associated with the key ring that is specified in the KEYRING system initialization parameter. For outbound SOAP messages, you need to generate and publish the public key to the intended recipients. The Integrated Cryptographic Service Facility (ICSF) is used to generate public keys.
When you specify the label associated with an X.509 digital certificate, do not use the following characters:
< > : ! =

You can also include a second X.509 certificate in the header and sign it using the first certificate. This allows you to run the work in CICS under the user ID associated with the second X.509 certificate. The certificate that you are using to sign the SOAP message must be associated with a trusted user ID, and have surrogate authority in order to assert that work should run under a different identity, the asserted identity, without the trusted user ID having the password associated with that identity.

Encrypting
In service provider and service requester mode, you can encrypt the SOAP message body using a symmetric algorithm such as Triple DES or AES. A symmetric algorithm is where the same key is used to encrypt and decrypt the data. This key is known as asymmetric key. It is then included in the message and encrypted using a combination of the intended recipient's public key and the asymmetric key encryption algorithm RSA 1.5. This provides you with increased security, because the asymmetric algorithm is complex and it is difficult to decrypt the symmetric key. However, you get better performance because the majority of the SOAP message is encrypted with the symmetric algorithm which is faster to decrypt.

For inbound SOAP messages, it is possible to encrypt an element in the SOAP body and then encrypt the SOAP body as a whole. This might be particularly appropriate for an element that contains sensitive data. If CICS receives a SOAP message with two levels of encryption, CICS decrypts both levels automatically. This is not supported for outbound SOAP messages.

CICS does not support inbound SOAP messages that only have an encrypted element in the message header and no encrypted elements in the SOAP body.

Signing and encrypting
In service provider and service requester mode, you can choose to both sign and encrypt a SOAP message. CICS always signs the SOAP message body first and then encrypts it. The advantage of this method is that it gives you both message confidentiality and integrity.
End of change