SSL initialization

The TCP/IP variable SSLENVAR points to an SSL interface configuration file that contains variable assignment statements that provide the information necessary for SSL initialization.

When you are configuring the IMS Connect SSL interface, you must also consider the ability of the IMS Connect client to support SSL connections.

The following example shows an SSL interface configuration file with the default SSL configuration:

####################################################
#   This is my SSL interface configuration file    #
####################################################
GSK_PROTOCOL_SSLV2=GSK_PROTOCOL_SSLV2_ON
GSK_PROTOCOL_SSLV3=GSK_PROTOCOL_SSLV3_ON
GSK_PROTOCOL_TLSV1=GSK_PROTOCOL_TLSV1_ON
GSK_KEYRING_FILE=IMSCONNECT
GSK_KEYRING_LABEL=IMS CONNECT
GSK_KEYRING_PW=
GSK_KEYRING_STASH_FILE=
GSK_CLIENT_AUTH_TYPE=GSK_CLIENT_AUTH_FULL_TYPE
GSK_SESSION_TYPE=GSK_SERVER_SESSION
GSK_V2_CIPHER_SPECS=64
GSK_V3_CIPHER_SPECS=090201

The SSL interface configuration file can contain both variable assignments and comments.

Each comment in the SSL interface configuration file begins with a number sign (#) when the default host codepage 037 is used. For example, #This is a comment.

Note: In the host codepage 037, the number sign is represented by X'7B'. If you are using a codepage other than host codepage 037, you must use the character in the codepage that is represented by X'7B'. For example, if you are using host code page 1144 for Italy, X'7B' represents the pound sign (£). Consequently, you must begin each comment line with £, instead of #.

Each variable assignment statement consists of a variable name and the value that you assign to the variable. Variable assignment statements have the following format: GSK_VARIABLE_NAME=value.

Variable assignment statements can continue across multiple lines. To continue a variable assignment statement on the next line, add a blank space and a dash ( -) at the end of the line. The line immediately following the blank space and dash character sequence is then read as a continuation of the line. Any characters after the blank space-dash sequence (" -") on the same line are ignored.

It is not possible to embed the blank space-dash (" -") character sequence within a variable assignment.

For example, the following excerpt from an SSL configuration file has two variable values that contain dashes, one without a blank space, IMS-Ring, and one with a blank space, IMSCONNECT - Test:

// GSK_KEYRING_FILE=IMS-Ring
// GSK_KEYRING_LABEL=IMSCONNECT - Test
// GSK_KEYRING_PW=
// GSK_KEYRING_STASH_FILE=

When the above configuration file is processed, GSK_KEYRING_FILE=IMS-Ring processes successfully, but GSK_KEYRING_LABEL=IMSCONNECT Certificate - Test produces an error because the blank space and dash is read as an end of the line. Consequently, the characters after the dash, Test, are discarded and the following line, GSK_KEYRING_PW=, is read as a continuation of the value assigned to GSK_KEYRING_LABEL. To illustrate, here is the job log produced by the above configuration file:

// HWSSSL00I   GSK_KEYRING_FILE = "IMS-Ring"
// HWSSSL00I   GSK_KEYRING_FILE...SUCCESS (rc = 0)
// HWSSSL00I   GSK_KEYRING_LABEL = "IMSCONNECTGSK_KEYRING_PW="
// HWSSSL00I   GSK_KEYRING_LABEL...SUCCESS (rc = 0)
// HWSSSL00I   GSK_KEYRING_STASH_FILE = NULL
// HWSSSL00I   GSK_KEYRING_STASH_FILE...SUCCESS (rc = 0)

The possible variables and the values associated with the variables are as follows:

GSK_KEYRING_FILE

Name of the key database or RACF® keyring. If a RACF key ring is specified, it must be an existing key ring and the current user ID must have READ access to the IRR.DIGTCERT.LISTRING and the IRR.DIGTCERT.LIST resources in the FACILITY class.

GSK_KEYRING_LABEL

Label name in the key database file of RACF key ring used. If this is not set, or set to NULL, the default key database or key ring entry is used.

GSK_KEYRING_PW

Password of the key database. This must be NULL when a RACF key ring is used or when a stash file is specified.

GSK_KEYRING_STASH_FILE

Name of the file that contains the password for the keyring. This value must be NULL when a RACF key ring is used.

GSK_V2_CIPHER_SPECS

A null-terminated character string which specifies the ciphers to enable for SSL V2.0. If the parameter is not specified, the default cipher spec list 64 is used.

1 - RC4 US
2 - RC4 Export
3 - RC2 US
4 - RC2 Export
6 - DES 56-bit Export
7 - Triple DES US

Usage example: GSK_V2_CIPHER_SPECS=6321

GSK_V3_CIPHER_SPECS

A null-terminated character string that specifies the ciphers to enable for the SSL V3.0 protocol and the TLS 1.0 and higher protocols. If the parameter is not specified, the default cipher spec list 090201 is used.

For the full list of supported cipher specifications, see z/OS Cryptographic Services System SSL Programming.

01 - NULL MD5
02 - NULL SHA
03 - RC4 MD5 Export
04 - RC4 MD5 US
05 - RC4 SHA US
06 - RC2 MD5 Export
09 - DES SHA Export
0A - Triple DES SHA US

Usage example: GSK_V3_CIPHER_SPECS=0306090201

GSK_PROTOCOL_SSLV2

Used to enable or disable SSL V2.0. Possible values are GSK_PROTOCOL_SSL_V2_ON and GSK_PROTOCOL_SSLV2_OFF.

Note: All SSL V2.0 non-US encryption schemes have been decrypted. Therefore, SSL V2.0 should not be enabled unless the client does not support SSL V3.0 or TLS V1.0 and higher protocols.

GSK_PROTOCOL_SSLV3

Used to enable or disable SSL V3.0. Possible values are GSK_PROTOCOL_SSLV3_ON and GSK_PROTOCOL_SSLV3_OFF.

GSK_PROTOCOL_TLSV1

Used to enable or disable TLS V1.0. Possible values are GSK_PROTOCOL_TLSV1_ON and GSK_PROTOCOL_TLSV1_OFF.

GSK_PROTOCOL_TLSV1_1

Used to enable or disable TLS V1.1. Possible values are GSK_PROTOCOL_TLSV1_1_ON and GSK_PROTOCOL_TLSV1_1_OFF.

GSK_PROTOCOL_TLSV1_2

Used to enable or disable TLS V1.0. Possible values are GSK_PROTOCOL_TLSV1_2_ON and GSK_PROTOCOL_TLSV1_2_OFF.

GSK_CLIENT_AUTH_TYPE

Indicates the type of client authentication to take place. Two options are available: GSK_CLIENT_AUTH_PASSTHRU_TYPE and GSK_CLIENT_AUTH_FULL_TYPE. The GSK_CLIENT_AUTH_PASSTHRU_TYPE specifies to not authenticate if the client sends a certificate. GSK_CLIENT_AUTH_FULL_TYPE validates all received certificates. If the certificate cannot be validated, the connection is terminated. If no certificate is sent by the client, the connection is unsuccessful.

GSK_SESSION_TYPE

Indicates whether or not to require client authentication. A value of GSK_SERVER_SESSION does not require authentication. GSK_SERVER_SESSION_WITH_CL_AUTH does require client authentication.

GSK_V2_SESSION_TIMEOUT

The number of seconds before the SSL V2.0 session identifier expires. The valid range is from 0 to 100 seconds. If the session timeout value has not expired, the client and server, as well as peer clients (multiple client connections from same client computer) do not need to perform a handshake when starting a new connection.

GSK_V3_SESSION_TIMEOUT

The number of seconds before the SSL V3.0 session identifier expires. The valid range is from 0 to 100 seconds. If the session timeout value has not expired, the client and server as well as peer clients (multiple client connections from same client computer) do not need to perform a handshake when starting a new connection.

GSK_V2_SIDCACHE_SIZE

The maximum number of session ID elements that can be stored in the SSL V3.0 cache. The range is 0 to 32000 entries.

GSK_TLS_SIG_ALG_PAIRS

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

The signature algorithm pair specifications are sent by either the client or server to the session partner to indicate which hash and signature algorithm combinations are supported for digital signatures. Signature algorithm pair specification only has relevance for sessions using TLS V1.2 or higher protocols.

For a list of valid 4-character signature algorithm pair specifications, see the Cipher suite definitions topic in z/OS: Cryptographic Services System SSL Programming.

FIPS_MODE

Used to enable or disable FIPS mode. Possible values are GSK_FIPS_STATE_ON and GSK_FIPS_STATE_OFF.

DEBUG_SSL

Indicates whether or not to turn on SSL debugging information. If the debug information is requested, it can be found in the job output after the IMS Connect job has completed. Possible assignment values are ON and OFF.

Usage example: DEBUG_SSL=ON