doc/ssl/SSL_CTX_set_alpn_select_cb.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 SSL_CTX_set_alpn_select_cb, SSL_CTX_set_alpn_protos, SSL_set_alpn_protos,
   6 SSL_get0_alpn_selected, SSL_select_next_proto - 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, no ALPN is not used. The B<arg> value is 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 contained with in the B<in>,
  47 B<inlen> vector. The B<arg> parameter is the pointer set via
  48 SSL_CTX_set_alpn_select_cb().
  49
  50 SSL_select_next_proto() is a helper function used to select protocols. It
  51 implements the standard protocol selection. It is expected that this function
  52 is called from the application callback B<cb>. The protocol data in B<server>,
  53 B<server_len> and B<client>, B<client_len> must be in protocol-list format
  54 described below. The first item in the B<server>, B<server_len> list that
  55 matches an item in the B<client>, B<client_len> list is selected, and returned
  56 in B<out>, B<outlen>. The B<out> value will point into either B<server> or
  57 B<client>, so it should be copied immediately. If no match is found, the first
  58 item in B<client>, B<client_len> is returned in B<out>, B<outlen>. This
  59 function can also be used in the NPN callback.
  60
  61 SSL_get0_alpn_selected() returns a pointer to the selected protocol in B<data>
  62 with length B<len>. It is not NUL-terminated. B<data> is set to NULL and B<len>
  63 is set to 0 if no protocol has been selected. B<data> value must not be freed.
  64
  65 =head1 NOTES
  66
  67 The protocol-lists must be in wire-format, which is defined as a vector of
  68 non-empty, 8-bit length-prefixed, byte strings. The length-prefix byte is not
  69 included in the length. Each string is limited to 255 bytes. A byte-string
  70 length of 0 is invalid. A truncated byte-string is invalid. The length of the
  71 vector is not in the vector itself, but in a separate variable.
  72
  73 Example:
  74
  75  unsigned char vector[] = {
  76      6, 's', 'p', 'd', 'y', '/', '1',
  77      8, 'h', 't', 't', 'p', '/', '1', '.', '1'
  78  };
  79  unsigned int length = sizeof(vector);
  80
  81 The ALPN callback is executed after the servername callback; as that servername
  82 callback may update the SSL_CTX, and subsequently, the ALPN callback.
  83
  84 If there is no ALPN proposed in the ClientHello, the ALPN callback is not
  85 invoked.
  86
  87 =head1 RETURN VALUES
  88
  89 SSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() return 0 on success, and
  90 non-0 on failure. WARNING: these functions reverse the return value convention.
  91
  92 SSL_select_next_proto() returns one of the following:
  93
  94 =over 4
  95
  96 =item OPENSSL_NPN_NEGOTIATED
  97
  98 A match was found and is returned in B<out>, B<outlen>.
  99
 100 =item OPENSSL_NPN_NO_OVERLAP
 101
 102 No match was found. The first item in B<client>, B<client_len> is returned in
 103 B<out>, B<outlen>.
 104
 105 =back
 106
 107 The ALPN select callback B<cb>, must return one of the following:
 108
 109 =over 4
 110
 111 =item SSL_TLSEXT_ERR_OK
 112
 113 ALPN protocol selected.
 114
 115 =item SSL_TLSEXT_ERR_NOACK
 116
 117 ALPN protocol not selected.
 118
 119 =back
 120
 121 =head1 SEE ALSO
 122
 123 L<ssl(3)>, L<SSL_CTX_set_tlsext_servername_callback(3)>,
 124 L<SSL_CTX_set_tlsext_servername_arg(3)>
 125
 126 =cut