1e71b7053SJung-uk Kim=pod 2e71b7053SJung-uk Kim 3e71b7053SJung-uk Kim=head1 NAME 4e71b7053SJung-uk Kim 5e71b7053SJung-uk KimSSL_CTX_set_alpn_protos, SSL_set_alpn_protos, SSL_CTX_set_alpn_select_cb, 6e71b7053SJung-uk KimSSL_CTX_set_next_proto_select_cb, SSL_CTX_set_next_protos_advertised_cb, 7e71b7053SJung-uk KimSSL_select_next_proto, SSL_get0_alpn_selected, SSL_get0_next_proto_negotiated 8e71b7053SJung-uk Kim- handle application layer protocol negotiation (ALPN) 9e71b7053SJung-uk Kim 10e71b7053SJung-uk Kim=head1 SYNOPSIS 11e71b7053SJung-uk Kim 12e71b7053SJung-uk Kim #include <openssl/ssl.h> 13e71b7053SJung-uk Kim 14e71b7053SJung-uk Kim int SSL_CTX_set_alpn_protos(SSL_CTX *ctx, const unsigned char *protos, 15e71b7053SJung-uk Kim unsigned int protos_len); 16e71b7053SJung-uk Kim int SSL_set_alpn_protos(SSL *ssl, const unsigned char *protos, 17e71b7053SJung-uk Kim unsigned int protos_len); 18e71b7053SJung-uk Kim void SSL_CTX_set_alpn_select_cb(SSL_CTX *ctx, 19e71b7053SJung-uk Kim int (*cb) (SSL *ssl, 20e71b7053SJung-uk Kim const unsigned char **out, 21e71b7053SJung-uk Kim unsigned char *outlen, 22e71b7053SJung-uk Kim const unsigned char *in, 23e71b7053SJung-uk Kim unsigned int inlen, 24e71b7053SJung-uk Kim void *arg), void *arg); 25e71b7053SJung-uk Kim void SSL_get0_alpn_selected(const SSL *ssl, const unsigned char **data, 26e71b7053SJung-uk Kim unsigned int *len); 27e71b7053SJung-uk Kim 28e71b7053SJung-uk Kim void SSL_CTX_set_next_protos_advertised_cb(SSL_CTX *ctx, 29e71b7053SJung-uk Kim int (*cb)(SSL *ssl, 30e71b7053SJung-uk Kim const unsigned char **out, 31e71b7053SJung-uk Kim unsigned int *outlen, 32e71b7053SJung-uk Kim void *arg), 33e71b7053SJung-uk Kim void *arg); 34e71b7053SJung-uk Kim void SSL_CTX_set_next_proto_select_cb(SSL_CTX *ctx, 35e71b7053SJung-uk Kim int (*cb)(SSL *s, 36e71b7053SJung-uk Kim unsigned char **out, 37e71b7053SJung-uk Kim unsigned char *outlen, 38e71b7053SJung-uk Kim const unsigned char *in, 39e71b7053SJung-uk Kim unsigned int inlen, 40e71b7053SJung-uk Kim void *arg), 41e71b7053SJung-uk Kim void *arg); 42e71b7053SJung-uk Kim int SSL_select_next_proto(unsigned char **out, unsigned char *outlen, 43e71b7053SJung-uk Kim const unsigned char *server, 44e71b7053SJung-uk Kim unsigned int server_len, 45e71b7053SJung-uk Kim const unsigned char *client, 46*b077aed3SPierre Pronchery unsigned int client_len); 47e71b7053SJung-uk Kim void SSL_get0_next_proto_negotiated(const SSL *s, const unsigned char **data, 48e71b7053SJung-uk Kim unsigned *len); 49e71b7053SJung-uk Kim 50e71b7053SJung-uk Kim=head1 DESCRIPTION 51e71b7053SJung-uk Kim 52e71b7053SJung-uk KimSSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() are used by the client to 53e71b7053SJung-uk Kimset the list of protocols available to be negotiated. The B<protos> must be in 54e71b7053SJung-uk Kimprotocol-list format, described below. The length of B<protos> is specified in 55e71b7053SJung-uk KimB<protos_len>. 56e71b7053SJung-uk Kim 57e71b7053SJung-uk KimSSL_CTX_set_alpn_select_cb() sets the application callback B<cb> used by a 58e71b7053SJung-uk Kimserver to select which protocol to use for the incoming connection. When B<cb> 59e71b7053SJung-uk Kimis NULL, ALPN is not used. The B<arg> value is a pointer which is passed to 60e71b7053SJung-uk Kimthe application callback. 61e71b7053SJung-uk Kim 62e71b7053SJung-uk KimB<cb> is the application defined callback. The B<in>, B<inlen> parameters are a 63e71b7053SJung-uk Kimvector in protocol-list format. The value of the B<out>, B<outlen> vector 64e71b7053SJung-uk Kimshould be set to the value of a single protocol selected from the B<in>, 65e71b7053SJung-uk KimB<inlen> vector. The B<out> buffer may point directly into B<in>, or to a 66e71b7053SJung-uk Kimbuffer that outlives the handshake. The B<arg> parameter is the pointer set via 67e71b7053SJung-uk KimSSL_CTX_set_alpn_select_cb(). 68e71b7053SJung-uk Kim 69e71b7053SJung-uk KimSSL_select_next_proto() is a helper function used to select protocols. It 70e71b7053SJung-uk Kimimplements the standard protocol selection. It is expected that this function 71e71b7053SJung-uk Kimis called from the application callback B<cb>. The protocol data in B<server>, 72e71b7053SJung-uk KimB<server_len> and B<client>, B<client_len> must be in the protocol-list format 73e71b7053SJung-uk Kimdescribed below. The first item in the B<server>, B<server_len> list that 74e71b7053SJung-uk Kimmatches an item in the B<client>, B<client_len> list is selected, and returned 75e71b7053SJung-uk Kimin B<out>, B<outlen>. The B<out> value will point into either B<server> or 76e71b7053SJung-uk KimB<client>, so it should be copied immediately. If no match is found, the first 77e71b7053SJung-uk Kimitem in B<client>, B<client_len> is returned in B<out>, B<outlen>. This 78e71b7053SJung-uk Kimfunction can also be used in the NPN callback. 79e71b7053SJung-uk Kim 80e71b7053SJung-uk KimSSL_CTX_set_next_proto_select_cb() sets a callback B<cb> that is called when a 81e71b7053SJung-uk Kimclient needs to select a protocol from the server's provided list, and a 82e71b7053SJung-uk Kimuser-defined pointer argument B<arg> which will be passed to this callback. 83e71b7053SJung-uk KimFor the callback itself, B<out> 84e71b7053SJung-uk Kimmust be set to point to the selected protocol (which may be within B<in>). 85e71b7053SJung-uk KimThe length of the protocol name must be written into B<outlen>. The 86e71b7053SJung-uk Kimserver's advertised protocols are provided in B<in> and B<inlen>. The 87e71b7053SJung-uk Kimcallback can assume that B<in> is syntactically valid. The client must 88e71b7053SJung-uk Kimselect a protocol. It is fatal to the connection if this callback returns 89e71b7053SJung-uk Kima value other than B<SSL_TLSEXT_ERR_OK>. The B<arg> parameter is the pointer 90e71b7053SJung-uk Kimset via SSL_CTX_set_next_proto_select_cb(). 91e71b7053SJung-uk Kim 92e71b7053SJung-uk KimSSL_CTX_set_next_protos_advertised_cb() sets a callback B<cb> that is called 93e71b7053SJung-uk Kimwhen a TLS server needs a list of supported protocols for Next Protocol 94e71b7053SJung-uk KimNegotiation. The returned list must be in protocol-list format, described 95e71b7053SJung-uk Kimbelow. The list is 96e71b7053SJung-uk Kimreturned by setting B<out> to point to it and B<outlen> to its length. This 97e71b7053SJung-uk Kimmemory will not be modified, but the B<SSL> does keep a 98e71b7053SJung-uk Kimreference to it. The callback should return B<SSL_TLSEXT_ERR_OK> if it 99e71b7053SJung-uk Kimwishes to advertise. Otherwise, no such extension will be included in the 100e71b7053SJung-uk KimServerHello. 101e71b7053SJung-uk Kim 102e71b7053SJung-uk KimSSL_get0_alpn_selected() returns a pointer to the selected protocol in B<data> 103e71b7053SJung-uk Kimwith length B<len>. It is not NUL-terminated. B<data> is set to NULL and B<len> 104e71b7053SJung-uk Kimis set to 0 if no protocol has been selected. B<data> must not be freed. 105e71b7053SJung-uk Kim 106e71b7053SJung-uk KimSSL_get0_next_proto_negotiated() sets B<data> and B<len> to point to the 107e71b7053SJung-uk Kimclient's requested protocol for this connection. If the client did not 108e71b7053SJung-uk Kimrequest any protocol or NPN is not enabled, then B<data> is set to NULL and 109e71b7053SJung-uk KimB<len> to 0. Note that 110e71b7053SJung-uk Kimthe client can request any protocol it chooses. The value returned from 111e71b7053SJung-uk Kimthis function need not be a member of the list of supported protocols 112e71b7053SJung-uk Kimprovided by the callback. 113e71b7053SJung-uk Kim 114e71b7053SJung-uk Kim=head1 NOTES 115e71b7053SJung-uk Kim 116e71b7053SJung-uk KimThe protocol-lists must be in wire-format, which is defined as a vector of 11758f35182SJung-uk Kimnonempty, 8-bit length-prefixed, byte strings. The length-prefix byte is not 118e71b7053SJung-uk Kimincluded in the length. Each string is limited to 255 bytes. A byte-string 119e71b7053SJung-uk Kimlength of 0 is invalid. A truncated byte-string is invalid. The length of the 120e71b7053SJung-uk Kimvector is not in the vector itself, but in a separate variable. 121e71b7053SJung-uk Kim 122e71b7053SJung-uk KimExample: 123e71b7053SJung-uk Kim 124e71b7053SJung-uk Kim unsigned char vector[] = { 125e71b7053SJung-uk Kim 6, 's', 'p', 'd', 'y', '/', '1', 126e71b7053SJung-uk Kim 8, 'h', 't', 't', 'p', '/', '1', '.', '1' 127e71b7053SJung-uk Kim }; 128e71b7053SJung-uk Kim unsigned int length = sizeof(vector); 129e71b7053SJung-uk Kim 130e71b7053SJung-uk KimThe ALPN callback is executed after the servername callback; as that servername 131e71b7053SJung-uk Kimcallback may update the SSL_CTX, and subsequently, the ALPN callback. 132e71b7053SJung-uk Kim 133e71b7053SJung-uk KimIf there is no ALPN proposed in the ClientHello, the ALPN callback is not 134e71b7053SJung-uk Kiminvoked. 135e71b7053SJung-uk Kim 136e71b7053SJung-uk Kim=head1 RETURN VALUES 137e71b7053SJung-uk Kim 138e71b7053SJung-uk KimSSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() return 0 on success, and 139e71b7053SJung-uk Kimnon-0 on failure. WARNING: these functions reverse the return value convention. 140e71b7053SJung-uk Kim 141e71b7053SJung-uk KimSSL_select_next_proto() returns one of the following: 142e71b7053SJung-uk Kim 143e71b7053SJung-uk Kim=over 4 144e71b7053SJung-uk Kim 145e71b7053SJung-uk Kim=item OPENSSL_NPN_NEGOTIATED 146e71b7053SJung-uk Kim 147e71b7053SJung-uk KimA match was found and is returned in B<out>, B<outlen>. 148e71b7053SJung-uk Kim 149e71b7053SJung-uk Kim=item OPENSSL_NPN_NO_OVERLAP 150e71b7053SJung-uk Kim 151e71b7053SJung-uk KimNo match was found. The first item in B<client>, B<client_len> is returned in 152e71b7053SJung-uk KimB<out>, B<outlen>. 153e71b7053SJung-uk Kim 154e71b7053SJung-uk Kim=back 155e71b7053SJung-uk Kim 156e71b7053SJung-uk KimThe ALPN select callback B<cb>, must return one of the following: 157e71b7053SJung-uk Kim 158e71b7053SJung-uk Kim=over 4 159e71b7053SJung-uk Kim 160e71b7053SJung-uk Kim=item SSL_TLSEXT_ERR_OK 161e71b7053SJung-uk Kim 162e71b7053SJung-uk KimALPN protocol selected. 163e71b7053SJung-uk Kim 164e71b7053SJung-uk Kim=item SSL_TLSEXT_ERR_ALERT_FATAL 165e71b7053SJung-uk Kim 166e71b7053SJung-uk KimThere was no overlap between the client's supplied list and the server 167e71b7053SJung-uk Kimconfiguration. 168e71b7053SJung-uk Kim 169e71b7053SJung-uk Kim=item SSL_TLSEXT_ERR_NOACK 170e71b7053SJung-uk Kim 171e71b7053SJung-uk KimALPN protocol not selected, e.g., because no ALPN protocols are configured for 172e71b7053SJung-uk Kimthis connection. 173e71b7053SJung-uk Kim 174e71b7053SJung-uk Kim=back 175e71b7053SJung-uk Kim 176e71b7053SJung-uk KimThe callback set using SSL_CTX_set_next_proto_select_cb() should return 177e71b7053SJung-uk KimB<SSL_TLSEXT_ERR_OK> if successful. Any other value is fatal to the connection. 178e71b7053SJung-uk Kim 179e71b7053SJung-uk KimThe callback set using SSL_CTX_set_next_protos_advertised_cb() should return 180e71b7053SJung-uk KimB<SSL_TLSEXT_ERR_OK> if it wishes to advertise. Otherwise, no such extension 181e71b7053SJung-uk Kimwill be included in the ServerHello. 182e71b7053SJung-uk Kim 183e71b7053SJung-uk Kim=head1 SEE ALSO 184e71b7053SJung-uk Kim 185e71b7053SJung-uk KimL<ssl(7)>, L<SSL_CTX_set_tlsext_servername_callback(3)>, 186e71b7053SJung-uk KimL<SSL_CTX_set_tlsext_servername_arg(3)> 187e71b7053SJung-uk Kim 188e71b7053SJung-uk Kim=head1 COPYRIGHT 189e71b7053SJung-uk Kim 19058f35182SJung-uk KimCopyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved. 191e71b7053SJung-uk Kim 192*b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 193e71b7053SJung-uk Kimthis file except in compliance with the License. You can obtain a copy 194e71b7053SJung-uk Kimin the file LICENSE in the source distribution or at 195e71b7053SJung-uk KimL<https://www.openssl.org/source/license.html>. 196e71b7053SJung-uk Kim 197e71b7053SJung-uk Kim=cut 198