SSL_CTX_set_custom_cli_ext(3) OpenSSL SSL_CTX_set_custom_cli_ext(3) NNAAMMEE SSL_CTX_add_client_custom_ext, SSL_CTX_add_server_custom_ext - custom TLS extension handling SSYYNNOOPPSSIISS #include int SSL_CTX_add_client_custom_ext(SSL_CTX *ctx, unsigned int ext_type, custom_ext_add_cb add_cb, custom_ext_free_cb free_cb, void *add_arg, custom_ext_parse_cb parse_cb, void *parse_arg); int SSL_CTX_add_server_custom_ext(SSL_CTX *ctx, unsigned int ext_type, custom_ext_add_cb add_cb, custom_ext_free_cb free_cb, void *add_arg, custom_ext_parse_cb parse_cb, void *parse_arg); int SSL_extension_supported(unsigned int ext_type); typedef int (*custom_ext_add_cb)(SSL *s, unsigned int ext_type, const unsigned char **out, size_t *outlen, int *al, void *add_arg); typedef void (*custom_ext_free_cb)(SSL *s, unsigned int ext_type, const unsigned char *out, void *add_arg); typedef int (*custom_ext_parse_cb)(SSL *s, unsigned int ext_type, const unsigned char *in, size_t inlen, int *al, void *parse_arg); DDEESSCCRRIIPPTTIIOONN _S_S_L___C_T_X___a_d_d___c_l_i_e_n_t___c_u_s_t_o_m___e_x_t_(_) adds a custom extension for a TLS client with extension type eexxtt__ttyyppee and callbacks aadddd__ccbb, ffrreeee__ccbb and ppaarrssee__ccbb. _S_S_L___C_T_X___a_d_d___s_e_r_v_e_r___c_u_s_t_o_m___e_x_t_(_) adds a custom extension for a TLS server with extension type eexxtt__ttyyppee and callbacks aadddd__ccbb, ffrreeee__ccbb and ppaarrssee__ccbb. In both cases the extension type must not be handled by OpenSSL inter- nally or an error occurs. _S_S_L___e_x_t_e_n_s_i_o_n___s_u_p_p_o_r_t_e_d_(_) returns 1 if the extension eexxtt__ttyyppee is han- dled internally by OpenSSL and 0 otherwise. EEXXTTEENNSSIIOONN CCAALLLLBBAACCKKSS The callback aadddd__ccbb is called to send custom extension data to be included in ClientHello for TLS clients or ServerHello for servers. The eexxtt__ttyyppee parameter is set to the extension type which will be added and aadddd__aarrgg to the value set when the extension handler was added. If the application wishes to include the extension eexxtt__ttyyppee it should set **oouutt to the extension data, set **oouuttlleenn to the length of the exten- sion data and return 1. If the aadddd__ccbb does not wish to include the extension it must return 0. If aadddd__ccbb returns -1 a fatal handshake error occurs using the TLS alert value specified in **aall. For clients (but not servers) if aadddd__ccbb is set to NULL a zero length extension is added for eexxtt__ttyyppee. For clients every registered aadddd__ccbb is always called to see if the application wishes to add an extension to ClientHello. For servers every registered aadddd__ccbb is called once if and only if the corresponding extension was received in ClientHello to see if the application wishes to add the extension to ServerHello. That is, if no corresponding extension was received in ClientHello then aadddd__ccbb will not be called. If an extension is added (that is aadddd__ccbb returns 1) ffrreeee__ccbb is called (if it is set) with the value of oouutt set by the add callback. It can be used to free up any dynamic extension data set by aadddd__ccbb. Since oouutt is constant (to permit use of constant data in aadddd__ccbb) applications may need to cast away const to free the data. The callback ppaarrssee__ccbb receives data for TLS extensions. For TLS clients the extension data will come from ServerHello and for TLS servers it will come from ClientHello. The extension data consists of iinnlleenn bytes in the buffer iinn for the extension eexxtteennssiioonn__ttyyppee. If the ppaarrssee__ccbb considers the extension data acceptable it must return 1. If it returns 0 or a negative value a fatal handshake error occurs using the TLS alert value specified in **aall. The buffer iinn is a temporary internal buffer which will not be valid after the callback returns. NNOOTTEESS The aadddd__aarrgg and ppaarrssee__aarrgg parameters can be set to arbitrary values which will be passed to the corresponding callbacks. They can, for example, be used to store the extension data received in a convenient structure or pass the extension data to be added or freed when adding extensions. The eexxtt__ttyyppee parameter corresponds to the eexxtteennssiioonn__ttyyppee field of RFC5246 et al. It is nnoott a NID. If the same custom extension type is received multiple times a fatal ddeeccooddee__eerrrroorr alert is sent and the handshake aborts. If a custom exten- sion is received in ServerHello which was not sent in ClientHello a fatal uunnssuuppppoorrtteedd__eexxtteennssiioonn alert is sent and the handshake is aborted. The ServerHello aadddd__ccbb callback is only called if the corresponding extension was received in ClientHello. This is compliant with the TLS specifications. This behaviour ensures that each callback is called at most once and that an application can never send unsolicited exten- sions. RREETTUURRNN VVAALLUUEESS _S_S_L___C_T_X___a_d_d___c_l_i_e_n_t___c_u_s_t_o_m___e_x_t_(_) and _S_S_L___C_T_X___a_d_d___s_e_r_v_e_r___c_u_s_t_o_m___e_x_t_(_) return 1 for success and 0 for failure. A failure can occur if an attempt is made to add the same eexxtt__ttyyppee more than once, if an attempt is made to use an extension type handled internally by OpenSSL or if an internal error occurs (for example a memory allocation failure). _S_S_L___e_x_t_e_n_s_i_o_n___s_u_p_p_o_r_t_e_d_(_) returns 1 if the extension eexxtt__ttyyppee is han- dled internally by OpenSSL and 0 otherwise. 1.0.2u 2019-12-20 SSL_CTX_set_custom_cli_ext(3)