Configuring RACF for Web Services Security

You must configure an external security manager, such as RACF®, to create public-private key pairs and X.509 certificates for signing and encrypting outbound SOAP messages and to authenticate and decrypt signed and encrypted inbound SOAP messages.

1. To authenticate inbound SOAP messages that are signed:
   1. Import the X.509 certificate into RACF as an ICSF key.
   2. Attach the certificate to the key ring specified in the KEYRING system initialization parameter, using the RACDCERT command:

      RACDCERT ID(userid1)
      CONNECT(ID(userid2) LABEL('label-name') RING(ring-name)

      where:

      • userid1 is the default user ID of the key ring or has authority to attach certificates to the key ring for other user IDs.
      • userid2 is the user ID that you want to associate with the certificate.
      • label-name is the name of the certificate.
      • ring-name is the name of the key ring that is specified in the KEYRING system initialization parameter.
   3. Optional: If you want to use asserted identities, ensure that the user ID associated with the certificate has surrogate authority to allow work to run under other user IDs.
      Also, make sure that any additional certificates included in the SOAP message header are also imported into RACF.
   The SOAP message can contain a binary security token in the header that either includes the certificate or contains a reference to the certificate. This reference can be the KEYNAME (the certificate label in RACF), a combination of the ISSUER and SERIAL number, or the SubjectKeyIdentifier. CICS can recognize the SubjectKeyIdentifier only if it has been specified as an attribute in the definition of the certificate in RACF.
2. To sign outbound SOAP messages:
   1. Create an X.509 certificate and a public-private key pair using the following RACDCERT command:

      RACDCERT ID(userid2) GENCERT
      SUBJECTSDN(CN('common-name')
                 T('title')
                 OU('organizational-unit')
                 O('organization')
                 L('locality')
                 SP('state-or-province')
                 C('country'))
      WITHLABEL('label-name')

      where userid2 is the user ID that you want to associate with the certificate.
      When you specify the certificate label-name value, do not use the following characters:

      < > : ! =

   2. Attach the certificate to the key ring specified in the KEYRING system initialization parameter.
      Use the RACDCERT command.
   3. Export the certificate and publish it to the intended recipient of the SOAP message.
   You can edit the pipeline configuration file so that CICS automatically includes the X.509 certificate in the binary security token of the SOAP message header for the intended recipient to validate the signature.
3. To decrypt inbound SOAP messages that are encrypted, the SOAP message must include the public key that is part of a key pair, where the private key is defined in CICS.
   1. Generate a public-private key pair and certificate in RACF for encryption.
      The key pair and certificate must be generated using ICSF.
   2. Attach the certificate to the key ring specified in the KEYRING system initialization parameter. Use the RACDCERT command.
   3. Export the certificate and publish it to the generator of the SOAP messages that you want to decrypt.
   The generator of the SOAP message can then import the certificate that contains the public key and use it to encrypt the SOAP message. The SOAP message can contain a binary security token in the header that either includes the public key or contains a reference to it. This reference can be the KEYNAME, a combination of the ISSUER and SERIAL number, or the SubjectKeyIdentifier. CICS can recognize the SubjectKeyIdentifier only if it has been specified as an attribute in the definition of the public key in RACF.
4. To encrypt outbound SOAP messages:
   1. Import the certificate that contains the public key that you want to use for encryption into RACF as an ICSF key.
      The intended recipient must have the private key associated with the public key to decrypt the SOAP message.
   2. Attach the certificate that contains the public key to the key ring specified in the KEYRING system initialization parameter. Use the RACDCERT command.
   CICS uses the public key in the certificate to encrypt the SOAP body and sends the certificate containing the public key as a binary security token in the SOAP message header. The public key is defined in the pipeline configuration file.