doc/man3/SSL_CTX_set_alpn_select_cb.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 SSL_CTX_set_alpn_protos, SSL_set_alpn_protos, SSL_CTX_set_alpn_select_cb,
   6 SSL_CTX_set_next_proto_select_cb, SSL_CTX_set_next_protos_advertised_cb,
   7 SSL_select_next_proto, SSL_get0_alpn_selected, SSL_get0_next_proto_negotiated
   8 - handle application layer protocol negotiation (ALPN)
   9
  10 =head1 SYNOPSIS
  11
  12  #include <openssl/ssl.h>
  13
  14  int SSL_CTX_set_alpn_protos(SSL_CTX *ctx, const unsigned char *protos,
  15                              unsigned int protos_len);
  16  int SSL_set_alpn_protos(SSL *ssl, const unsigned char *protos,
  17                          unsigned int protos_len);
  18  void SSL_CTX_set_alpn_select_cb(SSL_CTX *ctx,
  19                                  int (*cb) (SSL *ssl,
  20                                             const unsigned char **out,
  21                                             unsigned char *outlen,
  22                                             const unsigned char *in,
  23                                             unsigned int inlen,
  24                                             void *arg), void *arg);
  25  void SSL_get0_alpn_selected(const SSL *ssl, const unsigned char **data,
  26                              unsigned int *len);
  27
  28  void SSL_CTX_set_next_protos_advertised_cb(SSL_CTX *ctx,
  29                                             int (*cb)(SSL *ssl,
  30                                                       const unsigned char **out,
  31                                                       unsigned int *outlen,
  32                                                       void *arg),
  33                                             void *arg);
  34  void SSL_CTX_set_next_proto_select_cb(SSL_CTX *ctx,
  35                                int (*cb)(SSL *s,
  36                                          unsigned char **out,
  37                                          unsigned char *outlen,
  38                                          const unsigned char *in,
  39                                          unsigned int inlen,
  40                                          void *arg),
  41                                void *arg);
  42  int SSL_select_next_proto(unsigned char **out, unsigned char *outlen,
  43                            const unsigned char *server,
  44                            unsigned int server_len,
  45                            const unsigned char *client,
  46                            unsigned int client_len)
  47  void SSL_get0_next_proto_negotiated(const SSL *s, const unsigned char **data,
  48                              unsigned *len);
  49
  50 =head1 DESCRIPTION
  51
  52 SSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() are used by the client to
  53 set the list of protocols available to be negotiated. The B<protos> must be in
  54 protocol-list format, described below. The length of B<protos> is specified in
  55 B<protos_len>.
  56
  57 SSL_CTX_set_alpn_select_cb() sets the application callback B<cb> used by a
  58 server to select which protocol to use for the incoming connection. When B<cb>
  59 is NULL, ALPN is not used. The B<arg> value is a pointer which is passed to
  60 the application callback.
  61
  62 B<cb> is the application defined callback. The B<in>, B<inlen> parameters are a
  63 vector in protocol-list format. The value of the B<out>, B<outlen> vector
  64 should be set to the value of a single protocol selected from the B<in>,
  65 B<inlen> vector. The B<out> buffer may point directly into B<in>, or to a
  66 buffer that outlives the handshake. The B<arg> parameter is the pointer set via
  67 SSL_CTX_set_alpn_select_cb().
  68
  69 SSL_select_next_proto() is a helper function used to select protocols. It
  70 implements the standard protocol selection. It is expected that this function
  71 is called from the application callback B<cb>. The protocol data in B<server>,
  72 B<server_len> and B<client>, B<client_len> must be in the protocol-list format
  73 described below. The first item in the B<server>, B<server_len> list that
  74 matches an item in the B<client>, B<client_len> list is selected, and returned
  75 in B<out>, B<outlen>. The B<out> value will point into either B<server> or
  76 B<client>, so it should be copied immediately. If no match is found, the first
  77 item in B<client>, B<client_len> is returned in B<out>, B<outlen>. This
  78 function can also be used in the NPN callback.
  79
  80 SSL_CTX_set_next_proto_select_cb() sets a callback B<cb> that is called when a
  81 client needs to select a protocol from the server's provided list, and a
  82 user-defined pointer argument B<arg> which will be passed to this callback.
  83 For the callback itself, B<out>
  84 must be set to point to the selected protocol (which may be within B<in>).
  85 The length of the protocol name must be written into B<outlen>. The
  86 server's advertised protocols are provided in B<in> and B<inlen>. The
  87 callback can assume that B<in> is syntactically valid. The client must
  88 select a protocol. It is fatal to the connection if this callback returns
  89 a value other than B<SSL_TLSEXT_ERR_OK>. The B<arg> parameter is the pointer
  90 set via SSL_CTX_set_next_proto_select_cb().
  91
  92 SSL_CTX_set_next_protos_advertised_cb() sets a callback B<cb> that is called
  93 when a TLS server needs a list of supported protocols for Next Protocol
  94 Negotiation. The returned list must be in protocol-list format, described
  95 below.  The list is
  96 returned by setting B<out> to point to it and B<outlen> to its length. This
  97 memory will not be modified, but the B<SSL> does keep a
  98 reference to it. The callback should return B<SSL_TLSEXT_ERR_OK> if it
  99 wishes to advertise. Otherwise, no such extension will be included in the
 100 ServerHello.
 101
 102 SSL_get0_alpn_selected() returns a pointer to the selected protocol in B<data>
 103 with length B<len>. It is not NUL-terminated. B<data> is set to NULL and B<len>
 104 is set to 0 if no protocol has been selected. B<data> must not be freed.
 105
 106 SSL_get0_next_proto_negotiated() sets B<data> and B<len> to point to the
 107 client's requested protocol for this connection. If the client did not
 108 request any protocol or NPN is not enabled, then B<data> is set to NULL and
 109 B<len> to 0. Note that
 110 the client can request any protocol it chooses. The value returned from
 111 this function need not be a member of the list of supported protocols
 112 provided by the callback.
 113
 114 =head1 NOTES
 115
 116 The protocol-lists must be in wire-format, which is defined as a vector of
 117 non-empty, 8-bit length-prefixed, byte strings. The length-prefix byte is not
 118 included in the length. Each string is limited to 255 bytes. A byte-string
 119 length of 0 is invalid. A truncated byte-string is invalid. The length of the
 120 vector is not in the vector itself, but in a separate variable.
 121
 122 Example:
 123
 124  unsigned char vector[] = {
 125      6, 's', 'p', 'd', 'y', '/', '1',
 126      8, 'h', 't', 't', 'p', '/', '1', '.', '1'
 127  };
 128  unsigned int length = sizeof(vector);
 129
 130 The ALPN callback is executed after the servername callback; as that servername
 131 callback may update the SSL_CTX, and subsequently, the ALPN callback.
 132
 133 If there is no ALPN proposed in the ClientHello, the ALPN callback is not
 134 invoked.
 135
 136 =head1 RETURN VALUES
 137
 138 SSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() return 0 on success, and
 139 non-0 on failure. WARNING: these functions reverse the return value convention.
 140
 141 SSL_select_next_proto() returns one of the following:
 142
 143 =over 4
 144
 145 =item OPENSSL_NPN_NEGOTIATED
 146
 147 A match was found and is returned in B<out>, B<outlen>.
 148
 149 =item OPENSSL_NPN_NO_OVERLAP
 150
 151 No match was found. The first item in B<client>, B<client_len> is returned in
 152 B<out>, B<outlen>.
 153
 154 =back
 155
 156 The ALPN select callback B<cb>, must return one of the following:
 157
 158 =over 4
 159
 160 =item SSL_TLSEXT_ERR_OK
 161
 162 ALPN protocol selected.
 163
 164 =item SSL_TLSEXT_ERR_ALERT_FATAL
 165
 166 There was no overlap between the client's supplied list and the server
 167 configuration.
 168
 169 =item SSL_TLSEXT_ERR_NOACK
 170
 171 ALPN protocol not selected, e.g., because no ALPN protocols are configured for
 172 this connection.
 173
 174 =back
 175
 176 The callback set using SSL_CTX_set_next_proto_select_cb() should return
 177 B<SSL_TLSEXT_ERR_OK> if successful. Any other value is fatal to the connection.
 178
 179 The callback set using SSL_CTX_set_next_protos_advertised_cb() should return
 180 B<SSL_TLSEXT_ERR_OK> if it wishes to advertise. Otherwise, no such extension
 181 will be included in the ServerHello.
 182
 183 =head1 SEE ALSO
 184
 185 L<ssl(7)>, L<SSL_CTX_set_tlsext_servername_callback(3)>,
 186 L<SSL_CTX_set_tlsext_servername_arg(3)>
 187
 188 =head1 COPYRIGHT
 189
 190 Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved.
 191
 192 Licensed under the OpenSSL license (the "License").  You may not use
 193 this file except in compliance with the License.  You can obtain a copy
 194 in the file LICENSE in the source distribution or at
 195 L<https://www.openssl.org/source/license.html>.
 196
 197 =cut