doc/ssl/SSL_CTX_set_custom_cli_ext.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 SSL_CTX_add_client_custom_ext, SSL_CTX_add_server_custom_ext - custom TLS extension handling
   6
   7 =head1 SYNOPSIS
   8
   9  #include <openssl/ssl.h>
  10
  11  int SSL_CTX_add_client_custom_ext(SSL_CTX *ctx, unsigned int ext_type,
  12                                    custom_ext_add_cb add_cb,
  13                                    custom_ext_free_cb free_cb, void *add_arg,
  14                                    custom_ext_parse_cb parse_cb,
  15                                    void *parse_arg);
  16
  17  int SSL_CTX_add_server_custom_ext(SSL_CTX *ctx, unsigned int ext_type,
  18                                    custom_ext_add_cb add_cb,
  19                                    custom_ext_free_cb free_cb, void *add_arg,
  20                                    custom_ext_parse_cb parse_cb,
  21                                    void *parse_arg);
  22
  23  int SSL_extension_supported(unsigned int ext_type);
  24
  25  typedef int (*custom_ext_add_cb)(SSL *s, unsigned int ext_type,
  26                                   const unsigned char **out,
  27                                   size_t *outlen, int *al,
  28                                   void *add_arg);
  29
  30  typedef void (*custom_ext_free_cb)(SSL *s, unsigned int ext_type,
  31                                     const unsigned char *out,
  32                                     void *add_arg);
  33
  34  typedef int (*custom_ext_parse_cb)(SSL *s, unsigned int ext_type,
  35                                     const unsigned char *in,
  36                                     size_t inlen, int *al,
  37                                     void *parse_arg);
  38
  39
  40 =head1 DESCRIPTION
  41
  42 SSL_CTX_add_client_custom_ext() adds a custom extension for a TLS client
  43 with extension type B<ext_type> and callbacks B<add_cb>, B<free_cb> and
  44 B<parse_cb>.
  45
  46 SSL_CTX_add_server_custom_ext() adds a custom extension for a TLS server
  47 with extension type B<ext_type> and callbacks B<add_cb>, B<free_cb> and
  48 B<parse_cb>.
  49
  50 In both cases the extension type must not be handled by OpenSSL internally
  51 or an error occurs.
  52
  53 SSL_extension_supported() returns 1 if the extension B<ext_type> is handled
  54 internally by OpenSSL and 0 otherwise.
  55
  56 =head1 EXTENSION CALLBACKS
  57
  58 The callback B<add_cb> is called to send custom extension data to be
  59 included in ClientHello for TLS clients or ServerHello for servers. The
  60 B<ext_type> parameter is set to the extension type which will be added and
  61 B<add_arg> to the value set when the extension handler was added.
  62
  63 If the application wishes to include the extension B<ext_type> it should
  64 set B<*out> to the extension data, set B<*outlen> to the length of the
  65 extension data and return 1.
  66
  67 If the B<add_cb> does not wish to include the extension it must return 0.
  68
  69 If B<add_cb> returns -1 a fatal handshake error occurs using the TLS
  70 alert value specified in B<*al>.
  71
  72 For clients (but not servers) if B<add_cb> is set to NULL a zero length
  73 extension is added for B<ext_type>.
  74
  75 For clients every registered B<add_cb> is always called to see if the
  76 application wishes to add an extension to ClientHello.
  77
  78 For servers every registered B<add_cb> is called once if and only if the
  79 corresponding extension was received in ClientHello to see if the application
  80 wishes to add the extension to ServerHello. That is, if no corresponding extension
  81 was received in ClientHello then B<add_cb> will not be called.
  82
  83 If 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
  85 used to free up any dynamic extension data set by B<add_cb>. Since B<out> is
  86 constant (to permit use of constant data in B<add_cb>) applications may need to
  87 cast away const to free the data.
  88
  89 The callback B<parse_cb> receives data for TLS extensions. For TLS clients
  90 the extension data will come from ServerHello and for TLS servers it will
  91 come from ClientHello.
  92
  93 The extension data consists of B<inlen> bytes in the buffer B<in> for the
  94 extension B<extension_type>.
  95
  96 If the B<parse_cb> considers the extension data acceptable it must return
  97 1. If it returns 0 or a negative value a fatal handshake error occurs
  98 using the TLS alert value specified in B<*al>.
  99
 100 The buffer B<in> is a temporary internal buffer which will not be valid after
 101 the callback returns.
 102
 103 =head1 NOTES
 104
 105 The B<add_arg> and B<parse_arg> parameters can be set to arbitrary values
 106 which will be passed to the corresponding callbacks. They can, for example,
 107 be used to store the extension data received in a convenient structure or
 108 pass the extension data to be added or freed when adding extensions.
 109
 110 The B<ext_type> parameter corresponds to the B<extension_type> field of
 111 RFC5246 et al. It is B<not> a NID.
 112
 113 If the same custom extension type is received multiple times a fatal
 114 B<decode_error> alert is sent and the handshake aborts. If a custom extension
 115 is received in ServerHello which was not sent in ClientHello a fatal
 116 B<unsupported_extension> alert is sent and the handshake is aborted. The
 117 ServerHello B<add_cb> callback is only called if the corresponding extension
 118 was received in ClientHello. This is compliant with the TLS specifications.
 119 This behaviour ensures that each callback is called at most once and that
 120 an application can never send unsolicited extensions.
 121
 122 =head1 RETURN VALUES
 123
 124 SSL_CTX_add_client_custom_ext() and SSL_CTX_add_server_custom_ext() return 1 for
 125 success and 0 for failure. A failure can occur if an attempt is made to
 126 add the same B<ext_type> more than once, if an attempt is made to use an
 127 extension type handled internally by OpenSSL or if an internal error occurs
 128 (for example a memory allocation failure).
 129
 130 SSL_extension_supported() returns 1 if the extension B<ext_type> is handled
 131 internally by OpenSSL and 0 otherwise.
 132
 133 =cut