gsk_environment_init()--Initialize an SSL environment
Syntax
#include <gskssl.h>
int gsk_environment_init(gsk_handle my_env_handle);
Service Program Name: QSYS/QSOSSLSR
Default Public Authority: *USE
Threadsafe: Yes
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:
Multiple SSL environment handles may be opened in a process with different
attributes set for each SSL environment.
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().
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.
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
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():