gsk_attribute_get_buffer()--Get character information about a secure session or an SSL environment

 #include <gskssl.h>

 int gsk_attribute_get_buffer(gsk_handle my_gsk_handle,
                              GSK_BUF_ID bufID,
                              const char **buffer,
                              int *bufSize);

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.
  
  
  

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

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

1. 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
     
   
   
2. 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
     
   
   
3. 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
     
   
   
4. 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
   
   
5. The buffer pointer can be referenced as long as the handle for the secure session or the SSL environment is still open.
   
6. 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
   
   
7. 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