SSL_CTX_SET_ALPN_SELECT_CB(3)                         Library Functions Manual

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 int protos_len);

     int
     SSL_set_alpn_protos(SSL *ssl, const unsigned char *protos,
         unsigned int 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 *peer_list, unsigned int peer_list_len,
         const unsigned char *supported_list,
         unsigned int supported_list_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 out buffer may point directly into in, or to a buffer
     that outlives the handshake.  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 is expected that this function is called from the application callback
     cb.  If SSL_select_next_proto() returns OPENSSL_NPN_NO_OVERLAP, cb should
     ignore out and fail by returning SSL_TLSEXT_ERR_ALERT_FATAL.  The
     protocol data in peer_list, peer_list_len and supported_list,
     supported_list_len must be two non-empty lists, validly encoded in the
     protocol-list format described below.  The first item in the peer_list
     that matches an item in the supported_list is selected, and returned in
     out, outlen.  The out value will point into either peer_list or
     supported_list, so it must not be modified and should be copied
     immediately.  If no match is found, the first item in supported_list is
     returned in out, outlen.

     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.

     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.  The length of the vector is not in
     the vector itself, but in a separate variable.

     For example:

     const unsigned char *vector = "\x06" "spdy/1" "\x08" "http/1.1";
     unsigned int length = strlen(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
     or non-zero 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 supported_list,
             supported_list_len is returned in out, outlen.

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

     SSL_TLSEXT_ERR_OK
             ALPN protocol selected.

     SSL_TLSEXT_ERR_ALERT_FATAL
             There was no overlap between the client's supplied list and the
             server configuration.

     SSL_TLSEXT_ERR_NOACK
             ALPN protocol not selected, e.g., because no ALPN protocols are
             configured for this connection.

SEE ALSO
     ssl(3), SSL_CTX_set_tlsext_servername_arg(3),
     SSL_CTX_set_tlsext_servername_callback(3)

STANDARDS
     TLS Application-Layer Protocol Negotiation Extension, RFC 7301.

     TLS Next Protocol Negotiation Extension,
     https://datatracker.ietf.org/doc/html/draft-agl-tls-nextprotoneg.

HISTORY
     SSL_select_next_proto() first appeared in OpenSSL 1.0.1 and has been
     available since OpenBSD 5.3.

     SSL_CTX_set_alpn_protos(), SSL_set_alpn_protos(),
     SSL_CTX_set_alpn_select_cb(), and SSL_get0_alpn_selected() first appeared
     in OpenSSL 1.0.2 and have been available since OpenBSD 5.7.

CAVEATS
     The fallback to the first supported protocol in SSL_select_next_proto()
     comes from the opportunistic fallback mechanism in the NPN extension.
     This behavior does not make sense for ALPN, where missing protocol
     overlap should result in a handshake failure.  To avoid accidental
     selection of a protocol that the server does not support, it is
     recommended to pass the locally configured protocols as second pair of
     protocols in the ALPN callback.

BUGS
     The out argument of SSL_select_next_proto() should have been const.

Linux 6.13.7-arch1-1           February 4, 2025           Linux 6.13.7-arch1-1