public/openssl
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

SSL_CTX_set1_curves.pod: Move examples to own section

Browse source 
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)
This commit is contained in:
Andrew Dinh 2025-02-27 14:06:47 +07:00 • committed by Tomas Mraz
parent 493e067f90
commit 2240da83f9
1 changed files with 53 additions and 34 deletions
Download patch file Download diff file Expand all files Collapse all files

87
doc/man3/SSL_CTX_set1_curves.pod
View file

@ -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)>,