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_select_next_proto, SSL_get0_alpn_selected - handle application layer
   7 protocol negotiation (ALPN)
   8
   9 =head1 SYNOPSIS
  10
  11  #include <openssl/ssl.h>
  12
  13  int SSL_CTX_set_alpn_protos(SSL_CTX *ctx, const unsigned char *protos,
  14                              unsigned int protos_len);
  15  int SSL_set_alpn_protos(SSL *ssl, const unsigned char *protos,
  16                          unsigned int protos_len);
  17  void SSL_CTX_set_alpn_select_cb(SSL_CTX *ctx,
  18                                  int (*cb) (SSL *ssl,
  19                                             const unsigned char **out,
  20                                             unsigned char *outlen,
  21                                             const unsigned char *in,
  22                                             unsigned int inlen,
  23                                             void *arg), void *arg);
  24  int SSL_select_next_proto(unsigned char **out, unsigned char *outlen,
  25                            const unsigned char *server,
  26                            unsigned int server_len,
  27                            const unsigned char *client,
  28                            unsigned int client_len)
  29  void SSL_get0_alpn_selected(const SSL *ssl, const unsigned char **data,
  30                              unsigned int *len);
  31
  32 =head1 DESCRIPTION
  33
  34 SSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() are used by the client to
  35 set the list of protocols available to be negotiated. The B<protos> must be in
  36 protocol-list format, described below. The length of B<protos> is specified in
  37 B<protos_len>.
  38
  39 SSL_CTX_set_alpn_select_cb() sets the application callback B<cb> used by a
  40 server to select which protocol to use for the incoming connection. When B<cb>
  41 is NULL, ALPN is not used. The B<arg> value is a pointer which is passed to
  42 the application callback.
  43
  44 B<cb> is the application defined callback. The B<in>, B<inlen> parameters are a
  45 vector in protocol-list format. The value of the B<out>, B<outlen> vector
  46 should be set to the value of a single protocol selected from the B<in>,
  47 B<inlen> vector. The B<out> buffer may point directly into B<in>, or to a
  48 buffer that outlives the handshake. The B<arg> parameter is the pointer set via
  49 SSL_CTX_set_alpn_select_cb().
  50
  51 SSL_select_next_proto() is a helper function used to select protocols. It
  52 implements the standard protocol selection. It is expected that this function
  53 is called from the application callback B<cb>. The protocol data in B<server>,
  54 B<server_len> and B<client>, B<client_len> must be in the protocol-list format
  55 described below. The first item in the B<server>, B<server_len> list that
  56 matches an item in the B<client>, B<client_len> list is selected, and returned
  57 in B<out>, B<outlen>. The B<out> value will point into either B<server> or
  58 B<client>, so it should be copied immediately. If no match is found, the first
  59 item in B<client>, B<client_len> is returned in B<out>, B<outlen>. This
  60 function can also be used in the NPN callback.
  61
  62 SSL_get0_alpn_selected() returns a pointer to the selected protocol in B<data>
  63 with length B<len>. It is not NUL-terminated. B<data> is set to NULL and B<len>
  64 is set to 0 if no protocol has been selected. B<data> must not be freed.
  65
  66 =head1 NOTES
  67
  68 The protocol-lists must be in wire-format, which is defined as a vector of
  69 non-empty, 8-bit length-prefixed, byte strings. The length-prefix byte is not
  70 included in the length. Each string is limited to 255 bytes. A byte-string
  71 length of 0 is invalid. A truncated byte-string is invalid. The length of the
  72 vector is not in the vector itself, but in a separate variable.
  73
  74 Example:
  75
  76  unsigned char vector[] = {
  77      6, 's', 'p', 'd', 'y', '/', '1',
  78      8, 'h', 't', 't', 'p', '/', '1', '.', '1'
  79  };
  80  unsigned int length = sizeof(vector);
  81
  82 The ALPN callback is executed after the servername callback; as that servername
  83 callback may update the SSL_CTX, and subsequently, the ALPN callback.
  84
  85 If there is no ALPN proposed in the ClientHello, the ALPN callback is not
  86 invoked.
  87
  88 =head1 RETURN VALUES
  89
  90 SSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() return 0 on success, and
  91 non-0 on failure. WARNING: these functions reverse the return value convention.
  92
  93 SSL_select_next_proto() returns one of the following:
  94
  95 =over 4
  96
  97 =item OPENSSL_NPN_NEGOTIATED
  98
  99 A match was found and is returned in B<out>, B<outlen>.
 100
 101 =item OPENSSL_NPN_NO_OVERLAP
 102
 103 No match was found. The first item in B<client>, B<client_len> is returned in
 104 B<out>, B<outlen>.
 105
 106 =back
 107
 108 The ALPN select callback B<cb>, must return one of the following:
 109
 110 =over 4
 111
 112 =item SSL_TLSEXT_ERR_OK
 113
 114 ALPN protocol selected.
 115
 116 =item SSL_TLSEXT_ERR_ALERT_FATAL
 117
 118 There was no overlap between the client's supplied list and the server
 119 configuration.
 120
 121 =item SSL_TLSEXT_ERR_NOACK
 122
 123 ALPN protocol not selected, e.g., because no ALPN protocols are configured for
 124 this connection.
 125
 126 =back
 127
 128 =head1 SEE ALSO
 129
 130 L<ssl(7)>, L<SSL_CTX_set_tlsext_servername_callback(3)>,
 131 L<SSL_CTX_set_tlsext_servername_arg(3)>
 132
 133 =head1 COPYRIGHT
 134
 135 Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
 136
 137 Licensed under the OpenSSL license (the "License").  You may not use
 138 this file except in compliance with the License.  You can obtain a copy
 139 in the file LICENSE in the source distribution or at
 140 L<https://www.openssl.org/source/license.html>.
 141
 142 =cut