gsk_attribute_get_buffer()
Gets the value of an attribute buffer.
Format
#include <gskssl.h>
gsk_status gsk_attribute_get_buffer (
gsk_handle ssl_handle,
GSK_BUF_ID buffer_id,
const char ** buffer_value,
int * buffer_length)
Parameters
- ssl_handle
- Specifies an SSL environment handle returned by gsk_environment_open() or an SSL connection handle returned by gsk_secure_socket_open().
- buffer_id
- Specifies the buffer identifier.
- buffer_value
- Returns the address of the buffer value. The buffer is in storage owned by the SSL run time and must not be modified or released by the application. The buffer returned for the GSK_USER_DATA identifier may be modified by the application but must not be released.
- buffer_length
- Returns the length of the buffer value.
Results
- [GSK_ATTRIBUTE_INVALID_ID]
- The buffer identifier is not valid or cannot be used with the specified handle.
- [GSK_INSUFFICIENT_STORAGE]
- Insufficient storage is available.
- [GSK_INVALID_HANDLE]
- The handle is not valid.
- [GSK_INVALID_STATE]
- The handle is closed.
Usage
The gsk_attribute_get_buffer() routine will return a buffer value for an SSL environment or an SSL connection. The buffer is in storage owned by the SSL run time and must not be released by the application. The address remains valid until the SSL environment or connection is closed or until the application calls the gsk_attribute_set_buffer() routine to set a new buffer value.
- GSK_CLIENT_ECURVE_LIST
- Returns the list of elliptic curve specifications supported by the client as a string consisting of 4-character decimal values. GSK_CLIENT_ECURVE_LIST may be specified for an SSL environment or an SSL connection. The elliptic curve specifications are used by the client to guide the server as to which elliptic curves can be used when using cipher suites that use Elliptic Curve Cryptography for the TLS V1.0 or higher protocols. See Table 5 for a list of valid 4-character elliptic curve specifications.
- GSK_CONNECT_CIPHER_SPEC
- Returns the cipher specification selected for an initialized connection. When using the SSL V2 protocol the cipher specification will be returned as a single character. For other protocols the cipher specification may be returned as either a 2-character or 4-character cipher depending on the setting in GSK_V3_CIPHERS. See Table 1 for a list of valid SSL V2 cipher specifications. See Table 2 and Table 3 for a list of valid 2-character and 4-character cipher specifications for the SSL V3 and TLS protocols.
- GSK_CONNECT_SEC_TYPE
- Returns the security protocol for an initialized connection. The value will be "SSLV2", "SSLV3", "TLSV1", "TLSV1.1", or "TLSV1.2" depending upon the protocol selected during the SSL handshake. GSK_CONNECT_SEC_TYPE may be specified only for an SSL connection.
- GSK_HTTP_CDP_PROXY_SERVER_NAME
- Returns the DNS name or IP address of the HTTP proxy server for HTTP CDP CRL retrieval. GSK_HTTP_CDP_PROXY_SERVER_NAME may be specified only for an SSL environment
- GSK_KEYRING_FILE
- Returns the name of the key database file, PKCS #12 file, SAF key ring or z/OS® PKCS #11 token. A key database or PKCS #12 file is used if a database password is defined using either an environment variable or the gsk_attribute_set_buffer() routine. When a stash file is defined, a key database file is used.
- GSK_KEYRING_LABEL
- Returns the label associated with the certificate being used by the SSL environment or connection. This will be the value set by the application if the environment or connection is not initialized. GSK_KEYRING_LABEL may be specified for an SSL environment or an SSL connection. When querying a server's SSL connection and GSK_SERVER_KEYRING_LABEL_LIST is specified, the returned label name is the one chosen for the connection.
- GSK_SERVER_KEYRING_LABEL_LIST
- Returns the key labels that are available to be used for an SSL server connection.
- GSK_KEYRING_PW
- Returns the password for the key database or PKCS #12 file. A NULL address will be returned after the environment is initialized. GSK_KEYRING_PW may be specified only for an SSL environment.
- GSK_KEYRING_STASH_FILE
- Returns the name of the key database password stash file. GSK_KEYRING_STASH_FILE may be specified only for an SSL environment.
- GSK_LDAP_SERVER
- Returns the DNS name or IP address of the LDAP server. GSK_LDAP_SERVER may be specified only for an SSL environment.
- GSK_LDAP_USER
- Returns the distinguished name to use when connecting to the LDAP server. GSK_LDAP_USER may be specified only for an SSL environment.
- GSK_LDAP_USER_PW
- Returns the password to use when connecting to the LDAP server. GSK_LDAP_USER_PW may be specified only for an SSL environment.
- GSK_OCSP_PROXY_SERVER_NAME
- Returns the DNS name or IP address of the OCSP proxy server. GSK_OCSP_PROXY_SERVER_NAME may be specified only for an SSL environment.
- GSK_OCSP_REQUEST_SIGALG
- Returns the hash and signature algorithm pair to be used to sign OCSP requests as a string consisting of a 4-character value. See Table 6 for a list of valid 4-character signature algorithm pair specifications. GSK_OCSP_REQUEST_SIGALG may be specified only for an SSL environment.
- GSK_OCSP_REQUEST_SIGKEYLABEL
- Returns the certificate label of the key used to sign OCSP requests. GSK_OCSP_REQUEST_SIGKEYLABEL may be specified only for an SSL environment.
- GSK_OCSP_RESPONSE_SIGALG_PAIRS
- Returns a preference ordered list of hash and signature algorithm pair specifications that are sent on the OCSP request and may be used by the OCSP responder to select an appropriate algorithm for signing the OCSP response.
- GSK_OCSP_URL
- Returns the URL of the OCSP responder. GSK_OCSP_URL may be specified only for an SSL environment.
- GSK_PEER_ID
- Returns the Base64-encoded version of the cached session peer ID. GSK_PEER_ID may be specified
only for an SSL connection and is only applicable for a client SSL V3, TLS V1.0, or higher
connection when GSK_ENABLE_CLIENT_SET_PEERID is ON.
When the SSL connection is not initialized, the GSK_PEER_ID returned is either the session ID specified on a previous gsk_attribute_set_buffer() invocation or NULL.
When the SSL connection is initialized, the GSK_PEER_ID that is returned is either the peer ID data specified on a previous gsk_attribute_set_buffer() invocation or the Base64-encoded version of the peer ID data and consists of displayable characters.
When the SSL connection is initialized, the peer ID that is returned can be used as input to the gsk_attribute_set_buffer() function to identify the cached session information to be used for a subsequent connection.
For more information about using the GSK_PEER_ID, see Specifying a cached session in the gsk_secure_socket_init() usage section.
- GSK_SID_VALUE
- Returns the Base64-encoded version of the session identifier. GSK_SID_VALUE may be specified
only for an SSL connection.
When the SSL connection is not initialized, the GSK_SID_VALUE that is returned is either the session ID specified on a previous gsk_attribute_set_buffer() invocation or NULL.
When the SSL connection is initialized, the GSK_SID_VALUE that is returned is either the session ID specified on a previous gsk_attribute_set_buffer() invocation or the Base64-encoded version of the session identifier and consists of displayable characters.
GSK_SID_VALUE can be used as input to the gsk_attribute_set_buffer() function to identify the session information to be used for a subsequent server SSL V3, TLS V1.0, or higher connection.
For more information about using the GSK_SID_VALUE, see Specifying a cached session in the gsk_secure_socket_init() usage section.
- GSK_SNI_LIST
- Returns the address of a list of server names passed to the server by the client for use during server name indication callback routine. Server name indication is an extension to TLS V1.0 or higher protocols which allow the client to pass server names to the server. The server can use the list of server names as an aid in selection of the certificate to be used by the server. GSK_SNI_LIST may be specified only for an SSL connection and only on the server side of the connection. When returned, the buffer contains a list of server names with each server name preceded by a 1-byte name type and a 2-byte field (in large endian format) containing the length of the server name. The name type always contains X'00' to indicate that it is a hostname; however, new name types may be introduced in the future. The server name content will be in UTF-8 format.
- GSK_SUITE_B_CIPHER_SPECS
- Returns the Suite B cipher specifications configured for the environment as a string consisting of 4-character values. GSK_SUITE_B_CIPHER_SPECS may be specified for an SSL environment after the environment has been initialized. See Table 1 for a list of valid suite B cipher specifications.
- GSK_TLS_SIG_ALG_PAIRS
- Returns the list of hash and signature algorithm pair specifications set by the client or server as a string consisting of 1 or more 4-character values in order of preference for use. GSK_TLS_SIG_ALG_PAIRS may be specified for an SSL environment or an SSL connection. The signature algorithm pair specifications are sent by either the client or server to the session partner to indicate which signature/hash algorithm combinations are supported for digital signatures. Signature algorithm pair specification only has relevance for sessions using TLS V1.2. See Table 6 for a list of valid 4-character signature algorithm pair specifications.
- GSK_USER_DATA
- Returns the address of the user data to be passed to SSL exit routines. The application may alter the user data but may not free it. GSK_USER_DATA may be specified only for an SSL connection.
- GSK_V2_CIPHER_SPECS
- Returns the SSL V2 cipher specifications as a string consisting of 1-character values.
GSK_V2_CIPHER_SPECS may be specified for an SSL environment or an SSL connection. See Table 1 for a list of valid SSL v2 cipher specifications.Note: If Suite B support is enabled in the SSL environment, the SSL V2 cipher specifications are ignored. The Suite B ciphers in use in the SSL environment can be retrieved by specifying the GSK_SUITE_B_CIPHER_SPECS buffer identifier.
- GSK_V3_CIPHER_SPECS
- Returns the SSL V3 cipher specifications as a string consisting of 2-character values.
GSK_V3_CIPHER_SPECS may be specified for an SSL environment or an SSL connection. The SSL V3 cipher
specifications are used for the SSL V3, TLS V1.0, or higher protocols. See Table 2 for a list of valid 2-character cipher specifications.Note: If Suite B support is enabled in the SSL environment, the SSL V3 2-character cipher specifications are ignored. The Suite B ciphers in use in the SSL environment can be retrieved by specifying the GSK_SUITE_B_CIPHER_SPECS buffer identifier.
- GSK_V3_CIPHER_SPECS_EXPANDED
- Returns the SSL V3 cipher specifications as a string consisting of 4-character values.
GSK_V3_CIPHER_SPECS_EXPANDED may be specified for an SSL environment or an SSL connection. The SSL
V3 cipher specifications are used for the SSL V3, TLS V1.0, and higher protocols. See Table 3 for a list of valid 4-character cipher specifications.Note: If Suite B support is enabled in the SSL environment, the SSL V3 4-character cipher specifications are ignored. The Suite B ciphers in use in the SSL environment can be retrieved by specifying the GSK_SUITE_B_CIPHER_SPECS buffer identifier.