1.\" $OpenBSD: SSL_CTX_set_alpn_select_cb.3,v 1.10 2024/07/11 13:50:44 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: July 11 2024 $ 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 *peer_list" 89.Fa "unsigned int peer_list_len" 90.Fa "const unsigned char *supported_list" 91.Fa "unsigned int supported_list_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 is expected that this function is called from the application 153callback 154.Fa cb . 155If 156.Fn SSL_select_next_proto 157returns 158.Dv OPENSSL_NPN_NO_OVERLAP , 159.Fa cb 160should ignore 161.Fa out 162and fail by returning 163.Dv SSL_TLSEXT_ERR_ALERT_FATAL . 164The protocol data in 165.Fa peer_list , 166.Fa peer_list_len 167and 168.Fa supported_list , 169.Fa supported_list_len 170must be two non-empty lists, validly encoded 171in the protocol-list format described below. 172The first item in the 173.Fa peer_list 174that matches an item in the 175.Fa supported_list 176is selected, and returned in 177.Fa out , 178.Fa outlen . 179The 180.Fa out 181value will point into either 182.Fa peer_list 183or 184.Fa supported_list , 185so it must not be modified and 186should be copied immediately. 187If no match is found, the first item in 188.Fa supported_list 189is returned in 190.Fa out , 191.Fa outlen . 192.Pp 193.Fn SSL_get0_alpn_selected 194returns a pointer to the selected protocol in 195.Fa data 196with length 197.Fa len . 198It is not NUL-terminated. 199.Fa data 200is set to 201.Dv NULL 202and 203.Fa len 204is set to 0 if no protocol has been selected. 205.Fa data 206must not be freed. 207.Pp 208The protocol-lists must be in wire-format, which is defined as a vector 209of non-empty, 8-bit length-prefixed byte strings. 210The length-prefix byte is not included in the length. 211Each string is limited to 255 bytes. 212A byte-string length of 0 is invalid. 213The length of the vector is not in the vector itself, but in a separate 214variable. 215.Pp 216For example: 217.Bd -literal 218const unsigned char *vector = "\e6" "spdy/1" "\e8" "http/1.1"; 219unsigned int length = strlen(vector); 220.Ed 221.Pp 222The ALPN callback is executed after the servername callback; as that 223servername callback may update the SSL_CTX, and subsequently, the ALPN 224callback. 225.Pp 226If there is no ALPN proposed in the ClientHello, the ALPN callback is 227not invoked. 228.Sh RETURN VALUES 229.Fn SSL_CTX_set_alpn_protos 230and 231.Fn SSL_set_alpn_protos 232return 0 on success or non-zero on failure. 233WARNING: these functions reverse the return value convention. 234.Pp 235.Fn SSL_select_next_proto 236returns one of the following: 237.Bl -tag -width Ds 238.It OPENSSL_NPN_NEGOTIATED 239A match was found and is returned in 240.Fa out , 241.Fa outlen . 242.It OPENSSL_NPN_NO_OVERLAP 243No match was found. 244The first item in 245.Fa supported_list , 246.Fa supported_list_len 247is returned in 248.Fa out , 249.Fa outlen . 250.El 251.Pp 252The ALPN select callback 253.Fa cb 254must return one of the following: 255.Bl -tag -width Ds 256.It SSL_TLSEXT_ERR_OK 257ALPN protocol selected. 258.It SSL_TLSEXT_ERR_ALERT_FATAL 259There was no overlap between the client's supplied list and the 260server configuration. 261.It SSL_TLSEXT_ERR_NOACK 262ALPN protocol not selected, e.g., because no ALPN protocols are 263configured for this connection. 264.El 265.Sh SEE ALSO 266.Xr ssl 3 , 267.Xr SSL_CTX_set_tlsext_servername_arg 3 , 268.Xr SSL_CTX_set_tlsext_servername_callback 3 269.Sh STANDARDS 270.Rs 271.%T TLS Application-Layer Protocol Negotiation Extension 272.%R RFC 7301 273.Re 274.Pp 275.Rs 276.%T TLS Next Protocol Negotiation Extension 277.%U https://datatracker.ietf.org/doc/html/draft-agl-tls-nextprotoneg 278.Re 279.Sh HISTORY 280.Fn SSL_select_next_proto 281first appeared in OpenSSL 1.0.1 and has been available since 282.Ox 5.3 . 283.Pp 284.Fn SSL_CTX_set_alpn_protos , 285.Fn SSL_set_alpn_protos , 286.Fn SSL_CTX_set_alpn_select_cb , 287and 288.Fn SSL_get0_alpn_selected 289first appeared in OpenSSL 1.0.2 and have been available since 290.Ox 5.7 . 291.Sh CAVEATS 292The fallback to the first supported protocol in 293.Fn SSL_select_next_proto 294comes from the opportunistic fallback mechanism in the NPN extension. 295This behavior does not make sense for ALPN, 296where missing protocol overlap should result in a handshake failure. 297To avoid accidental selection of a protocol that the server does not 298support, it is recommended to pass the locally configured protocols 299as second pair of protocols in the ALPN callback. 300.Sh BUGS 301The 302.Fa out 303argument of 304.Fn SSL_select_next_proto 305should have been const. 306