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_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.
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_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.
- 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 pairs 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_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_PEER_ID 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 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.