gsk_environment_init()--Initialize an SSL environment

 #include <gskssl.h>

 int gsk_environment_init(gsk_handle my_env_handle);

The gsk_environment_init() function is used to initialize the SSL environment after any required attributes are set. The certificate store file is opened and other operations such as accessing information in the registration facility are performed to set up this environment. After this function call is issued, SSL is ready to process secure session requests.

Parameters

my_env_handle (Input) 

The handle identifying the SSL environment that will be initialized.

Authorities

Authorization of *R (allow access to the object) to the certificate store file and its associated files is required. Authorization of *X (allow use of the object) to each directory of the path name of the certificate store file and its associated files is required.

Return Value

gsk_environment_init() returns an integer. Possible values are:

[GSK_OK]

gsk_environment_init() was successful.

[GSK_INVALID_HANDLE]

The handle specified was not valid.

[GSK_INVALID_STATE]

A gsk_environment_init() has already been issued with this handle.

[GSK_KEYRING_OPEN_ERROR]

Certificate store file could not be opened.

[GSK_OS400_ERROR_NO_ACCESS]

No permission to access the certificate store file.

[GSK_ERROR_BAD_V3_CIPHER]

An SSLV3 or TLSV1 cipher suite was specified that is not valid.

[GSK_ERROR_BAD_V2_CIPHER]

An SSLV2 cipher suite was specified that is not valid.

[GSK_ERROR_BAD_CERTIFICATE]

The certificate is bad.

[GSK_ERROR_NO_PRIVATE_KEY]

There is no private key associated with the certificate.

[GSK_OS400_ERROR_PASSWORD_EXPIRED]

The validity time period of the certificate store file password has expired.

[GSK_ERROR_BAD_KEYFILE_LABEL]

The specified certificate store's certificate label is not valid or does not exist.

[GSK_ERROR_BAD_KEYFILE_PASSWORD]

The specified certificate store password is not valid.

[GSK_NO_KEYFILE_PASSWORD]

No certificate store password was specified.

[GSK_OS400_ERROR_NOT_REGISTERED]

The application identifier has not been registered.

[GSK_OS400_ERROR_INVALID_POINTER]

my_env_handle pointer is not valid.

[GSK_ERROR_BAD_KEY_LEN_FOR_EXPORT]

The certificate was created with a key length that cannot be exported.

[GSK_INSUFFICIENT_STORAGE]

Not able to allocate storage for the requested operation.

[GSK_INTERNAL_ERROR]

An unexpected error occurred during SSL processing.

[GSK_ERROR_UNSUPPORTED]

Operation is not supported by SSL.

None of the specified protocol or cipher values are supported by System SSL.

[GSK_ERROR_IO]

An error occurred in SSL processing, check errno value.

Error Conditions

When the gsk_environment_init() API fails with return code [GSK_ERROR_IO], errno can be set to:

[EINTR]

Interrupted function call.

[EDEADLK]

Resource deadlock avoided.

[ETERM]

Operation terminated.

If an errno is returned that is not in this list, look in Errno Values for UNIX^®-Type Functions for a description of the errno.

Error Messages

Usage Notes

1. If gsk_environment_init() fails, gsk_environment_close() must be issued to clean up resources.
   
   
2. Multiple SSL environment handles may be opened in a process with different attributes set for each SSL environment.
   
   
3. The status of the local certificate can be determined by checking the GSK_CERTIFICATE_VALIDATION_CODE enumId using gsk_attribute_get_numeric_value(). The numValue will indicate the certificate validation return code for the certificate used on this gsk_environment_init().
   
   
4. Change System Value (CHGSYSVAL) command 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. GSK_ERROR_UNSUPPORTED will be returned when no enabled values are specified. See gsk_environment_open() for additional details.
   
   
5. When GSK_OS400_APPLICATION_ID is used several of the attribute settings may have changed after this call completes. The Application ID definition configured using Digital Certificate Manager (DCM) can be used to override the settings without requiring the code to be changed. gsk_attribute_get_enum() and gsk_attribute_get_buffer() can be used to determine if a specific attribute setting changed.
   These are the buffer attributes that can be overwritten:
   • GSK_TLSV12_CIPHER_SPECS_EX
   • GSK_TLSV11_CIPHER_SPECS_EX
   • GSK_TLSV10_CIPHER_SPECS_EX
   • GSK_V3_CIPHER_SPECS_EX
   • GSK_TLSV12_CIPHER_SPECS
   • GSK_TLSV11_CIPHER_SPECS
   • GSK_TLSV10_CIPHER_SPECS
   • GSK_V3_CIPHER_SPECS
   • GSK_SSL_EXTN_SIGALG
   • GSK_OCSP_URL
   These are the enum attributes that can be overwritten:
   • GSK_PROTOCOL_TLSV12
   • GSK_PROTOCOL_TLSV11
   • GSK_PROTOCOL_TLSV10
   • GSK_PROTOCOL_TLSV1
   • GSK_PROTOCOL_SSLV3
   • GSK_PROTOCOL_SSLV2
   • GSK_OCSP_ENABLE
   • GSK_EXTENDED_RENEGOTIATION_CRITICAL_CLIENT
   • GSK_EXTENDED_RENEGOTIATION_CRITICAL_SERVER
   
   
6. When GSK_OS400_APPLICATION_ID is set, the settings of some of the SSL environment attributes will be affected by the corresponding value in the Application ID definition in Digital Certificate Manager (DCM). These are the buffer attributes that can be appended by DCM to the end of the existing SSL environment buffer attributes during the call to gsk_environment_init():
   • GSK_SSL_EXTN_SERVERNAME_LIST
   • GSK_SSL_EXTN_SERVERNAME_CRITICAL_LIST
   
   
   

Related Information

• gsk_attribute_set_buffer()--Set character information for a secure session or an 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_attribute_get_buffer()--Get character information for a secure session or an SSL environment.
  
  
• gsk_attribute_get_enum()--Get enumerated information for a secure session or an SSL environment.
  
  
• gsk_attribute_get_numeric_value()--Get numeric information for a secure session or an SSL environment
  
  
• gsk_environment_close()--Close the SSL environment
  
  
• gsk_environment_open()--Get a handle for an SSL environment
  
  
• gsk_strerror()--Retrieve GSK runtime error message