gsk_attribute_get_buffer()--Get character information about a secure session or an SSL environment
Syntax
#include <gskssl.h> int gsk_attribute_get_buffer(gsk_handle my_gsk_handle, GSK_BUF_ID bufID, const char **buffer, int *bufSize);Service Program Name: QSYS/QSOSSLSR
Default Public Authority: *USE
Threadsafe: Yes
The gsk_attribute_get_buffer() function is used to obtain specific character string information about a secure session or an SSL environment. It can be used to obtain values such as certificate store file, certificate store password, application ID, and ciphers.
Parameters
- my_gsk_handle (Input)
- Indicates one of the following handles:
- The handle for the secure session (my_session_handle)
- The handle for the SSL environment (my_env_handle)
- bufID (Input)
- The following values can be used to retrieve information about the secure
session or the SSL environment that is either defaulted or explicitly set:
- GSK_KEYRING_FILE (201) - buffer points to the
name of the certificate store file being used for the SSL environment.
- GSK_KEYRING_PW (202) - buffer points to the
password for the certificate store file being used for the SSL environment.
- GSK_KEYRING_LABEL (203) - buffer points to the
certificate label associated with the certificate in the certificate store
identified by GSK_KEYRING_FILE to be used for the secure
session or SSL environment.
-
GSK_KEYRING_LABEL_EX (254) - buffer points to a list of
up to four comma delimited string values of the certificate labels associated with the
certificates in the certificate store to be used for the secure session or SSL
environment.
- GSK_IBMI_APPLICATION_ID (6999) - buffer points
to the application identifier being used for the SSL environment.
-
GSK_TLSV12_CIPHER_SPECS_EX (243) - buffer points to a
list of comma delimited string values of the TLS Version 1.2 ciphers to be used
for the secure session or the SSL environment.
GSK_TLSV12_CIPHER_SPECS (238) (Deprecated) - buffer points to a list of two-character string codes of the TLS Version 1.2 ciphers to be used for the secure session or the SSL environment. Setting this to NULL will result in the System SSL default list of ciphers being used as indicated in the usage notes.
Replaced by GSK_TLSV12_CIPHER_SPECS_EX as some new ciphers can be not represented by two characters. The ciphers that can not be represented will be used for this session/environment where appropriate based on other settings; however, those ciphers will not appear for this attribute.
See the usage notes in gsk_attribute_set_buffer() API for the format of the ciphers.
- GSK_TLSV11_CIPHER_SPECS_EX (242) - buffer points to
a list of comma delimited string values of the TLS Version 1.1 ciphers to be
used for the secure session or the SSL environment.
GSK_TLSV11_CIPHER_SPECS (237) (Deprecated) - buffer points to a list of two-character string codes of the TLS Version 1.1 ciphers to be used for the secure session or the SSL environment. Setting this to NULL will result in the System SSL default list of ciphers being used as indicated in the usage notes.
Replaced by GSK_TLSV11_CIPHER_SPECS_EX as some new ciphers can be not represented by two characters. The ciphers that can not be represented will be used for this session/environment where appropriate based on other settings however those ciphers will not appear for this attribute.
See the usage notes in gsk_attribute_set_buffer() API for the format of the ciphers.
- GSK_TLSV10_CIPHER_SPECS_EX (241) - buffer points to
a list of comma delimited string values of the TLS Version 1.0 ciphers to be
used for the secure session or the SSL environment.
GSK_TLSV10_CIPHER_SPECS (236) (Deprecated) - buffer points to a list of two-character string codes of the TLS Version 1.0 ciphers to be used for the secure session or the SSL environment. Setting this to NULL will result in the System SSL default list of ciphers being used as indicated in the usage notes.
Replaced by GSK_TLSV10_CIPHER_SPECS_EX as some new ciphers can be not represented by two characters. The ciphers that can not be represented will be used for this session/environment where appropriate based on other settings however those ciphers will not appear for this attribute.
See the usage notes in gsk_attribute_set_buffer() API for the format of the ciphers.
- GSK_V3_CIPHER_SPECS_EX (240) - buffer points to a
list of comma delimited string values of the SSL Version 3 ciphers to be used
for the secure session or the SSL environment.
GSK_V3_CIPHER_SPECS (206) (Deprecated) - buffer points to a list of two-character string codes of the SSL Version 3 ciphers to be used for the secure session or the SSL environment. For compatibility with previous releases, if this value is set, its value will be duplicated into the GSK_TLSV10_CIPHER_SPECS and GSK_TLSV10_CIPHER_SPECS_EX values if the default value has not been changed by an explicit set call for either of those attributes.
Replaced by GSK_V3_CIPHER_SPECS_EX as some new ciphers can be not represented by two characters.
See the usage notes in gsk_attribute_set_buffer() API for the format of the ciphers.
- GSK_V2_CIPHER_SPECS (205) - buffer points to the
list of available SSL Version 2 ciphers to be used for the secure session or
the SSL environment. See the usage notes in gsk_attribute_set_buffer() API for the
format of the ciphers.
-
GSK_CONNECT_SEC_TYPE (208) - buffer points to a string
containing "SSLV2", "SSLV3", "TLSV1", "TLSV11" or "TLSV12," depending on what
was actually negotiated for use by the secure session. For compatibility with
previous releases, "TLSV1" is returned for TLS Version 1.0 instead of "TLSV10".
- GSK_CONNECT_CIPHER_SPEC_EX (244) - buffer is a
string describing the cipher specification negotiated for use by the secure
session.
GSK_CONNECT_CIPHER_SPEC (207) (Deprecated) - buffer points to a one- or two-character string describing the cipher specification negotiated for use by the secure session.
Replaced by GSK_CONNECT_CIPHER_SPEC_EX as some new ciphers can be not represented by two characters.
- GSK_SID_VALUE (212) - buffer points to a
string containing the session ID (SID) used for the secure session.
-
GSK_SSL_EXTN_SIGALG (245) - buffer points to the list
of comma delimited string values of signature algorithms to be supported by the
SSL environment when using TLS version 1.2. See the usage notes in gsk_attribute_set_buffer() API for the
format of the algorithms.
- GSK_OCSP_URL (221) - buffer points to the URL of
the Online Certificate Status Protocol (OCSP) responder to query during
certificate validation. HTTP is the only supported protocol; therefore, the
URL must begin with "http://". This attribute has precedence over
GSK_OSCP_ENABLE. See the usage notes in
gsk_attribute_set_buffer() API
for further use of this attribute in conjunction with
GSK_OCSP_ENABLE.
- GSK_OCSP_PROXY_SERVER_NAME (223) - buffer points
to the name of the proxy server to which OCSP requests should be sent. For
example, myocspproxy.com. If set, all OCSP requests will be sent to the
proxy HTTP server for processing.
- GSK_UNKNOWNREVOCATIONSTATUS_SUBJECT (224) - When a
non-zero buffer length is returned, buffer points to a list of
subject names in the form [SubjectName=]xxxxx for which revocation
status was unknown during certificate validation when OCSP was enabled. A
buffer length of zero indicates that there were no subjects for which
revocation was unknown. This call should be issued immediately after
gsk_secure_soc_init() if using
OCSP.
- GSK_UNKNOWNREVOCATIONSTATUS_SUBJECT_NO_AIA (252) - When a
non-zero buffer length is returned, buffer points to a list of
subject names in the form [SubjectName=]xxxxx for which revocation
status was unknown during certificate validation when OCSP Authority
Information Access (AIA) checking was enabled and an AIA extension was not available.
A buffer length of zero indicates that there were no subjects for which
revocation was unknown when an AIA extension was not available.
This call should be issued immediately after
gsk_secure_soc_init() if using
OCSP.
- GSK_VALIDATIONFAIL_SUBJECT (235) - When a
non-zero buffer length is returned, buffer points to a list of
subject names in the form [SubjectName=]xxxxx for which revocation
status was revoked during certificate validation when OCSP was enabled. A
buffer length of zero indicates that there were no subjects for which
revocation was revoked. This call should be issued immediately after
gsk_secure_soc_init() if using
OCSP.
- GSK_SSL_EXTN_SERVERNAME_REQUEST (230) - buffer
points to a string that represents the Fully Qualified
Domain Name (FQDN) of the server the client intends to communicate with. The
value is used in the TLS Server Name Indication (SNI) extension request as
defined by RFC 6066.
- GSK_SSL_EXTN_SERVERNAME_CRITICAL_REQUEST (231) -
buffer points to a string that represents the the
FQDN of the server the client intends to communicate with. The value is
used in the TLS SNI extension request as defined by RFC 6066.
This attribute should be used instead of GSK_SSL_EXTN_SERVERNAME_REQUEST if the server must respond affirmatively to the FQDN in the SNI request. The secure connection will fail when the server does not provide that affirmation. NOTE - The use of this attribute will result in interoperability issues with servers that do not support the SNI extension.
- GSK_SSL_EXTN_SERVERNAME_LIST (232) - buffer
points to both a null-terminated FQDN and certificate label set for the
server. The FQDN and certificate label strings are separated by a NULL
character (i.e., "www.gskit.org\0my_label\0"). The label must be
from the certificate store file specified for the SSL Environment. This
would be *SYSTEM if GSK_IBMI_APPLICATION_ID is set. The
server will use the certificate and private key for any secure connections
with a matching client SNI FQDN request. If the client SNI request is not
matched, the server session will use the configured default certificate with
no SNI acknowledgement. This attribute can be called multiple times to
retrieve an array of FQDN and certificate label pairs previously set.
NULL is returned when all array entries have been returned. The next call
would repeat the process starting at the beginning of the array.
- GSK_SSL_EXTN_SERVERNAME_CRITICAL_LIST (233) -
buffer points to both a null-terminated FQDN and certificate label
set for the server. Use this attribute instead of
GSK_SSL_EXTN_SERVERNAME_LIST if the client SNI request must
match an entry in this list and result in an error if it is not matched.
This critical condition only applies when a client sends the SNI extension
and does not apply when the client does not send the extension. This
attribute can be called multiple times to retrieve an array of FQDN and
certificate label pairs previously set. NULL is returned when all array
entries have been returned. The next call would repeat the process
starting at the beginning of the array.
- GSK_SSL_EXTN_SERVERNAME (234) - buffer points to
the FQDN that was negotiated using the SNI extension. This is one way a
server would determine which of its certificates was used for the secure
session.
- GSK_CONNECT_COMPRESSION (247) - buffer points to
a string describing the compression specification used for the connection.
*NONE is the only supported value.
- GSK_KEYRING_FILE (201) - buffer points to the
name of the certificate store file being used for the SSL environment.
- buffer (Output)
- The address of the location to place the pointer that will point to the
buffer containing the requested information. The storage for this information
was allocated by the system from user heap storage and will be freed by the
gsk_secure_soc_close() API or the
gsk_environment_close() API.
The data in the buffer is assumed to be represented in the CCSID (coded character set identifier) currently in effect for the job. If the CCSID of the job is 65535, this buffer is assumed to be represented in the default CCSID of the job.
- bufSize (Output)
- The address of the location to store the length of the requested information pointed to by buffer.
Authorities
No authorization is required.
Return Value
gsk_attribute_get_buffer()returns an integer. Possible values are:
- [GSK_OK]
- gsk_attribute_get_buffer() was successful.
- [GSK_ATTRIBUTE_INVALID_ID]
- The specified bufID was not valid.
- [GSK_INVALID_HANDLE]
- The specified handle was not valid.
- [GSK_IBMI_ERROR_INVALID_POINTER]
- The buffer or bufSize pointer is not valid.
- [GSK_ERROR_UNSUPPORTED]
- The bufID currently is not supported.
- [GSK_ERROR_IO]
- An error occurred in SSL processing. Check the errno value.
Error Conditions
When the gsk_attribute_get_buffer() 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.
Usage Notes
- The following GSK_BUF_ID values may be retrieved from the SSL
environment after gsk_environment_open().
- GSK_KEYRING_FILE
- GSK_KEYRING_PW
- GSK_KEYRING_LABEL
- GSK_KEYRING_LABEL_EX
- GSK_IBMI_APPLICATION_ID
- GSK_TLSV12_CIPHER_SPECS_EX
- GSK_TLSV12_CIPHER_SPECS
- GSK_TLSV11_CIPHER_SPECS_EX
- GSK_TLSV11_CIPHER_SPECS
- GSK_TLSV10_CIPHER_SPECS_EX
- GSK_TLSV10_CIPHER_SPECS
- GSK_V3_CIPHER_SPECS_EX
- GSK_V3_CIPHER_SPECS
- GSK_V2_CIPHER_SPECS
- GSK_SSL_EXTN_SIGALG
- GSK_OCSP_URL
- GSK_OCSP_PROXY_SERVER_NAME
- GSK_SSL_EXTN_SERVERNAME_REQUEST
- GSK_SSL_EXTN_SERVERNAME_CRITICAL_REQUEST
- GSK_SSL_EXTN_SERVERNAME_LIST
- GSK_SSL_EXTN_SERVERNAME_CRITICAL_LIST
- The following GSK_BUF_ID values may be retrieved from the secure
session after gsk_secure_soc_open().
- GSK_KEYRING_LABEL
- GSK_KEYRING_LABEL_EX
- GSK_TLSV12_CIPHER_SPECS_EX
- GSK_TLSV12_CIPHER_SPECS
- GSK_TLSV11_CIPHER_SPECS_EX
- GSK_TLSV11_CIPHER_SPECS
- GSK_TLSV10_CIPHER_SPECS_EX
- GSK_TLSV10_CIPHER_SPECS
- GSK_V3_CIPHER_SPECS_EX
- GSK_V3_CIPHER_SPECS
- GSK_V2_CIPHER_SPECS
- GSK_CONNECT_COMPRESSION
- The following GSK_BUF_ID values are defaulted after
gsk_secure_soc_open() and will be set for
the secure session after
gsk_secure_soc_init().
- GSK_SSL_EXTN_SERVERNAME
- GSK_CONNECT_CIPHER_SPEC_EX
- GSK_CONNECT_CIPHER_SPEC
- GSK_CONNECT_SEC_TYPE
- GSK_SID_VALUE
- GSK_UNKNOWNREVOCATIONSTATUS_SUBJECT
- GSK_UNKNOWNREVOCATIONSTATUS_SUBJECT_NO_AIA
- GSK_VALIDATIONFAIL_SUBJECT
- The following GSK_BUF_ID values may be changed for the secure session
after gsk_secure_soc_misc(),
gsk_secure_soc_read() or
gsk_secure_soc_startRecv() if an SSL Handshake
happened under the context of those calls for the secure session.
- GSK_CONNECT_CIPHER_SPEC_EX
- GSK_CONNECT_CIPHER_SPEC
- GSK_SID_VALUE
- GSK_CONNECT_CIPHER_SPEC_EX
- The buffer pointer can be referenced as long as the handle for the
secure session or the SSL environment is still open.
- When
GSK_IBMI_APPLICATION_ID is set, the settings of some of the SSL environment
attributes will be determined by the corresponding value in the Application ID
definition in Digital Certificate Manager (DCM). These are the buffer
attributes that can be overwritten by DCM during the call to gsk_environment_init():
- GSK_TLSV12_CIPHER_SPECS_EX
- GSK_TLSV11_CIPHER_SPECS_EX
- GSK_TLSV10_CIPHER_SPECS_EX
- GSK_TLSV12_CIPHER_SPECS
- GSK_TLSV11_CIPHER_SPECS
- GSK_TLSV10_CIPHER_SPECS
- GSK_SSL_EXTN_SIGALG
- GSK_OCSP_URL
- When
GSK_IBMI_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_get_enum()--Get
enumerated information about a secure session or a SSL environment.
- gsk_attribute_get_numeric_value()--Get
numeric information about a secure session or a SSL environment
- gsk_attribute_get_cert_info()--Get
information about a local or partner certificate
- gsk_environment_close()--Close the SSL
environment
- gsk_environment_init()--Initialize an
SSL environment
- gsk_environment_open()--Get a handle for
an SSL environment
- gsk_secure_soc_close()--Close a secure
session
- gsk_secure_soc_init()--Negotiate a secure
session
- gsk_secure_soc_misc()--Perform
miscellaneous functions for a secure session
- gsk_secure_soc_open()--Get a handle for a
secure session
- gsk_strerror()--Retrieve GSK runtime error
message
API introduced: V5R1
Top | UNIX-Type APIs | APIs by category |