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 *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
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 implements the standard
protocol selection. It is expected that this function is called from the
application callback cb. The protocol data in
server, 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.
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. A truncated byte-string is invalid. The length of the vector is not in the vector itself, but in a separate variable.
For 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 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 client, client_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)
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.