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