From: Andrew Dinh Date: Thu, 27 Feb 2025 07:06:47 +0000 (+0700) Subject: SSL_CTX_set1_curves.pod: Move examples to own section X-Git-Tag: openssl-3.5.0-alpha1~30 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=2240da83f91a307d0f8507a60cb33ae4a9f97c04;p=thirdparty%2Fopenssl.git SSL_CTX_set1_curves.pod: Move examples to own section Also specify whether server or client preference Reviewed-by: Viktor Dukhovni Reviewed-by: Tim Hudson Reviewed-by: Matt Caswell Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/26897) --- diff --git a/doc/man3/SSL_CTX_set1_curves.pod b/doc/man3/SSL_CTX_set1_curves.pod index 8fdb16375f2..2d4ff67c6d6 100755 --- a/doc/man3/SSL_CTX_set1_curves.pod +++ b/doc/man3/SSL_CTX_set1_curves.pod @@ -166,40 +166,7 @@ pseudo-code algorithm: Hence, if a client supports a group in a server group tuple, but does not send a key share for this group, a Hello Retry Request (HRR) is triggered, asking the client -to send a new Hello message with a more preferred keyshare. For example: -Assume the server I is "P-521:P-256/P-384/X25519:ffdhe2048". -If a client I is "P-521:*P-384" when connecting to such a server, meaning that -the client supports C but does not send a key share for this group to the server, -and the client supports C including key share for this group, a HRR will be -triggered for C despite the availability of a key share for P-384, which -overlaps with a lower priority server-side tuple. - -For example, consider the same server but different client with I -"P-521:P-384:*ffdhe2048". When the client attempts connecting to the server, -only a keyshare for ffdhe2048 will be sent. But because P-521 and P-384 are -supported by the client, an HRR will be triggered for P-521 (preferred by the -server). - -As another example, consider a server I "A:B/C:D/E:F". Listed in order of -highest preference to least, 3 group tuples are created: "A:B", "C:D", and "E:F". -Some example scenarios for the client I: - -- "A:D:*F": The server prefers "A" but did not receive a key share for "A", so - an HRR is triggered for "A". - -- "B:*C": The server prefers "B" from the first group tuple "A:B", so an HRR is - triggered for "B". - -- "C:*F": The server prefers "C" from the second group tuple "C:D", so an HRR is - triggered for "C". - -- "C:*D": Even though the server prefers "C" over "D", the server will accept - the key share for "D". Within a tuple, existing keyshares trump preference - order. - -- "*C:*D": The server accepts the "C" key share. - -- "F": The server accepts "F" key share. +to send a new Hello message with a more preferred keyshare. See examples below. A group name can optionally be preceded by any of C<*>, C or C<->, in any order, with the exception that only C<*> is allowed to precede C. Separator characters @@ -290,6 +257,58 @@ returns -1. SSL_get_negotiated_group() returns the NID of the negotiated group used for key exchange, or NID_undef if there was no negotiated group. +=head1 EXAMPLES + +Assume the server I is "P-521:P-256/P-384/X25519:ffdhe2048" and client +I is "P-521:*P-384" when connecting to such a server, meaning that the +client supports C but does not send a key share for this group to the +server, and the client supports C including key share for this group. +With both server and client preference, an HRR will be triggered for C +despite the availability of a key share for P-384, which overlaps with a lower +priority server-side tuple. + +As a separate example, consider a server I "A:B/C:D/E:F". Listed in order +of highest preference to least, 3 group tuples are created: "A:B", "C:D", and +"E:F". Here are some examples of a client I where setting server/client +preference will not change the outcome: + +- "A:D:*F": Both prefer "A", but the server didn't receive a keyshare for the +most-preferred tuple in which there's at least one group supported by both. +Therefore, an HRR is triggered for "A". + +- "B:*C": Both prefer "B" from the first group tuple "A:B", so an HRR is +triggered for "B". + +- "C:*F": Both prefer "C" from the second group tuple "C:D", so an HRR is +triggered for "C". + +- "C:*D": Even though both prefer "C" over "D", the server will accept +the key share for "D". Within a tuple, existing keyshares trump preference +order. + +- "*C:*D": The server accepts the "C" key share. + +- "F": Even though it is not prepended with a "*", the client will send a key +share for "F". The server will then accept the key share for "F". + +- "*E:C:A": The server prefers "A" from the "A:B" group tuple, so an HRR is +triggered for "A". + +- "*E:B:*A": The server uses the key share for "A". + +Here are some examples where setting server/client preference will change the +result: + +- "*D:*C" + - Client preference: The server uses the key share for "D". + - Server preference: The server uses the key share for "C". + +- "B:A:*C" + - Client preference: The server triggers an HRR for "B". For the server, +"A" and "B" are considered comparable in security. But because the client +prefers "B", the server will trigger an HRR for "B". + - Server preference: The server triggers an HRR for "A". + =head1 SEE ALSO L,