libressl-SSL_CTX_set_alpn_select_cb3

Usage

Overview

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.

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.