Setting the System SSL environment for CICS

CICS managed TLS connections are processed using the z/OS System SSL services. The System SSL environment is controlled by using either environment variables or the GSK API commands. CICS uses the API commands directly, which means that values set by CICS cannot be overridden by externally set environment variables.

You update System SSL environment variables in different ways, depending on whether they are set by CICS or not.

For a complete list of environment variables used by System SSL, see Environment variables in z/OS documentation.

Updating System SSL variables that are set by CICS

The following table lists the System SSL variables that are set by CICS and the value they are set to. Some values are fixed and some can be modified by changing the value specified on the associated CICS parameter.

Table 1. System SSL variables set by CICS
Variable name	Value
GSK_KEYRING_FILE	The KEYRING SIT parameter
GSK_KEYRING_LABEL	The `CERTIFICATE` label specified on the associated command or resource for a particular request
GSK_V3_CIPHER_SPECS	The list of 2-digit ciphers if a cipher file is not used
GSK_V3_CIPHER_SPECS_EXPANDED	The list of 4-digit ciphers from the associated cipher file
GSK_V2_SESSION_TIMEOUT	60
GSK_V3_SESSION_TIMEOUT	The SSLDELAY SIT parameter
GSK_PROTOCOL_SSLV2	OFF
GSK_PROTOCOL_SSLV3	OFF
GSK_PROTOCOL_TLSV1	OFF
GSK_PROTOCOL_TLSV1_1	ON or OFF based on the MINTLSLEVEL SIT parameter
GSK_PROTOCOL_TLSV1_2	ON or OFF based on the MINTLSLEVEL SIT parameter
GSK_CLIENT_EPHEMERAL_DH_GROUP_SIZE	2048 only if feature toggle `com.ibm.cics.tls.minimumkeystrength` is set to 2048 (the default is 1024). Otherwise, the system default value is used.
GSK_SERVER_EPHEMERAL_DH_GROUP_SIZE	2048 only if feature toggle `com.ibm.cics.tls.minimumkeystrength` is set to 2048 (the default is 1024). Otherwise, the system default value is used.
GSK_PEER_DH_MIN_KEY_SIZE	2048 only if feature toggle `com.ibm.cics.tls.minimumkeystrength` is set to 2048 (the default is 1024). Otherwise, the system default value is used.
GSK_PEER_DSA_MIN_KEY_SIZE	2048 only if feature toggle `com.ibm.cics.tls.minimumkeystrength` is set to 2048 (the default is 1024). Otherwise, the system default value is used.
GSK_PEER_RSA_MIN_KEY_SIZE	2048 only if feature toggle `com.ibm.cics.tls.minimumkeystrength` is set to 2048 (the default is 1024). Otherwise, the system default value is used.
GSK_PEER_ECC_MIN_KEY_SIZE	256 only if feature toggle `com.ibm.cics.tls.minimumkeystrength` is set to 2048 (the default is 1024). Otherwise, the system default value is used.
GSK_CLIENT_ECURVE_LIST	00250024002300300029 either when feature toggle `com.ibm.cics.tls.minimumkeystrength` is set to 2048 (the default is 1024). Otherwise, the system default value is used.
GSK_SERVER_ALLOWED_KEX_ECURVES	00250024002300300029 only if feature toggle `com.ibm.cics.tls.minimumkeystrength` is set to 2048 (the default is 1024). Otherwise, the system default value is used.
GSK_CLIENT_TLS_KEY_SHARES	00250024002300300029 if TLS 1.3 is used
GSK_SERVER_TLS_KEY_SHARES	00250024002300300029 if TLS 1.3 is used
GSK_LDAP_SERVER	The LDAP server URL that is obtained from the profile specified on the CRLPROFILE SIT parameter. It is set only if CRL processing is required and CRLPROFILE specifies a valid profile in the LDAPBIND resource class.
GSK_LDAP_USER	The LDAP user distinguished name that is obtained from the profile specified on the CRLPROFILE SIT parameter. It is set only if CRL processing is required and CRLPROFILE specifies a valid profile in the LDAPBIND resource class.
GSK_LDAP_USER_PW	The LDAP user password that is obtained from the profile specified on the CRLPROFILE SIT parameter. It is set only if CRL processing is required and CRLPROFILE specifies a valid profile in the LDAPBIND resource class.
GSK_SYSPLEX_SIDCACHE	ON if the SSLCACHE SIT parameter is set to `SYSPLEX`.

Updating System SSL variables that are not set by CICS

If a System SSL variable is not set by CICS, CICS uses the System SSL default value for that variable. You can change the default values that are used by CICS in either of the following ways:

Update CELQDOPT in the CEEPRMxx parmlib member to add an ENVAR statement that sets the required variable. This affects all 64-bit applications that use System SSL services, not just CICS applications. For detailed instructions, see Creating system-level runtime options and keyword defaults with CEEPRMxx in z/OS documentation.
Add a CEEOPTS DD statement to the CICS JCL. CEEOPTS needs to reference a data set or member that contains an ENVAR statement. This affects System SSL and JVM servers within CICS.
```
ENVAR("GSK_PEER_CERT_MIN_VERSION=3")
```