gsk_attribute_set_buffer()

Sets the value of an attribute buffer.

Format

   #include <gskssl.h>

   gsk_status gsk_attribute_set_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: Specifies the buffer value.
buffer_length: Specifies the buffer length. Specify 0 for this parameter if the buffer value is a null-delimited character string.

Results

The function return value will be 0 (GSK_OK) if no error is detected. Otherwise, it is 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_ATTRIBUTE_INVALID_LENGTH]: The buffer length is not valid.
[GSK_INSUFFICIENT_STORAGE]: Insufficient storage is available.
[GSK_INVALID_HANDLE]: The handle is not valid.
[GSK_INVALID_STATE]: The environment or connection is not in the open state.

Usage

The gsk_attribute_set_buffer() routine sets a buffer value in an SSL environment or an SSL connection. The environment or connection must be in the open state and not in the initialized state (that is, gsk_environment_init() or gsk_secure_socket_init() has not been called).

The values set using this service are treated as independent values. They are not validated with other values set using gsk_attribute_set_buffer(), gsk_attribute_set_enum(), or gsk_attribute_set_tls_extensions() APIs until used together to perform a SSL/TLS handshake by calling gsk_secure_socket_init().

Start of change If the input buffer_value is NULL, the target attribute is set to NULL. End of change

These buffer identifiers are supported:

GSK_CLIENT_ECURVE_LIST

Specifies the list of elliptic curves that are supported by the client as a string consisting of 1 or more 4-character decimal values in order of preference for use. GSK_CLIENT_ECURVE_LIST may be specified for an SSL environment or an SSL connection. The list is used by the client to guide the server as to which elliptic curves are preferred when using ECC-based cipher suites for the TLS V1.0 or higher protocols.

Only NIST recommended curves are able to be specified for the attribute. To use Brainpool standard curves for an SSL connection, the buffer must be reinitialized to NULL using either gsk_attribute_set_buffer() or the GSK_CLIENT_ECURVE_LIST environment variable. See Table 5 for a list of valid 4-character elliptic curve specifications

GSK_HTTP_CDP_PROXY_SERVER_NAME

Specifies the DNS name or IP address of the HTTP proxy server for HTTP CDP CRL retrieval. GSK_HTTP_CDP_PROXY_SERVER_NAME can be specified only for an SSL environment. End of change

GSK_KEYRING_FILE

Specifies the name of the key database file, Start of change

PKCS #12 file End of change

, SAF key ring, or z/OS® PKCS #11 token. A key database or Start of change

PKCS #12 file End of change

is used if a database password is defined using either an environment variable or the gsk_attribute_set_buffer() routine. Start of change

When a stash file is defined, a key database file is used. End of change

Otherwise, a SAF key ring or z/OS PKCS #11 token is used. GSK_KEYRING_FILE may be specified only for an SSL environment.

The SAF key ring name is specified as "userid/keyring". The current user ID is used if the user ID is omitted. The user must have READ access to the IRR.DIGTCERT.LISTRING resource in the FACILITY class when using a SAF key ring owned by the user. The user must have UPDATE access to the IRR.DIGTCERT.LISTRING resource in the FACILITY class when using a SAF key ring owned by another user.

A z/OS PKCS #11 token name is specified as *TOKEN*/token-name. *TOKEN* indicates a PKCS #11 token is being specified.

Note: Certificate private keys are not available when using a SAF key ring owned by another user, except for SITE certificates where CONTROL authority is given to IRR.DIGTCERT.GENCERT in the FACILITY class or for user certificates where READ or UPDATE authority is given to ringOwner.ringName.LST resource in the RDATALIB class.

GSK_KEYRING_LABEL

Specifies the label of the key that is used to authenticate the application. The default key is used if a key label is not specified. GSK_KEYRING_LABEL may be specified for an SSL environment or an SSL connection. If either the GSK_CLIENT_CERT_CALLBACK function or the GSK_SNI_CALLBACK function is registered, the key label can be set or reset by the callback function after a call to gsk_secure_socket_init().

GSK_KEYRING_PW

Specifies the password for the key database or Start of change

PKCS #12 file End of change

. GSK_KEYRING_PW may be specified only for an SSL environment.

GSK_KEYRING_STASH_FILE

Specifies the name of the key database password stash file. The stash file name always has an extension of ".sth" and the supplied name is changed if it does not have the correct extension. The GSK_KEYRING_PW value is used instead of the GSK_KEYRING_STASH value if it is also specified. GSK_KEYRING_STASH_FILE may be specified only for an SSL environment.

GSK_LDAP_SERVER

Specifies one or more blank-separated LDAP server host names. Each host name can contain an optional port number that is separated from the host name by a colon. GSK_LDAP_SERVER may be specified only for an SSL environment. The LDAP server is used to obtain CA certificates when validating a certificate and the local database does not contain the required certificate. The local database must contain the required certificates if no LDAP server is specified. Even when an LDAP server is used, root CA certificates must be found in the local database since the LDAP server is not a trusted data source. The LDAP server is also used to obtain certificate revocation lists.

GSK_LDAP_USER

Specifies 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

Specifies 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

Specifies the DNS name or IP address of the OCSP proxy server. GSK_OCSP_PROXY_SERVER_NAME can be specified only for an SSL environment. End of change

GSK_OCSP_REQUEST_SIGALG

Specifies 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. Defaults to RSA with SHA256 ('0401').

Only requests sent to the OCSP responder identified via the GSK_OCSP_URL setting are signed. GSK_OCSP_REQUEST_SIGALG can be specified only for an SSL environment.

GSK_OCSP_REQUEST_SIGKEYLABEL

Specifies the label of the key to be used to sign OCSP requests. OCSP requests are only signed when a key label is specified.

Only requests sent to the OCSP responder identified via the GSK_OCSP_URL setting are signed (not ones selected from a certificate AIA extension). GSK_OCSP_REQUEST_SIGKEYLABEL can be specified only for an SSL environment.

GSK_OCSP_URL

Specifies the URL of an OCSP responder. The OCSP responder is used to obtain certificate revocation status during certificate validation. A certificate does not need an AIA extension if a responder URL is configured using this option.

The value must conform to the definition of an HTTP URL:

http_URL = "http:" "//" host [ ":" port ] [ abs_path [ "?" query ]]

where host can be an Start of change

IPv4 or IPv6 address End of change

, or a domain name.

Start of change If GSK_OCSP_URL is specified, GSK_OCSP_ENABLE is set ON, and GSK_OCSP_URL_PRIORITY is set ON, the order that the responders are used is GSK_OCSP_URL defined responder first and then the responders identified in the AIA extension. End of change

Start of change If GSK_OCSP_URL is specified, GSK_OCSP_ENABLE is set ON, and GSK_OCSP_URL_PRIORITY is set OFF, the order that the responders are used is the responders identified in the AIA extension first and then the GSK_OCSP_URL defined responder. End of change

GSK_OCSP_URL can be specified only for an SSL environment.

GSK_PEER_ID

Specify the GSK_PEER_ID to uniquely identify the cached session to be used to resume an existing session or duplicate an existing session. Use gsk_attribute_get_buffer() to initially retrieve the GSK_PEER_ID to be used by gsk_attribute_set_buffer().

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 SSL environment enumerator GSK_ENABLE_CLIENT_SET_PEERID is ON and V3 session caching is enabled (session cache size and timeout are non-zero).

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

Specify the GSK_SID_VALUE to uniquely identify the cached session to be used to resume an existing session. GSK_SID_VALUE may be specified only for an SSL connection and is only applicable for a server connection when V3 session caching is enabled (session cache and timeout are non-zero). Use gsk_attribute_get_buffer() to initially retrieve the GSK_SID_VALUE to be used by gsk_attribute_set_buffer().

For more information about using the GSK_SID_VALUE, see Specifying a cached session in the gsk_secure_socket_init() usage section.

GSK_TLS_SIG_ALG_PAIRS

Specifies the list of hash and signature algorithm pair specifications that are supported 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 or higher protocols. See Table 6 for a list of valid 4-character signature algorithm pair specifications.

GSK_USER_DATA

Specifies the user data to be passed to SSL exit routines. The user data is copied to storage owned by the SSL run time and the address of this storage is passed to the SSL exit routines. The application may alter this copy of the user data but may not free it. GSK_USER_DATA may be specified only for an SSL connection.

GSK_V2_CIPHER_SPECS

Specifies the SSL V2 cipher specifications as a string consisting of 1 or more 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

Specifies the SSL V3 cipher specifications as a string consisting of 1 or more 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

Specifies the SSL V3 cipher specifications as a string consisting of 1 or more 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, or higher protocols. See Table 3 for a list of valid 4-character cipher specifications. Applications wanting to use cipher suites that use Elliptic Curve Cryptography must set an appropriate cipher specification in GSK_V3_CIPHER_SPECS_EXPANDED.

gsk_attribute_set_buffer()

Format

Parameters

Results

Usage

Related Topics