1.\" $OpenBSD: SSL_CTX_set_alpn_select_cb.3,v 1.8 2021/09/10 09:25:29 tb Exp $ 2.\" OpenSSL 87b81496 Apr 19 12:38:27 2017 -0400 3.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 4.\" 5.\" This file was written by Todd Short <tshort@akamai.com>. 6.\" Copyright (c) 2016 The OpenSSL Project. All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in 17.\" the documentation and/or other materials provided with the 18.\" distribution. 19.\" 20.\" 3. All advertising materials mentioning features or use of this 21.\" software must display the following acknowledgment: 22.\" "This product includes software developed by the OpenSSL Project 23.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 24.\" 25.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 26.\" endorse or promote products derived from this software without 27.\" prior written permission. For written permission, please contact 28.\" openssl-core@openssl.org. 29.\" 30.\" 5. Products derived from this software may not be called "OpenSSL" 31.\" nor may "OpenSSL" appear in their names without prior written 32.\" permission of the OpenSSL Project. 33.\" 34.\" 6. Redistributions of any form whatsoever must retain the following 35.\" acknowledgment: 36.\" "This product includes software developed by the OpenSSL Project 37.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 38.\" 39.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 40.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 41.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 42.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 43.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 44.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 45.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 46.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 47.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 48.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 49.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 50.\" OF THE POSSIBILITY OF SUCH DAMAGE. 51.\" 52.Dd $Mdocdate: September 10 2021 $ 53.Dt SSL_CTX_SET_ALPN_SELECT_CB 3 54.Os 55.Sh NAME 56.Nm SSL_CTX_set_alpn_protos , 57.Nm SSL_set_alpn_protos , 58.Nm SSL_CTX_set_alpn_select_cb , 59.Nm SSL_select_next_proto , 60.Nm SSL_get0_alpn_selected 61.Nd handle application layer protocol negotiation (ALPN) 62.Sh SYNOPSIS 63.In openssl/ssl.h 64.Ft int 65.Fo SSL_CTX_set_alpn_protos 66.Fa "SSL_CTX *ctx" 67.Fa "const unsigned char *protos" 68.Fa "unsigned int protos_len" 69.Fc 70.Ft int 71.Fo SSL_set_alpn_protos 72.Fa "SSL *ssl" 73.Fa "const unsigned char *protos" 74.Fa "unsigned int protos_len" 75.Fc 76.Ft void 77.Fo SSL_CTX_set_alpn_select_cb 78.Fa "SSL_CTX *ctx" 79.Fa "int (*cb)(SSL *ssl, const unsigned char **out,\ 80 unsigned char *outlen, const unsigned char *in,\ 81 unsigned int inlen, void *arg)" 82.Fa "void *arg" 83.Fc 84.Ft int 85.Fo SSL_select_next_proto 86.Fa "unsigned char **out" 87.Fa "unsigned char *outlen" 88.Fa "const unsigned char *server" 89.Fa "unsigned int server_len" 90.Fa "const unsigned char *client" 91.Fa "unsigned int client_len" 92.Fc 93.Ft void 94.Fo SSL_get0_alpn_selected 95.Fa "const SSL *ssl" 96.Fa "const unsigned char **data" 97.Fa "unsigned int *len" 98.Fc 99.Sh DESCRIPTION 100.Fn SSL_CTX_set_alpn_protos 101and 102.Fn SSL_set_alpn_protos 103are used by the client to set the list of protocols available to be 104negotiated. 105The 106.Fa protos 107must be in protocol-list format, described below. 108The length of 109.Fa protos 110is specified in 111.Fa protos_len . 112.Pp 113.Fn SSL_CTX_set_alpn_select_cb 114sets the application callback 115.Fa cb 116used by a server to select which protocol to use for the incoming 117connection. 118When 119.Fa cb 120is 121.Dv NULL , 122ALPN is not used. 123The 124.Fa arg 125value is a pointer which is passed to the application callback. 126.Pp 127.Fa cb 128is the application defined callback. 129The 130.Fa in , 131.Fa inlen 132parameters are a vector in protocol-list format. 133The value of the 134.Fa out , 135.Fa outlen 136vector should be set to the value of a single protocol selected from the 137.Fa in , 138.Fa inlen 139vector. 140The 141.Fa out 142buffer may point directly into 143.Fa in , 144or to a buffer that outlives the handshake. 145The 146.Fa arg 147parameter is the pointer set via 148.Fn SSL_CTX_set_alpn_select_cb . 149.Pp 150.Fn SSL_select_next_proto 151is a helper function used to select protocols. 152It implements the standard protocol selection. 153It is expected that this function is called from the application 154callback 155.Fa cb . 156The protocol data in 157.Fa server , 158.Fa server_len 159and 160.Fa client , 161.Fa client_len 162must be in the protocol-list format described below. 163The first item in the 164.Fa server , 165.Fa server_len 166list that matches an item in the 167.Fa client , 168.Fa client_len 169list is selected, and returned in 170.Fa out , 171.Fa outlen . 172The 173.Fa out 174value will point into either 175.Fa server 176or 177.Fa client , 178so it should be copied immediately. 179If no match is found, the first item in 180.Fa client , 181.Fa client_len 182is returned in 183.Fa out , 184.Fa outlen . 185.Pp 186.Fn SSL_get0_alpn_selected 187returns a pointer to the selected protocol in 188.Fa data 189with length 190.Fa len . 191It is not NUL-terminated. 192.Fa data 193is set to 194.Dv NULL 195and 196.Fa len 197is set to 0 if no protocol has been selected. 198.Fa data 199must not be freed. 200.Pp 201The protocol-lists must be in wire-format, which is defined as a vector 202of non-empty, 8-bit length-prefixed byte strings. 203The length-prefix byte is not included in the length. 204Each string is limited to 255 bytes. 205A byte-string length of 0 is invalid. 206A truncated byte-string is invalid. 207The length of the vector is not in the vector itself, but in a separate 208variable. 209.Pp 210For example: 211.Bd -literal 212unsigned char vector[] = { 213 6, 's', 'p', 'd', 'y', '/', '1', 214 8, 'h', 't', 't', 'p', '/', '1', '.', '1' 215}; 216unsigned int length = sizeof(vector); 217.Ed 218.Pp 219The ALPN callback is executed after the servername callback; as that 220servername callback may update the SSL_CTX, and subsequently, the ALPN 221callback. 222.Pp 223If there is no ALPN proposed in the ClientHello, the ALPN callback is 224not invoked. 225.Sh RETURN VALUES 226.Fn SSL_CTX_set_alpn_protos 227and 228.Fn SSL_set_alpn_protos 229return 0 on success or non-zero on failure. 230WARNING: these functions reverse the return value convention. 231.Pp 232.Fn SSL_select_next_proto 233returns one of the following: 234.Bl -tag -width Ds 235.It OPENSSL_NPN_NEGOTIATED 236A match was found and is returned in 237.Fa out , 238.Fa outlen . 239.It OPENSSL_NPN_NO_OVERLAP 240No match was found. 241The first item in 242.Fa client , 243.Fa client_len 244is returned in 245.Fa out , 246.Fa outlen . 247.El 248.Pp 249The ALPN select callback 250.Fa cb 251must return one of the following: 252.Bl -tag -width Ds 253.It SSL_TLSEXT_ERR_OK 254ALPN protocol selected. 255.It SSL_TLSEXT_ERR_ALERT_FATAL 256There was no overlap between the client's supplied list and the 257server configuration. 258.It SSL_TLSEXT_ERR_NOACK 259ALPN protocol not selected, e.g., because no ALPN protocols are 260configured for this connection. 261.El 262.Sh SEE ALSO 263.Xr ssl 3 , 264.Xr SSL_CTX_set_tlsext_servername_arg 3 , 265.Xr SSL_CTX_set_tlsext_servername_callback 3 266.Sh HISTORY 267.Fn SSL_select_next_proto 268first appeared in OpenSSL 1.0.1 and has been available since 269.Ox 5.3 . 270.Pp 271.Fn SSL_CTX_set_alpn_protos , 272.Fn SSL_set_alpn_protos , 273.Fn SSL_CTX_set_alpn_select_cb , 274and 275.Fn SSL_get0_alpn_selected 276first appeared in OpenSSL 1.0.2 and have been available since 277.Ox 5.7 . 278