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 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=head1 DESCRIPTION 37 38For all of the functions below that set the supported groups there must be at 39least one group in the list. A number of these functions identify groups via a 40unique integer NID value. However, support for some groups may be added by 41external providers. In this case there will be no NID assigned for the group. 42When setting such groups applications should use the "list" form of these 43functions (i.e. SSL_CTX_set1_groups_list() and SSL_set1_groups_list). 44 45SSL_CTX_set1_groups() sets the supported groups for B<ctx> to B<glistlen> 46groups in the array B<glist>. The array consist of all NIDs of supported groups. 47Currently supported groups for B<TLSv1.3> are B<NID_X9_62_prime256v1>, 48B<NID_secp384r1>, B<NID_secp521r1>, B<NID_X25519>, B<NID_X448>, 49B<NID_brainpoolP256r1tls13>, B<NID_brainpoolP384r1tls13>, 50B<NID_brainpoolP512r1tls13>, B<NID_ffdhe2048>, B<NID_ffdhe3072>, 51B<NID_ffdhe4096>, B<NID_ffdhe6144> and B<NID_ffdhe8192>. 52OpenSSL will use this array in different ways depending on TLS role and version: 53 54=over 4 55 56=item For a TLS client, the groups are used directly in the supported groups 57extension. The extension's preference order, to be evaluated by the server, is 58determined by the order of the elements in the array. 59 60=item For a TLS 1.2 server, the groups determine the selected group. If 61B<SSL_OP_CIPHER_SERVER_PREFERENCE> is set, the order of the elements in the 62array determines the selected group. Otherwise, the order is ignored and the 63client's order determines the selection. 64 65=item For a TLS 1.3 server, the groups determine the selected group, but 66selection is more complex. A TLS 1.3 client sends both a group list as well as a 67predicted subset of groups. Choosing a group outside the predicted subset incurs 68an extra roundtrip. However, in some situations, the most preferred group may 69not be predicted. OpenSSL considers all supported groups to be comparable in 70security and prioritizes avoiding roundtrips above either client or server 71preference order. If an application uses an external provider to extend OpenSSL 72with, e.g., a post-quantum algorithm, this behavior may allow a network attacker 73to downgrade connections to a weaker algorithm. 74 75=back 76 77SSL_CTX_set1_groups_list() sets the supported groups for B<ctx> to 78string B<list>. The string is a colon separated list of group names, for example 79"P-521:P-384:P-256:X25519:ffdhe2048". The groups are used as in 80SSL_CTX_set1_groups(), described above. Currently supported groups for 81B<TLSv1.3> are B<P-256>, B<P-384>, B<P-521>, B<X25519>, B<X448>, 82B<brainpoolP256r1tls13>, B<brainpoolP384r1tls13>, B<brainpoolP512r1tls13>, 83B<ffdhe2048>, B<ffdhe3072>, B<ffdhe4096>, B<ffdhe6144> and B<ffdhe8192>. Support 84for other groups may be added by external providers, however note the discussion 85on TLS 1.3 selection criteria above. If a group name is preceded with the C<?> 86character, it will be ignored if an implementation is missing. 87 88SSL_set1_groups() and SSL_set1_groups_list() are similar except they set 89supported groups for the SSL structure B<ssl>. 90 91SSL_get1_groups() returns the set of supported groups sent by a client 92in the supported groups extension. It returns the total number of 93supported groups. The B<groups> parameter can be B<NULL> to simply 94return the number of groups for memory allocation purposes. The 95B<groups> array is in the form of a set of group NIDs in preference 96order. It can return zero if the client did not send a supported groups 97extension. If a supported group NID is unknown then the value is set to the 98bitwise OR of TLSEXT_nid_unknown (0x1000000) and the id of the group. 99 100SSL_get0_iana_groups() retrieves the list of groups sent by the 101client in the supported_groups extension. The B<*out> array of bytes 102is populated with the host-byte-order representation of the uint16_t group 103identifiers, as assigned by IANA. The group list is returned in the same order 104that was received in the ClientHello. The return value is the number of groups, 105not the number of bytes written. 106 107SSL_get_shared_group() returns the NID of the shared group B<n> for a 108server-side SSL B<ssl>. If B<n> is -1 then the total number of shared groups is 109returned, which may be zero. Other than for diagnostic purposes, 110most applications will only be interested in the first shared group 111so B<n> is normally set to zero. If the value B<n> is out of range, 112NID_undef is returned. If the NID for the shared group is unknown then the value 113is set to the bitwise OR of TLSEXT_nid_unknown (0x1000000) and the id of the 114group. 115 116SSL_get_negotiated_group() returns the NID of the negotiated group used for 117the handshake key exchange process. For TLSv1.3 connections this typically 118reflects the state of the current connection, though in the case of PSK-only 119resumption, the returned value will be from a previous connection. For earlier 120TLS versions, when a session has been resumed, it always reflects the group 121used for key exchange during the initial handshake (otherwise it is from the 122current, non-resumption, connection). This can be called by either client or 123server. If the NID for the shared group is unknown then the value is set to the 124bitwise OR of TLSEXT_nid_unknown (0x1000000) and the id of the group. 125 126All these functions are implemented as macros. 127 128The curve functions are synonyms for the equivalently named group functions and 129are identical in every respect. They exist because, prior to TLS1.3, there was 130only the concept of supported curves. In TLS1.3 this was renamed to supported 131groups, and extended to include Diffie Hellman groups. The group functions 132should be used in preference. 133 134=head1 NOTES 135 136If an application wishes to make use of several of these functions for 137configuration purposes either on a command line or in a file it should 138consider using the SSL_CONF interface instead of manually parsing options. 139 140=head1 RETURN VALUES 141 142SSL_CTX_set1_groups(), SSL_CTX_set1_groups_list(), SSL_set1_groups() and 143SSL_set1_groups_list(), return 1 for success and 0 for failure. 144 145SSL_get1_groups() returns the number of groups, which may be zero. 146 147SSL_get0_iana_groups() returns the number of (uint16_t) groups, which may be zero. 148 149SSL_get_shared_group() returns the NID of shared group B<n> or NID_undef if there 150is no shared group B<n>; or the total number of shared groups if B<n> 151is -1. 152 153When called on a client B<ssl>, SSL_get_shared_group() has no meaning and 154returns -1. 155 156SSL_get_negotiated_group() returns the NID of the negotiated group used for 157key exchange, or NID_undef if there was no negotiated group. 158 159=head1 SEE ALSO 160 161L<ssl(7)>, 162L<SSL_CTX_add_extra_chain_cert(3)> 163 164=head1 HISTORY 165 166The curve functions were added in OpenSSL 1.0.2. The equivalent group 167functions were added in OpenSSL 1.1.1. The SSL_get_negotiated_group() function 168was added in OpenSSL 3.0.0. 169 170Support for ignoring unknown groups in SSL_CTX_set1_groups_list() and 171SSL_set1_groups_list() was added in OpenSSL 3.3. 172 173Earlier versions of this document described the list as a preference order. 174However, OpenSSL's behavior as a TLS 1.3 server is to consider I<all> 175supported groups as comparable in security. 176 177=head1 COPYRIGHT 178 179Copyright 2013-2024 The OpenSSL Project Authors. All Rights Reserved. 180 181Licensed under the Apache License 2.0 (the "License"). You may not use 182this file except in compliance with the License. You can obtain a copy 183in the file LICENSE in the source distribution or at 184L<https://www.openssl.org/source/license.html>. 185 186=cut 187
