SSL_CTX_set1_curves.pod: Move examples to own section

Also specify whether server or client preference

Reviewed-by: Viktor Dukhovni <viktor@openssl.org>
Reviewed-by: Tim Hudson <tjh@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(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 8fdb16375f22be7455e564a891a1e228d94fc137..2d4ff67c6d6bd63a31311a666057629041d1d377 100755 (executable)
--- 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<list> is "P-521:P-256/P-384/X25519:ffdhe2048".
-If a client I<list> is "P-521:*P-384" when connecting to such a server, meaning that
-the client supports C<P-521> but does not send a key share for this group to the server,
-and the client supports C<P-384> including key share for this group, a HRR will be
-triggered for C<P-521> 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<list>
-"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<list> "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<list>:
-
-- "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<DEFAULT>. 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<list> is "P-521:P-256/P-384/X25519:ffdhe2048" and client
+I<list> is "P-521:*P-384" when connecting to such a server, meaning that the
+client supports C<P-521> but does not send a key share for this group to the
+server, and the client supports C<P-384> including key share for this group.
+With both server and client preference, an HRR will be triggered for C<P-521>
+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<list> "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<list> 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<ssl(7)>,