Create an SSL environment

For both the client and server System SSL programs, you must initialize the System SSL environment using the programming interfaces associated with the SSL environment layer.

gsk_environment_open()

Will define and obtain storage for the SSL environment and return an environment handle to be used on subsequent API invocations.

gsk_attribute_set...()

Sets environment attributes such as:

The SSL protocol version to be used: SSL Version 2.0, SSL Version 3.0, TLS Version 1.0, TLS Version 1.1, and/or TLS Version 1.2.
The key database to be used. (key database file, SAF key ring or z/OS® PKCS #11 token)
The password for the key database. This can be specified directly by the application or by using a stashed password file. See Certificate/Key management for details about creating a stashed password file.
Note: When using SAF key rings or z/OS PKCS #11 tokens, the password and stash file must not be specified.
The amount of time the SSL session identifier information is valid. By using already negotiated and agreed to SSL session identifier information, System SSL can reduce the amount of data exchanged during the SSL handshake that occurs during the gsk_secure_socket_init() call.

gsk_environment_init()

Initializes the SSL environment.

This example code illustrates how to call the environment layer programming interface from a client or server System SSL program. In this example, TLS Version 1.0 support is requested, /keyring/key.kdb is the key database that is used, the password for the key database is "password", and default values are taken for the remaining SSL environment variable attributes.

    gsk_handle env_handle;
    int      rc;

    /* create the SSL environment */
    rc = gsk_environment_open(&env_handle);

    /* set environment attributes */
    rc = gsk_attribute_set_enum(env_handle, GSK_PROTOCOL_SSLV2, GSK_PROTOCOL_SSLV2_OFF); 
                                        /* By default, SSL V2 protocol is set on */
    rc = gsk_attribute_set_enum(env_handle, GSK_PROTOCOL_SSLV3, GSK_PROTOCOL_SSLV3_OFF);
                                        /* By default, SSL V3.0 protocol is set on */
    rc = gsk_attribute_set_enum(env_handle, GSK_PROTOCOL_TLSV1, GSK_PROTOCOL_TLSV1_ON);
    rc = gsk_attribute_set_enum(env_handle, GSK_PROTOCOL_TLSV1_1, GSK_PROTOCOL_TLSV1_1_OFF);
    rc = gsk_attribute_set_enum(env_handle, GSK_PROTOCOL_TLSV1_2, GSK_PROTOCOL_TLSV1_2_OFF); 
    rc = gsk_attribute_set_buffer(env_handle, GSK_KEYRING_FILE, "/keyring/key.kdb",0);
    rc = gsk_attribute_set_buffer(env_handle, GSK_KEYRING_PW, "password",0);

    /* initialize environment     */
    rc = gsk_environment_init(env_handle);

This example code illustrates how to create an SSL environment for a server System SSL program supporting TLS Version 1.0, TLS Version 1.1, and TLS Version 1.2.

    gsk_handle env_handle;
    int     rc;

    /* create the SSL environment */
    rc = gsk_environment_open(&env_handle);

    /* set environment attributes */
    rc = gsk_attribute_set_enum(env_handle, GSK_PROTOCOL_SSLV2, GSK_PROTOCOL_SSLV2_OFF);
                                             /* By default, SSL V2.0 protocol is set on */
    rc = gsk_attribute_set_enum(env_handle, GSK_PROTOCOL_SSLV3, GSK_PROTOCOL_SSLV3_OFF);
                                             /* By default, SSL V3.0 protocol is set on */
    rc = gsk_attribute_set_enum(env_handle, GSK_PROTOCOL_TLSV1, GSK_PROTOCOL_TLSV1_ON);
    rc = gsk_attribute_set_enum(env_handle, GSK_PROTOCOL_TLSV1_1, GSK_PROTOCOL_TLSV1_1_ON);
                                             /* By default, TLS V1.1 protocol is set off */
    rc = gsk_attribute_set_enum(env_handle, GSK_PROTOCOL_TLSV1_2, GSK_PROTOCOL_TLSV1_2_ON);
                                             /* By default, TLS V1.2 protocol is set off */
    rc = gsk_attribute_set_buffer(env_handle, GSK_KEYRING_FILE, "/keyring/key.kdb",0);
    rc = gsk_attribute_set_buffer(env_handle, GSK_KEYRING_PW, "password",0);

    /* initialize environment     */
    rc = gsk_environment_init(env_handle);

Note: When the environment is initialized, the environment attributes cannot be changed unless they are also attributes of the secure socket connection. In this case, they can be changed only for that connection. If changes are necessary to the environment, a new SSL environment can be created within the same process.

When the System SSL program successfully creates the SSL environment, it must now perform the steps that are needed to allow the program to communicate with a peer program. The exact sockets and System SSL calls required to allow the program to communicate differ depending on whether the program is a client or a server.