1=pod 2 3=head1 NAME 4 5SSL_CTX_set_alpn_protos, SSL_set_alpn_protos, SSL_CTX_set_alpn_select_cb, 6SSL_CTX_set_next_proto_select_cb, SSL_CTX_set_next_protos_advertised_cb, 7SSL_select_next_proto, SSL_get0_alpn_selected, SSL_get0_next_proto_negotiated 8- handle application layer protocol negotiation (ALPN) 9 10=head1 SYNOPSIS 11 12 #include <openssl/ssl.h> 13 14 int SSL_CTX_set_alpn_protos(SSL_CTX *ctx, const unsigned char *protos, 15 unsigned int protos_len); 16 int SSL_set_alpn_protos(SSL *ssl, const unsigned char *protos, 17 unsigned int 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 void SSL_get0_alpn_selected(const SSL *ssl, const unsigned char **data, 26 unsigned int *len); 27 28 void SSL_CTX_set_next_protos_advertised_cb(SSL_CTX *ctx, 29 int (*cb)(SSL *ssl, 30 const unsigned char **out, 31 unsigned int *outlen, 32 void *arg), 33 void *arg); 34 void SSL_CTX_set_next_proto_select_cb(SSL_CTX *ctx, 35 int (*cb)(SSL *s, 36 unsigned char **out, 37 unsigned char *outlen, 38 const unsigned char *in, 39 unsigned int inlen, 40 void *arg), 41 void *arg); 42 int SSL_select_next_proto(unsigned char **out, unsigned char *outlen, 43 const unsigned char *server, 44 unsigned int server_len, 45 const unsigned char *client, 46 unsigned int client_len); 47 void SSL_get0_next_proto_negotiated(const SSL *s, const unsigned char **data, 48 unsigned *len); 49 50=head1 DESCRIPTION 51 52SSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() are used by the client to 53set the list of protocols available to be negotiated. The B<protos> must be in 54protocol-list format, described below. The length of B<protos> is specified in 55B<protos_len>. Setting B<protos_len> to 0 clears any existing list of ALPN 56protocols and no ALPN extension will be sent to the server. 57 58SSL_CTX_set_alpn_select_cb() sets the application callback B<cb> used by a 59server to select which protocol to use for the incoming connection. When B<cb> 60is NULL, ALPN is not used. The B<arg> value is a pointer which is passed to 61the application callback. 62 63B<cb> is the application defined callback. The B<in>, B<inlen> parameters are a 64vector in protocol-list format. The value of the B<out>, B<outlen> vector 65should be set to the value of a single protocol selected from the B<in>, 66B<inlen> vector. The B<out> buffer may point directly into B<in>, or to a 67buffer that outlives the handshake. The B<arg> parameter is the pointer set via 68SSL_CTX_set_alpn_select_cb(). 69 70SSL_select_next_proto() is a helper function used to select protocols. It 71implements the standard protocol selection. It is expected that this function 72is called from the application callback B<cb>. The protocol data in B<server>, 73B<server_len> and B<client>, B<client_len> must be in the protocol-list format 74described below. The first item in the B<server>, B<server_len> list that 75matches an item in the B<client>, B<client_len> list is selected, and returned 76in B<out>, B<outlen>. The B<out> value will point into either B<server> or 77B<client>, so it should be copied immediately. The client list must include at 78least one valid (nonempty) protocol entry in the list. 79 80The SSL_select_next_proto() helper function can be useful from either the ALPN 81callback or the NPN callback (described below). If no match is found, the first 82item in B<client>, B<client_len> is returned in B<out>, B<outlen> and 83B<OPENSSL_NPN_NO_OVERLAP> is returned. This can be useful when implementing 84the NPN callback. In the ALPN case, the value returned in B<out> and B<outlen> 85must be ignored if B<OPENSSL_NPN_NO_OVERLAP> has been returned from 86SSL_select_next_proto(). 87 88SSL_CTX_set_next_proto_select_cb() sets a callback B<cb> that is called when a 89client needs to select a protocol from the server's provided list, and a 90user-defined pointer argument B<arg> which will be passed to this callback. 91For the callback itself, B<out> 92must be set to point to the selected protocol (which may be within B<in>). 93The length of the protocol name must be written into B<outlen>. The 94server's advertised protocols are provided in B<in> and B<inlen>. The 95callback can assume that B<in> is syntactically valid. The client must 96select a protocol (although it may be an empty, zero length protocol). It is 97fatal to the connection if this callback returns a value other than 98B<SSL_TLSEXT_ERR_OK> or if the zero length protocol is selected. The B<arg> 99parameter is the pointer set via SSL_CTX_set_next_proto_select_cb(). 100 101SSL_CTX_set_next_protos_advertised_cb() sets a callback B<cb> that is called 102when a TLS server needs a list of supported protocols for Next Protocol 103Negotiation. The returned list must be in protocol-list format, described 104below. The list is 105returned by setting B<out> to point to it and B<outlen> to its length. This 106memory will not be modified, but the B<SSL> does keep a 107reference to it. The callback should return B<SSL_TLSEXT_ERR_OK> if it 108wishes to advertise. Otherwise, no such extension will be included in the 109ServerHello. 110 111SSL_get0_alpn_selected() returns a pointer to the selected protocol in B<data> 112with length B<len>. It is not NUL-terminated. B<data> is set to NULL and B<len> 113is set to 0 if no protocol has been selected. B<data> must not be freed. 114 115SSL_get0_next_proto_negotiated() sets B<data> and B<len> to point to the 116client's requested protocol for this connection. If the client did not 117request any protocol or NPN is not enabled, then B<data> is set to NULL and 118B<len> to 0. Note that 119the client can request any protocol it chooses. The value returned from 120this function need not be a member of the list of supported protocols 121provided by the callback. 122 123=head1 NOTES 124 125The protocol-lists must be in wire-format, which is defined as a vector of 126nonempty, 8-bit length-prefixed, byte strings. The length-prefix byte is not 127included in the length. Each string is limited to 255 bytes. A byte-string 128length of 0 is invalid. A truncated byte-string is invalid. The length of the 129vector is not in the vector itself, but in a separate variable. 130 131Example: 132 133 unsigned char vector[] = { 134 6, 's', 'p', 'd', 'y', '/', '1', 135 8, 'h', 't', 't', 'p', '/', '1', '.', '1' 136 }; 137 unsigned int length = sizeof(vector); 138 139The ALPN callback is executed after the servername callback; as that servername 140callback may update the SSL_CTX, and subsequently, the ALPN callback. 141 142If there is no ALPN proposed in the ClientHello, the ALPN callback is not 143invoked. 144 145=head1 RETURN VALUES 146 147SSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() return 0 on success, and 148non-0 on failure. WARNING: these functions reverse the return value convention. 149 150SSL_select_next_proto() returns one of the following: 151 152=over 4 153 154=item OPENSSL_NPN_NEGOTIATED 155 156A match was found and is returned in B<out>, B<outlen>. 157 158=item OPENSSL_NPN_NO_OVERLAP 159 160No match was found. The first item in B<client>, B<client_len> is returned in 161B<out>, B<outlen> (or B<NULL> and 0 in the case where the first entry in 162B<client> is invalid). 163 164=back 165 166The ALPN select callback B<cb>, must return one of the following: 167 168=over 4 169 170=item SSL_TLSEXT_ERR_OK 171 172ALPN protocol selected. 173 174=item SSL_TLSEXT_ERR_ALERT_FATAL 175 176There was no overlap between the client's supplied list and the server 177configuration. 178 179=item SSL_TLSEXT_ERR_NOACK 180 181ALPN protocol not selected, e.g., because no ALPN protocols are configured for 182this connection. 183 184=back 185 186The callback set using SSL_CTX_set_next_proto_select_cb() should return 187B<SSL_TLSEXT_ERR_OK> if successful. Any other value is fatal to the connection. 188 189The callback set using SSL_CTX_set_next_protos_advertised_cb() should return 190B<SSL_TLSEXT_ERR_OK> if it wishes to advertise. Otherwise, no such extension 191will be included in the ServerHello. 192 193=head1 SEE ALSO 194 195L<ssl(7)>, L<SSL_CTX_set_tlsext_servername_callback(3)>, 196L<SSL_CTX_set_tlsext_servername_arg(3)> 197 198=head1 COPYRIGHT 199 200Copyright 2016-2024 The OpenSSL Project Authors. All Rights Reserved. 201 202Licensed under the Apache License 2.0 (the "License"). You may not use 203this file except in compliance with the License. You can obtain a copy 204in the file LICENSE in the source distribution or at 205L<https://www.openssl.org/source/license.html>. 206 207=cut 208