gsk_attribute_set_callback()

Sets an SSL callback.

Format

   #include <gskssl.h>

   gsk_status gsk_attribute_set_callback (
                                           gsk_handle          ssl_handle,
                                           GSK_CALLBACK_ID     callback_id,
                                           void *              callback)

Parameters

ssl_handle: Specifies an SSL environment handle returned by gsk_environment_open() or an SSL connection handle returned by gsk_secure_socket_open().
callback_id: Specifies the callback identifier.
callback: Specifies the address of the callback parameter.

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 callback identifier is not valid or cannot be used with the specified handle.
[GSK_ATTRIBUTE_INVALID_PARAMETER]: The attribute parameter value is not valid.
[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_callback() routine establishes a callback to an application routine by the SSL run time. A callback allows the application to replace the default routine used by the SSL run time. The SSL environment or SSL 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 callback routine must use standard C linkage and not C++ linkage.

These callback identifiers are supported:

GSK_CLIENT_CERT_CALLBACK

Indicates that the application is providing a routine to be used during a full handshake to prompt a client user to select a certificate from a list during the client authentication process. The callback parameter is the address of this routine. The exit routine can obtain the user data address by calling the gsk_attribute_get_buffer() routine. The gsk_attribute_set_buffer() routine should be called to set the selected key label before returning from the callback routine. The function return value should be 0 if a key label has been set or GSK_ERR_NO_CERTIFICATE if no client certificate is to be used. GSK_CLIENT_CERT_CALLBACK can be specified only for an SSL environment.

This is the prototype for the callback routine provided by the application. It shows the parameters passed to the application callback and the value returned by the callback.

int client_cert_callback (
                           gsk_handle     soc_handle)

GSK_IO_CALLBACK

Indicates that the application is providing the routines to perform read, write, and control functions. The callback parameter is the address of a gsk_iocallback structure. Each entry in the structure overrides the corresponding SSL runtime routine. A NULL entry will cause the current callback routine to be used or the SSL runtime routine will be used if there is no callback routine. GSK_IO_CALLBACK can be specified for an SSL environment or an SSL connection.

The routine specified by the io_read entry is used to read data from the network. The fd parameter is the socket descriptor, the buffer parameter is the address of the data buffer, the count parameter is the buffer size, and the user_data parameter is the user data address. The function return value should be 0 if the connection has been closed by the remote partner, -1 if an error is detected, or the number of bytes read from the network. The error code is returned in the errno runtime variable. The default routine uses the recv() library routine to read data from the network.

int io_read (
              int        fd,
              void *     buffer,
              int        count,
              char *     user_data)

The routine specified by the io_write entry is used to write data to the network. The fd parameter is the socket descriptor, the buffer parameter is the address of the data buffer, the count parameter is the data length, and the user_data parameter is the user data address. The function return value should be -1 if an error is detected or the number of bytes written to the network. The error code is returned in the errno runtime variable. The default routine uses the send() library routine to write data to the network.

int io_write (
               int        fd,
               void *     buffer,
               int        count,
               char *     user_data)

The routine specified by the io_getpeerid entry is used to get the 32-bit network identifier for the remote partner. The fd parameter is the socket descriptor and the user_data parameter is the user data address. However, the io_getpeerid entry is deprecated and should not be used since it does not support IPv6 networks which use a 16-byte network identifier. Instead, the io_getpeername entry should be used for both IPv4 and IPv6 networks. The io_getpeerid entry will not be used if the io_getpeername entry is not NULL.

unsigned long io_getpeerid (
                             int        fd,
                             char *     user_data)

The routine specified by the io_setsocketoptions entry is used to set socket options. The fd parameter is the socket descriptor, the cmd parameter is the function to be performed, and the user_data parameter is the user data address. The return value should be -1 if an error is detected and 0 otherwise. The error code is returned in the errno runtime variable. The io_setsocketoptions() routine is called by the gsk_secure_socket_init() routine before initiating the SSL handshake (GSK_SET_SOCKET_STATE_FOR_HANDSHAKE) and again upon completion of the SSL handshake (GSK_SET_SOCKET_STATE_FOR_READ_WRITE). The default io_setsocketoptions() routine puts the socket into blocking mode for GSK_SET_SOCKET_STATE_FOR_HANDSHAKE and restores the original mode for GSK_SET_SOCKET_STATE_FOR_READ_WRITE.

int io_setsocketoptions (
                          int        fd,
                          int        cmd,
                          char *     user_data)

The routine specified by the io_getpeername entry is used to get the network identifier for the remote partner. The fd parameter is the socket descriptor, the buffer parameter is the address of the return buffer, the length parameter is the size of the return buffer, and the user_data parameter is the user data address. Upon return, the length parameter should contain the actual length of the network identifier. The function return value should be -1 if an error is detected and 0 otherwise. The error code is returned in the errno runtime variable. The default routine uses the getpeername() library routine and returns the IP address of the remote partner (4 bytes for IPv4 and 16 bytes for IPv6) followed by the 2-byte port number.

int io_getpeername (
                  int        fd,
                  void *     buffer,
                  int *      length,
                  char *     user_data)

GSK_SESSION_RESET_CALLBACK

Indicates that the application is providing the routines to be called when a session renegotiation has been initiated or completed to establish a new session key or have the session cipher reset. The callback parameter is the address of a gsk_reset_callback structure.

GSK_SESSION_RESET_CALLBACK can be specified for an SSL environment or an SSL connection. The callback is only invoked when using SSL V3, TLS V1.0, or higher protocols.

The routine specified by the Reset_Init entry is called when a session renegotiation has been initiated, and the SSL client has commenced the renegotiation process. The con_handle parameter is the handle for the SSL connection.

void (Reset_Init)  (
              gsk_handle        con_handle)

The Reset_Complete routine is called when a session renegotiation has been completed. If session renegotiation does not successfully complete, for example because of renegotiation not being allowed, then the Reset_Complete routine is not invoked even though the Reset_Init routine was called at the commencement of renegotiation. The con_handle parameter is the handle for the SSL connection.

void (Reset_Complete)  (
               gsk_handle        con_handle)

GSK_SID_CACHE_CALLBACK

Indicates that the application is providing the routines to maintain the session identifier cache. The callback parameter is the address of a gsk_sidcache_callback structure. GSK_SID_CACHE_CALLBACK can be specified only for an SSL environment and will be used only for SSL servers (the internal cache is always used for SSL clients).

The routine specified by the Get entry is called to retrieve an entry from the session identifier cache. The session_id parameter is the session identifier, the session_id_length parameter is the length of the session identifier, and the ssl_version parameter is the SSL protocol version number (GSK_SSLVERSION_V2 or GSK_SSLVERSION_V3). The function return value is the address of the session data buffer or NULL if an error is detected. The FreeDataBuffer routine will be called to release the session data buffer when it is no longer needed by the SSL run time.

gsk_data_buffer * Get (
                        const unsigned char *     session_id,
                        unsigned int              session_id_length,
                        gsk_sslversion            ssl_version)

The routine specified by the Put entry is called to store an entry in the session identifier cache. The ssl_session_data parameter is the session data, the session_id parameter is the session identifier, the session_id_length parameter is the length of the session identifier, and the ssl_version parameter is the SSL protocol version number (GSK_SSLVERSION_V2 or GSK_SSLVERSION_V3). The function return value is ignored and can be a NULL address. The callback routine must make its own copy of the session data since the SSL structure will be released when the connection is closed.

gsk_data_buffer * Put (
                        gsk_data_buffer *         ssl_session_data,
                        const unsigned char *     session_id,
                        unsigned int              session_id_length,
                        gsk_sslversion            ssl_version)

The routine specified by the Delete entry is called to remove an entry from the session identifier cache. The session_id parameter is the session identifier, the session_id_length parameter is the length of the session identifier, and the ssl_version parameter is the SSL protocol version number (GSK_SSLVERSION_V2 or GSK_SSLVERSION_V3).

void Delete (
              const unsigned char *     session_id,
              unsigned int              session_id_length,
              gsk_sslversion            ssl_version)

The routine specified by the FreeDataBuffer entry is called to release the data buffer returned by the Get routine.

void FreeDataBuffer (
                      gsk_data_buffer *     ssl_session_data)

GSK_SNI_CALLBACK

Indicates that the application is providing the routine to allow a server to interrogate a list of server names supplied by the client and select an appropriate key label for use as the server certificate based on the information received from the client. The selected certificate from the key database, Start of change

PKCS #12 file End of change

, key ring or token will be sent to the client as the server certificate during the handshake process. The callback parameter is the address of this routine. The exit routine can obtain the server name list provided by the client by calling the gsk_attribute_get_buffer() routine. The gsk_attribute_set_buffer() routine should be called to set the selected key label before returning from the callback routine.

The callback routine cannot enforce the required use of the server name indication extension. The failure to select a key label causes a fatal UNRECOGNIZED_NAME alert. To enforce such actions with the callback routine the user must set the GSK_TLS_EXTID_SNI_SERVER_LABELS extension by calling the attribute_set_tls_extension() routine. The required and unrecognized_name_fatal fields of the extension must be set appropriately to achieve the requested outcome, although the serverKeyLabel list may be empty.

The function return value should be 0 if a key label has been set or GSK_ERR_UNRECOGNIZED_NAME if no server certificate is selected. Enforcement of the required and unrecognized_name_fatal settings occur on return from the callback routine. GSK_SNI_CALLBACK can be specified only for an SSL environment.