gsk_attribute_set_tls_extension()
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
- [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.
- 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 an SSL/TLS handshake by calling gsk_secure_socket_init().
- 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, PKCS #12 file, 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 (29 bytes), GSK_TLS_MFL_1024 (210), GSK_TLS_MFL_2048 (211) or GSK_TLS_MFL_4096 (212). 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.