SSL Support for CICS Web Interface Servers

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 %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src for Windows environments. For Unix environments, the corresponding location is $COBDIR/copylib.

Note that the example provided contains keyfile passwords in plain text. 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.