mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2024-12-27 06:21:43 +08:00
Code Issues Packages Projects Releases Wiki Activity
3f76339a3f
openssl/doc/man3/SSL_CTX_set1_curves.pod

153 lines
6.6 KiB
Plaintext
Raw Normal View History

Document supported curve functions.
2013-09-03 22:42:40 +08:00
=pod
=head1 NAME
Rename the Elliptic Curves extension to supported_groups This is a skin deep change, which simply renames most places where we talk about curves in a TLS context to groups. This is because TLS1.3 has renamed the extension, and it can now include DH groups too. We still only support curves, but this rename should pave the way for a future extension for DH groups. Reviewed-by: Rich Salz <rsalz@openssl.org>
2016-11-09 22:51:06 +08:00
SSL_CTX_set1_groups, SSL_CTX_set1_groups_list, SSL_set1_groups,
add SSL_get0_iana_groups() & SSL_client_hello_get_extension_order() The function/macro allow user get groups/extensions without memory allcations. So we could calculate the ssl fignerprint(ja3) in low cost. Reviewed-by: Paul Dale <pauli@openssl.org> Reviewed-by: Tomas Mraz <tomas@openssl.org> (Merged from https://github.com/openssl/openssl/pull/16910)
2021-10-25 18:47:00 +08:00
SSL_set1_groups_list, SSL_get1_groups, SSL_get0_iana_groups,
SSL_get_shared_group, SSL_get_negotiated_group, SSL_CTX_set1_curves,
SSL_CTX_set1_curves_list, SSL_set1_curves, SSL_set1_curves_list,
SSL_get1_curves, SSL_get_shared_curve
Rename the Elliptic Curves extension to supported_groups This is a skin deep change, which simply renames most places where we talk about curves in a TLS context to groups. This is because TLS1.3 has renamed the extension, and it can now include DH groups too. We still only support curves, but this rename should pave the way for a future extension for DH groups. Reviewed-by: Rich Salz <rsalz@openssl.org>
2016-11-09 22:51:06 +08:00
- EC supported curve functions
Document supported curve functions.
2013-09-03 22:42:40 +08:00
=head1 SYNOPSIS
#include <openssl/ssl.h>
Rename the Elliptic Curves extension to supported_groups This is a skin deep change, which simply renames most places where we talk about curves in a TLS context to groups. This is because TLS1.3 has renamed the extension, and it can now include DH groups too. We still only support curves, but this rename should pave the way for a future extension for DH groups. Reviewed-by: Rich Salz <rsalz@openssl.org>
2016-11-09 22:51:06 +08:00
int SSL_CTX_set1_groups(SSL_CTX *ctx, int *glist, int glistlen);
int SSL_CTX_set1_groups_list(SSL_CTX *ctx, char *list);
int SSL_set1_groups(SSL *ssl, int *glist, int glistlen);
int SSL_set1_groups_list(SSL *ssl, char *list);
int SSL_get1_groups(SSL *ssl, int *groups);
add SSL_get0_iana_groups() & SSL_client_hello_get_extension_order() The function/macro allow user get groups/extensions without memory allcations. So we could calculate the ssl fignerprint(ja3) in low cost. Reviewed-by: Paul Dale <pauli@openssl.org> Reviewed-by: Tomas Mraz <tomas@openssl.org> (Merged from https://github.com/openssl/openssl/pull/16910)
2021-10-25 18:47:00 +08:00
int SSL_get0_iana_groups(SSL *ssl, uint16_t **out);
Rename the Elliptic Curves extension to supported_groups This is a skin deep change, which simply renames most places where we talk about curves in a TLS context to groups. This is because TLS1.3 has renamed the extension, and it can now include DH groups too. We still only support curves, but this rename should pave the way for a future extension for DH groups. Reviewed-by: Rich Salz <rsalz@openssl.org>
2016-11-09 22:51:06 +08:00
int SSL_get_shared_group(SSL *s, int n);
Update man page for new API SSL_get_negotiated_group() Reviewed-by: Paul Dale <paul.dale@oracle.com> Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/9323)
2019-07-08 20:43:24 +08:00
int SSL_get_negotiated_group(SSL *s);
Rename the Elliptic Curves extension to supported_groups This is a skin deep change, which simply renames most places where we talk about curves in a TLS context to groups. This is because TLS1.3 has renamed the extension, and it can now include DH groups too. We still only support curves, but this rename should pave the way for a future extension for DH groups. Reviewed-by: Rich Salz <rsalz@openssl.org>
2016-11-09 22:51:06 +08:00
Document supported curve functions.
2013-09-03 22:42:40 +08:00
int SSL_CTX_set1_curves(SSL_CTX *ctx, int *clist, int clistlen);
int SSL_CTX_set1_curves_list(SSL_CTX *ctx, char *list);
int SSL_set1_curves(SSL *ssl, int *clist, int clistlen);
int SSL_set1_curves_list(SSL *ssl, char *list);
int SSL_get1_curves(SSL *ssl, int *curves);
int SSL_get_shared_curve(SSL *s, int n);
=head1 DESCRIPTION
Give a better error if an attempt is made to set a zero length groups list Previously we indicated this as a malloc failure which isn't very helpful. Reviewed-by: Kurt Roeckx <kurt@roeckx.be> (Merged from https://github.com/openssl/openssl/pull/7479)
2018-10-26 22:29:15 +08:00
For all of the functions below that set the supported groups there must be at
Update the various SSL group getting and setting functions A number of these functions returned a NID or an array of NIDs for the groups. Now that groups can come from the providers we do not necessarily know the NID. Therefore we need to handle this in a clean way. Reviewed-by: Shane Lontis <shane.lontis@oracle.com> (Merged from https://github.com/openssl/openssl/pull/11914)
2020-05-21 23:36:32 +08:00
least one group in the list. A number of these functions identify groups via a
Fix typos and repeated words CLA: trivial Reviewed-by: Shane Lontis <shane.lontis@oracle.com> Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com> (Merged from https://github.com/openssl/openssl/pull/12320)
2020-06-30 03:13:07 +08:00
unique integer NID value. However, support for some groups may be added by
Update the various SSL group getting and setting functions A number of these functions returned a NID or an array of NIDs for the groups. Now that groups can come from the providers we do not necessarily know the NID. Therefore we need to handle this in a clean way. Reviewed-by: Shane Lontis <shane.lontis@oracle.com> (Merged from https://github.com/openssl/openssl/pull/11914)
2020-05-21 23:36:32 +08:00
external providers. In this case there will be no NID assigned for the group.
When setting such groups applications should use the "list" form of these
functions (i.e. SSL_CTX_set1_groups_list() and SSL_set1_groups_list).
Give a better error if an attempt is made to set a zero length groups list Previously we indicated this as a malloc failure which isn't very helpful. Reviewed-by: Kurt Roeckx <kurt@roeckx.be> (Merged from https://github.com/openssl/openssl/pull/7479)
2018-10-26 22:29:15 +08:00
Rename the Elliptic Curves extension to supported_groups This is a skin deep change, which simply renames most places where we talk about curves in a TLS context to groups. This is because TLS1.3 has renamed the extension, and it can now include DH groups too. We still only support curves, but this rename should pave the way for a future extension for DH groups. Reviewed-by: Rich Salz <rsalz@openssl.org>
2016-11-09 22:51:06 +08:00
SSL_CTX_set1_groups() sets the supported groups for B<ctx> to B<glistlen>
groups in the array B<glist>. The array consist of all NIDs of groups in
preference order. For a TLS client the groups are used directly in the
supported groups extension. For a TLS server the groups are used to
Update docs for TLS1.3 FFDHE Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/8178)
2019-05-12 01:58:26 +08:00
determine the set of shared groups. Currently supported groups for
B<TLSv1.3> are B<NID_X9_62_prime256v1>, B<NID_secp384r1>, B<NID_secp521r1>,
B<NID_X25519>, B<NID_X448>, B<NID_ffdhe2048>, B<NID_ffdhe3072>,
B<NID_ffdhe4096>, B<NID_ffdhe6144> and B<NID_ffdhe8192>.
Document supported curve functions.
2013-09-03 22:42:40 +08:00
Rename the Elliptic Curves extension to supported_groups This is a skin deep change, which simply renames most places where we talk about curves in a TLS context to groups. This is because TLS1.3 has renamed the extension, and it can now include DH groups too. We still only support curves, but this rename should pave the way for a future extension for DH groups. Reviewed-by: Rich Salz <rsalz@openssl.org>
2016-11-09 22:51:06 +08:00
SSL_CTX_set1_groups_list() sets the supported groups for B<ctx> to
string B<list>. The string is a colon separated list of group NIDs or
Update docs for TLS1.3 FFDHE Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/8178)
2019-05-12 01:58:26 +08:00
names, for example "P-521:P-384:P-256:X25519:ffdhe2048". Currently supported
groups for B<TLSv1.3> are B<P-256>, B<P-384>, B<P-521>, B<X25519>, B<X448>,
Update the various SSL group getting and setting functions A number of these functions returned a NID or an array of NIDs for the groups. Now that groups can come from the providers we do not necessarily know the NID. Therefore we need to handle this in a clean way. Reviewed-by: Shane Lontis <shane.lontis@oracle.com> (Merged from https://github.com/openssl/openssl/pull/11914)
2020-05-21 23:36:32 +08:00
B<ffdhe2048>, B<ffdhe3072>, B<ffdhe4096>, B<ffdhe6144>, B<ffdhe8192>. Support
for other groups may be added by external providers.
Document supported curve functions.
2013-09-03 22:42:40 +08:00
Rename the Elliptic Curves extension to supported_groups This is a skin deep change, which simply renames most places where we talk about curves in a TLS context to groups. This is because TLS1.3 has renamed the extension, and it can now include DH groups too. We still only support curves, but this rename should pave the way for a future extension for DH groups. Reviewed-by: Rich Salz <rsalz@openssl.org>
2016-11-09 22:51:06 +08:00
SSL_set1_groups() and SSL_set1_groups_list() are similar except they set
supported groups for the SSL structure B<ssl>.
Document supported curve functions.
2013-09-03 22:42:40 +08:00
Rename the Elliptic Curves extension to supported_groups This is a skin deep change, which simply renames most places where we talk about curves in a TLS context to groups. This is because TLS1.3 has renamed the extension, and it can now include DH groups too. We still only support curves, but this rename should pave the way for a future extension for DH groups. Reviewed-by: Rich Salz <rsalz@openssl.org>
2016-11-09 22:51:06 +08:00
SSL_get1_groups() returns the set of supported groups sent by a client
in the supported groups extension. It returns the total number of
supported groups. The B<groups> parameter can be B<NULL> to simply
return the number of groups for memory allocation purposes. The
B<groups> array is in the form of a set of group NIDs in preference
order. It can return zero if the client did not send a supported groups
Update the various SSL group getting and setting functions A number of these functions returned a NID or an array of NIDs for the groups. Now that groups can come from the providers we do not necessarily know the NID. Therefore we need to handle this in a clean way. Reviewed-by: Shane Lontis <shane.lontis@oracle.com> (Merged from https://github.com/openssl/openssl/pull/11914)
2020-05-21 23:36:32 +08:00
extension. If a supported group NID is unknown then the value is set to the
bitwise OR of TLSEXT_nid_unknown (0x1000000) and the id of the group.
Document supported curve functions.
2013-09-03 22:42:40 +08:00
add SSL_get0_iana_groups() & SSL_client_hello_get_extension_order() The function/macro allow user get groups/extensions without memory allcations. So we could calculate the ssl fignerprint(ja3) in low cost. Reviewed-by: Paul Dale <pauli@openssl.org> Reviewed-by: Tomas Mraz <tomas@openssl.org> (Merged from https://github.com/openssl/openssl/pull/16910)
2021-10-25 18:47:00 +08:00
SSL_get0_iana_groups() retrieves the list of groups sent by the
client in the supported_groups extension. The B<*out> array of bytes
is populated with the host-byte-order representation of the uint16_t group
identifiers, as assigned by IANA. The group list is returned in the same order
that was received in the ClientHello. The return value is the number of groups,
not the number of bytes written.
Update the various SSL group getting and setting functions A number of these functions returned a NID or an array of NIDs for the groups. Now that groups can come from the providers we do not necessarily know the NID. Therefore we need to handle this in a clean way. Reviewed-by: Shane Lontis <shane.lontis@oracle.com> (Merged from https://github.com/openssl/openssl/pull/11914)
2020-05-21 23:36:32 +08:00
SSL_get_shared_group() returns the NID of the shared group B<n> for a
server-side SSL B<ssl>. If B<n> is -1 then the total number of shared groups is
Clarify the return values for SSL_get_shared_curve. Reviewed-by: Matt Caswell <matt@openssl.org>
2014-12-04 22:00:11 +08:00
returned, which may be zero. Other than for diagnostic purposes,
Rename the Elliptic Curves extension to supported_groups This is a skin deep change, which simply renames most places where we talk about curves in a TLS context to groups. This is because TLS1.3 has renamed the extension, and it can now include DH groups too. We still only support curves, but this rename should pave the way for a future extension for DH groups. Reviewed-by: Rich Salz <rsalz@openssl.org>
2016-11-09 22:51:06 +08:00
most applications will only be interested in the first shared group
Clarify the return values for SSL_get_shared_curve. Reviewed-by: Matt Caswell <matt@openssl.org>
2014-12-04 22:00:11 +08:00
so B<n> is normally set to zero. If the value B<n> is out of range,
Update the various SSL group getting and setting functions A number of these functions returned a NID or an array of NIDs for the groups. Now that groups can come from the providers we do not necessarily know the NID. Therefore we need to handle this in a clean way. Reviewed-by: Shane Lontis <shane.lontis@oracle.com> (Merged from https://github.com/openssl/openssl/pull/11914)
2020-05-21 23:36:32 +08:00
NID_undef is returned. If the NID for the shared group is unknown then the value
is set to the bitwise OR of TLSEXT_nid_unknown (0x1000000) and the id of the
group.
Promote SSL_get_negotiated_group() for non-TLSv1.3 It can be useful to know what group was used for the handshake's key exchange process even on non-TLS 1.3 connections. Allow this API, new in OpenSSL 3.0.0, to be used on other TLS versions as well. Since pre-TLS-1.3 key exchange occurs only on full handshakes, this necessitates adding a field to the SSL_SESSION object to carry the group information across resumptions. The key exchange group in the SSL_SESSION can also be relevant in TLS 1.3 when the resumption handshake uses the "psk_ke" key-exchange mode, so also track whether a fresh key exchange was done for TLS 1.3. Since the new field is optional in the ASN.1 sense, there is no need to increment SSL_SESSION_ASN1_VERSION (which incurs strong incompatibility churn). Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/14750)
2021-03-16 22:47:09 +08:00
SSL_get_negotiated_group() returns the NID of the negotiated group used for
the handshake key exchange process. For TLSv1.3 connections this typically
reflects the state of the current connection, though in the case of PSK-only
resumption, the returned value will be from a previous connection. For earlier
TLS versions, when a session has been resumed, it always reflects the group
used for key exchange during the initial handshake (otherwise it is from the
current, non-resumption, connection). This can be called by either client or
server. If the NID for the shared group is unknown then the value is set to the
bitwise OR of TLSEXT_nid_unknown (0x1000000) and the id of the group.
Update man page for new API SSL_get_negotiated_group() Reviewed-by: Paul Dale <paul.dale@oracle.com> Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/9323)
2019-07-08 20:43:24 +08:00
Document supported curve functions.
2013-09-03 22:42:40 +08:00
All these functions are implemented as macros.
Rename the Elliptic Curves extension to supported_groups This is a skin deep change, which simply renames most places where we talk about curves in a TLS context to groups. This is because TLS1.3 has renamed the extension, and it can now include DH groups too. We still only support curves, but this rename should pave the way for a future extension for DH groups. Reviewed-by: Rich Salz <rsalz@openssl.org>
2016-11-09 22:51:06 +08:00
The curve functions are synonyms for the equivalently named group functions and
are identical in every respect. They exist because, prior to TLS1.3, there was
only the concept of supported curves. In TLS1.3 this was renamed to supported
groups, and extended to include Diffie Hellman groups. The group functions
should be used in preference.
Document supported curve functions.
2013-09-03 22:42:40 +08:00
=head1 NOTES
If an application wishes to make use of several of these functions for
configuration purposes either on a command line or in a file it should
consider using the SSL_CONF interface instead of manually parsing options.
=head1 RETURN VALUES
Rename the Elliptic Curves extension to supported_groups This is a skin deep change, which simply renames most places where we talk about curves in a TLS context to groups. This is because TLS1.3 has renamed the extension, and it can now include DH groups too. We still only support curves, but this rename should pave the way for a future extension for DH groups. Reviewed-by: Rich Salz <rsalz@openssl.org>
2016-11-09 22:51:06 +08:00
SSL_CTX_set1_groups(), SSL_CTX_set1_groups_list(), SSL_set1_groups() and
SSL_set1_groups_list(), return 1 for success and 0 for failure.
Document supported curve functions.
2013-09-03 22:42:40 +08:00
Rename the Elliptic Curves extension to supported_groups This is a skin deep change, which simply renames most places where we talk about curves in a TLS context to groups. This is because TLS1.3 has renamed the extension, and it can now include DH groups too. We still only support curves, but this rename should pave the way for a future extension for DH groups. Reviewed-by: Rich Salz <rsalz@openssl.org>
2016-11-09 22:51:06 +08:00
SSL_get1_groups() returns the number of groups, which may be zero.
Document supported curve functions.
2013-09-03 22:42:40 +08:00
add SSL_get0_iana_groups() & SSL_client_hello_get_extension_order() The function/macro allow user get groups/extensions without memory allcations. So we could calculate the ssl fignerprint(ja3) in low cost. Reviewed-by: Paul Dale <pauli@openssl.org> Reviewed-by: Tomas Mraz <tomas@openssl.org> (Merged from https://github.com/openssl/openssl/pull/16910)
2021-10-25 18:47:00 +08:00
SSL_get0_iana_groups() returns the number of (uint16_t) groups, which may be zero.
Rename the Elliptic Curves extension to supported_groups This is a skin deep change, which simply renames most places where we talk about curves in a TLS context to groups. This is because TLS1.3 has renamed the extension, and it can now include DH groups too. We still only support curves, but this rename should pave the way for a future extension for DH groups. Reviewed-by: Rich Salz <rsalz@openssl.org>
2016-11-09 22:51:06 +08:00
SSL_get_shared_group() returns the NID of shared group B<n> or NID_undef if there
is no shared group B<n>; or the total number of shared groups if B<n>
Clarify the return values for SSL_get_shared_curve. Reviewed-by: Matt Caswell <matt@openssl.org>
2014-12-04 22:00:11 +08:00
is -1.
Rename the Elliptic Curves extension to supported_groups This is a skin deep change, which simply renames most places where we talk about curves in a TLS context to groups. This is because TLS1.3 has renamed the extension, and it can now include DH groups too. We still only support curves, but this rename should pave the way for a future extension for DH groups. Reviewed-by: Rich Salz <rsalz@openssl.org>
2016-11-09 22:51:06 +08:00
When called on a client B<ssl>, SSL_get_shared_group() has no meaning and
Clarify the return values for SSL_get_shared_curve. Reviewed-by: Matt Caswell <matt@openssl.org>
2014-12-04 22:00:11 +08:00
returns -1.
Document supported curve functions.
2013-09-03 22:42:40 +08:00
Promote SSL_get_negotiated_group() for non-TLSv1.3 It can be useful to know what group was used for the handshake's key exchange process even on non-TLS 1.3 connections. Allow this API, new in OpenSSL 3.0.0, to be used on other TLS versions as well. Since pre-TLS-1.3 key exchange occurs only on full handshakes, this necessitates adding a field to the SSL_SESSION object to carry the group information across resumptions. The key exchange group in the SSL_SESSION can also be relevant in TLS 1.3 when the resumption handshake uses the "psk_ke" key-exchange mode, so also track whether a fresh key exchange was done for TLS 1.3. Since the new field is optional in the ASN.1 sense, there is no need to increment SSL_SESSION_ASN1_VERSION (which incurs strong incompatibility churn). Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/14750)
2021-03-16 22:47:09 +08:00
SSL_get_negotiated_group() returns the NID of the negotiated group used for
key exchange, or NID_undef if there was no negotiated group.
Update man page for new API SSL_get_negotiated_group() Reviewed-by: Paul Dale <paul.dale@oracle.com> Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/9323)
2019-07-08 20:43:24 +08:00
Document supported curve functions.
2013-09-03 22:42:40 +08:00
=head1 SEE ALSO
Add L<ssl(7)> to all SSL pages Reviewed-by: Matt Caswell <matt@openssl.org> Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/10208)
2019-11-02 00:27:29 +08:00
L<ssl(7)>,
Fix L<> content in manpages L<foo|foo> is sub-optimal If the xref is the same as the title, which is what we do, then you only need L<foo>. This fixes all 1457 occurrences in 349 files. Approximately. (And pod used to need both.) Reviewed-by: Richard Levitte <levitte@openssl.org>
2015-08-18 03:21:33 +08:00
L<SSL_CTX_add_extra_chain_cert(3)>
Document supported curve functions.
2013-09-03 22:42:40 +08:00
=head1 HISTORY
man: harmonize the various formulations in the HISTORY sections While stereotyped repetitions are frowned upon in literature, they serve a useful purpose in manual pages, because it is easier for the user to find certain information if it is always presented in the same way. For that reason, this commit harmonizes the varying formulations in the HISTORY section about which functions, flags, etc. were added in which OpenSSL version. It also attempts to make the pod files more grep friendly by avoiding to insert line breaks between the symbol names and the corresponding version number in which they were introduced (wherever possible). Some punctuation and typographical errors were fixed on the way. Reviewed-by: Tim Hudson <tjh@openssl.org> (Merged from https://github.com/openssl/openssl/pull/7854)
2018-12-09 08:02:36 +08:00
The curve functions were added in OpenSSL 1.0.2. The equivalent group
Update man page for new API SSL_get_negotiated_group() Reviewed-by: Paul Dale <paul.dale@oracle.com> Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/9323)
2019-07-08 20:43:24 +08:00
functions were added in OpenSSL 1.1.1. The SSL_get_negotiated_group() function
was added in OpenSSL 3.0.0.
Document supported curve functions.
2013-09-03 22:42:40 +08:00
Add copyright to manpages Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-05-18 23:44:05 +08:00
=head1 COPYRIGHT
Update copyright year Reviewed-by: Tomas Mraz <tomas@openssl.org> Release: yes
2022-05-03 18:52:38 +08:00
Copyright 2013-2022 The OpenSSL Project Authors. All Rights Reserved.
Add copyright to manpages Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-05-18 23:44:05 +08:00
Following the license change, modify the boilerplates in doc/man3/ [skip ci] Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/7829)
2018-12-06 21:04:44 +08:00
Licensed under the Apache License 2.0 (the "License"). You may not use
Add copyright to manpages Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-05-18 23:44:05 +08:00
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut
Reference in New Issue Copy Permalink