gsk_environment_open()

Creates an SSL environment.

Format

   #include <gskssl.h>

   gsk_status gsk_environment_open (
                                     gsk_handle *     env_handle)

Parameters

env_handle: Returns the handle for the environment. The application should call the gsk_environment_close() routine to release the environment when it is no longer needed.

Results

The function return value will be 0 (GSK_OK) if no error is detected. Otherwise, it will be one of the return codes listed in the gskssl.h include file. These are some possible errors:

[GSK_ATTRIBUTE_INVALID_ENUMERATION]: The value of an environment variable is not valid.
[GSK_ATTRIBUTE_INVALID_LENGTH]: The length of an environment variable value is not valid.
[GSK_ATTRIBUTE_INVALID_NUMERIC_VALUE]: The value of an environment variable is not valid.
[GSK_ERR_PROTOCOL_NOT_SUPPORTED_WITH_FIPS]: Protocol is not supported in FIPS mode.
[GSK_INSUFFICIENT_STORAGE]: Insufficient storage is available.

Usage

The gsk_environment_open() routine creates an SSL environment. The environment will be initialized with default values and then any SSL environment variables will be processed. These values can be changed by the application using the appropriate gsk_attribute_set_*() routines. The gsk_environment_init() routine should then be called to initialize the SSL environment. This environment can then be used to establish one or more SSL connections.

When not executing in FIPS mode, the following default values are set:

TLS V1.0 is enabled (SSL V2, SSL V3, TLS V1.1, TLS V1.2, and TLS V1.3 are disabled by default).
The connection type is set to CLIENT.
The SSL V2 connection timeout is set to 100 seconds.
The SSL V3 connection timeout is set to 86400 seconds.
The SSL V2 cache size is set to 256.
The SSL V3 cache size is set to 512.
The sysplex session cache is disabled.
The default key will be used.
No revoked certificate checking performed.
The default callback routines will be used.
The SSL V2 cipher specification is set to "34" if United States only encryption is enabled (System SSL Security Level 3 FMID installed or CPACF Feature 3863 installed) and "4" otherwise.
2-character cipher definitions in GSK_V3_CIPHER_SPECS will be used for SSL V3 cipher values.
The SSL V3 cipher specification is set to "3538392F3233" if United States only encryption is enabled (System SSL Security Level 3 FMID installed or CPACF Feature 3863 installed) and "" (empty string - no default) otherwise.
The Signaling Cipher Suite Value (SCSV) is disabled.
The supported client elliptic curve list is set to "00210023002400250019".
The allowed server elliptic curve list is set to "00230024002500210019".
The signature algorithm pair list is set to "0601060305010503040104030402030103030302020102030202".
No TLS extensions are initialized.
Suite B is disabled.
OCSP revocation and OCSP server stapling support is disabled (OCSP URL is not defined and AIA extensions are not enabled).
HTTP CDP CRL support is disabled.
LDAP CRL support is disabled.
Strict 3DES key enforcement is not enabled.
Minimum peer x.509 end-entity certificate key size is set to RSA (1024), DSA(1024), DH(1024), and ECC(192).
The client and server key share lists have no default value.
Middlebox compatibility mode for TLS V1.3 connections is disabled.
Session ticket support is enabled for both the client and the server.
The maximum session ticket size accepted by the client is 8192 (8K) bytes.
The algorithm used to encrypt server session tickets is set to AES-CBC 128.
The number of session tickets that are sent by the server after a TLS V1.3 handshake has completed is set to 2.
The server session ticket key refresh is set to 300 seconds.
The sysplex session cache for SSL V3, TLS V1.0, TLS V1.1, and TLS V1.2 server sessions is disabled.
The sysplex session ticket cache for TLS V1.3 server sessions is disabled.
The maximum number of session tickets that are allowed to be cached by the client for a TLS V1.3 session is set to 8.
The server session ticket timeout is set to 300 seconds when sysplex session ticket cache is disabled. If sysplex session ticket cache is enabled, the server session ticket timeout is set to 600 seconds.
The signature algorithm cert list is empty.
The client (when enabled for TLS V1.0, TLS V1.1, or TLS V1.2) sends the extended master secret extension to the server, but does not require the server to negotiate the extension.
The server (when enabled for TLS V1.0, TLS V1.1, or TLS V1.2) supports negotiating the extended master secret if the client sends the extension, but does not require the client to send the extension.

When executing in FIPS mode, the following default values are set:

TLS V1.0 is enabled (SSL V2, SSL V3, TLS V1.1, TLS V1.2, and TLS V1.3 are disabled by default).
The connection type is set to CLIENT.
The connection timeout is set to 86400 seconds.
The cache size is set to 512.
The sysplex session cache is disabled.
The default key will be used.
No revoked certificate checking performed.
The default callback routines will be used.
2-character cipher definitions in GSK_V3_CIPHER_SPECS will be used for SSL V3 cipher values.
The SSL V3 cipher specification is set to "3538392F3233".
The Signaling Cipher Suite Value (SCSV) is disabled.
The supported client elliptic curve list is set to "00210023002400250019".
The allowed server elliptic curve list is set to "00230024002500210019".
The signature algorithm pair list is set to "0601060305010503040104030402030103030302020102030202".
Suite B is disabled.
OCSP revocation and OCSP server stapling support is disabled (OCSP URL is not defined and AIA extensions are not enabled).
HTTP CDP CRL support is disabled.
LDAP CRL support is disabled.
Strict 3DES key enforcement is enabled.
Minimum peer x.509 end-entity certificate key size is set to RSA (1024), DSA(1024), DH(2048), and ECC(192).
The signature algorithm cert list is empty.
The client (when enabled for TLS V1.0, TLS V1.1, or TLS V1.2) sends the extended master secret extension to the server, but does not require the server to negotiate the extension.
The server (when enabled for TLS V1.0, TLS V1.1, or TLS V1.2) supports negotiating the extended master secret if the client sends the extension, but does not require the client to send the extension.

Note: The TLS V1.3 protocol is not currently supported in FIPS mode. If an attempt is made to enable this protocol while running in FIPS mode, an error is returned during environment initialization.

See Table 1 for a list of supported SSL V2 cipher specifications.

See Table 2 for a list of supported 2-character SSL V3 cipher specifications.

See Table 3 for a list of supported 4-character SSL V3 cipher specifications.

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

Applications wanting to use cipher suites that use elliptic curve certificates must set an appropriate cipher specification in GSK_V3_CIPHER_SPECS_EXPANDED. If an application requires an SSL V3, TLS V1.0, or higher session to use the 4-character cipher suites specified in GSK_V3_CIPHER_SPECS_EXPANDED then it must explicitly call gsk_attribute_set_enum() and set the enumeration identifier GSK_V3_CIPHERS to have a value of GSK_V3_CIPHERS_CHAR4.

If the application is to be enabled for TLS V1.3, see TLS V1.3 protocol support for the configuration requirements.

If an application has indicated it is using the 4-character cipher specifications by setting GSK_V3_CIPHERS to GSK_V3_CIPHERS_CHAR4, but does not set a cipher specification in GSK_V3_CIPHER_SPECS_EXPANDED, the default cipher specification will be set as follows:

Executing in non-FIPS mode with United States only encryption enabled (System SSL Security Level 3 FMID installed or CPACF Feature 3863 installed):
```
"003500380039002F00320033"
```
Executing in non-FIPS mode with United States only encryption disabled (System SSL Security Level 3 FMID is not installed and CPACF Feature 3863 is not installed):
```
("" empty string – no default)
```
Executing in FIPS mode:
```
"003500380039002F00320033"
```

If an application has indicated it will be running in Suite B compatibility mode by setting GSK_SUITE_B_PROFILE to a value other than GSK_SUITE_B_PROFILE_OFF, the cipher specifications in GSK_V2_CIPHER_SPECS, GSK_V3_CIPHER_SPECS, and GSK_V3_CIPHER_SPECS_EXPANDED are ignored. The Suite B ciphers that are in use in the initialized SSL environment can be obtained by calling the gsk_attribute_get_buffer() routine by passing in the GSK_SUITE_B_CIPHER_SPECS buffer identifier. The cipher specifications will be set based on the values for GSK_SUITE_B_PROFILE as follows:

Executing with GSK_SUITE_B_PROFILE_128 "C02BC023".
Executing with GSK_SUITE_B_PROFILE_128MIN "C02BC02C".
Executing with GSK_SUITE_B_PROFILE_192 "C02CC024".
Executing with GSK_SUITE_B_PROFILE_192MIN "C02C".
Executing with GSK_SUITE_B_PROFILE_ALL "C02CC024C02BC023".

If executing in FIPS mode, the following cipher specifications are supported:

When using 2-character cipher suites:
0A 0D 10 13 16 2F 30 31 32 33 35 36 37 38 39 3C 3D 3E 3F 40 67 68 69
6A 6B 9C 9D 9E 9F A0 A1 A2 A3 A4 A5
When using 4-character cipher suites:
000A 000D 0010 0013 0016 002F 0030 0031 0032 0033 0035 0036 0037 0038
0039 003C 003D 003E 003F 0040 0067 0068 0069 006A 006B 009C 009D 009E
009F 00A0 00A1 00A2 00A3 00A4 00A5 C003 C004 C005 C008 C009 C00A
C00D C00E C00F C012 C013 C014 C023 C024 C025 C026 C027 C028 C029
C02A C02B C02C C02D C02E C02F C030 C031 C032

If using TLS V1.1 or TLS V1.2 protocols, export ciphers are not supported. The 40-bit ciphers (cipher specifications "03" and "06" or "0003" and "0006") will be ignored if specified.

If using TLS V1.2, the 56-bit DES cipher suites "09", "0C", "0F", "12" and "15" (or "0009", "000C", "000F", "0012" and "0015") will be ignored if specified.

These environment variables are processed (See Environment variables for information about environment variables):

GSK_3DES_KEYCHECK: Specifies that each part of a Triple DES key is checked to be unique when in non-FIPS mode.
GSK_AIA_CDP_PRIORITY: Specifies the priority order that the AIA and the CDP extensions are checked for certificate revocation information.
GSK_CERT_DIAG_INFO: Specifies that when validation is being performed against the peer’s certificate and certificate chain, certificate validation information will be provided for failures, successes, or both through the GSK_CERT_DIAGNOSTIC_CALLBACK.
GSK_CERT_VALIDATION_KEYRING_ROOT: Specifies how certificates in a SAF key ring are validated.
GSK_CERT_VALIDATION_MODE: Specifies which internet standard is used for certificate validation.
GSK_CLIENT_AUTH_NOCERT_ALERT: Specifies whether the SSL server application accepts a connection from a client where client authentication is requested and the client fails to supply an X.509 certificate.
GSK_CLIENT_ECURVE_LIST: Specifies the list of elliptic curves or groups that are supported by the client.
GSK_CLIENT_EPHEMERAL_DH_GROUP_SIZE: Specifies the minimum Diffie-Hellman group size required by the client to be used by the server for an ephemeral Diffie-Hellman key exchange.
GSK_CLIENT_EXTENDED_MASTER_SECRET: Specifies if the TLS client sends the extended master secret extension to the server for TLS V1.0, TLS V1.1, or TLS V1.2 handshakes.
GSK_CLIENT_TLS_KEY_SHARES: Specifies the list of key share groups that are supported by the client during a TLS V1.3 handshake.
GSK_CRL_CACHE_ENTRY_MAXSIZE: Specifies the maximum size in bytes of a CRL to be kept in the LDAP CRL cache.
GSK_CRL_CACHE_EXTENDED: Specifies that LDAP extended CRL cache support is enabled.
GSK_CRL_CACHE_SIZE: Specifies the maximum number of CRLs that are allowed to be stored in the LDAP CRL cache.
GSK_CRL_CACHE_TIMEOUT: Specifies the number of hours that a cached LDAP CRL remains valid.
GSK_CRL_CACHE_TEMP_CRL: Specifies if a temporary LDAP CRL cache entry is added to the LDAP CRL cache when the CRL does not reside on the LDAP server.
GSK_CRL_CACHE_TEMP_CRL_TIMEOUT: Specifies the time in hours that a temporary CRL cache entry resides in the LDAP CRL cache.
GSK_CRL_SECURITY_LEVEL: Specifies the level of security used when contacting LDAP servers to check CRLs for revoked certificates.
GSK_EXTENDED_RENEGOTIATION_INDICATOR: Specifies the level of enforcement of renegotiation indication.
GSK_HTTP_CDP_CACHE_ENTRY_MAXSIZE: Specifies the maximum size in bytes of a CRL that can be stored in the HTTP CDP CRL cache.
GSK_HTTP_CDP_CACHE_SIZE: Specifies the maximum number of CRLs that are allowed to be stored in the HTTP CDP CRL cache.
GSK_HTTP_CDP_ENABLE: Specifies if certificate revocation checking with the HTTP URI values in the CDP extension is enabled.
GSK_HTTP_CDP_MAX_RESPONSE_SIZE: Specifies the maximum size in bytes accepted as a response from an HTTP server when retrieving a CRL.
GSK_HTTP_CDP_PROXY_SERVER_NAME: Specifies the DNS name or IP address of the HTTP proxy server.
GSK_HTTP_CDP_PROXY_SERVER_PORT: Specifies the HTTP proxy server port.
GSK_HTTP_CDP_RESPONSE_TIMEOUT: Specifies the time in seconds to wait for a response from the HTTP server.
GSK_KEY_LABEL: Specifies the label of the key that used to authenticate the application.
GSK_KEYRING_FILE: Specifies the name of the key database file, PKCS #12 file, SAF key ring, or z/OS PKCS #11 token.
GSK_KEYRING_PW: Specifies the password for the key database or PKCS #12 file.
GSK_KEYRING_STASH: Specifies the name of the key database password stash file.
GSK_LDAP_PASSWORD: Specifies the password to use when connecting to the LDAP server.
GSK_LDAP_PORT: Specifies the LDAP server port.
GSK_LDAP_RESPONSE_TIMEOUT: Specifies the time in seconds to wait for a response from the LDAP server.
GSK_LDAP_SERVER: Specifies one or more blank-separated LDAP server host names.
GSK_LDAP_USER: Specifies the distinguished name to use when connecting to the LDAP server.
GSK_MAX_SOURCE_REV_EXT_LOC_VALUES: Specifies the maximum number of location values that will be contacted per data source when attempting validation of a certificate.
GSK_MAX_VALIDATION_REV_EXT_LOC_VALUES: Specifies the maximum number of location values that will be contacted when performing validation of a certificate.
GSK_MIDDLEBOX_COMPAT_MODE: Specifies that the TLS V1.3 handshake process ought to use or tolerate handshake messages in a manner compliant with earlier TLS protocols to alleviate possible issues with middleboxes or proxies.
GSK_OCSP_CLIENT_CACHE_ENTRY_MAXSIZE: Specifies the maximum number of OCSP responses or cached certificate statuses that are allowed to be kept in the OCSP response cache for an issuing CA certificate.
GSK_OCSP_CLIENT_CACHE_SIZE: Specifies the maximum number of OCSP responses or cached certificate statuses to be kept in the OCSP response cache.
GSK_OCSP_ENABLE: Specifies whether the AIA extensions are to be used for revocation checking.
GSK_OCSP_MAX_RESPONSE_SIZE: Specifies the maximum size in bytes allowed in a response from an OCSP responder.
GSK_OCSP_NONCE_CHECK_ENABLE: Specifies if OCSP response nonce checking is on or off.
GSK_OCSP_NONCE_GENERATION_ENABLE: Specifies whether an OCSP request will contain a generated nonce.
GSK_OCSP_NONCE_SIZE: Specifies the size in bytes for the value of the nonce to be sent in OCSP requests.
GSK_OCSP_PROXY_SERVER_NAME: Specifies the DNS name or IP address of the OCSP proxy server.
GSK_OCSP_PROXY_SERVER_PORT: Specifies the OCSP responder port for the proxy.
GSK_OCSP_REQUEST_SIGALG: Specifies the hash and signature algorithm pair to be used to sign OCSP requests.
GSK_OCSP_REQUEST_SIGKEYLABEL: Specifies the label of the key to be used to sign OCSP requests.
GSK_OCSP_RESPONSE_SIGALG_PAIRS: Specifies a preference ordered list of hash and signature algorithm pair specifications that are sent on the OCSP request and may be used by the OCSP responder to select an appropriate algorithm for signing the OCSP response.
GSK_OCSP_RESPONSE_TIMEOUT: Specifies the time in seconds to wait for a complete response from the OCSP responder.
GSK_OCSP_RETRIEVE_VIA_GET: Specifies whether the HTTP request to the OCSP responder is sent using the HTTP Get Method or the HTTP Post method.
GSK_OCSP_URL: Specifies the URI of an OCSP responder.
GSK_OCSP_URL_PRIORITY: Specifies the order of precedence for contacting OCSP responder locations if both GSK_OCSP_URL and GSK_OCSP_ENABLE are active.
GSK_PEER_CERT_MIN_VERSION: Specifies the minimum X.509 version number allowed for a peer's X.509 end-entity certificate.
GSK_PEER_DH_MIN_KEY_SIZE: Specifies the minimum allowed X.509 certificate Diffie-Hellman key size for a peer's X.509 end-entity certificate.
GSK_PEER_DSA_MIN_KEY_SIZE: Specifies the minimum allowed X.509 certificate DSA key size for a peer's X.509 end-entity certificate.
GSK_PEER_ECC_MIN_KEY_SIZE: Specifies the minimum allowed X.509 certificate ECC key size for a peer's X.509 end-entity certificate.
GSK_PEER_RSA_MIN_KEY_SIZE: Specifies the minimum allowed X.509 certificate RSA key size for a peer's X.509 end-entity certificate.
GSK_PROTOCOL_SSLV2: Specifies whether the SSL V2 protocol is supported.
GSK_PROTOCOL_SSLV3: Specifies whether the SSL V3 protocol is supported.
GSK_PROTOCOL_TLSV1: Specifies whether the TLS V1.0 protocol is supported.
GSK_PROTOCOL_TLSV1_1: Specifies whether the TLS V1.1 protocol is supported.
GSK_PROTOCOL_TLSV1_2: Specifies whether the TLS V1.2 protocol is supported.
GSK_PROTOCOL_TLSV1_3: Specifies whether the TLS V1.3 protocol is supported.
GSK_REFERENCE_ID_CN: Specifies a list of common name values to compare against the server certificate’s subject DN common name.
GSK_REFERENCE_ID_DNS: Specifies a list of DNS values to compare against the server certificate’s DNS entry for the subject alternative name.
GSK_REVOCATION_SECURITY_LEVEL: Specifies the level of security to be used when contacting an OCSP responder or an HTTP server specified in a URI value of the CDP extension.
GSK_RENEGOTIATION: Specifies the type of session renegotiation allowed for an SSL environment.
GSK_RENEGOTIATION_PEER_CERT_CHECK: Specifies if the peer certificate is allowed to change during renegotiation.
GSK_SERVER_ALLOWED_KEX_ECURVES: Specifies the list of elliptic curves that are allowed by the server for the TLS V1.0, TLS V1.1, and TLS V1.2 server key exchange.
GSK_SERVER_EPHEMERAL_DH_GROUP_SIZE: Specifies the minimum Diffie-Hellman group size to be used by the server for an ephemeral Diffie-Hellman key exchange.
GSK_SERVER_EXTENDED_MASTER_SECRET: Specifies if the TLS server supports negotiating the extended master secret extension from clients for TLS V1.0, TLS V1.1, or TLS V1.2 handshakes.
GSK_SERVER_FALLBACK_SCSV: Specifies if the server accepts the TLS fallback Signaling Cipher Suite Value (SCSV) when the client's cipher list includes it during an SSL or TLS handshake.
GSK_SERVER_KEY_LABEL_LIST: Specifies one or more labels that can be used to authenticate the server application.
GSK_SERVER_OCSP_STAPLING: Specifies if the server supports the retrieval of the OCSP responses for the server's end entity certificate or the server's certificate chain if the client specifies support for the OCSP responses in the TLS handshake.
GSK_SERVER_TLS_KEY_SHARES: Specifies the list of key share groups that are supported by the server during a TLS V1.3 handshake.
GSK_SESSION_TICKET_CLIENT_ENABLE: Specifies if the client supports caching session tickets received from a server after a TLS V1.3 handshake has completed and if it supports TLS V1.3 resumption attempts to the server.
GSK_SESSION_TICKET_CLIENT_MAXCACHED: Specifies the maximum of session tickets that are allowed to be cached by the client for a TLS V1.3 session.
GSK_SESSION_TICKET_CLIENT_MAXSIZE: Specifies the maximum size in bytes of a session ticket that is allowed to be stored in the client session ticket cache.
GSK_SESSION_TICKET_SERVER_ALGORITHM: Specifies the algorithm to be used by the server to encrypt and decrypt the session tickets used for TLS V1.3 session resumption.
GSK_SESSION_TICKET_SERVER_COUNT: Specifies the number of session tickets that will be sent by the server after the initial TLS V1.3 handshake has completed.
GSK_SESSION_TICKET_SERVER_ENABLE: Specifies if the server supports sending session tickets after a TLS V1.3 handshake has completed and if it will accept resumption attempts from the client.
GSK_SESSION_TICKET_SERVER_KEY_REFRESH: Returns the key refresh interval of the encryption key used by the server to encrypt session tickets, in seconds.
GSK_SESSION_TICKET_SERVER_TIMEOUT: Specifies the maximum time that a server accepts a TLS V1.3 session resumption request from the client measured in seconds from the initial handshake.
GSK_SUITE_B_PROFILE: Specifies the Suite B profile to be applied to TLS V1.2 sessions.
GSK_SYSPLEX_SESSION_TICKET_CACHE: Specifies whether sysplex session ticket caching for TLS V1.3 server sessions is supported.
GSK_SYSPLEX_SIDCACHE: Specifies whether sysplex session caching for SSL V3, TLS V1.0, TLS V1.1, and TLS V1.2 server sessions is supported.
GSK_TLS_CBC_PROTECTION_METHOD: Specifies an optional SSL V3.0 or TLS V1.0 CBC IV protection method when writing application data.
GSK_TLS_CERT_SIG_ALG_PAIRS: Specifies the list of TLS V1.2 and TLS V1.3 hash and signature algorithm pair specifications that are supported by a TLS V1.2 or TLS V1.3 client or a TLS V1.3 server for use in digital signatures of X.509 certificates.
GSK_TLS_SIG_ALG_PAIRS: Specifies the list of TLS V1.2 and TLS V1.3 hash and signature algorithm pair specifications that are supported by the client or server for use in digital signatures of X.509 certificates and TLS handshake messages.
GSK_V2_CIPHER_SPECS: Specifies the SSL V2 cipher specifications in order of preference.
GSK_V2_SESSION_TIMEOUT: Specifies the session timeout value in seconds for the SSL V2 protocol.
GSK_V2_SIDCACHE_SIZE: Specifies the number of session identifiers that can be contained in the SSL V2 cache.
GSK_V3_CIPHER_SPECS: Specifies the SSL V3 cipher specifications in order of preference (2-character values).
GSK_V3_CIPHER_SPECS_EXPANDED: Specifies the SSL V3 cipher specifications in order of preference (4-character values).
GSK_V3_SESSION_TIMEOUT: Specifies the session timeout value in seconds for the SSL V3 to TLS V1.2 session identifiers and TLS V1.3 session tickets in the cache.
GSK_V3_SIDCACHE_SIZE: Specifies the size in number of entries in the SSL V3 to TLS V1.2 session identifier and TLS V1.3 session ticket cache.
GSK_WILDCARD_VALIDATION_ENABLE: Specifies whether the asterisk will be accepted as the wildcard character within the first label of the server certificate’s subject alternative name DNS or subject DN common name to replace zero or more values.