gsk_attribute_get

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

The function return value will be 0 (GSK_OK) if no error is detected. Otherwise, it will be one of the return codes listed in the gskssl.h include file. These are some possible errors:

[GSK_ATTRIBUTE_INVALID_ID]: The buffer identifier is not valid or cannot be used with the specified handle.
[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.

These buffer identifiers are supported:

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_KEYRING_FILE: Returns the name of the key database file, SAF key ring or z/OS® PKCS #11 token. A key database is used if a database password or stash file is defined using either an environment variable or the gsk_attribute_set_buffer() routine.
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.
GSK_KEYRING_PW: Returns the password for the key database. 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_SID_VALUE: Returns the session identifier for an initialized connection. This is the Base64-encoded version of the session identifier and consists of displayable characters. GSK_SID_VALUE may be specified only for an SSL connection.
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 pairs set by the client or server as a string consisting of 1 or more 4-character values. GSK_TLS_SIG_ALG_PAIRS may be specified for an SSL environment or an SSL connection. The signature algorithm pair specifications are used by the client and server to show which signature/hash algorithm combinations are supported for digital signatures. Signature algorithm pair specification only has relevance for sessions using TLS V1.2 or higher protocols. See Table 6 for a list of valid 4-character signature algorithm pairs 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.
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.
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.

Format

Parameters

Results

Usage

Related Topics