[z/OS]

Modifying the certificate validation mode on z/OS

How you use the GSK_CERT_VALIDATION_MODE environment variable to modify the certificate validation mode on z/OS® when moving to TLS 1.3.

When establishing a TLS connection, the internet standard used to validate certificates depends on the value of the GSK_CERT_VALIDATION_MODE environment variable. For more information, see Environment variables in the z/OS Cryptographic Services System SSL Programming documentation.

  • A value of 2459 specifies certificate validation against RFC 2459 only .
  • A value of 3280 specifies certificate validation against RFC 3280 only.
  • A value of 5280 specifies certificate validation against RFC 5280 only.
  • A value of ANY specifies certificate validation against RFC 2459 initially. If that fails, validate against RFC 3280 and if that fails, validate against RFC 5280.

The default value is ANY unless TLS 1.3 is negotiated for a secure connection. In that case, certificate validation is done according to RFC 5280 unless explicitly specified.

In some circumstances (for example, when moving to TLS 1.3 and using existing certificates that include an Extended Key Usage extension without the clientAuth usage) it is necessary to specify a different validation mode by changing the value of the GSK_CERT_VALIDATION_MODE environment variable (that is, for the example given, GSK_CERT_VALIDATION_MODE=2459). The changed value will be applied for all TLS channels.

You can set this TLS environment variable in the channel initiator startup JCL, using the CEEOPTS DD statement:
CEEOPTS DD DSN=<dataset-name>,DISP=SHR
In the dataset referenced in this example, specify the list that you want to use, for example:
ENVAR("GSK_CERT_VALIDATION_MODE=2459")
Important: Do not use this CEEOPTS statement with in-stream data, as this prevents the environment variable from being set for all TLS tasks using that statement.

Ensure that you reference a sequential dataset, or partitioned dataset member, to allow this to work when using an SSLTASKS value greater than one.

Important: Important: You must apply the fix in z/OS APAR OA68554 to allow the validation mode setting to be used when checking the extended key usage in a TLS 1.3 environment.