/usr/man/cat.3/SSL_CTX_set_alpn_select_cb.3

SSL_CTX_set_alpn_select_cb(3)OpenSSLSSL_CTX_set_alpn_select_cb(3)

NAME

     SSL_CTX_set_alpn_protos, SSL_set_alpn_protos,
     SSL_CTX_set_alpn_select_cb, SSL_select_next_proto,
     SSL_get0_alpn_selected - handle application layer protocol
     negotiation (ALPN)

SYNOPSIS

      #include <openssl/ssl.h>

      int SSL_CTX_set_alpn_protos(SSL_CTX *ctx, const unsigned char *protos,
                                  unsigned protos_len);
      int SSL_set_alpn_protos(SSL *ssl, const unsigned char *protos,
                              unsigned protos_len);
      void SSL_CTX_set_alpn_select_cb(SSL_CTX *ctx,
                                      int (*cb) (SSL *ssl,
                                                 const unsigned char **out,
                                                 unsigned char *outlen,
                                                 const unsigned char *in,
                                                 unsigned int inlen,
                                                 void *arg), void *arg);
      int SSL_select_next_proto(unsigned char **out, unsigned char *outlen,
                                const unsigned char *server,
                                unsigned int server_len,
                                const unsigned char *client,
                                unsigned int client_len)
      void SSL_get0_alpn_selected(const SSL *ssl, const unsigned char **data,
                                  unsigned int *len);

DESCRIPTION

     SSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() are used
     by the client to set the list of protocols available to be
     negotiated. The protos must be in protocol-list format,
     described below. The length of protos is specified in
     protos_len.

     SSL_CTX_set_alpn_select_cb() sets the application callback
     cb used by a server to select which protocol to use for the
     incoming connection. When cb is NULL, ALPN is not used. The
     arg value is a pointer which is passed to the application
     callback.

     cb is the application defined callback. The in, inlen
     parameters are a vector in protocol-list format. The value
     of the out, outlen vector should be set to the value of a
     single protocol selected from the in, inlen vector. The arg
     parameter is the pointer set via
     SSL_CTX_set_alpn_select_cb().

     SSL_select_next_proto() is a helper function used to select
     protocols. It implements the standard protocol selection. It
     is expected that this function is called from the
     application callback cb. The protocol data in server,

1.0.2t               Last change: 2019-09-10                    1

SSL_CTX_set_alpn_select_cb(3)OpenSSLSSL_CTX_set_alpn_select_cb(3)

     server_len and client, client_len must be in the protocol-
     list format described below. The first item in the server,
     server_len list that matches an item in the client,
     client_len list is selected, and returned in out, outlen.
     The out value will point into either server or client, so it
     should be copied immediately. If no match is found, the
     first item in client, client_len is returned in out, outlen.
     This function can also be used in the NPN callback.

     SSL_get0_alpn_selected() returns a pointer to the selected
     protocol in data with length len. It is not NUL-terminated.
     data is set to NULL and len is set to 0 if no protocol has
     been selected. data must not be freed.

NOTES

     The protocol-lists must be in wire-format, which is defined
     as a vector of non-empty, 8-bit length-prefixed, byte
     strings. The length-prefix byte is not included in the
     length. Each string is limited to 255 bytes. A byte-string
     length of 0 is invalid. A truncated byte-string is invalid.
     The length of the vector is not in the vector itself, but in
     a separate variable.

     Example:

      unsigned char vector[] = {
          6, 's', 'p', 'd', 'y', '/', '1',
          8, 'h', 't', 't', 'p', '/', '1', '.', '1'
      };
      unsigned int length = sizeof(vector);

     The ALPN callback is executed after the servername callback;
     as that servername callback may update the SSL_CTX, and
     subsequently, the ALPN callback.

     If there is no ALPN proposed in the ClientHello, the ALPN
     callback is not invoked.

RETURN VALUES

     SSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() return 0
     on success, and non-0 on failure. WARNING: these functions
     reverse the return value convention.

     SSL_select_next_proto() returns one of the following:

     OPENSSL_NPN_NEGOTIATED
         A match was found and is returned in out, outlen.

     OPENSSL_NPN_NO_OVERLAP
         No match was found. The first item in client, client_len
         is returned in out, outlen.

1.0.2t               Last change: 2019-09-10                    2

SSL_CTX_set_alpn_select_cb(3)OpenSSLSSL_CTX_set_alpn_select_cb(3)

     The ALPN select callback cb, must return one of the
     following:

     SSL_TLSEXT_ERR_OK
         ALPN protocol selected.

     SSL_TLSEXT_ERR_NOACK
         ALPN protocol not selected.

SEE ALSO

     ssl(3), SSL_CTX_set_tlsext_servername_callback(3),
     SSL_CTX_set_tlsext_servername_arg(3)

1.0.2t               Last change: 2019-09-10                    3

See also SSL_CTX_set_alpn_protos(3)
See also SSL_get0_alpn_selected(3)
See also SSL_select_next_proto(3)
See also SSL_set_alpn_protos(3)