OpenBSD manual page server

Manual Page Search Parameters
SSL_CTX_SET_ALPN_SELECT_CB(3) Library Functions Manual SSL_CTX_SET_ALPN_SELECT_CB(3)

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)

#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);

() and () 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.

() 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 ().

() 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.

() 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 = "\6" "spdy/1" "\8" "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.

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.

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

TLS Application-Layer Protocol Negotiation Extension, RFC 7301.

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

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.

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.

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

July 11, 2024 OpenBSD-current