]>
Commit | Line | Data |
---|---|---|
c3eb3376 DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
de4d764e | 5 | SSL_CTX_set1_groups, SSL_CTX_set1_groups_list, SSL_set1_groups, |
13a53fbf PL |
6 | SSL_set1_groups_list, SSL_get1_groups, SSL_get0_iana_groups, |
7 | SSL_get_shared_group, SSL_get_negotiated_group, SSL_CTX_set1_curves, | |
8 | SSL_CTX_set1_curves_list, SSL_set1_curves, SSL_set1_curves_list, | |
9 | SSL_get1_curves, SSL_get_shared_curve | |
de4d764e | 10 | - EC supported curve functions |
c3eb3376 DSH |
11 | |
12 | =head1 SYNOPSIS | |
13 | ||
14 | #include <openssl/ssl.h> | |
15 | ||
de4d764e MC |
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); | |
13a53fbf | 23 | int SSL_get0_iana_groups(SSL *ssl, uint16_t **out); |
de4d764e | 24 | int SSL_get_shared_group(SSL *s, int n); |
88f19d86 | 25 | int SSL_get_negotiated_group(SSL *s); |
de4d764e | 26 | |
c3eb3376 DSH |
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 | ||
c3eb3376 DSH |
36 | =head1 DESCRIPTION |
37 | ||
680bd131 | 38 | For all of the functions below that set the supported groups there must be at |
260009d8 | 39 | least one group in the list. A number of these functions identify groups via a |
8c1cbc72 | 40 | unique integer NID value. However, support for some groups may be added by |
260009d8 MC |
41 | external providers. In this case there will be no NID assigned for the group. |
42 | When setting such groups applications should use the "list" form of these | |
43 | functions (i.e. SSL_CTX_set1_groups_list() and SSL_set1_groups_list). | |
680bd131 | 44 | |
de4d764e MC |
45 | SSL_CTX_set1_groups() sets the supported groups for B<ctx> to B<glistlen> |
46 | groups in the array B<glist>. The array consist of all NIDs of groups in | |
47 | preference order. For a TLS client the groups are used directly in the | |
48 | supported groups extension. For a TLS server the groups are used to | |
dfa1f547 | 49 | determine the set of shared groups. Currently supported groups for |
50 | B<TLSv1.3> are B<NID_X9_62_prime256v1>, B<NID_secp384r1>, B<NID_secp521r1>, | |
8377f26c MC |
51 | B<NID_X25519>, B<NID_X448>, B<NID_brainpoolP256r1tls13>, |
52 | B<NID_brainpoolP384r1tls13>, B<NID_brainpoolP512r1tls13>, B<NID_ffdhe2048>, | |
53 | B<NID_ffdhe3072>, B<NID_ffdhe4096>, B<NID_ffdhe6144> and B<NID_ffdhe8192>. | |
c3eb3376 | 54 | |
de4d764e | 55 | SSL_CTX_set1_groups_list() sets the supported groups for B<ctx> to |
8377f26c MC |
56 | string B<list>. The string is a colon separated list of group names, for example |
57 | "P-521:P-384:P-256:X25519:ffdhe2048". Currently supported groups for B<TLSv1.3> | |
58 | are B<P-256>, B<P-384>, B<P-521>, B<X25519>, B<X448>, B<brainpoolP256r1tls13>, | |
59 | B<brainpoolP384r1tls13>, B<brainpoolP512r1tls13>, B<ffdhe2048>, B<ffdhe3072>, | |
60 | B<ffdhe4096>, B<ffdhe6144> and B<ffdhe8192>. Support for other groups may be | |
cd2cdb61 TM |
61 | added by external providers. If a group name is preceded with the C<?> |
62 | character, it will be ignored if an implementation is missing. | |
c3eb3376 | 63 | |
de4d764e MC |
64 | SSL_set1_groups() and SSL_set1_groups_list() are similar except they set |
65 | supported groups for the SSL structure B<ssl>. | |
c3eb3376 | 66 | |
de4d764e MC |
67 | SSL_get1_groups() returns the set of supported groups sent by a client |
68 | in the supported groups extension. It returns the total number of | |
69 | supported groups. The B<groups> parameter can be B<NULL> to simply | |
70 | return the number of groups for memory allocation purposes. The | |
71 | B<groups> array is in the form of a set of group NIDs in preference | |
72 | order. It can return zero if the client did not send a supported groups | |
260009d8 MC |
73 | extension. If a supported group NID is unknown then the value is set to the |
74 | bitwise OR of TLSEXT_nid_unknown (0x1000000) and the id of the group. | |
c3eb3376 | 75 | |
13a53fbf PL |
76 | SSL_get0_iana_groups() retrieves the list of groups sent by the |
77 | client in the supported_groups extension. The B<*out> array of bytes | |
78 | is populated with the host-byte-order representation of the uint16_t group | |
79 | identifiers, as assigned by IANA. The group list is returned in the same order | |
80 | that was received in the ClientHello. The return value is the number of groups, | |
81 | not the number of bytes written. | |
82 | ||
260009d8 MC |
83 | SSL_get_shared_group() returns the NID of the shared group B<n> for a |
84 | server-side SSL B<ssl>. If B<n> is -1 then the total number of shared groups is | |
376e2ca3 | 85 | returned, which may be zero. Other than for diagnostic purposes, |
de4d764e | 86 | most applications will only be interested in the first shared group |
376e2ca3 | 87 | so B<n> is normally set to zero. If the value B<n> is out of range, |
260009d8 MC |
88 | NID_undef is returned. If the NID for the shared group is unknown then the value |
89 | is set to the bitwise OR of TLSEXT_nid_unknown (0x1000000) and the id of the | |
90 | group. | |
91 | ||
aa6bd216 BK |
92 | SSL_get_negotiated_group() returns the NID of the negotiated group used for |
93 | the handshake key exchange process. For TLSv1.3 connections this typically | |
94 | reflects the state of the current connection, though in the case of PSK-only | |
95 | resumption, the returned value will be from a previous connection. For earlier | |
96 | TLS versions, when a session has been resumed, it always reflects the group | |
97 | used for key exchange during the initial handshake (otherwise it is from the | |
98 | current, non-resumption, connection). This can be called by either client or | |
99 | server. If the NID for the shared group is unknown then the value is set to the | |
100 | bitwise OR of TLSEXT_nid_unknown (0x1000000) and the id of the group. | |
88f19d86 | 101 | |
c3eb3376 DSH |
102 | All these functions are implemented as macros. |
103 | ||
de4d764e MC |
104 | The curve functions are synonyms for the equivalently named group functions and |
105 | are identical in every respect. They exist because, prior to TLS1.3, there was | |
106 | only the concept of supported curves. In TLS1.3 this was renamed to supported | |
107 | groups, and extended to include Diffie Hellman groups. The group functions | |
108 | should be used in preference. | |
109 | ||
c3eb3376 DSH |
110 | =head1 NOTES |
111 | ||
112 | If an application wishes to make use of several of these functions for | |
113 | configuration purposes either on a command line or in a file it should | |
114 | consider using the SSL_CONF interface instead of manually parsing options. | |
115 | ||
c3eb3376 DSH |
116 | =head1 RETURN VALUES |
117 | ||
de4d764e MC |
118 | SSL_CTX_set1_groups(), SSL_CTX_set1_groups_list(), SSL_set1_groups() and |
119 | SSL_set1_groups_list(), return 1 for success and 0 for failure. | |
c3eb3376 | 120 | |
de4d764e | 121 | SSL_get1_groups() returns the number of groups, which may be zero. |
c3eb3376 | 122 | |
13a53fbf PL |
123 | SSL_get0_iana_groups() returns the number of (uint16_t) groups, which may be zero. |
124 | ||
de4d764e MC |
125 | SSL_get_shared_group() returns the NID of shared group B<n> or NID_undef if there |
126 | is no shared group B<n>; or the total number of shared groups if B<n> | |
376e2ca3 EK |
127 | is -1. |
128 | ||
de4d764e | 129 | When called on a client B<ssl>, SSL_get_shared_group() has no meaning and |
376e2ca3 | 130 | returns -1. |
c3eb3376 | 131 | |
aa6bd216 BK |
132 | SSL_get_negotiated_group() returns the NID of the negotiated group used for |
133 | key exchange, or NID_undef if there was no negotiated group. | |
88f19d86 | 134 | |
c3eb3376 DSH |
135 | =head1 SEE ALSO |
136 | ||
98ca37e4 | 137 | L<ssl(7)>, |
9b86974e | 138 | L<SSL_CTX_add_extra_chain_cert(3)> |
c3eb3376 DSH |
139 | |
140 | =head1 HISTORY | |
141 | ||
fc5ecadd | 142 | The curve functions were added in OpenSSL 1.0.2. The equivalent group |
88f19d86 | 143 | functions were added in OpenSSL 1.1.1. The SSL_get_negotiated_group() function |
144 | was added in OpenSSL 3.0.0. | |
c3eb3376 | 145 | |
cd2cdb61 TM |
146 | Support for ignoring unknown groups in SSL_CTX_set1_groups_list() and |
147 | SSL_set1_groups_list() was added in OpenSSL 3.3. | |
148 | ||
e2f92610 RS |
149 | =head1 COPYRIGHT |
150 | ||
b6461792 | 151 | Copyright 2013-2024 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 152 | |
4746f25a | 153 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
154 | this file except in compliance with the License. You can obtain a copy |
155 | in the file LICENSE in the source distribution or at | |
156 | L<https://www.openssl.org/source/license.html>. | |
157 | ||
158 | =cut |