]>
Commit | Line | Data |
---|---|---|
c3eb3376 DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
de4d764e MC |
5 | SSL_CTX_set1_groups, SSL_CTX_set1_groups_list, SSL_set1_groups, |
6 | SSL_set1_groups_list, SSL_get1_groups, SSL_get_shared_group, | |
c3eb3376 | 7 | SSL_CTX_set1_curves, SSL_CTX_set1_curves_list, SSL_set1_curves, |
de4d764e MC |
8 | SSL_set1_curves_list, SSL_get1_curves, SSL_get_shared_curve |
9 | - EC supported curve functions | |
c3eb3376 DSH |
10 | |
11 | =head1 SYNOPSIS | |
12 | ||
13 | #include <openssl/ssl.h> | |
14 | ||
de4d764e MC |
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 | ||
c3eb3376 DSH |
24 | int SSL_CTX_set1_curves(SSL_CTX *ctx, int *clist, int clistlen); |
25 | int SSL_CTX_set1_curves_list(SSL_CTX *ctx, char *list); | |
26 | ||
27 | int SSL_set1_curves(SSL *ssl, int *clist, int clistlen); | |
28 | int SSL_set1_curves_list(SSL *ssl, char *list); | |
29 | ||
30 | int SSL_get1_curves(SSL *ssl, int *curves); | |
31 | int SSL_get_shared_curve(SSL *s, int n); | |
32 | ||
c3eb3376 DSH |
33 | =head1 DESCRIPTION |
34 | ||
680bd131 MC |
35 | For all of the functions below that set the supported groups there must be at |
36 | least one group in the list. | |
37 | ||
de4d764e MC |
38 | SSL_CTX_set1_groups() sets the supported groups for B<ctx> to B<glistlen> |
39 | groups in the array B<glist>. The array consist of all NIDs of groups in | |
40 | preference order. For a TLS client the groups are used directly in the | |
41 | supported groups extension. For a TLS server the groups are used to | |
42 | determine the set of shared groups. | |
c3eb3376 | 43 | |
de4d764e MC |
44 | SSL_CTX_set1_groups_list() sets the supported groups for B<ctx> to |
45 | string B<list>. The string is a colon separated list of group NIDs or | |
c3eb3376 DSH |
46 | names, for example "P-521:P-384:P-256". |
47 | ||
de4d764e MC |
48 | SSL_set1_groups() and SSL_set1_groups_list() are similar except they set |
49 | supported groups for the SSL structure B<ssl>. | |
c3eb3376 | 50 | |
de4d764e MC |
51 | SSL_get1_groups() returns the set of supported groups sent by a client |
52 | in the supported groups extension. It returns the total number of | |
53 | supported groups. The B<groups> parameter can be B<NULL> to simply | |
54 | return the number of groups for memory allocation purposes. The | |
55 | B<groups> array is in the form of a set of group NIDs in preference | |
56 | order. It can return zero if the client did not send a supported groups | |
c3eb3376 DSH |
57 | extension. |
58 | ||
de4d764e MC |
59 | SSL_get_shared_group() returns shared group B<n> for a server-side |
60 | SSL B<ssl>. If B<n> is -1 then the total number of shared groups is | |
376e2ca3 | 61 | returned, which may be zero. Other than for diagnostic purposes, |
de4d764e | 62 | most applications will only be interested in the first shared group |
376e2ca3 EK |
63 | so B<n> is normally set to zero. If the value B<n> is out of range, |
64 | NID_undef is returned. | |
c3eb3376 | 65 | |
c3eb3376 DSH |
66 | All these functions are implemented as macros. |
67 | ||
de4d764e MC |
68 | The curve functions are synonyms for the equivalently named group functions and |
69 | are identical in every respect. They exist because, prior to TLS1.3, there was | |
70 | only the concept of supported curves. In TLS1.3 this was renamed to supported | |
71 | groups, and extended to include Diffie Hellman groups. The group functions | |
72 | should be used in preference. | |
73 | ||
c3eb3376 DSH |
74 | =head1 NOTES |
75 | ||
76 | If an application wishes to make use of several of these functions for | |
77 | configuration purposes either on a command line or in a file it should | |
78 | consider using the SSL_CONF interface instead of manually parsing options. | |
79 | ||
c3eb3376 DSH |
80 | =head1 RETURN VALUES |
81 | ||
de4d764e MC |
82 | SSL_CTX_set1_groups(), SSL_CTX_set1_groups_list(), SSL_set1_groups() and |
83 | SSL_set1_groups_list(), return 1 for success and 0 for failure. | |
c3eb3376 | 84 | |
de4d764e | 85 | SSL_get1_groups() returns the number of groups, which may be zero. |
c3eb3376 | 86 | |
de4d764e MC |
87 | SSL_get_shared_group() returns the NID of shared group B<n> or NID_undef if there |
88 | is no shared group B<n>; or the total number of shared groups if B<n> | |
376e2ca3 EK |
89 | is -1. |
90 | ||
de4d764e | 91 | When called on a client B<ssl>, SSL_get_shared_group() has no meaning and |
376e2ca3 | 92 | returns -1. |
c3eb3376 | 93 | |
c3eb3376 DSH |
94 | =head1 SEE ALSO |
95 | ||
9b86974e | 96 | L<SSL_CTX_add_extra_chain_cert(3)> |
c3eb3376 DSH |
97 | |
98 | =head1 HISTORY | |
99 | ||
de4d764e MC |
100 | The curve functions were first added to OpenSSL 1.0.2. The equivalent group |
101 | functions were first added to OpenSSL 1.1.1. | |
c3eb3376 | 102 | |
e2f92610 RS |
103 | =head1 COPYRIGHT |
104 | ||
105 | Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved. | |
106 | ||
107 | Licensed under the OpenSSL license (the "License"). You may not use | |
108 | this file except in compliance with the License. You can obtain a copy | |
109 | in the file LICENSE in the source distribution or at | |
110 | L<https://www.openssl.org/source/license.html>. | |
111 | ||
112 | =cut |