gsk_environment_open()--Get a handle for an SSL environment

 #include <gskssl.h>

 int gsk_environment_open(gsk_handle *my_env_handle);

The gsk_environment_open() function is used to get storage for the SSL environment. This function call must be issued before any other gsk function calls are issued. This call returns an SSL environment handle that must be saved and used on subsequent gsk calls.

Parameters

my_env_handle (Output) 

A pointer to the SSL environment handle to be used for subsequent gsk function calls.

Authorities

No authorization is required.

Return Value

gsk_environment_open() returns an integer. Possible values are:

[GSK_OK]

gsk_environment_open() was successful.

[GSK_API_NOT_AVAILABLE]

Digital Certificate Manager (DCM), 57xx-SS1 - IBM i Option 34 is not installed.

[GSK_INSUFFICIENT_STORAGE]

Not able to allocate storage for the requested operation.

[GSK_INTERNAL_ERROR]

An internal error occured during system processing.

[GSK_IBMI_ERROR_INVALID_POINTER]

The my_env_handle pointer is not valid.

Error Messages

Usage Notes

1. After gsk_environment_open() returns with a GSK_OK return value, attributes for the SSL environment have been set and can be retrieved using any of the get function calls. The following is a list of the defaulted values:
   • GSK_V2_SESSION_TIMEOUT set to 100 seconds.
   • GSK_V3_SESSION_TIMEOUT set to 86400 seconds (24 hours).
   • GSK_HANDSHAKE_TIMEOUT set to 0 (wait forever).
   • GSK_IBMI_RECEIVE_TIMEOUT set to 0 (wait forever).
   • GSK_SESSION_TYPE set to GSK_CLIENT_SESSION.
   • GSK_KEYRING_LABEL set to use the default certificate from the certificate store file.
   • GSK_KEYRING_LABEL_EX set to use the default certificate from the certificate store file.
   • GSK_PROTOCOL_TLSV12 set to GSK_TRUE.
   • GSK_PROTOCOL_TLSV11 set to GSK_TRUE.
   • GSK_PROTOCOL_TLSV10 set to GSK_TRUE.
     
   • GSK_PROTOCOL_TLSV1 set to GSK_PROTOCOL_TLSV1_ON.
   • GSK_PROTOCOL_SSLV3 set to GSK_PROTOCOL_SSLV3_OFF.
   • GSK_PROTOCOL_SSLV2 set to GSK_PROTOCOL_SSLV2_OFF.
   • GSK_TLS12_CIPHER_SPECS_EX set to the default TLS Version 1.2 cipher suite list.
   • GSK_TLS12_CIPHER_SPECS set to the default TLS Version 1.2 cipher suite list.
   • GSK_TLS11_CIPHER_SPECS_EX set to the default TLS Version 1.1 cipher suite list.
   • GSK_TLS11_CIPHER_SPECS set to the default TLS Version 1.1 cipher suite list.
   • GSK_TLS10_CIPHER_SPECS_EX set to the default TLS Version 1.0 cipher suite list.
   • GSK_TLS10_CIPHER_SPECS set to the default TLS Version 1.0 cipher suite list.
   • GSK_V3_CIPHER_SPECS_EX set to the default SSL Version 3 cipher suite list.
     
   • GSK_V3_CIPHER_SPECS set to the default SSL Version 3 cipher suite list.
   • GSK_V2_CIPHER_SPECS set to the default SSL Version 2 cipher suite list.
   • GSK_OCSP_PROXY_SERVER_PORT set to 0.
   • GSK_OCSP_MAX_RESPONSE_SIZE set to 20480 bytes.
   • GSK_OCSP_TIMEOUT set to 10 seconds.
   • GSK_OCSP_NONCE_SIZE set to 8 bytes.
   • GSK_OCSP_CLIENT_CACHE_SIZE set to 1. (OSCP response caching enabled)
   • GSK_OCSP_ENABLE set to GSK_FALSE.
   • GSK_OCSP_NONCE_GENERATION_ENABLE set to GSK_FALSE.
   • GSK_OCSP_NONCE_CHECK_ENABLE set to GSK_FALSE.
   • GSK_OCSP_RETRIEVE_VIA_GET set to GSK_TRUE.
   • GSK_EXTENDED_RENEGOTIATION_CRITICAL_CLIENT set to GSK_FALSE.
   • GSK_EXTENDED_RENEGOTIATION_CRITICAL_SERVER set to GSK_FALSE.
   • GSK_ALLOW_UNAUTHENTICATED_RESUME set to GSK_ALLOW_UNAUTHENTICATED_RESUME_OFF.
   • GSK_CERTREQ_DNLIST_ENABLE set to GSK_TRUE.
   • GSK_SSL_EXTN_SIGALG set to use the System SSL default signature algorithm list.
   • GSK_SSL_EXTN_MAXFRAGMENT_SIZE set to 16384.
   • GSK_TLS_CBCPROTECTION_METHOD set to GSK_TLS_CBCPROTECTION_METHOD_NONE.
     
   
   
2. The default cipher suite list in preference order as shipped is as follows:
   • GSK_TLS12_CIPHER_SPECS_EX set to:

     
        'TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384,
         TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
         TLS_RSA_WITH_AES_128_CBC_SHA256,TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA256,
         TLS_RSA_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_128_GCM_SHA256,TLS_RSA_WITH_AES_256_GCM_SHA384,
         TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,
         TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384'
     

     GSK_TLS12_CIPHER_SPECS set to "3C2F3D359C9D".
     
     Note: The GSK_TLSV12_CIPHER_SPECS list may not reflect all of the ciphers in use by the environment or session if ciphers that do not have a GSK_TLSV12_CIPHER_SPECS equivalent representation are enabled.
     
     
   • GSK_TLS11_CIPHER_SPECS_EX set to the equivalent string representation of TLS Version 1.1 default cipher list "2F35" stored in GSK_TLS11_CIPHER_SPECS.
   • GSK_TLS10_CIPHER_SPECS_EX set to the equivalent string representation of TLS Version 1.0 default cipher list "2F35" stored in GSK_TLS10_CIPHER_SPECS.
   • GSK_V3_CIPHER_SPECS_EX set to the equivalent string representation of SSL Version 3 default cipher list "" stored in GSK_V3_CIPHER_SPECS.
   • GSK_V2_CIPHER_SPECS set to ""
     

     The current default cipher suite list can be different from the install time list due to changes made to the QSSLCSL (SSL cipher specification list) system value via the Change System Value (CHGSYSVAL) command. A cipher suite removed from the SSL cipher specification list will also be removed from the default cipher suite list shown here. A cipher suite removed from the eligible default cipher specification list using System Service Tools (SST) Advanced Analysis Command SSLCONFIG will also be removed from the default cipher suite list shown here. For additional information see the help text for SSLCONFIG. The order of the cipher suites in QSSLCSL will be used to order the cipher suites in the default list. gsk_attribute_get_buffer() for GSK_TLS12_CIPHER_SPECS_EX, GSK_TLS11_CIPHER_SPECS_EX, GSK_TLS10_CIPHER_SPECS_EX, and GSK_V3_CIPHER_SPECS_EX can be used to determine the current default cipher suite list configuration for the appropriate protocol version.

     See the usage notes in gsk_attribute_set_buffer() API for the format of the ciphers.

3. The default values for GSK_PROTOCOL_TLSV12, GSK_PROTOCOL_TLSV11, GSK_PROTOCOL_TLSV10, GSK_PROTOCOL_TLSV1 and GSK_PROTOCOL_SSLV3 can be altered by changing the QSSLPCL (SSL protocols) system value via the Change System Value (CHGSYSVAL) command. When a protocol is removed from the SSL protocols system value it results in the protocol being set to off rather than on by default as that protocol is now disabled for the entire system. A protocol value removed from the eligible default protocol list using System Service Tools (SST) Advanced Analysis Command SSLCONFIG will also be removed as a default here. For additional information see the help text for SSLCONFIG. gsk_attribute_get_enum() for each of those values can be called to determine the current default protocols enabled.
   
   
4. The Display System Value (DSPSYSVAL) command or the Retrieve System Values (QWCRSVAL) API can be used to determine the current settings of the supported ciphers and protocols for system SSL.
   
   
5. Change System Value (CHGSYSVAL) allows an administrator to disable protocols or ciphers from being used by the GSKit APIs. For backwards compatibility, GSKit support will silently ignore attempts by applications to use disabled protocols or ciphers unless only disabled values are used.

Related Information

• gsk_attribute_set_buffer()--Set character information for an secure session or a SSL environment
  
  
• gsk_attribute_set_enum()--Set enumerated information for a secure session or an SSL environment
  
  
• gsk_attribute_set_numeric_value()--Set numeric information for a secure session or an SSL environment
  
  
• gsk_environment_close()--Close the SSL environment
  
  
• gsk_environment_init()--Initialize an SSL environment
  
  
• gsk_strerror()--Retrieve GSK runtime error message