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