gsk_environment_open()--Get a handle for an SSL environment
Syntax
#include <gskssl.h>
int gsk_environment_open(gsk_handle *my_env_handle);
Service Program Name: QSYS/QSOSSLSR
Default Public Authority: *USE
Threadsafe: Yes
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_OS400_ERROR_INVALID_POINTER]
The my_env_handle pointer is not valid.
Error Messages
Message ID
Error Message Text
CPE3418 E
Possible APAR condition or hardware failure.
CPF9872 E
Program or service program &1 in library &2 ended.
Reason code &3.
CPFA081 E
Unable to set return value or error code.
Usage Notes
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_OS400_READ_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_PROTOCOL_TLSV12 set
to GSK_FALSE.
GSK_PROTOCOL_TLSV11 set to GSK_FALSE.
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.
The default cipher suite list in preference order as shipped is as follows:
GSK_TLS12_CIPHER_SPECS_EX set to the equivalent
string representation of TLS Version 1.2 default cipher list "3C2F3D35"
stored in GSK_TLS12_CIPHER_SPECS.
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 "2F35" 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.
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.
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.
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.