gsk_initialize()

Initializes the System SSL runtime environment.

Format

   #include <gskssl.h>

   gsk_status gsk_initialize(
                              gsk_init_data *     init_data)

Parameters

init_data: Specifies the data used to initialize the SSL runtime environment.

Results

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

[GSK_ERR_INIT_PARM_NOT_VALID]: An initialization parameter is not valid.
[GSK_ERROR_BAD_MALLOC]: Insufficient storage is available.
[GSK_ERROR_CRYPTO]: Cryptographic error detected.
[GSK_ERROR_ICSF_FIPS_DISABLED]: ICSF PKCS #11 services are disabled.
[GSK_ERROR_ICSF_NOT_AVAILABLE]: ICSF services are not available.
[GSK_ERROR_ICSF_NOT_FIPS]: ICSF PKCS #11 not operating in FIPS mode.
[GSK_ERROR_ICSF_SERVICE_FAILURE]: ICSF callable service returned an error.
[GSK_ERROR_LDAP]: Unable to initialize the LDAP client.
[GSK_ERROR_MULTIPLE_LABEL]: Multiple certificates exist for label.
[GSK_ERROR_MULTIPLE_DEFAULT]: Multiple keys are marked as the default.
[GSK_ERROR_PERMISSION_DENIED]: Not authorized to access the key database, key ring or token.
[GSK_INIT_SEC_TYPE_NOT_VALID]: The security type is not valid.
[GSK_INIT_V2_TIMEOUT_NOT_VALID]: The SSL V2 timeout is not valid.
[GSK_INIT_V3_TIMEOUT_NOT_VALID]: The SSL V3 timeout is not valid.
[GSK_KEYFILE_BAD_FORMAT]: Key database or key ring format is not valid.
[GSK_KEYFILE_BAD_PASSWORD]: Key database password is not correct.
[GSK_KEYFILE_IO_ERROR]: Unable to read the key database, key ring or token.
[GSK_KEYFILE_NO_CERTIFICATES]: The key database, key ring or token does not contain any certificates.
[GSK_KEYFILE_OPEN_FAILED]: Unable to open the key database, key ring or token.
[GSK_KEYFILE_PW_EXPIRED]: Key database password is expired.

Usage

The gsk_initialize() routine initializes the System SSL runtime environment for the current process. The gsk_uninitialize() routine should be called to release the SSL environment when it is no longer needed. Multiple calls to gsk_initialize() causes the existing environment to be released before creating the new environment.

Environment variables are processed along with the gsk_initialize data structures. Information passed in the key database, key ring or token is read as part of the environment initialization. Upon successful completion of gsk_initialize(), the application is ready to begin creating and using secure socket connections.

The gsk_init_data structure contains these fields:

sec_types

Specifies one of these null-terminated character strings:

"SSLV2" or "SSL20" to use the SSL V2 protocol
"SSLV3" or "SSL30" to use the SSL V3 protocol
"TLSV1" or "TLS10" to use the TLS V1.0 protocol
"SSLV2_OFF" to allow either TLS V1.0 or SSL V3 to be used
"ALL" to use any supported protocol (SSL V2, SSL V3, and TLS V1.0).

When "SSLV2_OFF" is specified the SSL client/server attempts first to use the TLS V1.0 protocol, before falling back to the most secure protocol supported by its SSL partner, excluding the SSL V2 protocol.

When "ALL" is specified for an SSL client, the client attempts first to use the TLS V1.0 protocol and falls back to the most secure protocol that the server supports, excluding the SSL V2 protocol (the client must explicitly request the SSL V2 protocol if it wants to use this protocol).

When "ALL" is specified for an SSL server, the server accepts any of the supported protocols.

When running in FIPS mode, the minimum requirement is TLS V1.0 protocol. If only the SSL V2 or the SSL V3 protocol is enabled, then a FIPS mode SSL connection is not possible.

keyring

Specifies the name of the key database, SAF key ring, or z/OS® PKCS #11 token as a null-terminated character string. When both the password and stash file name are NULL, a SAF key ring or PKCS #11 token is used.

The SAF key ring name is specified as "userid/keyring". The current user ID is used if the user ID is omitted. The user must have READ access to the IRR.DIGTCERT.LISTRING resource in the FACILITY class when using a SAF key ring owned by the user. The user must have UPDATE access to the IRR.DIGTCERT.LISTRING resource in the FACILITY class when using a SAF key ring owned by another user.

Note: Certificate private keys are not available when using a SAF key ring owned by another user, except for SITE certificates where CONTROL authority is given to IRR.DIGTCERT.GENCERT in the FACILITY class or for user certificates where READ or UPDATE authority is given to ringOwner.ringName.LST resource in the RDATALIB class.

The z/OS PKCS #11 token name is specified as *TOKEN*/token-name. *TOKEN* indicates that the specified key ring is actually a token name. The application user ID must have READ access to resource USER.token-name in the CRYPTOZ class in order for the certificate and their private keys, if present, to be read.

keyring_pw

Specifies the password for the key database as a null-terminated character string. Specify NULL to indicate that no password is provided.

keyring_stash

Specifies the name of the password stash file as a null-terminated character string. Specify NULL to indicate no stash file is provided. The password stash file is used if the keyring_pw value is NULL.

V2_session_timeout

Specifies the SSL V2 session cache timeout value in seconds. The valid range is 0 to 100. A short SSL handshake is performed when a cached session exists since the session parameters have already been negotiated between the client and the server.

V3_session_timeout

Specifies the SSL V3 session cache timeout value in seconds. The valid range is 0 to 86400. A short SSL handshake is performed when a cached session exists since the session parameters have already been negotiated between the client and the server.

LDAP_server

Specifies one or more blank-separated LDAP server host names as a null-terminated character string. Each host name can contain an optional port number separated from the host name by a colon. The LDAP server is used for certificate validation . The LDAP server is used only when LDAP_CA_roots is set to GSK_CA_ROOTS_LOCAL_AND_X500 and auth_type is not set to GSK_CLIENT_AUTH_LOCAL or GSK_CLIENT_AUTH_PASSTHRU.

LDAP_port

Specifies the LDAP server port. The default LDAP port will be used if 0 is specified.

LDAP_user

Specifies the distinguished name to use when connecting to the LDAP server and is a null-terminated character string. An anonymous bind is done if NULL is specified for this field.

LDAP_password

Specifies the password to use when connecting to the LDAP server and is a null-terminated character string. This field is ignored if NULL is specified for LDAP_user.

LDAP_CA_roots

Specifies the location of CA certificates and certificate revocation lists used to validate certificates. When GSK_CA_ROOTS_LOCAL_ONLY is specified, the CA certificates and certificate revocation lists are obtained from the local database. When GSK_CA_ROOTS_LOCAL_AND_X500 is specified, the CA certificates and certificate revocation lists are obtained from the LDAP server if they are not found in the local database. Even when an LDAP server is used, root CA certificates must be found in the local database since the LDAP server is not a trusted data source.

auth_type

Specifies the client authentication type. This field is ignored unless LDAP_CA_roots is set to GSK_CA_ROOTS_LOCAL_AND_X500. The client certificate is not validated when GSK_CLIENT_AUTH_PASSTHRU is specified. The client certificate is validated using just the local database when GSK_CLIENT_AUTH_LOCAL is specified. CA certificates and certificate revocation lists not found in the local database are obtained from the LDAP server when GSK_CLIENT_AUTH_STRONG or GSK_CLIENT_AUTH_STRONG_OVER_SSL is specified (the local database must still contain the root CA certificates). There is no difference between GSK_CLIENT_AUTH_STRONG and GSK_CLIENT_AUTH_STRONG_OVER_SSL.

gsk_initialize() Supported environment variables:

Environment variables are processed along with the information passed in the gsk_init_data structure during environment initialization. Also, during environment initialization, the key database, key ring, or token is read.

The gsk_initialize() routine supports these environment variables:

GSK_CERT_VALIDATE_KEYRING_ROOT

Specifies the setting of how certificates in a SAF key ring are validated. Specify GSK_CERT_VALIDATE_KEYRING_ROOT "ON" or "1" if SAF key ring certificates must be validated to the root CA certificate. 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 and PKCS #11 token certificates as these certificates are always validated to the root CA certificate.

GSK_EXTENDED_RENEGOTIATION_INDICATOR

Specifies the level of enforcement of renegotiation indication as specified by RFC 5746 during the initial handshake.

Specify "OPTIONAL" to not require the renegotiation indicator during initial handshake. This is the default.

Specify "CLIENT" to allow the client initial handshake to proceed only if the server indicates support for RFC 5746 Renegotiation.

Specify "SERVER" to allow the server initial handshake to proceed only if the client indicates support for RFC 5746 Renegotiation.

Specify "BOTH" to allow the server and client initial handshakes to proceed only if partner indicates support for RFC 5746 Renegotiation.

GSK_RENEGOTIATION

Specifies the type of session renegotiation that is allowed for an SSL environment.

Specify "NONE" to disable SSL V3 and TLS handshake renegotiation as a server and allow RFC 5746 renegotiation. This is the default.

Specify "DISABLED" to disable SSL V3 and TLS handshake renegotiation as a server and also disable RFC 5746 renegotiation.

Specify "ALL" to allow SSL V3 and TLS handshake renegotiation as a server while also allowing RFC 5746 renegotiation.

Specify "ABBREVIATED" to allow 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.

GSK_RENEGOTIATION_PEER_CERT_CHECK

Specifies if the peer certificate is allowed to change during renegotiation.

Specify "OFF" or "0" to 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.

Specify "ON" or "1" to perform a comparison against the peer's certificate to ensure that certificate does not change during renegotiation.

GSKV2CACHESIZE

Specifies the number of entries in the SSL V2 session cache with a range of 0 to 32000. The value that is specified by the GSK_V2_SIDCACHE_SIZE environment variable is used if the GSKV2CACHESIZE variable is not defined. The default value is 256 if neither environment variable is defined.

GSKV3CACHESIZE

Specifies the number of entries in the SSL V3 session cache with a range of 0 to 64000. The value that is specified by the GSK_V3_SIDCACHE_SIZE environment variable is used if the GSKV3CACHESIZE variable is not defined. The default value is 512 if neither environment variable is defined. The SSL V3 session cache is used for both the SSL V3 and TLS V1.0 protocols.

The environment variables that are overridden with information passed in the gsk_init_data structure are:

GSK_KEYRING_FILE
GSK_KEYRING_PW
GSK_KEYRING_STASH
GSK_LDAP_SERVER
GSK_LDAP_PASSWORD
GSK_LDAP_PORT
GSK_LDAP_USER
GSK_PROTOCOL_SSLV2
GSK_PROTOCOL_SSLV3
GSK_PROTOCOL_TLSV1
GSK_V2_SESSION_TIMEOUT
GSK_V3_SESSION_TIMEOUT

Format

Parameters

Results

Usage

Related Topics