SSL_CTX_set_custom_cli_ext.pod revision 303975
19831Sgdamore@opensolaris.org=pod 29831Sgdamore@opensolaris.org 39831Sgdamore@opensolaris.org=head1 NAME 49831Sgdamore@opensolaris.org 59831Sgdamore@opensolaris.orgSSL_CTX_add_client_custom_ext, SSL_CTX_add_server_custom_ext - custom TLS extension handling 69831Sgdamore@opensolaris.org 79831Sgdamore@opensolaris.org=head1 SYNOPSIS 89831Sgdamore@opensolaris.org 99831Sgdamore@opensolaris.org #include <openssl/ssl.h> 109831Sgdamore@opensolaris.org 119831Sgdamore@opensolaris.org int SSL_CTX_add_client_custom_ext(SSL_CTX *ctx, unsigned int ext_type, 129831Sgdamore@opensolaris.org custom_ext_add_cb add_cb, 139831Sgdamore@opensolaris.org custom_ext_free_cb free_cb, void *add_arg, 149831Sgdamore@opensolaris.org custom_ext_parse_cb parse_cb, 159831Sgdamore@opensolaris.org void *parse_arg); 169831Sgdamore@opensolaris.org 179831Sgdamore@opensolaris.org int SSL_CTX_add_server_custom_ext(SSL_CTX *ctx, unsigned int ext_type, 189831Sgdamore@opensolaris.org custom_ext_add_cb add_cb, 199831Sgdamore@opensolaris.org custom_ext_free_cb free_cb, void *add_arg, 209831Sgdamore@opensolaris.org custom_ext_parse_cb parse_cb, 219831Sgdamore@opensolaris.org void *parse_arg); 229831Sgdamore@opensolaris.org 239831Sgdamore@opensolaris.org int SSL_extension_supported(unsigned int ext_type); 249831Sgdamore@opensolaris.org 259831Sgdamore@opensolaris.org typedef int (*custom_ext_add_cb)(SSL *s, unsigned int ext_type, 269831Sgdamore@opensolaris.org const unsigned char **out, 279831Sgdamore@opensolaris.org size_t *outlen, int *al, 289831Sgdamore@opensolaris.org void *add_arg); 299831Sgdamore@opensolaris.org 309831Sgdamore@opensolaris.org typedef void (*custom_ext_free_cb)(SSL *s, unsigned int ext_type, 319831Sgdamore@opensolaris.org const unsigned char *out, 329831Sgdamore@opensolaris.org void *add_arg); 339831Sgdamore@opensolaris.org 349831Sgdamore@opensolaris.org typedef int (*custom_ext_parse_cb)(SSL *s, unsigned int ext_type, 359831Sgdamore@opensolaris.org const unsigned char *in, 369831Sgdamore@opensolaris.org size_t inlen, int *al, 379831Sgdamore@opensolaris.org void *parse_arg); 389831Sgdamore@opensolaris.org 399831Sgdamore@opensolaris.org 409831Sgdamore@opensolaris.org=head1 DESCRIPTION 419831Sgdamore@opensolaris.org 429831Sgdamore@opensolaris.orgSSL_CTX_add_client_custom_ext() adds a custom extension for a TLS client 439831Sgdamore@opensolaris.orgwith extension type B<ext_type> and callbacks B<add_cb>, B<free_cb> and 449831Sgdamore@opensolaris.orgB<parse_cb>. 459831Sgdamore@opensolaris.org 469831Sgdamore@opensolaris.orgSSL_CTX_add_server_custom_ext() adds a custom extension for a TLS server 479831Sgdamore@opensolaris.orgwith extension type B<ext_type> and callbacks B<add_cb>, B<free_cb> and 489831Sgdamore@opensolaris.orgB<parse_cb>. 499831Sgdamore@opensolaris.org 509831Sgdamore@opensolaris.orgIn both cases the extension type must not be handled by OpenSSL internally 519831Sgdamore@opensolaris.orgor an error occurs. 529831Sgdamore@opensolaris.org 539831Sgdamore@opensolaris.orgSSL_extension_supported() returns 1 if the extension B<ext_type> is handled 549831Sgdamore@opensolaris.orginternally by OpenSSL and 0 otherwise. 559831Sgdamore@opensolaris.org 569831Sgdamore@opensolaris.org=head1 EXTENSION CALLBACKS 579831Sgdamore@opensolaris.org 589831Sgdamore@opensolaris.orgThe callback B<add_cb> is called to send custom extension data to be 599831Sgdamore@opensolaris.orgincluded in ClientHello for TLS clients or ServerHello for servers. The 609831Sgdamore@opensolaris.orgB<ext_type> parameter is set to the extension type which will be added and 619831Sgdamore@opensolaris.orgB<add_arg> to the value set when the extension handler was added. 629831Sgdamore@opensolaris.org 639831Sgdamore@opensolaris.orgIf the application wishes to include the extension B<ext_type> it should 649831Sgdamore@opensolaris.orgset B<*out> to the extension data, set B<*outlen> to the length of the 659831Sgdamore@opensolaris.orgextension data and return 1. 669831Sgdamore@opensolaris.org 679831Sgdamore@opensolaris.orgIf the B<add_cb> does not wish to include the extension it must return 0. 689831Sgdamore@opensolaris.org 699831Sgdamore@opensolaris.orgIf B<add_cb> returns -1 a fatal handshake error occurs using the TLS 709831Sgdamore@opensolaris.orgalert value specified in B<*al>. 719831Sgdamore@opensolaris.org 729831Sgdamore@opensolaris.orgFor clients (but not servers) if B<add_cb> is set to NULL a zero length 739831Sgdamore@opensolaris.orgextension is added for B<ext_type>. 749831Sgdamore@opensolaris.org 759831Sgdamore@opensolaris.orgFor clients every registered B<add_cb> is always called to see if the 769831Sgdamore@opensolaris.orgapplication wishes to add an extension to ClientHello. 779831Sgdamore@opensolaris.org 789831Sgdamore@opensolaris.orgFor servers every registered B<add_cb> is called once if and only if the 799831Sgdamore@opensolaris.orgcorresponding extension was received in ClientHello to see if the application 809831Sgdamore@opensolaris.orgwishes to add the extension to ServerHello. That is, if no corresponding extension 819831Sgdamore@opensolaris.orgwas received in ClientHello then B<add_cb> will not be called. 82 83If an extension is added (that is B<add_cb> returns 1) B<free_cb> is called 84(if it is set) with the value of B<out> set by the add callback. It can be 85used to free up any dynamic extension data set by B<add_cb>. Since B<out> is 86constant (to permit use of constant data in B<add_cb>) applications may need to 87cast away const to free the data. 88 89The callback B<parse_cb> receives data for TLS extensions. For TLS clients 90the extension data will come from ServerHello and for TLS servers it will 91come from ClientHello. 92 93The extension data consists of B<inlen> bytes in the buffer B<in> for the 94extension B<extension_type>. 95 96If the B<parse_cb> considers the extension data acceptable it must return 971. If it returns 0 or a negative value a fatal handshake error occurs 98using the TLS alert value specified in B<*al>. 99 100The buffer B<in> is a temporary internal buffer which will not be valid after 101the callback returns. 102 103=head1 NOTES 104 105The B<add_arg> and B<parse_arg> parameters can be set to arbitrary values 106which will be passed to the corresponding callbacks. They can, for example, 107be used to store the extension data received in a convenient structure or 108pass the extension data to be added or freed when adding extensions. 109 110The B<ext_type> parameter corresponds to the B<extension_type> field of 111RFC5246 et al. It is B<not> a NID. 112 113If the same custom extension type is received multiple times a fatal 114B<decode_error> alert is sent and the handshake aborts. If a custom extension 115is received in ServerHello which was not sent in ClientHello a fatal 116B<unsupported_extension> alert is sent and the handshake is aborted. The 117ServerHello B<add_cb> callback is only called if the corresponding extension 118was received in ClientHello. This is compliant with the TLS specifications. 119This behaviour ensures that each callback is called at most once and that 120an application can never send unsolicited extensions. 121 122=head1 RETURN VALUES 123 124SSL_CTX_add_client_custom_ext() and SSL_CTX_add_server_custom_ext() return 1 for 125success and 0 for failure. A failure can occur if an attempt is made to 126add the same B<ext_type> more than once, if an attempt is made to use an 127extension type handled internally by OpenSSL or if an internal error occurs 128(for example a memory allocation failure). 129 130SSL_extension_supported() returns 1 if the extension B<ext_type> is handled 131internally by OpenSSL and 0 otherwise. 132 133=cut 134