You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
79 lines
4.0 KiB
79 lines
4.0 KiB
From 8e81c57adbbf703dfb63955f65599765fdacc741 Mon Sep 17 00:00:00 2001
|
|
From: Matt Caswell <matt@openssl.org>
|
|
Date: Fri, 31 May 2024 11:46:38 +0100
|
|
Subject: [PATCH 04/10] Clarify the SSL_select_next_proto() documentation
|
|
|
|
We clarify the input preconditions and the expected behaviour in the event
|
|
of no overlap.
|
|
|
|
Follow on from CVE-2024-5535
|
|
|
|
Reviewed-by: Neil Horman <nhorman@openssl.org>
|
|
Reviewed-by: Tomas Mraz <tomas@openssl.org>
|
|
(Merged from https://github.com/openssl/openssl/pull/24717)
|
|
---
|
|
doc/man3/SSL_CTX_set_alpn_select_cb.pod | 26 +++++++++++++++++--------
|
|
1 file changed, 18 insertions(+), 8 deletions(-)
|
|
|
|
diff --git a/doc/man3/SSL_CTX_set_alpn_select_cb.pod b/doc/man3/SSL_CTX_set_alpn_select_cb.pod
|
|
index 05fee2fbec..79e1a252f6 100644
|
|
--- a/doc/man3/SSL_CTX_set_alpn_select_cb.pod
|
|
+++ b/doc/man3/SSL_CTX_set_alpn_select_cb.pod
|
|
@@ -52,7 +52,8 @@ SSL_select_next_proto, SSL_get0_alpn_selected, SSL_get0_next_proto_negotiated
|
|
SSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() are used by the client to
|
|
set the list of protocols available to be negotiated. The B<protos> must be in
|
|
protocol-list format, described below. The length of B<protos> is specified in
|
|
-B<protos_len>.
|
|
+B<protos_len>. Setting B<protos_len> to 0 clears any existing list of ALPN
|
|
+protocols and no ALPN extension will be sent to the server.
|
|
|
|
SSL_CTX_set_alpn_select_cb() sets the application callback B<cb> used by a
|
|
server to select which protocol to use for the incoming connection. When B<cb>
|
|
@@ -73,9 +74,16 @@ B<server_len> and B<client>, B<client_len> must be in the protocol-list format
|
|
described below. The first item in the B<server>, B<server_len> list that
|
|
matches an item in the B<client>, B<client_len> list is selected, and returned
|
|
in B<out>, B<outlen>. The B<out> value will point into either B<server> or
|
|
-B<client>, so it should be copied immediately. If no match is found, the first
|
|
-item in B<client>, B<client_len> is returned in B<out>, B<outlen>. This
|
|
-function can also be used in the NPN callback.
|
|
+B<client>, so it should be copied immediately. The client list must include at
|
|
+least one valid (nonempty) protocol entry in the list.
|
|
+
|
|
+The SSL_select_next_proto() helper function can be useful from either the ALPN
|
|
+callback or the NPN callback (described below). If no match is found, the first
|
|
+item in B<client>, B<client_len> is returned in B<out>, B<outlen> and
|
|
+B<OPENSSL_NPN_NO_OVERLAP> is returned. This can be useful when implementating
|
|
+the NPN callback. In the ALPN case, the value returned in B<out> and B<outlen>
|
|
+must be ignored if B<OPENSSL_NPN_NO_OVERLAP> has been returned from
|
|
+SSL_select_next_proto().
|
|
|
|
SSL_CTX_set_next_proto_select_cb() sets a callback B<cb> that is called when a
|
|
client needs to select a protocol from the server's provided list, and a
|
|
@@ -85,9 +93,10 @@ must be set to point to the selected protocol (which may be within B<in>).
|
|
The length of the protocol name must be written into B<outlen>. The
|
|
server's advertised protocols are provided in B<in> and B<inlen>. The
|
|
callback can assume that B<in> is syntactically valid. The client must
|
|
-select a protocol. It is fatal to the connection if this callback returns
|
|
-a value other than B<SSL_TLSEXT_ERR_OK>. The B<arg> parameter is the pointer
|
|
-set via SSL_CTX_set_next_proto_select_cb().
|
|
+select a protocol (although it may be an empty, zero length protocol). It is
|
|
+fatal to the connection if this callback returns a value other than
|
|
+B<SSL_TLSEXT_ERR_OK> or if the zero length protocol is selected. The B<arg>
|
|
+parameter is the pointer set via SSL_CTX_set_next_proto_select_cb().
|
|
|
|
SSL_CTX_set_next_protos_advertised_cb() sets a callback B<cb> that is called
|
|
when a TLS server needs a list of supported protocols for Next Protocol
|
|
@@ -154,7 +163,8 @@ A match was found and is returned in B<out>, B<outlen>.
|
|
=item OPENSSL_NPN_NO_OVERLAP
|
|
|
|
No match was found. The first item in B<client>, B<client_len> is returned in
|
|
-B<out>, B<outlen>.
|
|
+B<out>, B<outlen> (or B<NULL> and 0 in the case where the first entry in
|
|
+B<client> is invalid).
|
|
|
|
=back
|
|
|
|
--
|
|
2.46.0
|
|
|