Setting Environment Variables
To activate SSL Support for CWI Servers, the following environment variables need to be set:
- ES_CERTIFICATES_LOCATION
- For CICS as an HTTP server, this should be set to the location of your server certificates.
- For CICS as an HTTP client, this should be set to the location of your client certificates.
- ES_DFLT_CERTIFICATE_NAME_SERVER
- This should be set to the label for the certificate that CICS will use when no name has been specified in the TCPIPSERVICE
for the
CERTIFICATE attribute.
- ES_DFLT_CERTIFICATE_NAME_CLIENT
- This should be set to the label for the certificate that CICS will use if a
WEB OPEN:
- Doesn't specify the
CERTIFICATE option AND
- Doesn't specify the
URIMAP option OR the specified
URIMAP doesn't contain a
CERTIFICATE label.
Certificate labels should be the name of the certificate file with no extension. The key file should have the same name as
the certificate with
_key appended, retaining its extension.
For example, if you have a certificate called
srvcert.pem:
- Name the keyfile
srvcert_key.pem.
- Set
ES_DFLT_CERTIFICATE_NAME_SERVER = srvcert.
- The folder pointed to by
ES_CERTIFICATES_LOCATION will contain the following files:
- srvcert.pem
- srvcert_key.pem
Customizing the
ESCERTPAS User Exit
To complete the SSL configuration, you also need to customize the
ESCERTPAS.CBL User Exit.
ESCERTPAS is called:
- Whenever a listener is started for an SSL-enabled
TCPIPSERVICE.
- On every
WEB OPEN that uses SCHEME(HTTPS).
When an SSL listener is being started,
ESCERTPAS needs to return:
- The passphrase for the keyfile of the server certificate that is going to be used.
- The fully-qualified CA root certificate file which contains trusted CA root certificates that were used to sign any client
certificates that may use this connection (only required where the
TCPIPSERVICE specified CLIENTAUTH).
On a
WEB OPEN where client authentication is required,
ESCERTPAS should return:
- The passphrase for the keyfile of the client certificate that is going to be used.
- The fully-qualified CA root certificate file which contains a trusted CA root certificate that was used to sign the server
certificate for this connection.
On a
WEB OPEN where client authentication is not required,
ESCERTPAS only needs to return:
- The fully-qualified CA root certificate/file which contains a trusted CA root certificate that was used to sign the server
certificate for this connection.
A full example of
ESCERTPAS.CBL is provided in
$COBDIR\copylib.
Note: The example provided contains keyfile passwords in plain text. However, this is not recommended; the exit should acquire the
password securely.
Client certificates and CA root certificates that were used to sign server certificates will need to be added to your browser
in order to be used when accessing the
TCPIPSERVICE port using the HTTPS URL.
Note: The newly-compiled
ESCERTPAS should replace the one shipped with the product. If you are using CICS as a web client, then this needs to happen on the
client machine as well.