1=pod 2 3=head1 NAME 4 5SSL_CTX_set1_groups, SSL_CTX_set1_groups_list, SSL_set1_groups, 6SSL_set1_groups_list, SSL_get1_groups, SSL_get0_iana_groups, 7SSL_get_shared_group, SSL_get_negotiated_group, SSL_CTX_set1_curves, 8SSL_CTX_set1_curves_list, SSL_set1_curves, SSL_set1_curves_list, 9SSL_get1_curves, SSL_get_shared_curve, SSL_CTX_get0_implemented_groups 10- EC supported curve functions 11 12=head1 SYNOPSIS 13 14 #include <openssl/ssl.h> 15 16 int SSL_CTX_set1_groups(SSL_CTX *ctx, int *glist, int glistlen); 17 int SSL_CTX_set1_groups_list(SSL_CTX *ctx, char *list); 18 19 int SSL_set1_groups(SSL *ssl, int *glist, int glistlen); 20 int SSL_set1_groups_list(SSL *ssl, char *list); 21 22 int SSL_get1_groups(SSL *ssl, int *groups); 23 int SSL_get0_iana_groups(SSL *ssl, uint16_t **out); 24 int SSL_get_shared_group(SSL *s, int n); 25 int SSL_get_negotiated_group(SSL *s); 26 27 int SSL_CTX_set1_curves(SSL_CTX *ctx, int *clist, int clistlen); 28 int SSL_CTX_set1_curves_list(SSL_CTX *ctx, char *list); 29 30 int SSL_set1_curves(SSL *ssl, int *clist, int clistlen); 31 int SSL_set1_curves_list(SSL *ssl, char *list); 32 33 int SSL_get1_curves(SSL *ssl, int *curves); 34 int SSL_get_shared_curve(SSL *s, int n); 35 36 int SSL_CTX_get0_implemented_groups(SSL_CTX *ctx, int all, 37 STACK_OF(OPENSSL_CSTRING) *names); 38 39=head1 DESCRIPTION 40 41For all of the functions below that set the supported groups there must be at 42least one group in the list. A number of these functions identify groups via a 43unique integer NID value. However, support for some groups may be added by 44external providers. In this case there will be no NID assigned for the group. 45When setting such groups applications should use the "list" form of these 46functions (i.e. SSL_CTX_set1_groups_list() and SSL_set1_groups_list()). 47 48SSL_CTX_set1_groups() sets the supported groups for B<ctx> to B<glistlen> 49groups in the array B<glist>. The array consist of all NIDs of supported groups. 50The supported groups for B<TLSv1.3> include: 51B<NID_X9_62_prime256v1>, 52B<NID_secp384r1>, 53B<NID_secp521r1>, 54B<NID_X25519>, 55B<NID_X448>, 56B<NID_brainpoolP256r1tls13>, 57B<NID_brainpoolP384r1tls13>, 58B<NID_brainpoolP512r1tls13>, 59B<NID_ffdhe2048>, 60B<NID_ffdhe3072>, 61B<NID_ffdhe4096>, 62B<NID_ffdhe6144>, and 63B<NID_ffdhe8192>. 64OpenSSL will use this array in different ways based on the TLS version, and 65whether the groups are used in a client or server. 66 67For a TLS client, the groups are used directly in the supported groups 68extension. The extension's preference order, to be evaluated by the server, is 69determined by the order of the elements in the array. 70 71For a TLS 1.2 server, the groups determine the selected group. If 72B<SSL_OP_CIPHER_SERVER_PREFERENCE> is set, the order of the elements in the 73array determines the selected group. Otherwise, the order is ignored and the 74client's order determines the selection. 75 76For a TLS 1.3 server, the groups determine the selected group, but 77selection is more complex. A TLS 1.3 client sends both a group list as well as a 78predicted subset of groups. Choosing a group outside the predicted subset incurs 79an extra roundtrip. However, in some situations, the most preferred group may 80not be predicted. OpenSSL considers all supported groups in I<clist> to be comparable 81in security and prioritizes avoiding roundtrips above either client or server 82preference order. If an application uses an external provider to extend OpenSSL 83with, e.g., a post-quantum algorithm, this behavior may allow a network attacker 84to downgrade connections to a weaker algorithm. It is therefore recommended 85to use SSL_CTX_set1_groups_list() with the ability to specify group tuples. 86 87SSL_CTX_set1_groups_list() sets the supported groups for B<ctx> to 88string I<list>. In contrast to SSL_CTX_set1_groups(), the names of the 89groups, rather than their NIDs, are used. 90 91The commands below list the available groups for TLS 1.2 and TLS 1.3, 92respectively: 93 94 $ openssl list -tls1_2 -tls-groups 95 $ openssl list -tls1_3 -tls-groups 96 97Each group can be either the B<NIST> name (e.g. B<P-256>), some other commonly 98used name where applicable (e.g. B<X25519>, B<ffdhe2048>) or an OpenSSL OID name 99(e.g. B<prime256v1>). 100Group names are case-insensitive in OpenSSL 3.5 and later. 101The preferred group names are those defined by 102L<IANA|https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8>. 103 104The I<list> can be used to define several group tuples of comparable security 105levels, and can specify which key shares should be sent by a client. 106The specified list elements can optionally be ignored, if not implemented 107(listing unknown groups otherwise results in error). 108It is also possible to specify the built-in default set of groups, and to explicitly 109remove a group from that list. 110 111In its simplest form, the string I<list> is just a colon separated list 112of group names, for example "P-521:P-384:P-256:X25519:ffdhe2048". The first 113group listed will also be used for the B<key_share> sent by a client in a 114TLSv1.3 B<ClientHello>. For servers note the discussion above. The list should 115be in order of preference with the most preferred group first. 116 117Group tuples of comparable security are defined by separating them from each 118other by a tuple separator C</>. Keyshares to be sent by a client are specified 119by prepending a C<*> to the group name, while any C<*> will be ignored by a 120server. The following string I<list> for example defines three tuples when 121used on the server-side, and triggers the generation of three key shares 122when used on the client-side: P-521:*P-256/*P-384/*X25519:P-384:ffdhe2048. 123 124If a group name is preceded with the C<?> character, it will be ignored if an 125implementation is missing. If a group name is preceded with the C<-> character, it 126will be removed from the list of groups if present (including not sending a 127key share for this group), ignored otherwise. The pseudo group name 128C<DEFAULT> can be used to select the OpenSSL built-in default list of groups. 129 130For a TLS 1.3 client, all the groups in the string I<list> are added to the 131supported groups extension of a C<ClientHello>, in the order in which they are listed, 132thereby interpreting tuple separators as group separators. The extension's 133preference order, to be evaluated by the server, is determined by the 134order of the elements in the array, see below. 135 136If a group name is preceded by C<*>, a key share will be sent for this group. 137When preceding C<DEFAULT> with C<*>, a key share will be sent for the first group 138of the OpenSSL built-in default list of groups. If no C<*> is used anywhere in the list, 139a single key share for the leftmost valid group is sent. A maximum of 4 key shares 140are supported. Example: "P-521:*P-256/*P-384" will add P-521, P-256 and P-384 to the 141supported groups extension in a C<ClientHello> and will send key shares for P-256 and P-384. 142 143For a TLS 1.3 server, the groups in the string I<list> will be used to determine which group 144is used for the key agreement. The preference order of the group tuples is determined 145by the order of the tuples in the array, and the preference order of the groups within 146a group tuple is determined by the order of the groups in the tuple. Server preference 147can be enforced by setting B<SSL_OP_CIPHER_SERVER_PREFERENCE> using 148B<SSL_set_options> (default: client preference). 149 150The server will select the group to be used for a key agreement using the following 151pseudo-code algorithm: 152 153 FOR each group tuple 154 IF client preference (= default) 155 FOR each client key-share group 156 IF current key-share group is also part of current group tuple: SH, return success 157 FOR each client supported groups 158 IF current supported group is also part of current group tuple: HRR, return success 159 ELSE (= server preference = with SSL_OP_CIPHER_SERVER_PREFERENCE option set) 160 FOR each group in current tuple 161 IF current group is also part of client key-share groups: SH, return success 162 FOR each group in current tuple 163 IF current group is also part of client supported groups: HRR, return success 164 return failure 165 166 with : SH: Server hello with current group 167 HRR: Server retry request with current group 168 169Hence, if a client supports a group in a server group tuple, but does not send a key 170share for this group, a Hello Retry Request (HRR) is triggered, asking the client 171to send a new Hello message with a more preferred keyshare. See examples below. 172 173A group name can optionally be preceded by any of C<*>, C<?> or C<->, in any order, with 174the exception that only C<*> is allowed to precede C<DEFAULT>. Separator characters 175C<:> and C</> are only allowed inside the I<list> and not at the very beginning or end. 176 177SSL_set1_groups() and SSL_set1_groups_list() are similar except they set 178supported groups for the SSL structure B<ssl>. 179 180SSL_get1_groups() returns the set of supported groups sent by a client 181in the supported groups extension. It returns the total number of 182supported groups. The B<groups> parameter can be B<NULL> to simply 183return the number of groups for memory allocation purposes. The 184B<groups> array is in the form of a set of group NIDs in preference 185order. It can return zero if the client did not send a supported groups 186extension. If a supported group NID is unknown then the value is set to the 187bitwise OR of TLSEXT_nid_unknown (0x1000000) and the id of the group. 188 189SSL_get0_iana_groups() retrieves the list of groups sent by the 190client in the supported_groups extension. The B<*out> array of bytes 191is populated with the host-byte-order representation of the uint16_t group 192identifiers, as assigned by IANA. The group list is returned in the same order 193that was received in the ClientHello. The return value is the number of groups, 194not the number of bytes written. 195 196SSL_get_shared_group() returns the NID of the shared group B<n> for a 197server-side SSL B<ssl>. If B<n> is -1 then the total number of shared groups is 198returned, which may be zero. Other than for diagnostic purposes, 199most applications will only be interested in the first shared group 200so B<n> is normally set to zero. If the value B<n> is out of range, 201NID_undef is returned. If the NID for the shared group is unknown then the value 202is set to the bitwise OR of TLSEXT_nid_unknown (0x1000000) and the id of the 203group. 204 205SSL_get_negotiated_group() returns the NID of the negotiated group used for 206the handshake key exchange process. For TLSv1.3 connections this typically 207reflects the state of the current connection, though in the case of PSK-only 208resumption, the returned value will be from a previous connection. For earlier 209TLS versions, when a session has been resumed, it always reflects the group 210used for key exchange during the initial handshake (otherwise it is from the 211current, non-resumption, connection). This can be called by either client or 212server. If the NID for the shared group is unknown then the value is set to the 213bitwise OR of TLSEXT_nid_unknown (0x1000000) and the id of the group. See also 214L<SSL_get0_group_name(3)> which returns the name of the negotiated group 215directly and is generally preferred over SSL_get_negotiated_group(). 216 217SSL_CTX_get0_implemented_groups() populates a stack with the names of TLS 218groups that are compatible with the TLS version of the B<ctx> argument. 219The returned names are references to internal constants and must not be 220modified or freed. When B<all> is nonzero, the returned list includes not 221only the preferred IANA names of the groups, but also any associated aliases. 222If the SSL_CTX is version-flexible, the groups will be those compatible 223with any configured minimum and maximum protocol versions. 224The B<names> stack should be allocated by the caller and be empty, the 225matching group names are appended to the provided stack. 226The B<-tls-groups> and B<-all-tls-groups> options of the 227L<openssl list|openssl-list(1)> command output these lists for either 228TLS 1.2 or TLS 1.3 (by default). 229 230All these functions are implemented as macros. 231 232The curve functions are synonyms for the equivalently named group functions and 233are identical in every respect. They exist because, prior to TLS1.3, there was 234only the concept of supported curves. In TLS1.3 this was renamed to supported 235groups, and extended to include Diffie Hellman groups. The group functions 236should be used in preference. 237 238=head1 NOTES 239 240If an application wishes to make use of several of these functions for 241configuration purposes either on a command line or in a file it should 242consider using the SSL_CONF interface instead of manually parsing options. 243 244=head1 RETURN VALUES 245 246SSL_CTX_set1_groups(), SSL_CTX_set1_groups_list(), SSL_set1_groups(), 247SSL_set1_groups_list(), and SSL_CTX_get0_implemented_groups() return 1 for 248success and 0 for failure. 249 250SSL_get1_groups() returns the number of groups, which may be zero. 251 252SSL_get0_iana_groups() returns the number of (uint16_t) groups, which may be zero. 253 254SSL_get_shared_group() returns the NID of shared group B<n> or NID_undef if there 255is no shared group B<n>; or the total number of shared groups if B<n> 256is -1. 257 258When called on a client B<ssl>, SSL_get_shared_group() has no meaning and 259returns -1. 260 261SSL_get_negotiated_group() returns the NID of the negotiated group used for 262key exchange, or NID_undef if there was no negotiated group. 263 264=head1 EXAMPLES 265 266Assume the server I<list> is "P-521:P-256/P-384/X25519:ffdhe2048" and client 267I<list> is "P-521:*P-384" when connecting to such a server, meaning that the 268client supports C<P-521> but does not send a key share for this group to the 269server, and the client supports C<P-384> including key share for this group. 270With both server and client preference, an HRR will be triggered for C<P-521> 271despite the availability of a key share for P-384, which overlaps with a lower 272priority server-side tuple. 273 274As a separate example, consider a server I<list> "A:B/C:D/E:F". Listed in order 275of highest preference to least, 3 group tuples are created: "A:B", "C:D", and 276"E:F". Here are some examples of a client I<list> where setting server/client 277preference will not change the outcome: 278 279- "A:D:*F": Both prefer "A", but the server didn't receive a keyshare for the 280most-preferred tuple in which there's at least one group supported by both. 281Therefore, an HRR is triggered for "A". 282 283- "B:*C": Both prefer "B" from the first group tuple "A:B", so an HRR is 284triggered for "B". 285 286- "C:*F": Both prefer "C" from the second group tuple "C:D", so an HRR is 287triggered for "C". 288 289- "C:*D": Even though both prefer "C" over "D", the server will accept 290the key share for "D". Within a tuple, existing keyshares trump preference 291order. 292 293- "*C:*D": The server accepts the "C" key share. 294 295- "F": Even though it is not prepended with a "*", the client will send a key 296share for "F". The server will then accept the key share for "F". 297 298- "*E:C:A": The server prefers "A" from the "A:B" group tuple, so an HRR is 299triggered for "A". 300 301- "*E:B:*A": The server uses the key share for "A". 302 303Here are some examples where setting server/client preference will change the 304result: 305 306- "*D:*C" 307 - Client preference: The server uses the key share for "D". 308 - Server preference: The server uses the key share for "C". 309 310- "B:A:*C" 311 - Client preference: The server triggers an HRR for "B". For the server, 312"A" and "B" are considered comparable in security. But because the client 313prefers "B", the server will trigger an HRR for "B". 314 - Server preference: The server triggers an HRR for "A". 315 316=head1 SEE ALSO 317 318L<ssl(7)>, 319L<SSL_CTX_add_extra_chain_cert(3)>, 320L<SSL_get0_group_name(3)> 321 322=head1 HISTORY 323 324The curve functions were added in OpenSSL 1.0.2. The equivalent group 325functions were added in OpenSSL 1.1.1. The SSL_get_negotiated_group() function 326was added in OpenSSL 3.0.0. 327 328Support for ignoring unknown groups in SSL_CTX_set1_groups_list() and 329SSL_set1_groups_list() was added in OpenSSL 3.3. 330 331Support for B<ML-KEM> was added in OpenSSL 3.5. 332 333OpenSSL 3.5 also introduces support for three I<hybrid> ECDH PQ key exchange 334TLS groups: B<X25519MLKEM768>, B<SecP256r1MLKEM768> and 335B<SecP384r1MLKEM1024>. 336They offer CPU performance comparable to the associated ECDH group, though at 337the cost of significantly larger key exchange messages. 338The third group, B<SecP384r1MLKEM1024> is substantially more CPU-intensive, 339largely as a result of the high CPU cost of ECDH for the underlying B<P-384> 340group. 341Also its key exchange messages at close to 1700 bytes are larger than the 342roughly 1200 bytes for the first two groups. 343 344As of OpenSSL 3.5 key exchange group names are case-insensitive. 345 346B<SSL_CTX_get0_implemented_groups> was first implemented in OpenSSL 3.5. 347 348Earlier versions of this document described the list as a preference order. 349However, OpenSSL's behavior as a TLS 1.3 server is to consider I<all> 350supported groups as comparable in security. 351 352=head1 COPYRIGHT 353 354Copyright 2013-2025 The OpenSSL Project Authors. All Rights Reserved. 355 356Licensed under the Apache License 2.0 (the "License"). You may not use 357this file except in compliance with the License. You can obtain a copy 358in the file LICENSE in the source distribution or at 359L<https://www.openssl.org/source/license.html>. 360 361=cut 362