gsk_attribute_set_tls

Defines a TLS extension to the SSL environment or connection.

Format

   #include <gskssl.h>

   gsk_attribute_set_tls_extension (
                                    gsk_handle           ssl_handle, 
                                    gsk_tls_extension *  tls_extension)

Parameters

ssl_handle: Specifies an SSL environment handle returned by gsk_environment_open() or an SSL connection handle returned by gsk_secure_socket_open().
tls_extension: Specifies the TLS extension structure containing extension data.

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_TLS_EXTENSION]: The TLS extension type identifier is not valid or cannot be used with the specified handle.
[GSK_ATTRIBUTE_INVALID_TLS_EXT_DATA]: TLS extension data has been incorrectly defined.
[GSK_INVALID_HANDLE]: The handle is not valid.
[GSK_INVALID_STATE]: The handle is closed.

Usage

The gsk_attribute_set_tls_extension() routine defines a TLS extension for 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() is not called). TLS extensions that are defined for an SSL environment applies to all connections made as part of that environment unless explicitly deactivated or replaced using a call to gsk_attribute_set_tls_extension() for the connection. TLS extensions are applied to TLS V1.0 or higher connections only.

The application must prime the TLS extension structure with the appropriate TLS extension data before calling the routine, including the TLS extension type identifier and the specific data that is required for the TLS extension type. The TLS extension may be designated as required or optional in the gsk_tls_extension structure. A required setting enforces support requirements of the specific extension type on the communicating partner. If the partner indicates that it does not support the extension, the connection is rejected. An optional setting allows the connection to continue without support for that particular extension type if the communicating partner indicates that it does not support the TLS extension type.

Note:

Setting an extension as required for a server means that all clients connecting to the server must have the extension enabled. Failure for a client to do so results in the server rejecting the connection request from the client. It is recommended that for maximum interoperability, that the required field is not enabled on the server side.
The gsk_tls_extension structure contains a 32-byte field, rsvd, which is reserved for future use. This field must contain binary zeros; any non-zero data results in gsk_attribute_set_tls_extension() returning a GSK_ATTRIBUTE_INVALID_TLS_EXT_DATA error.
Definition of TLS extensions for the client when any of the TLS protocols are enabled prevents the SSL V2 protocol from being used.

The values set by 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 TLS extension type identifiers are supported:

GSK_TLS_EXTID_SNI_SERVER_LABELS

Specifies the pairings of server name to certificate key label to be used when the TLS server receives a 'Server Name Indication' type TLS extension from the TLS client. The server name/key label pairs are used with the server name details received from the client to determine which certificate from the key database, key ring or token is sent to the client as the servers certificate.

Set the setSni setting of the gsk_sni_server_labels extension data to TRUE to register the extension data with the SSL environment or connection. A setSni setting of FALSE deactivates a previously registered GSK_TLS_EXTID_SNI_SERVER_LABELS type TLS extension setting.

If the TLS server does not recognize any server names in the clients server name list, the server sends an 'unrecognized_name' alert to the client, which, by default, is a warning. Set the unrecognized_name_fatal flag in the gsk_sni_server_labels extension data to TRUE to treat the 'unrecognized_name' alert as fatal and close the connection.

GSK_TLS_EXTID_SNI_SERVER_LABELS can be defined on both the server and client sides. Its settings, however, are effective when running as a server; it is ignored for clients.

Note:

It is recommended that the gsk_sni_server_labels structure to be included in the gsk_tls_extension data be initialized with binary zeros before setting the required server label data. This ensures future application compatibility when additional bits within the gsk_sni_server_labels structure are used.
System SSL only supports server names that contain US-ASCII characters.

GSK_TLS_EXTID_SNI_CLIENT_SNAMES

Specifies the server name (or list of server names) that the client sends to the server in a 'Server Name Indication' type TLS extension to indicate with which server the client wants to communicate. The list of server names is defined using a pointer to an array of pointers to strings containing the server names.

Set the setSni setting of the gsk_sni_client_names extension data to TRUE to register the extension data with the SSL environment or connection. A setSni setting of FALSE deactivates a previously registered GSK_TLS_EXTID_SNI_CLIENT_SNAMES type TLS extension setting.

If the TLS server does not recognize any server names in the clients server name list, the server sends an 'unrecognized_name' alert to the client, which, by default, is a warning. Set the unrecognized_name_fatal flag in the gsk_sni_client_names extension data to TRUE to treat the 'unrecognized_name' alert as fatal and close the connection.

GSK_TLS_EXTID_SNI_CLIENT_SNAMES can be defined on both the server and client sides. Its settings, however, are effective when running as a client; it is ignored for servers.

Note:

It is recommended that the gsk_sni_client_snames structure to be included in the gsk_tls_extension data be initialized with binary zeros before setting the required server label data. This will ensure future application compatibility when additional bits within the gsk_sni_client_snames structure are used.
System SSL only supports server names that contain US-ASCII characters.

GSK_TLS_EXTID_SERVER_MFL

Specifies the 'Maximum Fragment Length' type TLS extension requirements for the TLS server. Specify to the TLS server whether to support the 'Maximum Fragment Length' TLS extension using the GSK_TLS_MFL_ON setting. The GSK_TLS_MFL_OFF setting deactivates a previously registered GSK_TLS_EXTID_SERVER_MFL type TLS extension setting.

GSK_TLS_EXTID_CLIENT_MFL

Specifies the 'Maximum Fragment Length' type TLS extension requirements for the TLS client. Specify the size of the maximum fragment length to be used using settings GSK_TLS_MFL_512 (2⁹ bytes), GSK_TLS_MFL_1024 (2¹⁰), GSK_TLS_MFL_2048 (2¹¹) or GSK_TLS_MFL_4096 (2¹²). The GSK_TLS_MFL_OFF setting deactivates a previously registered GSK_TLS_EXTID_CLIENT_MFL type TLS extension setting.

GSK_TLS_EXTID_TRUNCATED_HMAC

Specifies whether the TLS server or client supports the 'Truncated HMAC' type TLS extension. Set truncateHmac to TRUE to enable the extension. A truncateHmac setting of FALSE deactivates a previously registered GSK_TLS_EXTID_TRUNCATED_HMAC type TLS extension setting.