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 an SSL/TLS handshake by calling gsk_secure_socket_init().

If the input buffer_value is NULL, the target attribute is set to NULL.

These buffer identifiers are supported:

GSK_CLIENT_ECURVE_LIST

Specifies the list of elliptic curves or supported groups 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. For TLS V1.0, TLS V1.1, and TLS V1.2 protocols, this list is used by the client to guide the server to the elliptic curves that are preferred when using ECC-based cipher suites. For the TLS V1.3 protocol, this list is used by the client to guide the server to the elliptic curves that are preferred and guide group selection to encrypt and decrypt TLS V1.3 handshake messages.

Only NIST recommended curves are able to be specified for the attribute. To use Brainpool standard curves for an SSL/TLS connection, the buffer must be reinitialized to NULL using either gsk_attribute_set_buffer() or the GSK_CLIENT_ECURVE_LIST environment variable. Brainpool certificates cannot be used if the selected protocol is TLS V1.3. Start of change

If the application is only enabled for TLS V1.3, the 0021 and 0019 elliptic curves or supported groups are ignored. If the application is not enabled for TLS V1.3, supported groups valid for only TLS V1.3 (such as 0029 and 0030) are ignored. End of change

See Table 5 for a list of valid 4-character elliptic curve and supported groups specifications.

GSK_CLIENT_TLS_KEY_SHARES

Specifies the list of the key share groups that are supported by the client during a TLS V1.3 handshake. During a TLS V1.3 handshake, the client sends the key share groups that are in common and in the same order as the supported groups list (GSK_CLIENT_ECURVE_LIST). The server selects a group from the client’s preferred order and the ones that it supports. The client and server use the selected group to encrypt and decrypt TLS V1.3 handshake messages. See Table 5 for a list of valid 4-character key share specifications.

GSK_CLIENT_TLS_KEY_SHARES may be specified for an SSL environment or SSL connection.

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.

GSK_KEYRING_FILE

Specifies 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. 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.

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().

If GSK_KEYRING_LABEL is specified along with GSK_SERVER_KEYRING_LABEL_LIST, GSK_KEYRING_LABEL is used when an SSL V2 secure connection is being established. Otherwise, GSK_KEYRING_LABEL is ignored.

GSK_KEYRING_PW

Specifies the password for the key database or PKCS #12 file. 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.

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 7 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_RESPONSE_SIGALG_PAIRS

Specifies 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. The string consists of one or more 4-character values in order of preference for use. If specified, the OCSP response must be signed with one of these hash and signature algorithm pairs and if it is not, the OCSP response is rejected. It should be noted that not all OCSP responders support the preference ordered list and the OCSP response may be signed by a signature algorithm that was not specified. These signature algorithm pair specifications only have relevance when OCSP is enabled in the application. See Table 7 for a list of valid 4-character signature algorithm pair specifications.

GSK_OCSP_RESPONSE_SIGALG_PAIRS 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 IPv4 or IPv6 address, or a domain name.

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.

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.

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().

Start of change GSK_PEER_ID may be specified only for an SSL connection and is only applicable for client SSL V3, TLS V1.0, or higher connections when SSL environment enumerator GSK_ENABLE_CLIENT_SET_PEERID is ON and V3 session caching is enabled (GSK_V3_SIDCACHE_SIZE is non-zero, GSK_V3_SESSION_TIMEOUT is non-zero, and GSK_SESSION_TICKET_CLIENT_ENABLE is set to ON). End of change

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

GSK_SERVER_KEYRING_LABEL_LIST

Specifies a list of labels that can be selected from in order to authenticate a server application. The list can consist of 1 to 8 key labels each delimited using a comma or a blank space. If either a comma or a blank space appears in the label name, the backslash (\) character must be used as an escape character. Each key label cannot be greater than 127 characters minus any escaping characters. GSK_SERVER_KEYRING_LABEL_LIST may be specified for an SSL environment or an SSL connection. See Using server multiple key label support for additional information about using GSK_SERVER_KEYRING_LABEL_LIST.

GSK_SERVER_TLS_KEY_SHARES

Specifies the list of the key share groups that are supported by the server during a TLS V1.3 handshake. During a TLS V1.3 handshake, the server uses the client’s preferred key share group order and selects a group that is in common with this list. The client and server use the selected group to encrypt and decrypt TLS V1.3 handshake messages. See Table 3 for a list of valid 4-character key share specifications.

GSK_SERVER_TLS_KEY_SHARES may be specified for an SSL environment or SSL connection.

GSK_SID_VALUE

Specify the GSK_SID_VALUE to uniquely identify the cached session or session ticket to be used to resume an existing session. For SSL V3 through TLS V1.2 connections, the 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). For TLS V1.3 connections, the server must have issued a session ticket with the specified ID value (GSK_SESSION_TICKET_SERVER_ENABLE is ON and GSK_SESSION_TICKET_SERVER_COUNT is non-zero, or the gsk_secure_socket_misc() routine has been called with attribute ID GSK_SEND_SESSION_TICKET). 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_CERT_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 one or more 4-character values in order of preference for use in digital signatures of X.509 certificates. The certificate 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 in X.509 certificates. The GSK_TLS_CERT_SIG_ALG_PAIRS setting overrides the GSK_TLS_SIG_ALG_PAIRS setting when checking the digital signatures of the remote peer’s X.509 certificates. The certificate signature algorithm pair specification only has relevance for TLS V1.2 client or TLS V1.3 client and server sessions. See Table 6 for a list of valid 4-character certificate signature algorithm pair specifications.

GSK_CERT_TLS_SIG_ALG_PAIRS may be specified for an SSL environment or SSL connection.

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 in digital signatures of X.509 certificates and TLS handshake messages. 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 in X.509 certificates and TLS handshake messages. If the GSK_TLS_CERT_SIG_ALG_PAIRS setting is specified, the GSK_TLS_SIG_ALG_PAIRS setting is only used to indicate the signature/hash algorithm combinations supported for digital signatures in TLS handshake messages. The 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_TLS_SIG_ALG_PAIRS may be specified for an SSL environment or an SSL connection.

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.

Note: If Suite B support is enabled in the SSL environment, the SSL V2 cipher specifications are ignored.

GSK_V3_CIPHER_SPECS

Specifies the SSL V3 and TLS 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, TLS V1.1, and TLS V1.2 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.

GSK_V3_CIPHER_SPECS_EXPANDED

Specifies the SSL V3 and TLS 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, TLS V1.1, TLS V1.2, and TLS V1.3 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.

Note: If Suite B support is enabled in the SSL environment, the SSL V3 4-character cipher specifications are ignored.