gsk_attribute_set

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

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_KEYRING_FILE: Specifies 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. 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. 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_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.

Format

Parameters

Results

Usage

Related Topics