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_get_shared_group, 7SSL_get_negotiated_group, SSL_CTX_set1_curves, SSL_CTX_set1_curves_list, 8SSL_set1_curves, SSL_set1_curves_list, SSL_get1_curves, SSL_get_shared_curve 9- EC supported curve functions 10 11=head1 SYNOPSIS 12 13 #include <openssl/ssl.h> 14 15 int SSL_CTX_set1_groups(SSL_CTX *ctx, int *glist, int glistlen); 16 int SSL_CTX_set1_groups_list(SSL_CTX *ctx, char *list); 17 18 int SSL_set1_groups(SSL *ssl, int *glist, int glistlen); 19 int SSL_set1_groups_list(SSL *ssl, char *list); 20 21 int SSL_get1_groups(SSL *ssl, int *groups); 22 int SSL_get_shared_group(SSL *s, int n); 23 int SSL_get_negotiated_group(SSL *s); 24 25 int SSL_CTX_set1_curves(SSL_CTX *ctx, int *clist, int clistlen); 26 int SSL_CTX_set1_curves_list(SSL_CTX *ctx, char *list); 27 28 int SSL_set1_curves(SSL *ssl, int *clist, int clistlen); 29 int SSL_set1_curves_list(SSL *ssl, char *list); 30 31 int SSL_get1_curves(SSL *ssl, int *curves); 32 int SSL_get_shared_curve(SSL *s, int n); 33 34=head1 DESCRIPTION 35 36For all of the functions below that set the supported groups there must be at 37least one group in the list. A number of these functions identify groups via a 38unique integer NID value. However, support for some groups may be added by 39external providers. In this case there will be no NID assigned for the group. 40When setting such groups applications should use the "list" form of these 41functions (i.e. SSL_CTX_set1_groups_list() and SSL_set1_groups_list). 42 43SSL_CTX_set1_groups() sets the supported groups for B<ctx> to B<glistlen> 44groups in the array B<glist>. The array consist of all NIDs of groups in 45preference order. For a TLS client the groups are used directly in the 46supported groups extension. For a TLS server the groups are used to 47determine the set of shared groups. Currently supported groups for 48B<TLSv1.3> are B<NID_X9_62_prime256v1>, B<NID_secp384r1>, B<NID_secp521r1>, 49B<NID_X25519>, B<NID_X448>, B<NID_ffdhe2048>, B<NID_ffdhe3072>, 50B<NID_ffdhe4096>, B<NID_ffdhe6144> and B<NID_ffdhe8192>. 51 52SSL_CTX_set1_groups_list() sets the supported groups for B<ctx> to 53string B<list>. The string is a colon separated list of group NIDs or 54names, for example "P-521:P-384:P-256:X25519:ffdhe2048". Currently supported 55groups for B<TLSv1.3> are B<P-256>, B<P-384>, B<P-521>, B<X25519>, B<X448>, 56B<ffdhe2048>, B<ffdhe3072>, B<ffdhe4096>, B<ffdhe6144>, B<ffdhe8192>. Support 57for other groups may be added by external providers. 58 59SSL_set1_groups() and SSL_set1_groups_list() are similar except they set 60supported groups for the SSL structure B<ssl>. 61 62SSL_get1_groups() returns the set of supported groups sent by a client 63in the supported groups extension. It returns the total number of 64supported groups. The B<groups> parameter can be B<NULL> to simply 65return the number of groups for memory allocation purposes. The 66B<groups> array is in the form of a set of group NIDs in preference 67order. It can return zero if the client did not send a supported groups 68extension. If a supported group NID is unknown then the value is set to the 69bitwise OR of TLSEXT_nid_unknown (0x1000000) and the id of the group. 70 71SSL_get_shared_group() returns the NID of the shared group B<n> for a 72server-side SSL B<ssl>. If B<n> is -1 then the total number of shared groups is 73returned, which may be zero. Other than for diagnostic purposes, 74most applications will only be interested in the first shared group 75so B<n> is normally set to zero. If the value B<n> is out of range, 76NID_undef is returned. If the NID for the shared group is unknown then the value 77is set to the bitwise OR of TLSEXT_nid_unknown (0x1000000) and the id of the 78group. 79 80SSL_get_negotiated_group() returns the NID of the negotiated group used for 81the handshake key exchange process. For TLSv1.3 connections this typically 82reflects the state of the current connection, though in the case of PSK-only 83resumption, the returned value will be from a previous connection. For earlier 84TLS versions, when a session has been resumed, it always reflects the group 85used for key exchange during the initial handshake (otherwise it is from the 86current, non-resumption, connection). This can be called by either client or 87server. If the NID for the shared group is unknown then the value is set to the 88bitwise OR of TLSEXT_nid_unknown (0x1000000) and the id of the group. 89 90All these functions are implemented as macros. 91 92The curve functions are synonyms for the equivalently named group functions and 93are identical in every respect. They exist because, prior to TLS1.3, there was 94only the concept of supported curves. In TLS1.3 this was renamed to supported 95groups, and extended to include Diffie Hellman groups. The group functions 96should be used in preference. 97 98=head1 NOTES 99 100If an application wishes to make use of several of these functions for 101configuration purposes either on a command line or in a file it should 102consider using the SSL_CONF interface instead of manually parsing options. 103 104=head1 RETURN VALUES 105 106SSL_CTX_set1_groups(), SSL_CTX_set1_groups_list(), SSL_set1_groups() and 107SSL_set1_groups_list(), return 1 for success and 0 for failure. 108 109SSL_get1_groups() returns the number of groups, which may be zero. 110 111SSL_get_shared_group() returns the NID of shared group B<n> or NID_undef if there 112is no shared group B<n>; or the total number of shared groups if B<n> 113is -1. 114 115When called on a client B<ssl>, SSL_get_shared_group() has no meaning and 116returns -1. 117 118SSL_get_negotiated_group() returns the NID of the negotiated group used for 119key exchange, or NID_undef if there was no negotiated group. 120 121=head1 SEE ALSO 122 123L<ssl(7)>, 124L<SSL_CTX_add_extra_chain_cert(3)> 125 126=head1 HISTORY 127 128The curve functions were added in OpenSSL 1.0.2. The equivalent group 129functions were added in OpenSSL 1.1.1. The SSL_get_negotiated_group() function 130was added in OpenSSL 3.0.0. 131 132=head1 COPYRIGHT 133 134Copyright 2013-2021 The OpenSSL Project Authors. All Rights Reserved. 135 136Licensed under the Apache License 2.0 (the "License"). You may not use 137this file except in compliance with the License. You can obtain a copy 138in the file LICENSE in the source distribution or at 139L<https://www.openssl.org/source/license.html>. 140 141=cut 142