Environment variables

A value of 0 or OFF indicates that the CDP extension is queried before examining the AIA extension. This means that the HTTP servers specified in the URI values of the CDP extension is contacted before attempting to contact the OCSP responders in the AIA extension or the OCSP responder specified in GSK_OCSP_URL.

The default value is ON.

Specify OFF or 0 if SAF key ring certificates are only validated to the trust anchor certificate. If a sole intermediate certificate is found in a SAF key ring and the next issuer is not found in the same SAF key ring, the intermediate certificate acts as a trust anchor and the certificate chain is considered complete. By default, SAF key ring certificates are only validated to the trust anchor certificate. This setting does not affect the validation of SSL key database file, PKCS #12 file, or PKCS #11 token certificates because these certificates are always validated to the root CA certificate. The default value is OFF.

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 - if that fails, validate against RFC 5280. The default value is ANY.

Specifies the list of elliptic curves that are supported by the client as a string consisting of 1 or more 4-character values in order of preference for use. The list is used by the client to guide the server as to which elliptic curves are preferred when using ECC-based cipher suites for TLS V1.0 and higher protocols.

Only NIST recommended curves can be specified. To use Brainpool standard curves for an SSL environment or connection, set GSK_CLIENT_ECURVE_LIST to "" or use gsk_attribute_set_buffer() to re-initialize the GSK_CLIENT_ECURVE_LIST buffer to NULL.

See Table 5 for a list of valid 4-character elliptic curve specifications.

The default value is 0, which means there is no limit on the size of a CRL that is allowed to be stored in the LDAP CRL cache.

The size must be greater than or equal to 0.

When disabled, LDAP basic CRL caching can be used and retrieved LDAP CRLs are only cached when GSK_CRL_CACHE_TIMEOUT is greater than 0 and GSK_CRL_CACHE_SIZE is set to a non-zero number.

A value of OFF or 0 disables LDAP extended CRL caching.

The default value is OFF.

A value of -1 means unlimited while a value of 0 means caching is not enabled.

If LDAP extended CRL cache support is enabled, the default is 32 and caching only occurs if the CRL contains an expiration time that is later than the current time.

If LDAP basic CRL cache support is enabled, the default is unlimited or -1 and caching only occurs when GSK_CRL_CACHE_TIMEOUT is greater than 0.

A value of OFF or 0 indicates that a temporary LDAP CRL cache entry is not to be added to the LDAP CRL cache.

If LDAP extended CRL cache support is enabled, the default value is OFF.

If LDAP basic CRL cache support is enabled, the default value is ON.

A temporary LDAP CRL cache entry is added to the LDAP CRL cache when the CRL does not reside on the LDAP server.

Specifies the number of hours that a cached LDAP CRL remains valid.

The valid timeout values are 0 through 720 and defaults to 24. A value of 0 disables the LDAP CRL cache.

An attempt to contact the LDAP server is performed when the CRL is not found in the LDAP cache. To enforce contact with the LDAP server for each CRL being checked, CRL caching must be disabled.

For LDAP basic CRL caching, see the GSK_CRL_CACHE_TIMEOUT or GSK_CRL_CACHE_SIZE settings.

For LDAP extended CRL caching, see the GSK_CRL_CACHE_SIZE setting.

LOW - Certificate validation does not fail if the LDAP server cannot be contacted.

MEDIUM - Certificate validation requires the LDAP server to be contactable, but does not require a CRL to be defined. This is the default.

HIGH - Certificate validation requires revocation information to be provided by the LDAP server.

Specifies whether the SSL condition handler should call the cdump() service to dump the current thread before resuming the failing routine. The dump is placed in the current directory unless LE is instructed to use a different directory by the _CEE_DMPTARG environment variable. See z/OS Language Environment Programming Guide for more information about LE callable services.

A value of 1 enables SSL dumps and a value of 0 disables SSL dumps. The default is 0. The export file contains just the requested certificate when the DER format is selected.

A value of OPTIONAL does not require the renegotiation indicator during initial handshake. This is the default.

A value of CLIENT allows the client initial handshake to proceed only if the server indicates support for RFC 5746 Renegotiation.

A value of SERVER allows the server initial handshake to proceed only if the client indicates support for RFC 5746 Renegotiation.

A value of BOTH will allow the server and client initial handshakes to proceed only if partner indicates support for RFC 5746 Renegotiation.

The default value is 0, which means there is no limit on the size of the CRL stored in the HTTP CDP CRL cache.

The default value is 32. If set to 0, HTTP CDP CRL caching is disabled.

A value of 1, ON, or ENABLED indicates certificate revocation checking with the HTTP URI values in the CDP extension is enabled.

The default value is OFF.

The default value is 204800 (200K).

A value of 0 disables checking the size and allows a CRL of any size.

The default value is 15 seconds and a value of 0 indicates that there is no time limit.

Specifies whether the hardware cryptographic support is used. Note that ICSF (Integrated Cryptographic Service Facility) must be configured and running in order for System SSL to use the hardware cryptographic support that is available in the cryptographic cards.

SHA-1, SHA-2, DES, Triple DES, and AES hardware functions can be used without ICSF if the zArchitecture message-security assist is installed.

For more information about hardware cryptographic support, see Using cryptographic features with System SSL.

Selected hardware cryptographic functions can be disabled by setting the appropriate bits to zero in the GSK_HW_CRYPTO value. The corresponding software algorithms are used when a hardware function is disabled. These bit assignments are defined:

• 1 = SHA-1 digest generation
• 2 = 56-bit DES encryption/decryption
• 4 = 168-bit Triple DES encryption/decryption
• 8 = Public key encryption/decryption
• 16 = AES 128-bit encryption/decryption
• 32 = SHA-256 digest generation
• 64 = AES-256-bit encryption/decryption
• 128 = SHA-224 digest generation
• 256 = SHA-384 digest generation
• 512 = SHA-512 digest generation

A value of 0 disables the use of hardware support while a value of 65535 enables the use of hardware support. The default value is 65535 and only available hardware support is used.

Specifies the label of the key that is used to authenticate the application.

Any key label. The default key is used if a key label is not specified.

Specifies the name of the key database file, PKCS #12 file, SAF key ring, or z/OS® PKCS #11 token. A key database or PKCS #12 file is used if the GSK_KEYRING_PW environment variable is also specified. A key database file is used if GSK_KEYRING_STASH environment variable is also specified. Otherwise, a SAF key ring or z/OS PKCS #11 token is used.

Note that certificate private keys are not available when using a SAF key ring owned by another user.

The user must have READ access to resource USER.tokenname in the CRYPTOZ class when using a z/OS PKCS #11 token.

The SAF key ring name is specified as userid/keyring. The current user ID is used if the user ID is omitted.

The z/OS PKCS #11 token name is specified as *TOKEN*/token-name.

If no certificate source is specified, defaults to NULL.

Specifies the password for the key database or PKCS #12 file.

NULL or value consisting of up to 128 characters.

The default value is NULL

Specifies the name of the key database password stash file.

The stash file name always has an extension of .sth and the supplied name is changed if it does not have the correct extension. The GSK_KEYRING_PW environment variable is used instead of the GSK_KEYRING_STASH environment variable if it is also specified.

The default value is NULL.

Specifies the password to use when connecting to the LDAP server.

The default value is NULL.

Specifies the LDAP server port.

Port must be between 1 and 65535. Port 389 is used if no LDAP server port is specified.

The default value is 15 seconds and a value of 0 indicates that there is no time limit.

The default value is NULL.

The default value is 10 and a value of 0 indicates there is no limit on the number of locations contacted.

The default value is 100 and a value of 0 indicates there is no limit on the number of locations contacted.

The default value is 0 which indicates that there is no limit on the number of cached certificate statuses allowed for a specific issuing CA certificate other than the limit imposed by GSK_OCSP_CLIENT_CACHE_SIZE. This cache size is rounded up to the nearest multiple of 16 with a minimum size of 16.

If GSK_OSCP_URL is specified, GSK_OCSP_ENABLE is set to ON and GSK_OCSP_URL_PRIORITY is set to ON, then the order the responders are used is GSK_OCSP_URL defined responder first and then the responders identified in the AIA extension.

If GSK_OCSP_URL is specified, GSK_OCSP_ENABLE is set to ON and GSK_OCSP_URL_PRIORITY is set to OFF, then the order that responders are used is the responders identified in the AIA extension first and then the GSK_OCSP_URL defined responder.

A value of 1, ON, or ENABLED enables OCSP revocation checking via the AIA extension.

The default value is OFF.

The default value is 20480 (20K).

A value of 0 disables checking of the OCSP response size and allows an OCSP response of any size.

A value of 1, ON, or ENABLED enables OCSP nonce checking.

The default value is OFF.

A value of 1, ON, or ENABLED enables OCSP nonce generation.

The default value is OFF.

Only requests sent to the OCSP responder identified by GSK_OCSP_URL are signed and not the ones selected from a certificate AIA extension.

See Table 6 for a list of valid 4-character signature algorithm pairs specifications.

Only requests sent to the OCSP responder identified by GSK_OCSP_URL are signed.

The default value is 15 seconds and a value of 0 indicates that there is no time limit.

A value of 1 or ON sends the OCSP request via the HTTP GET method when the total request size after Base64 encoding is less than 255 bytes.

The default value is OFF.

If GSK_OCSP_URL is specified, GSK_OCSP_ENABLE is set to ON, and GSK_OCSP_URL_PRIORITY is set to ON, the order that responders are used is GSK_OCSP_URL defined responder first and then the responders identified in the AIA extension.

If GSK_OCSP_URL is specified, GSK_OCSP_ENABLE is set to ON, and GSK_OCSP_URL_PRIORITY is set to OFF, the order that responders are used is the responders identified in the AIA extension first and then the GSK_OCSP_URL defined responder.

http_URL = "http:" "//" host 
[ ":" port ] [ abs_path 
[ "?" query ]]

The default value is NULL.

A value of 0 or OFF indicates that the order that responders are used is the responders identified in the AIA extension first and then the GSK_OCSP_URL defined responder.

The default value is ON.

Specifies whether the SSL V2 protocol is supported. The SSL V2 and SSL V3 protocols should be disabled whenever possible because the TLS V1.0, TLS V1.1, and TLS V1.2 protocols provide significant security enhancements. This variable has no effect when operating in FIPS mode.

A value of 0, OFF or DISABLED disables the SSL V2 protocol while a value of 1, ON or ENABLED enables the SSL V2 protocol. The default value is OFF.

Specifies whether the SSL V3 protocol is supported. The SSL V2 and SSL V3 protocols should be disabled whenever possible because the TLS V1.0, TLS V1.1, and TLS V1.2 protocols provide significant security enhancements. This variable has no effect when operating in FIPS mode.

A value of 0, OFF or DISABLED disables the SSL V3 protocol while a value of 1, ON or ENABLED enables the SSL V3 protocol. The default value is OFF.

Specifies whether the TLS V1.0 protocol is supported.

A value of 0, OFF or DISABLED disables the TLS V1.0 protocol while a value of 1, ON or ENABLED enables the TLS V1.0 protocol. The default value is ON.

Specifies whether the TLS V1.1 protocol is supported.

A value of 0, OFF or DISABLED disables the TLS V1.1 protocol while a value of 1, ON or ENABLED enables the TLS V1.1 protocol. The default value is OFF.

A value of NONE disables SSL V3 and TLS handshake renegotiation as a server and allow RFC 5746 renegotiation. This is the default.

A value of DISABLED disables SSL V3 and TLS handshake renegotiation as a server and also disable RFC 5746 renegotiation.

A value of ALL allows SSL V3 and TLS handshake renegotiation as a server while also allowing RFC 5746 renegotiation.

A value of ABBREVIATED allows SSL V3 and TLS abbreviated handshake renegotiation as a server for resuming the current session only, while disabling SSL V3 and TLS full handshake renegotiation as a server. With this value specified, the System SSL session ID cache is not checked when resuming the current session. RFC 5746 renegotiation is allowed if this value is specified.

A value of OFF or 0 does not perform an identity check against the peer's certificate during renegotiation. This allows the peer certificate to change during renegotiation. This is the default.

A value of ON or 1 performs a comparison against the peer's certificate to ensure that certificate does not change during renegotiation.

An attempt to contact either an OCSP responder or HTTP server is performed when revocation information is not found in cache. To enforce contact with either the OCSP responder or HTTP server for each validation, caching must be disabled.

For OCSP caching, see GSK_OCSP_CLIENT_CACHE_SIZE.

For HTTP CRL caching, see GSK_HTTP_CDP_CACHE_SIZE.

A value of MEDIUM requires the OCSP responder or the HTTP server in a URI value in the CDP extension to be contactable. For an OCSP responder, it must be able to provide a valid certificate revocation status. If the certificate status is revoked or unknown, certificate validation fails. For an HTTP server in a CDP extension, it must be contactable and able to provide an CRL.

A value of HIGH requires revocation information to be provided by the OCSP responder or HTTP server. If OCSP revocation checking with the AIA extension is enabled, there must be HTTP URI values present in the certificate that are able to be contactable and able to provide a valid certificate revocation status. If HTTP CRL checking is enabled, there must be HTTP URI values in the CDP extension that are able to be contactable and able to provide a CRL.

The default value is MEDIUM.

Specifies whether the SSL random number generator, gsk_generate_random_bytes includes bytes with a zero value in the random byte output stream, or remove them.

The GSK_RNG_ALLOW_ZERO_BYTES environment variable is processed during System SSL initialization and is not checked afterward.

A value of TRUE, ON or 1 sets the random number generator to retain bytes with a zero value in the output stream. A value of FALSE, OFF or 0 results in bytes with a zero value being removed. The default setting is TRUE.

Setting this environment variable to 1 causes a series of messages to be written to stderr during System SSL initialization. These messages displays the current status of the hardware cryptographic support. These messages are intended for diagnostic use only and are not translated based on the setting of the LANG environment variable.

Specify 1 to have messages written. Any other value is ignored, which is the default.

Setting this environment variable to 1 causes a message to be written to stderr when an ICSF callable service returns an error. These messages are intended for diagnostic use only and are not translated based on the setting of the LANG environment variable.

Specify 1 to have messages written. Any other value is ignored, which is the default.

Specifies the fully-qualified name of the file to receive standard error messages generated using SSL message services. Messages displayed from externally documented messages is written to stderr if this environment variable is not defined.

If fully qualified file not specified, the default action is to write standard errors to stderr.

Specifies the fully-qualified name of the file to receive standard output messages generated using SSL message services. Messages displayed from externally documented messages is written to stdout if this environment variable is not defined.

If fully qualified file not specified, the default action is to write standard output to stdout.

Specifies the Suite B profile to be applied to TLS sessions.

A Suite B compliant TLS V1.2 or later client must offer only the following cipher suites when conversing with a TLS V1.2 Suite B compliant server.

A value of OFF specifies that Suite B compliant profiles are not in use for TLS sessions. This is the default value.

A value of 128 specifies that only ciphers defined within 128-bit Suite B compliant profile can be used for a TLS session.

A value of 192 specifies that only ciphers defined within 192-bit Suite B compliant profile can be used for a TLS session.

A value of ALL specifies that ciphers defined within both the 128-bit and 192-bit Suite B compliant profiles can be used for a TLS session.

Specifies whether sysplex session caching is supported for this application.

A value of 0, OFF or DISABLED disables sysplex session caching while a value of 1, ON or ENABLED enables sysplex session caching. The default value is OFF.

Specifies the character set for ASN.1 TELETEXSTRING conversions. The T.61 character set is supposed to be used for strings tagged as TELETEXSTRING. The X.690 ASN.1 definition specifies the 7-bit T.61character set (ISO IR-102). However, many certificate authorities issue certificates using the 8-bit ISO8859-1 character set (ISO IR-100) instead of the 7-bit T.61 character set. This causes conversion errors when the certificate is decoded. To add to the confusion, the 8-bit T.61 character set (ISO IR-103) is also used by some implementations.

If the GSK_T61_AS_LATIN1 environment variable is set to YES or 1, the 8-bit ISO8859-1 character set is used when processing a TELETEX string. If the GSK_T61_AS_LATIN1 environment variable is set to NO or 0, the 8-bit T.61 character set is used. The default is to use the ISO8859-1 character set. The GSK_T61_AS_LATIN1 environment variable is processed during System SSL initialization and is not checked afterward. Note that selecting the incorrect character set can cause strings to be converted incorrectly.

A value of ZEROBYTEFRAGMENT indicates that zero byte record fragmenting is enabled. When this value is specified, a zero byte record fragment is sent before the application data records are sent.

A value of ONEBYTEFRAGMENT indicates that one byte record fragmenting is enabled. When this value is specified, the first record is sent in two record fragments with the first record fragment containing only one byte of application data. The rest of the application data in the first record is sent in the second record fragment. All following records are written whole.

Specifies the list of hash and signature algorithm pair specifications supported by the client or server as a string consisting of 1 or more 4-character values in order of preference for use.

The signature algorithm pair specifications are sent by either the client or server to the session partner to indicate which signature/hash algorithm combinations are supported for digital signatures.

The signature algorithm pair specification only has relevance for sessions using TLS V1.2 or higher protocols.

See Table 6 for a list of valid 4-character signature algorithm pairs specifications.

Specifies a bit mask enabling System SSL trace options. No trace option is enabled if the bit mask is 0 and all trace options are enabled if the bit mask is 0xffff. The bit mask can be specified as a decimal (nnn), octal (0nnnn) or hexadecimal (0xhh) value.

These trace options are available:

• 0x01 = Trace function entry
• 0x02 = Trace function exit
• 0x04 = Trace errors
• 0x08 = Include informational messages
• 0x10 = Include EBCDIC data dumps
• 0x20 = Include ASCII data dumps

The default value is 0x00.

Specifies the name of the trace file. The gsktrace command is used to format the trace file. The trace file is not used if the GSK_TRACE environment variable is not defined or is set to 0.

The current process identifier is included as part of the trace file name when the name contains a percent sign (%). For example, if GSK_TRACE_FILE is set to /tmp/gskssl.%.trc and the current process identifier is 247, then the trace file name is /tmp/gskssl.247.trc.

Must be set to the name of an UNIX System Services file in a directory for which the executing application has write permission.

The default trace file is /tmp/gskssl.%.trc.

Specifies the SSL V2 cipher specifications in order of preference as a string consisting of 1 or more 1-character values.

See Table 1 for the list of the supported ciphers.

If United States only encryption is enabled (System SSL Security Level 3 FMID is installed), the default is 7364. Otherwise, the default is 64.

Specifies the session timeout value in seconds for the SSL V2 protocol.

The valid timeout values are 0 through 100, default value is 100.

Specifies the number of session identifiers that can be contained in the SSL V2 cache.

The valid cache sizes are 0 through 32000 and defaults to 256. The SSL V2 cache is disabled if 0 is specified. The session identifier cache is allocated using the requested size rounded up to a power of 2 with a minimum size of 16.

Specifies the SSL V3 cipher specifications in order of preference as a string consisting of 1 or more 2-character values. The SSL V3 cipher specifications are used for the SSL V3, TLS V1.0, and higher protocols.

For protocols TLS V1.1 and higher, export cipher suites is not used. 40-bit ciphers are ignored if these security protocols are negotiated.

For protocols TLS V1.2 and higher, 56-bit DES cipher suites are not used. DES ciphers are ignored if these communications protocols are negotiated.

Any ciphers that use SHA-256 or greater message authentication or use AES-GCM encryption can only be used if TLS V1.2 or higher is the negotiated protocol.

See Table 2 for the list of the supported 2-character ciphers.

For protocols TLS V1.1 and higher export cipher suites are not used. 40-bit ciphers are ignored if these security protocols are negotiated.

For protocols TLS V1.2 and higher, 56-bit DES cipher suites are not used. DES ciphers are ignored if these communications protocols are negotiated.

Any ciphers that use SHA-256 or greater message authentication or use AES-GCM encryption can only be used if TLS V1.2 or higher is the negotiated protocol.

See Table 3 for the list of the supported 4-character ciphers.

Specifies the session timeout value in seconds for the SSL V3, TLS V1.0 and higher protocols.

The valid timeout values are 0 through 86400 and defaults to 86400. The timeout is disabled if 0 is specified.

Specifies the number of session identifiers that can be contained in the SSL V3 cache. The SSL V3 session cache is used for the SSL V3, TLS V1.0 and higher protocols.

The valid cache sizes are 0 through 64000 and defaults to 512. The SSL V3 cache is disabled if 0 is specified. The session identifier cache is allocated by using the requested size rounded up to a power of 2 with a minimum size of 16.

Used to control the size limit for a V2 session cache. This variable is for use only with the deprecated API set.

The valid cache sizes are 0 through 32000 and defaults to 256.

Used to control the size limit for a V3 session cache. This variable is for use only with the deprecated API set.

The valid cache sizes are 0 through 64000 and defaults to 512 entries.

The default location is /usr/lib/nls/msg/%L/%N:/usr/lib/nls/msg/ En_US.IBM-1047/%N