| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "SSL_CTX_SET1_CURVES 3SSL" |
| 58 |
.TH SSL_CTX_SET1_CURVES 3SSL 2026-04-07 3.6.2 OpenSSL |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
SSL_CTX_set1_groups, SSL_CTX_set1_groups_list, SSL_set1_groups, |
| 65 |
SSL_set1_groups_list, SSL_get1_groups, SSL_get0_iana_groups, |
| 66 |
SSL_get_shared_group, SSL_get_negotiated_group, SSL_CTX_set1_curves, |
| 67 |
SSL_CTX_set1_curves_list, SSL_set1_curves, SSL_set1_curves_list, |
| 68 |
SSL_get1_curves, SSL_get_shared_curve, SSL_CTX_get0_implemented_groups |
| 69 |
\&\- EC supported curve functions |
| 70 |
.SH SYNOPSIS |
| 71 |
.IX Header "SYNOPSIS" |
| 72 |
.Vb 1 |
| 73 |
\& #include <openssl/ssl.h> |
| 74 |
\& |
| 75 |
\& int SSL_CTX_set1_groups(SSL_CTX *ctx, int *glist, int glistlen); |
| 76 |
\& int SSL_CTX_set1_groups_list(SSL_CTX *ctx, char *list); |
| 77 |
\& |
| 78 |
\& int SSL_set1_groups(SSL *ssl, int *glist, int glistlen); |
| 79 |
\& int SSL_set1_groups_list(SSL *ssl, char *list); |
| 80 |
\& |
| 81 |
\& int SSL_get1_groups(SSL *ssl, int *groups); |
| 82 |
\& int SSL_get0_iana_groups(SSL *ssl, uint16_t **out); |
| 83 |
\& int SSL_get_shared_group(SSL *s, int n); |
| 84 |
\& int SSL_get_negotiated_group(SSL *s); |
| 85 |
\& |
| 86 |
\& int SSL_CTX_set1_curves(SSL_CTX *ctx, int *clist, int clistlen); |
| 87 |
\& int SSL_CTX_set1_curves_list(SSL_CTX *ctx, char *list); |
| 88 |
\& |
| 89 |
\& int SSL_set1_curves(SSL *ssl, int *clist, int clistlen); |
| 90 |
\& int SSL_set1_curves_list(SSL *ssl, char *list); |
| 91 |
\& |
| 92 |
\& int SSL_get1_curves(SSL *ssl, int *curves); |
| 93 |
\& int SSL_get_shared_curve(SSL *s, int n); |
| 94 |
\& |
| 95 |
\& int SSL_CTX_get0_implemented_groups(SSL_CTX *ctx, int all, |
| 96 |
\& STACK_OF(OPENSSL_CSTRING) *names); |
| 97 |
.Ve |
| 98 |
.SH DESCRIPTION |
| 99 |
.IX Header "DESCRIPTION" |
| 100 |
For all of the functions below that set the supported groups there must be at |
| 101 |
least one group in the list. A number of these functions identify groups via a |
| 102 |
unique integer \fBNID\fR value. However, support for some groups may be added by |
| 103 |
external providers. In this case there will be no \fBNID\fR assigned for the group. |
| 104 |
When setting such groups applications should use the "list" form of these |
| 105 |
functions (i.e. \fBSSL_CTX_set1_groups_list()\fR and \fBSSL_set1_groups_list()\fR). |
| 106 |
.PP |
| 107 |
\&\fBSSL_CTX_set1_groups()\fR sets the supported groups for \fBctx\fR to \fBglistlen\fR |
| 108 |
groups in the array \fBglist\fR. The array consist of all \fBNIDs\fR of supported groups. |
| 109 |
The supported groups for \fBTLSv1.3\fR include: |
| 110 |
\&\fBNID_X9_62_prime256v1\fR, |
| 111 |
\&\fBNID_secp384r1\fR, |
| 112 |
\&\fBNID_secp521r1\fR, |
| 113 |
\&\fBNID_X25519\fR, |
| 114 |
\&\fBNID_X448\fR, |
| 115 |
\&\fBNID_brainpoolP256r1tls13\fR, |
| 116 |
\&\fBNID_brainpoolP384r1tls13\fR, |
| 117 |
\&\fBNID_brainpoolP512r1tls13\fR, |
| 118 |
\&\fBNID_ffdhe2048\fR, |
| 119 |
\&\fBNID_ffdhe3072\fR, |
| 120 |
\&\fBNID_ffdhe4096\fR, |
| 121 |
\&\fBNID_ffdhe6144\fR, and |
| 122 |
\&\fBNID_ffdhe8192\fR. |
| 123 |
OpenSSL will use this array in different ways based on the TLS version, and |
| 124 |
whether the groups are used in a client or server. |
| 125 |
.PP |
| 126 |
For a TLS client, the groups are used directly in the supported groups |
| 127 |
extension. The extension's preference order, to be evaluated by the server, is |
| 128 |
determined by the order of the elements in the array. |
| 129 |
.PP |
| 130 |
For a TLS 1.2 server, the groups determine the selected group. If |
| 131 |
\&\fBSSL_OP_SERVER_PREFERENCE\fR is set, the order of the elements in the |
| 132 |
array determines the selected group. Otherwise, the order is ignored and the |
| 133 |
client's order determines the selection. |
| 134 |
.PP |
| 135 |
For a TLS 1.3 server, the groups determine the selected group, but selection is |
| 136 |
more complex. |
| 137 |
A TLS 1.3 client sends both a group list and predicted keyshares for a subset |
| 138 |
of groups. |
| 139 |
A server choosing a group outside the client's predicted subset incurs an extra |
| 140 |
roundtrip. |
| 141 |
However, in some situations, the most preferred group may not be predicted. |
| 142 |
.PP |
| 143 |
When groups are specified via \fBSSL_CTX_set1_groups()\fR as a list of \fBNID\fR |
| 144 |
values, OpenSSL considers all supported groups in \fIclist\fR to be comparable in |
| 145 |
security and prioritises avoiding roundtrips above either client or server |
| 146 |
preference order. |
| 147 |
If an application uses an external provider to extend OpenSSL with, e.g., a |
| 148 |
post-quantum algorithm, this behavior may allow a network attacker to downgrade |
| 149 |
connections to a weaker algorithm. |
| 150 |
It is therefore recommended to use \fBSSL_CTX_set1_groups_list()\fR instead, making |
| 151 |
it possible to specify group tuples as described below. |
| 152 |
.PP |
| 153 |
\&\fBSSL_CTX_set1_groups_list()\fR sets the supported groups for \fBctx\fR to |
| 154 |
string \fIlist\fR. In contrast to \fBSSL_CTX_set1_groups()\fR, the names of the |
| 155 |
groups, rather than their \fBNIDs\fR, are used. |
| 156 |
.PP |
| 157 |
The commands below list the available groups for TLS 1.2 and TLS 1.3, |
| 158 |
respectively: |
| 159 |
.PP |
| 160 |
.Vb 2 |
| 161 |
\& $ openssl list \-tls1_2 \-tls\-groups |
| 162 |
\& $ openssl list \-tls1_3 \-tls\-groups |
| 163 |
.Ve |
| 164 |
.PP |
| 165 |
Each group can be either the \fBNIST\fR name (e.g. \fBP\-256\fR), some other commonly |
| 166 |
used name where applicable (e.g. \fBX25519\fR, \fBffdhe2048\fR) or an OpenSSL OID name |
| 167 |
(e.g. \fBprime256v1\fR). |
| 168 |
Group names are case-insensitive in OpenSSL 3.5 and later. |
| 169 |
The preferred group names are those defined by |
| 170 |
IANA <https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8>. |
| 171 |
.PP |
| 172 |
The \fIlist\fR can be used to define several group tuples of comparable security |
| 173 |
levels, and can specify which predicted key shares should be sent by a client. |
| 174 |
Group tuples are used by OpenSSL TLS servers to decide whether to request a |
| 175 |
stronger keyshare than those predicted by sending a Hello Retry Request |
| 176 |
(\fBHRR\fR) even if some of the predicted groups are supported. |
| 177 |
OpenSSL clients ignore tuple boundaries, and pay attenion only to the overall |
| 178 |
order of \fIlist\fR elements and which groups are selected as predicted keyshares |
| 179 |
as described below. |
| 180 |
.PP |
| 181 |
The specified list elements can optionally be ignored if not implemented |
| 182 |
(listing unknown groups otherwise results in error). |
| 183 |
It is also possible to specify the built-in default set of groups, and to |
| 184 |
explicitly remove a group from that list. |
| 185 |
.PP |
| 186 |
In its simplest legacy form, the string \fIlist\fR is just a colon separated list |
| 187 |
of group names, for example "P\-521:P\-384:P\-256:X25519:ffdhe2048". |
| 188 |
The first group listed will in this case be used as the sole predicted |
| 189 |
\&\fBkey_share\fR sent by a client in a TLSv1.3 \fBClientHello\fR. |
| 190 |
The list should be in order of preference with the most preferred group first. |
| 191 |
.PP |
| 192 |
A more expressive syntax supports definition of group tuples of comparable |
| 193 |
security by separating them from each other with \f(CW\*(C`/\*(C'\fR characters. |
| 194 |
.PP |
| 195 |
The predicted keyshares to be sent by clients can be explicitly specified by |
| 196 |
adding a \f(CW\*(C`*\*(C'\fR prefix to the associated group name. |
| 197 |
These \f(CW\*(C`*\*(C'\fR prefixes are ignored by servers. |
| 198 |
.PP |
| 199 |
If a group name is prefixed with the \f(CW\*(C`?\*(C'\fR character, it will be ignored if an |
| 200 |
implementation is missing. |
| 201 |
Otherwise, listing an unknown group name will cause a failure to parse the |
| 202 |
\&\fIlist\fR. |
| 203 |
Note that whether a group is known or not may depend on the OpenSSL version, |
| 204 |
how OpenSSL was compiled and/or which providers are loaded. |
| 205 |
Make sure you have the correct spelling of the group name and when in doubt |
| 206 |
prefix it with a \f(CW\*(C`?\*(C'\fR to handle configurations in which it might nevertheless |
| 207 |
be unknown. |
| 208 |
.PP |
| 209 |
If a group name is prefixed with the \f(CW\*(C`\-\*(C'\fR character, it will be removed from |
| 210 |
the list of groups specified up to that point. |
| 211 |
It can be added again if specified later. |
| 212 |
Removal of groups that have not been included earlier in the list is silently |
| 213 |
ignored. |
| 214 |
.PP |
| 215 |
The pseudo group name \f(CW\*(C`DEFAULT\*(C'\fR can be used to select the OpenSSL built-in |
| 216 |
default list of groups. |
| 217 |
Prepending one or more groups to \f(CW\*(C`DEFAULT\*(C'\fR using only \f(CW\*(C`:\*(C'\fR separators prepends those |
| 218 |
groups to the built-in default list's first tuple. |
| 219 |
Additional tuples can be prepended by use of the \f(CW\*(C`/\*(C'\fR separator. |
| 220 |
Appending a set of groups to \f(CW\*(C`DEFAULT\*(C'\fR using only \f(CW\*(C`:\*(C'\fR separators appends those |
| 221 |
groups to the built-in default list's last tuple. |
| 222 |
Additional tuples can be appended by use of the \f(CW\*(C`/\*(C'\fR separator. |
| 223 |
.PP |
| 224 |
The \fBDEFAULT\fR list selects \fBX25519MLKEM768\fR as one of the predicted keyshares. |
| 225 |
In rare cases this can lead to failures or timeouts because the resulting |
| 226 |
larger TLS Client Hello message may no longer fit in a single TCP segment and |
| 227 |
firewall software may erroneously disrupt the TLS handshake. |
| 228 |
If this is an issue or concern, prepending \f(CW\*(C`?X25519MLKEM768:\*(C'\fR without a \f(CW\*(C`*\*(C'\fR |
| 229 |
prefix leads to its occurrence in the default list to be ignored as a duplicate, |
| 230 |
and along with that also the keyshare prediction. |
| 231 |
The group will then only be selected by servers that specifically expect it, |
| 232 |
after a Hello Retry Request (HRR). |
| 233 |
Servers that specifically prefer \fBX25519MLKEM768\fR, are much less likely to be |
| 234 |
found behind problematic firewalls. |
| 235 |
.PP |
| 236 |
The following string \fIlist\fR for example defines three tuples when used on the |
| 237 |
server-side, and triggers the generation of three key shares when used on the |
| 238 |
client-side: P\-521:*P\-256/*P\-384/*X25519:P\-384:ffdhe2048. |
| 239 |
.PP |
| 240 |
For a TLS 1.3 client, all the groups in the string \fIlist\fR are added to the |
| 241 |
supported groups extension of a \f(CW\*(C`ClientHello\*(C'\fR, in the order in which they are listed, |
| 242 |
thereby interpreting tuple separators as group separators. The extension's |
| 243 |
preference order, to be evaluated by the server, is determined by the |
| 244 |
order of the elements in the array, see below. |
| 245 |
.PP |
| 246 |
If a group name is preceded by \f(CW\*(C`*\*(C'\fR, a key share will be sent for this group. |
| 247 |
When preceding \f(CW\*(C`DEFAULT\*(C'\fR with \f(CW\*(C`*\*(C'\fR, a key share will be sent for the first group |
| 248 |
of the OpenSSL built-in default list of groups. If no \f(CW\*(C`*\*(C'\fR is used anywhere in the list, |
| 249 |
a single key share for the leftmost valid group is sent. A maximum of 4 key shares |
| 250 |
are supported. Example: "P\-521:*P\-256/*P\-384" will add P\-521, P\-256 and P\-384 to the |
| 251 |
supported groups extension in a \f(CW\*(C`ClientHello\*(C'\fR and will send key shares for P\-256 and P\-384. |
| 252 |
.PP |
| 253 |
For a TLS 1.3 server, the groups in the string \fIlist\fR will be used to determine which group |
| 254 |
is used for the key agreement. The preference order of the group tuples is determined |
| 255 |
by the order of the tuples in the array, and the preference order of the groups within |
| 256 |
a group tuple is determined by the order of the groups in the tuple. Server preference |
| 257 |
can be enforced by setting \fBSSL_OP_SERVER_PREFERENCE\fR using |
| 258 |
\&\fBSSL_set_options\fR (default: client preference). |
| 259 |
.PP |
| 260 |
The server will select the group to be used for a key agreement using the following |
| 261 |
pseudo-code algorithm: |
| 262 |
.PP |
| 263 |
.Vb 12 |
| 264 |
\& FOR each group tuple |
| 265 |
\& IF client preference (= default) |
| 266 |
\& FOR each client key\-share group |
| 267 |
\& IF current key\-share group is also part of current group tuple: SH, return success |
| 268 |
\& FOR each client supported groups |
| 269 |
\& IF current supported group is also part of current group tuple: HRR, return success |
| 270 |
\& ELSE (= server preference = with SSL_OP_SERVER_PREFERENCE option set) |
| 271 |
\& FOR each group in current tuple |
| 272 |
\& IF current group is also part of client key\-share groups: SH, return success |
| 273 |
\& FOR each group in current tuple |
| 274 |
\& IF current group is also part of client supported groups: HRR, return success |
| 275 |
\& return failure |
| 276 |
\& |
| 277 |
\& with : SH: Server hello with current group |
| 278 |
\& HRR: Server retry request with current group |
| 279 |
.Ve |
| 280 |
.PP |
| 281 |
Hence, if a client supports a group in a server group tuple, but does not send a key |
| 282 |
share for this group, a Hello Retry Request (HRR) is triggered, asking the client |
| 283 |
to send a new Hello message with a more preferred keyshare. See examples below. |
| 284 |
.PP |
| 285 |
A group name can optionally be preceded by any of \f(CW\*(C`*\*(C'\fR, \f(CW\*(C`?\*(C'\fR or \f(CW\*(C`\-\*(C'\fR, in any order, with |
| 286 |
the exception that only \f(CW\*(C`*\*(C'\fR is allowed to precede \f(CW\*(C`DEFAULT\*(C'\fR. Separator characters |
| 287 |
\&\f(CW\*(C`:\*(C'\fR and \f(CW\*(C`/\*(C'\fR are only allowed inside the \fIlist\fR and not at the very beginning or end. |
| 288 |
.PP |
| 289 |
\&\fBSSL_set1_groups()\fR and \fBSSL_set1_groups_list()\fR are similar except they set |
| 290 |
supported groups for the SSL structure \fBssl\fR. |
| 291 |
.PP |
| 292 |
\&\fBSSL_get1_groups()\fR returns the set of supported groups sent by a client |
| 293 |
in the supported groups extension. It returns the total number of |
| 294 |
supported groups. The \fBgroups\fR parameter can be \fBNULL\fR to simply |
| 295 |
return the number of groups for memory allocation purposes. The |
| 296 |
\&\fBgroups\fR array is in the form of a set of group NIDs in preference |
| 297 |
order. It can return zero if the client did not send a supported groups |
| 298 |
extension. If a supported group NID is unknown then the value is set to the |
| 299 |
bitwise OR of TLSEXT_nid_unknown (0x1000000) and the id of the group. |
| 300 |
.PP |
| 301 |
\&\fBSSL_get0_iana_groups()\fR retrieves the list of groups sent by the |
| 302 |
client in the supported_groups extension. The \fB*out\fR array of bytes |
| 303 |
is populated with the host-byte-order representation of the uint16_t group |
| 304 |
identifiers, as assigned by IANA. The group list is returned in the same order |
| 305 |
that was received in the ClientHello. The return value is the number of groups, |
| 306 |
not the number of bytes written. |
| 307 |
.PP |
| 308 |
\&\fBSSL_get_shared_group()\fR returns the NID of the shared group \fBn\fR for a |
| 309 |
server-side SSL \fBssl\fR. If \fBn\fR is \-1 then the total number of shared groups is |
| 310 |
returned, which may be zero. Other than for diagnostic purposes, |
| 311 |
most applications will only be interested in the first shared group |
| 312 |
so \fBn\fR is normally set to zero. If the value \fBn\fR is out of range, |
| 313 |
NID_undef is returned. If the NID for the shared group is unknown then the value |
| 314 |
is set to the bitwise OR of TLSEXT_nid_unknown (0x1000000) and the id of the |
| 315 |
group. |
| 316 |
.PP |
| 317 |
\&\fBSSL_get_negotiated_group()\fR returns the NID of the negotiated group used for |
| 318 |
the handshake key exchange process. For TLSv1.3 connections this typically |
| 319 |
reflects the state of the current connection, though in the case of PSK-only |
| 320 |
resumption, the returned value will be from a previous connection. For earlier |
| 321 |
TLS versions, when a session has been resumed, it always reflects the group |
| 322 |
used for key exchange during the initial handshake (otherwise it is from the |
| 323 |
current, non-resumption, connection). This can be called by either client or |
| 324 |
server. If the NID for the shared group is unknown then the value is set to the |
| 325 |
bitwise OR of TLSEXT_nid_unknown (0x1000000) and the id of the group. See also |
| 326 |
\&\fBSSL_get0_group_name\fR\|(3) which returns the name of the negotiated group |
| 327 |
directly and is generally preferred over \fBSSL_get_negotiated_group()\fR. |
| 328 |
.PP |
| 329 |
\&\fBSSL_CTX_get0_implemented_groups()\fR populates a stack with the names of TLS |
| 330 |
groups that are compatible with the TLS version of the \fBctx\fR argument. |
| 331 |
The returned names are references to internal constants and must not be |
| 332 |
modified or freed. When \fBall\fR is nonzero, the returned list includes not |
| 333 |
only the preferred IANA names of the groups, but also any associated aliases. |
| 334 |
If the SSL_CTX is version-flexible, the groups will be those compatible |
| 335 |
with any configured minimum and maximum protocol versions. |
| 336 |
The \fBnames\fR stack should be allocated by the caller and be empty, the |
| 337 |
matching group names are appended to the provided stack. |
| 338 |
The \fB\-tls\-groups\fR and \fB\-all\-tls\-groups\fR options of the |
| 339 |
openssl list command output these lists for either |
| 340 |
TLS 1.2 or TLS 1.3 (by default). |
| 341 |
.PP |
| 342 |
All these functions are implemented as macros. |
| 343 |
.PP |
| 344 |
The curve functions are synonyms for the equivalently named group functions and |
| 345 |
are identical in every respect. They exist because, prior to TLS1.3, there was |
| 346 |
only the concept of supported curves. In TLS1.3 this was renamed to supported |
| 347 |
groups, and extended to include Diffie Hellman groups. The group functions |
| 348 |
should be used in preference. |
| 349 |
.SH NOTES |
| 350 |
.IX Header "NOTES" |
| 351 |
If an application wishes to make use of several of these functions for |
| 352 |
configuration purposes either on a command line or in a file it should |
| 353 |
consider using the SSL_CONF interface instead of manually parsing options. |
| 354 |
.SH "RETURN VALUES" |
| 355 |
.IX Header "RETURN VALUES" |
| 356 |
\&\fBSSL_CTX_set1_groups()\fR, \fBSSL_CTX_set1_groups_list()\fR, \fBSSL_set1_groups()\fR, |
| 357 |
\&\fBSSL_set1_groups_list()\fR, and \fBSSL_CTX_get0_implemented_groups()\fR return 1 for |
| 358 |
success and 0 for failure. |
| 359 |
.PP |
| 360 |
\&\fBSSL_get1_groups()\fR returns the number of groups, which may be zero. |
| 361 |
.PP |
| 362 |
\&\fBSSL_get0_iana_groups()\fR returns the number of (uint16_t) groups, which may be zero. |
| 363 |
.PP |
| 364 |
\&\fBSSL_get_shared_group()\fR returns the NID of shared group \fBn\fR or NID_undef if there |
| 365 |
is no shared group \fBn\fR; or the total number of shared groups if \fBn\fR |
| 366 |
is \-1. |
| 367 |
.PP |
| 368 |
When called on a client \fBssl\fR, \fBSSL_get_shared_group()\fR has no meaning and |
| 369 |
returns \-1. |
| 370 |
.PP |
| 371 |
\&\fBSSL_get_negotiated_group()\fR returns the NID of the negotiated group used for |
| 372 |
key exchange, or NID_undef if there was no negotiated group. |
| 373 |
.SH EXAMPLES |
| 374 |
.IX Header "EXAMPLES" |
| 375 |
Assume the server \fIlist\fR is "P\-521:P\-256/P\-384/X25519:ffdhe2048" and client |
| 376 |
\&\fIlist\fR is "P\-521:*P\-384" when connecting to such a server, meaning that the |
| 377 |
client supports \f(CW\*(C`P\-521\*(C'\fR but does not send a key share for this group to the |
| 378 |
server, and the client supports \f(CW\*(C`P\-384\*(C'\fR including key share for this group. |
| 379 |
With both server and client preference, an HRR will be triggered for \f(CW\*(C`P\-521\*(C'\fR |
| 380 |
despite the availability of a key share for P\-384, which overlaps with a lower |
| 381 |
priority server-side tuple. |
| 382 |
.PP |
| 383 |
As a separate example, consider a server \fIlist\fR "A:B/C:D/E:F". Listed in order |
| 384 |
of highest preference to least, 3 group tuples are created: "A:B", "C:D", and |
| 385 |
"E:F". Here are some examples of a client \fIlist\fR where setting server/client |
| 386 |
preference will not change the outcome: |
| 387 |
.PP |
| 388 |
\&\- "A:D:*F": Both prefer "A", but the server didn't receive a keyshare for the |
| 389 |
most-preferred tuple in which there's at least one group supported by both. |
| 390 |
Therefore, an HRR is triggered for "A". |
| 391 |
.PP |
| 392 |
\&\- "B:*C": Both prefer "B" from the first group tuple "A:B", so an HRR is |
| 393 |
triggered for "B". |
| 394 |
.PP |
| 395 |
\&\- "C:*F": Both prefer "C" from the second group tuple "C:D", so an HRR is |
| 396 |
triggered for "C". |
| 397 |
.PP |
| 398 |
\&\- "C:*D": Even though both prefer "C" over "D", the server will accept |
| 399 |
the key share for "D". Within a tuple, existing keyshares trump preference |
| 400 |
order. |
| 401 |
.PP |
| 402 |
\&\- "*C:*D": The server accepts the "C" key share. |
| 403 |
.PP |
| 404 |
\&\- "F": Even though it is not prepended with a "*", the client will send a key |
| 405 |
share for "F". The server will then accept the key share for "F". |
| 406 |
.PP |
| 407 |
\&\- "*E:C:A": The server prefers "A" from the "A:B" group tuple, so an HRR is |
| 408 |
triggered for "A". |
| 409 |
.PP |
| 410 |
\&\- "*E:B:*A": The server uses the key share for "A". |
| 411 |
.PP |
| 412 |
Here are some examples where setting server/client preference will change the |
| 413 |
result: |
| 414 |
.PP |
| 415 |
\&\- "*D:*C" |
| 416 |
\- Client preference: The server uses the key share for "D". |
| 417 |
\- Server preference: The server uses the key share for "C". |
| 418 |
.PP |
| 419 |
\&\- "B:A:*C" |
| 420 |
\- Client preference: The server triggers an HRR for "B". For the server, |
| 421 |
"A" and "B" are considered comparable in security. But because the client |
| 422 |
prefers "B", the server will trigger an HRR for "B". |
| 423 |
\- Server preference: The server triggers an HRR for "A". |
| 424 |
.SH "SEE ALSO" |
| 425 |
.IX Header "SEE ALSO" |
| 426 |
\&\fBssl\fR\|(7), |
| 427 |
\&\fBSSL_CTX_add_extra_chain_cert\fR\|(3), |
| 428 |
\&\fBSSL_get0_group_name\fR\|(3) |
| 429 |
.SH HISTORY |
| 430 |
.IX Header "HISTORY" |
| 431 |
The curve functions were added in OpenSSL 1.0.2. The equivalent group |
| 432 |
functions were added in OpenSSL 1.1.1. The \fBSSL_get_negotiated_group()\fR function |
| 433 |
was added in OpenSSL 3.0.0. |
| 434 |
.PP |
| 435 |
Support for ignoring unknown groups in \fBSSL_CTX_set1_groups_list()\fR and |
| 436 |
\&\fBSSL_set1_groups_list()\fR was added in OpenSSL 3.3. |
| 437 |
.PP |
| 438 |
Support for \fBML-KEM\fR was added in OpenSSL 3.5. |
| 439 |
.PP |
| 440 |
OpenSSL 3.5 also introduces support for three \fIhybrid\fR ECDH PQ key exchange |
| 441 |
TLS groups: \fBX25519MLKEM768\fR, \fBSecP256r1MLKEM768\fR and |
| 442 |
\&\fBSecP384r1MLKEM1024\fR. |
| 443 |
They offer CPU performance comparable to the associated ECDH group, though at |
| 444 |
the cost of significantly larger key exchange messages. |
| 445 |
The third group, \fBSecP384r1MLKEM1024\fR is substantially more CPU-intensive, |
| 446 |
largely as a result of the high CPU cost of ECDH for the underlying \fBP\-384\fR |
| 447 |
group. |
| 448 |
Also its key exchange messages at close to 1700 bytes are larger than the |
| 449 |
roughly 1200 bytes for the first two groups. |
| 450 |
.PP |
| 451 |
As of OpenSSL 3.5 key exchange group names are case-insensitive. |
| 452 |
.PP |
| 453 |
\&\fBSSL_CTX_get0_implemented_groups\fR was first implemented in OpenSSL 3.5. |
| 454 |
.PP |
| 455 |
Earlier versions of this document described the list as a preference order. |
| 456 |
However, OpenSSL's behavior as a TLS 1.3 server is to consider \fIall\fR |
| 457 |
supported groups as comparable in security. |
| 458 |
.SH COPYRIGHT |
| 459 |
.IX Header "COPYRIGHT" |
| 460 |
Copyright 2013\-2026 The OpenSSL Project Authors. All Rights Reserved. |
| 461 |
.PP |
| 462 |
Licensed under the Apache License 2.0 (the "License"). You may not use |
| 463 |
this file except in compliance with the License. You can obtain a copy |
| 464 |
in the file LICENSE in the source distribution or at |
| 465 |
<https://www.openssl.org/source/license.html>. |