1289848Sjkim=pod 2289848Sjkim 3289848Sjkim=head1 NAME 4289848Sjkim 5289848SjkimSSL_CTX_add_client_custom_ext, SSL_CTX_add_server_custom_ext - custom TLS extension handling 6289848Sjkim 7289848Sjkim=head1 SYNOPSIS 8289848Sjkim 9289848Sjkim #include <openssl/ssl.h> 10289848Sjkim 11289848Sjkim int SSL_CTX_add_client_custom_ext(SSL_CTX *ctx, unsigned int ext_type, 12289848Sjkim custom_ext_add_cb add_cb, 13289848Sjkim custom_ext_free_cb free_cb, void *add_arg, 14289848Sjkim custom_ext_parse_cb parse_cb, 15289848Sjkim void *parse_arg); 16289848Sjkim 17289848Sjkim int SSL_CTX_add_server_custom_ext(SSL_CTX *ctx, unsigned int ext_type, 18289848Sjkim custom_ext_add_cb add_cb, 19289848Sjkim custom_ext_free_cb free_cb, void *add_arg, 20289848Sjkim custom_ext_parse_cb parse_cb, 21289848Sjkim void *parse_arg); 22289848Sjkim 23289848Sjkim int SSL_extension_supported(unsigned int ext_type); 24289848Sjkim 25289848Sjkim typedef int (*custom_ext_add_cb)(SSL *s, unsigned int ext_type, 26289848Sjkim const unsigned char **out, 27289848Sjkim size_t *outlen, int *al, 28289848Sjkim void *add_arg); 29289848Sjkim 30289848Sjkim typedef void (*custom_ext_free_cb)(SSL *s, unsigned int ext_type, 31289848Sjkim const unsigned char *out, 32289848Sjkim void *add_arg); 33289848Sjkim 34289848Sjkim typedef int (*custom_ext_parse_cb)(SSL *s, unsigned int ext_type, 35289848Sjkim const unsigned char *in, 36289848Sjkim size_t inlen, int *al, 37289848Sjkim void *parse_arg); 38289848Sjkim 39289848Sjkim 40289848Sjkim=head1 DESCRIPTION 41289848Sjkim 42289848SjkimSSL_CTX_add_client_custom_ext() adds a custom extension for a TLS client 43289848Sjkimwith extension type B<ext_type> and callbacks B<add_cb>, B<free_cb> and 44289848SjkimB<parse_cb>. 45289848Sjkim 46289848SjkimSSL_CTX_add_server_custom_ext() adds a custom extension for a TLS server 47289848Sjkimwith extension type B<ext_type> and callbacks B<add_cb>, B<free_cb> and 48289848SjkimB<parse_cb>. 49289848Sjkim 50289848SjkimIn both cases the extension type must not be handled by OpenSSL internally 51289848Sjkimor an error occurs. 52289848Sjkim 53289848SjkimSSL_extension_supported() returns 1 if the extension B<ext_type> is handled 54289848Sjkiminternally by OpenSSL and 0 otherwise. 55289848Sjkim 56289848Sjkim=head1 EXTENSION CALLBACKS 57289848Sjkim 58289848SjkimThe callback B<add_cb> is called to send custom extension data to be 59289848Sjkimincluded in ClientHello for TLS clients or ServerHello for servers. The 60289848SjkimB<ext_type> parameter is set to the extension type which will be added and 61289848SjkimB<add_arg> to the value set when the extension handler was added. 62289848Sjkim 63289848SjkimIf the application wishes to include the extension B<ext_type> it should 64289848Sjkimset B<*out> to the extension data, set B<*outlen> to the length of the 65289848Sjkimextension data and return 1. 66289848Sjkim 67289848SjkimIf the B<add_cb> does not wish to include the extension it must return 0. 68289848Sjkim 69289848SjkimIf B<add_cb> returns -1 a fatal handshake error occurs using the TLS 70289848Sjkimalert value specified in B<*al>. 71289848Sjkim 72289848SjkimFor clients (but not servers) if B<add_cb> is set to NULL a zero length 73289848Sjkimextension is added for B<ext_type>. 74289848Sjkim 75289848SjkimFor clients every registered B<add_cb> is always called to see if the 76289848Sjkimapplication wishes to add an extension to ClientHello. 77289848Sjkim 78289848SjkimFor servers every registered B<add_cb> is called once if and only if the 79289848Sjkimcorresponding extension was received in ClientHello to see if the application 80289848Sjkimwishes to add the extension to ServerHello. That is, if no corresponding extension 81289848Sjkimwas received in ClientHello then B<add_cb> will not be called. 82289848Sjkim 83289848SjkimIf an extension is added (that is B<add_cb> returns 1) B<free_cb> is called 84289848Sjkim(if it is set) with the value of B<out> set by the add callback. It can be 85289848Sjkimused to free up any dynamic extension data set by B<add_cb>. Since B<out> is 86289848Sjkimconstant (to permit use of constant data in B<add_cb>) applications may need to 87289848Sjkimcast away const to free the data. 88289848Sjkim 89289848SjkimThe callback B<parse_cb> receives data for TLS extensions. For TLS clients 90289848Sjkimthe extension data will come from ServerHello and for TLS servers it will 91289848Sjkimcome from ClientHello. 92289848Sjkim 93289848SjkimThe extension data consists of B<inlen> bytes in the buffer B<in> for the 94289848Sjkimextension B<extension_type>. 95289848Sjkim 96289848SjkimIf the B<parse_cb> considers the extension data acceptable it must return 97289848Sjkim1. If it returns 0 or a negative value a fatal handshake error occurs 98289848Sjkimusing the TLS alert value specified in B<*al>. 99289848Sjkim 100289848SjkimThe buffer B<in> is a temporary internal buffer which will not be valid after 101289848Sjkimthe callback returns. 102289848Sjkim 103289848Sjkim=head1 NOTES 104289848Sjkim 105289848SjkimThe B<add_arg> and B<parse_arg> parameters can be set to arbitrary values 106289848Sjkimwhich will be passed to the corresponding callbacks. They can, for example, 107289848Sjkimbe used to store the extension data received in a convenient structure or 108289848Sjkimpass the extension data to be added or freed when adding extensions. 109289848Sjkim 110289848SjkimThe B<ext_type> parameter corresponds to the B<extension_type> field of 111289848SjkimRFC5246 et al. It is B<not> a NID. 112289848Sjkim 113289848SjkimIf the same custom extension type is received multiple times a fatal 114289848SjkimB<decode_error> alert is sent and the handshake aborts. If a custom extension 115289848Sjkimis received in ServerHello which was not sent in ClientHello a fatal 116289848SjkimB<unsupported_extension> alert is sent and the handshake is aborted. The 117289848SjkimServerHello B<add_cb> callback is only called if the corresponding extension 118289848Sjkimwas received in ClientHello. This is compliant with the TLS specifications. 119289848SjkimThis behaviour ensures that each callback is called at most once and that 120289848Sjkiman application can never send unsolicited extensions. 121289848Sjkim 122289848Sjkim=head1 RETURN VALUES 123289848Sjkim 124289848SjkimSSL_CTX_add_client_custom_ext() and SSL_CTX_add_server_custom_ext() return 1 for 125289848Sjkimsuccess and 0 for failure. A failure can occur if an attempt is made to 126289848Sjkimadd the same B<ext_type> more than once, if an attempt is made to use an 127289848Sjkimextension type handled internally by OpenSSL or if an internal error occurs 128289848Sjkim(for example a memory allocation failure). 129289848Sjkim 130289848SjkimSSL_extension_supported() returns 1 if the extension B<ext_type> is handled 131289848Sjkiminternally by OpenSSL and 0 otherwise. 132289848Sjkim 133289848Sjkim=cut 134