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.
Before you perform this task, you must have RACF set up to work with
CICS. The DFLTUSER, KEYRING, and SEC=YES system
initialization parameters should be specified in the CICS region that contains
your Web services pipelines.
- To authenticate inbound SOAP messages that are signed:
- Import the X.509 certificate into RACF as an ICSF key.
- 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.
- 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. You should 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 (this is the certificate label in RACF),
a combination of the ISSUER and SERIAL number, or the SubjectKeyIdentifier.
CICS can only recognize the SubjectKeyIdentifier if this has been specified
as an attribute in the definition of the certificate in RACF.
- To sign outbound SOAP messages:
- 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: < > : ! =
- Attach the certificate to the key ring specified in the KEYRING system
initialization parameter. Use the RACDCERT command.
- 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.
- 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.
- Generate a public-private key pair and certificate in RACF for
encryption. The key pair and certificate should be generated using
ICSF.
- Attach the certificate to the key ring specified in the KEYRING system
initialization parameter. Use the RACDCERT command.
- 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 only recognize the SubjectKeyIdentifier if this has been specified
as an attribute in the definition of the public key in RACF.
- To encrypt outbound SOAP messages:
- Import the certificate that contains the public key that you
want to use for encryption into RACF as an ICSF key. The intended
recipient should have the private key associated with the public key to decrypt
the SOAP message.
- 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. This is defined in the
pipeline configuration file.