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_AS400_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_AS400_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_AS400_ERROR_NOT_REGISTERED]

The application identifier has not been registered.

[GSK_AS400_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_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().

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_environment_close()--Close the SSL environment
  
  
• gsk_environment_open()--Get a handle for an SSL environment
  
  
• gsk_strerror()--Retrieve GSK runtime error message