1=pod
2
3=head1 NAME
4
5SSL_CTX_set_alpn_protos, SSL_set_alpn_protos, SSL_CTX_set_alpn_select_cb,
6SSL_select_next_proto, SSL_get0_alpn_selected - handle application layer
7protocol negotiation (ALPN)
8
9=head1 SYNOPSIS
10
11 #include <openssl/ssl.h>
12
13 int SSL_CTX_set_alpn_protos(SSL_CTX *ctx, const unsigned char *protos,
14                             unsigned protos_len);
15 int SSL_set_alpn_protos(SSL *ssl, const unsigned char *protos,
16                         unsigned protos_len);
17 void SSL_CTX_set_alpn_select_cb(SSL_CTX *ctx,
18                                 int (*cb) (SSL *ssl,
19                                            const unsigned char **out,
20                                            unsigned char *outlen,
21                                            const unsigned char *in,
22                                            unsigned int inlen,
23                                            void *arg), void *arg);
24 int SSL_select_next_proto(unsigned char **out, unsigned char *outlen,
25                           const unsigned char *server,
26                           unsigned int server_len,
27                           const unsigned char *client,
28                           unsigned int client_len)
29 void SSL_get0_alpn_selected(const SSL *ssl, const unsigned char **data,
30                             unsigned int *len);
31
32=head1 DESCRIPTION
33
34SSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() are used by the client to
35set the list of protocols available to be negotiated. The B<protos> must be in
36protocol-list format, described below. The length of B<protos> is specified in
37B<protos_len>.
38
39SSL_CTX_set_alpn_select_cb() sets the application callback B<cb> used by a
40server to select which protocol to use for the incoming connection. When B<cb>
41is NULL, ALPN is not used. The B<arg> value is a pointer which is passed to
42the application callback.
43
44B<cb> is the application defined callback. The B<in>, B<inlen> parameters are a
45vector in protocol-list format. The value of the B<out>, B<outlen> vector
46should be set to the value of a single protocol selected from the B<in>,
47B<inlen> vector. The B<arg> parameter is the pointer set via
48SSL_CTX_set_alpn_select_cb().
49
50SSL_select_next_proto() is a helper function used to select protocols. It
51implements the standard protocol selection. It is expected that this function
52is called from the application callback B<cb>. The protocol data in B<server>,
53B<server_len> and B<client>, B<client_len> must be in the protocol-list format
54described below. The first item in the B<server>, B<server_len> list that
55matches an item in the B<client>, B<client_len> list is selected, and returned
56in B<out>, B<outlen>. The B<out> value will point into either B<server> or
57B<client>, so it should be copied immediately. If no match is found, the first
58item in B<client>, B<client_len> is returned in B<out>, B<outlen>. This
59function can also be used in the NPN callback.
60
61SSL_get0_alpn_selected() returns a pointer to the selected protocol in B<data>
62with length B<len>. It is not NUL-terminated. B<data> is set to NULL and B<len>
63is set to 0 if no protocol has been selected. B<data> must not be freed.
64
65=head1 NOTES
66
67The protocol-lists must be in wire-format, which is defined as a vector of
68non-empty, 8-bit length-prefixed, byte strings. The length-prefix byte is not
69included in the length. Each string is limited to 255 bytes. A byte-string
70length of 0 is invalid. A truncated byte-string is invalid. The length of the
71vector is not in the vector itself, but in a separate variable.
72
73Example:
74
75 unsigned char vector[] = {
76     6, 's', 'p', 'd', 'y', '/', '1',
77     8, 'h', 't', 't', 'p', '/', '1', '.', '1'
78 };
79 unsigned int length = sizeof(vector);
80
81The ALPN callback is executed after the servername callback; as that servername
82callback may update the SSL_CTX, and subsequently, the ALPN callback.
83
84If there is no ALPN proposed in the ClientHello, the ALPN callback is not
85invoked.
86
87=head1 RETURN VALUES
88
89SSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() return 0 on success, and
90non-0 on failure. WARNING: these functions reverse the return value convention.
91
92SSL_select_next_proto() returns one of the following:
93
94=over 4
95
96=item OPENSSL_NPN_NEGOTIATED
97
98A match was found and is returned in B<out>, B<outlen>.
99
100=item OPENSSL_NPN_NO_OVERLAP
101
102No match was found. The first item in B<client>, B<client_len> is returned in
103B<out>, B<outlen>.
104
105=back
106
107The ALPN select callback B<cb>, must return one of the following:
108
109=over 4
110
111=item SSL_TLSEXT_ERR_OK
112
113ALPN protocol selected.
114
115=item SSL_TLSEXT_ERR_NOACK
116
117ALPN protocol not selected.
118
119=back
120
121=head1 SEE ALSO
122
123L<ssl(3)>, L<SSL_CTX_set_tlsext_servername_callback(3)>,
124L<SSL_CTX_set_tlsext_servername_arg(3)>
125
126=cut
127