gsk_attribute_get_buffer()--Get character information about a secure session or 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 a 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 secure environment (my_env_handle)
- bufID (Input)
- The following values can be used to retrieve information about the secure
session or 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 secure environment.
- GSK_KEYRING_PW (202) - buffer points to the
password for the certificate store file being used for the secure 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 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
environment.
- GSK_IBMI_APPLICATION_ID (6999) - buffer points
to the application identifier being used for the secure environment.
-
GSK_TLSV13_CIPHER_SPECS_EX (2008) - buffer points to a
list of comma delimited string values of the TLS Version 1.3 ciphers to be used
for the secure session or 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 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 environment. Setting this to NULL will result in the System TLS 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 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 environment. Setting this to NULL will result in the System TLS 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 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 environment. Setting this to NULL will result in the System TLS 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 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 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_CONNECT_SEC_TYPE (208) - buffer points to a string
containing "SSLV3", "TLSV1", "TLSV11", "TLSV12",
or "TLSV13"
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
secure 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
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 secure 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 acknowledgment. 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 secure session.
*NONE is the only supported value.
-
GSK_SSL_EXTN_ALPN (276) - buffer points to a list of
comma delimited string values of the Application-Layer Protocol Negotiation (ALPN)
protocols IDs to be used for the secure session or environment.
- GSK_SSL_EXTN_SELECTED_ALPN_PROTOCOL (277) - buffer points
to a string describing the ALPN protocol negotiated for the secure session.
-
GSK_TLS_EXTN_SIG_SCHEME (2001) - buffer points to the list
of comma delimited string values of signature scheme algorithms to be supported by the
secure environment when using TLS version 1.3. See the usage notes in gsk_attribute_set_buffer() API for the
format of the algorithms.
-
GSK_TLS_EXTN_SIG_SCHEME_CERT (2003) - buffer points to the list
of comma delimited string values of signature scheme certificate algorithms to be supported by the
secure environment when using TLS version 1.3. See the usage notes in gsk_attribute_set_buffer() API for the
format of the algorithms.
-
GSK_TLS_EXTN_SUPPORTED_GROUPS (2005) - buffer points to the list
of comma delimited string values of groups to be supported by the
secure environment when using TLS version 1.2 and newer versions.
See the usage notes in gsk_attribute_set_buffer() API for the
format of the algorithms.
- GSK_KEYRING_FILE (201) - buffer points to the
name of the certificate store file being used for the secure 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 TLS 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 secure
environment after gsk_environment_open().
- GSK_KEYRING_FILE
- GSK_KEYRING_PW
- GSK_KEYRING_LABEL
- GSK_KEYRING_LABEL_EX
- GSK_IBMI_APPLICATION_ID
- GSK_TLSV13_CIPHER_SPECS_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_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
- GSK_SSL_EXTN_ALPN
- GSK_TLS_EXTN_SIG_SCHEME
- GSK_TLS_EXTN_SIG_SCHEME_CERT
- GSK_TLS_EXTN_SUPPORTED_GROUPS
- 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_TLSV13_CIPHER_SPECS_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_CONNECT_COMPRESSION
- GSK_SSL_EXTN_ALPN
- 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
- GSK_SSL_EXTN_SELECTED_ALPN_PROTOCOL
- 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 a TLS handshake
happened under the context of those calls for the secure session.
- GSK_CONNECT_CIPHER_SPEC_EX
- GSK_CONNECT_CIPHER_SPEC
- GSK_SID_VALUE
- The buffer pointer can be referenced as long as the handle for the
secure session or environment is still open.
- When GSK_IBMI_APPLICATION_ID is set, the settings of some of the secure 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_TLSV13_CIPHER_SPECS_EX
- 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
- GSK_TLS_EXTN_SIG_SCHEME
- GSK_TLS_EXTN_SIG_SCHEME_CERT
- When
GSK_IBMI_APPLICATION_ID is set, the settings of some of the secure 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 secure environment
buffer attributes during the call to
gsk_environment_init():
- GSK_SSL_EXTN_SERVERNAME_LIST
- GSK_SSL_EXTN_SERVERNAME_CRITICAL_LIST
- The default cipher suite list in preference order as shipped is as follows:
- GSK_TLSV13_CIPHER_SPECS_EX set to:
"TLS_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256"
- GSK_TLSV12_CIPHER_SPECS_EX set to:
"TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256"
GSK_TLSV12_CIPHER_SPECS set to the null character (\0).
Note: The GSK_TLSV12_CIPHER_SPECS list may not reflect all of the ciphers in use by the environment or session if ciphers that do not have a GSK_TLSV12_CIPHER_SPECS equivalent representation are enabled.
- TLS Version 1.1 support is disabled when the operating system is installed resulting in GSK_TLSV11_CIPHER_SPECS_EX and GSK_TLSV11_CIPHER_SPECS set to the null character (\0).
- TLS Version 1.0 support is disabled when the operating system is installed resulting in GSK_TLSV10_CIPHER_SPECS_EX and GSK_TLSV10_CIPHER_SPECS set to the null character (\0).
- SSL Version 3 support is disabled when the operating system is installed resulting in GSK_V3_CIPHER_SPECS_EX and GSK_V3_CIPHER_SPECS set to the null character (\0).
The current default cipher suite list can be different from the install time list due to changes made to the QSSLCSL (TLS cipher specification list) system value via the Change System Value (CHGSYSVAL) command. A cipher suite removed from the TLS 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 TLSCONFIG will also be removed from the default cipher suite list shown here. For additional information see the help text for TLSCONFIG. 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_TLSV13_CIPHER_SPECS_EX, GSK_TLSV12_CIPHER_SPECS_EX, GSK_TLSV11_CIPHER_SPECS_EX, GSK_TLSV10_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.
See the usage notes in gsk_attribute_set_buffer() API for the format of the ciphers.
- GSK_TLSV13_CIPHER_SPECS_EX set to:
Related Information
- gsk_attribute_set_buffer()--Set
character information for a secure session or environment
- gsk_attribute_get_enum()--Get
enumerated information about a secure session or environment.
- gsk_attribute_get_numeric_value()--Get
numeric information about a secure session or environment
- gsk_attribute_get_cert_info()--Get
information about a local or partner certificate
- gsk_environment_close()--Close the secure
environment
- gsk_environment_init()--Initialize a
secure environment
- gsk_environment_open()--Get a handle for
a secure 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 |