SSL_CTX_set_alpn_select_cb(3ssl)

1SSL_CTX_set_alpn_select_cb(3)       OpenSSL      SSL_CTX_set_alpn_select_cb(3)
2
3
4

NAME

6       SSL_CTX_set_alpn_protos, SSL_set_alpn_protos,
7       SSL_CTX_set_alpn_select_cb, SSL_select_next_proto,
8       SSL_get0_alpn_selected - handle application layer protocol negotiation
9       (ALPN)
10

SYNOPSIS

12        #include <openssl/ssl.h>
13
14        int SSL_CTX_set_alpn_protos(SSL_CTX *ctx, const unsigned char *protos,
15                                    unsigned protos_len);
16        int SSL_set_alpn_protos(SSL *ssl, const unsigned char *protos,
17                                unsigned protos_len);
18        void SSL_CTX_set_alpn_select_cb(SSL_CTX *ctx,
19                                        int (*cb) (SSL *ssl,
20                                                   const unsigned char **out,
21                                                   unsigned char *outlen,
22                                                   const unsigned char *in,
23                                                   unsigned int inlen,
24                                                   void *arg), void *arg);
25        int SSL_select_next_proto(unsigned char **out, unsigned char *outlen,
26                                  const unsigned char *server,
27                                  unsigned int server_len,
28                                  const unsigned char *client,
29                                  unsigned int client_len)
30        void SSL_get0_alpn_selected(const SSL *ssl, const unsigned char **data,
31                                    unsigned int *len);
32

DESCRIPTION

34       SSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() are used by the
35       client to set the list of protocols available to be negotiated. The
36       protos must be in protocol-list format, described below. The length of
37       protos is specified in protos_len.
38
39       SSL_CTX_set_alpn_select_cb() sets the application callback cb used by a
40       server to select which protocol to use for the incoming connection.
41       When cb is NULL, ALPN is not used. The arg value is a pointer which is
42       passed to the application callback.
43
44       cb is the application defined callback. The in, inlen parameters are a
45       vector in protocol-list format. The value of the out, outlen vector
46       should be set to the value of a single protocol selected from the in,
47       inlen vector. The arg parameter is the pointer set via
48       SSL_CTX_set_alpn_select_cb().
49
50       SSL_select_next_proto() is a helper function used to select protocols.
51       It implements the standard protocol selection. It is expected that this
52       function is called from the application callback cb. The protocol data
53       in server, server_len and client, client_len must be in the protocol-
54       list format described below. The first item in the server, server_len
55       list that matches an item in the client, client_len list is selected,
56       and returned in out, outlen. The out value will point into either
57       server or client, so it should be copied immediately. If no match is
58       found, the first item in client, client_len is returned in out, outlen.
59       This function can also be used in the NPN callback.
60
61       SSL_get0_alpn_selected() returns a pointer to the selected protocol in
62       data with length len. It is not NUL-terminated. data is set to NULL and
63       len is set to 0 if no protocol has been selected. data must not be
64       freed.
65

NOTES

67       The protocol-lists must be in wire-format, which is defined as a vector
68       of non-empty, 8-bit length-prefixed, byte strings. The length-prefix
69       byte is not included in the length. Each string is limited to 255
70       bytes. A byte-string length of 0 is invalid. A truncated byte-string is
71       invalid. The length of the vector is not in the vector itself, but in a
72       separate variable.
73
74       Example:
75
76        unsigned char vector[] = {
77            6, 's', 'p', 'd', 'y', '/', '1',
78            8, 'h', 't', 't', 'p', '/', '1', '.', '1'
79        };
80        unsigned int length = sizeof(vector);
81
82       The ALPN callback is executed after the servername callback; as that
83       servername callback may update the SSL_CTX, and subsequently, the ALPN
84       callback.
85
86       If there is no ALPN proposed in the ClientHello, the ALPN callback is
87       not invoked.
88

RETURN VALUES

90       SSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() return 0 on
91       success, and non-0 on failure. WARNING: these functions reverse the
92       return value convention.
93
94       SSL_select_next_proto() returns one of the following:
95
96       OPENSSL_NPN_NEGOTIATED
97           A match was found and is returned in out, outlen.
98
99       OPENSSL_NPN_NO_OVERLAP
100           No match was found. The first item in client, client_len is
101           returned in out, outlen.
102
103       The ALPN select callback cb, must return one of the following:
104
105       SSL_TLSEXT_ERR_OK
106           ALPN protocol selected.
107
108       SSL_TLSEXT_ERR_NOACK
109           ALPN protocol not selected.
110

NAME

SYNOPSIS

DESCRIPTION

NOTES

RETURN VALUES

SEE ALSO