1=pod
2
3=head1 NAME
4
5SSL_CTX_set1_curves, SSL_CTX_set1_curves_list, SSL_set1_curves,
6SSL_set1_curves_list, SSL_get1_curves, SSL_get_shared_curve,
7SSL_CTX_set_ecdh_auto, SSL_set_ecdh_auto - EC supported curve functions
8
9=head1 SYNOPSIS
10
11 #include <openssl/ssl.h>
12
13 int SSL_CTX_set1_curves(SSL_CTX *ctx, int *clist, int clistlen);
14 int SSL_CTX_set1_curves_list(SSL_CTX *ctx, char *list);
15
16 int SSL_set1_curves(SSL *ssl, int *clist, int clistlen);
17 int SSL_set1_curves_list(SSL *ssl, char *list);
18
19 int SSL_get1_curves(SSL *ssl, int *curves);
20 int SSL_get_shared_curve(SSL *s, int n);
21
22 int SSL_CTX_set_ecdh_auto(SSL_CTX *ctx, int onoff);
23 int SSL_set_ecdh_auto(SSL *s, int onoff);
24
25=head1 DESCRIPTION
26
27SSL_CTX_set1_curves() sets the supported curves for B<ctx> to B<clistlen>
28curves in the array B<clist>. The array consist of all NIDs of curves in
29preference order. For a TLS client the curves are used directly in the
30supported curves extension. For a TLS server the curves are used to 
31determine the set of shared curves.
32
33SSL_CTX_set1_curves_list() sets the supported curves for B<ctx> to
34string B<list>. The string is a colon separated list of curve NIDs or
35names, for example "P-521:P-384:P-256".
36
37SSL_set1_curves() and SSL_set1_curves_list() are similar except they set
38supported curves for the SSL structure B<ssl>.
39
40SSL_get1_curves() returns the set of supported curves sent by a client
41in the supported curves extension. It returns the total number of 
42supported curves. The B<curves> parameter can be B<NULL> to simply
43return the number of curves for memory allocation purposes. The
44B<curves> array is in the form of a set of curve NIDs in preference
45order. It can return zero if the client did not send a supported curves
46extension.
47
48SSL_get_shared_curve() returns shared curve B<n> for a server-side
49SSL B<ssl>. If B<n> is -1 then the total number of shared curves is
50returned, which may be zero. Other than for diagnostic purposes,
51most applications will only be interested in the first shared curve
52so B<n> is normally set to zero. If the value B<n> is out of range,
53NID_undef is returned.
54
55SSL_CTX_set_ecdh_auto() and SSL_set_ecdh_auto() set automatic curve
56selection for server B<ctx> or B<ssl> to B<onoff>. If B<onoff> is 1 then 
57the highest preference curve is automatically used for ECDH temporary
58keys used during key exchange.
59
60All these functions are implemented as macros.
61
62=head1 NOTES
63
64If an application wishes to make use of several of these functions for
65configuration purposes either on a command line or in a file it should
66consider using the SSL_CONF interface instead of manually parsing options.
67
68The functions SSL_CTX_set_ecdh_auto() and SSL_set_ecdh_auto() can be used to
69make a server always choose the most appropriate curve for a client. If set
70it will override any temporary ECDH parameters set by a server. Previous
71versions of OpenSSL could effectively only use a single ECDH curve set
72using a function such as SSL_CTX_set_ecdh_tmp(). Newer applications should
73just call:
74
75 SSL_CTX_set_ecdh_auto(ctx, 1);
76
77and they will automatically support ECDH using the most appropriate shared
78curve.
79
80=head1 RETURN VALUES
81
82SSL_CTX_set1_curves(), SSL_CTX_set1_curves_list(), SSL_set1_curves(),
83SSL_set1_curves_list(), SSL_CTX_set_ecdh_auto() and SSL_set_ecdh_auto()
84return 1 for success and 0 for failure.
85
86SSL_get1_curves() returns the number of curves, which may be zero.
87
88SSL_get_shared_curve() returns the NID of shared curve B<n> or NID_undef if there
89is no shared curve B<n>; or the total number of shared curves if B<n>
90is -1.
91
92When called on a client B<ssl>, SSL_get_shared_curve() has no meaning and
93returns -1.
94
95=head1 SEE ALSO
96
97L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>
98
99=head1 HISTORY
100
101These functions were first added to OpenSSL 1.0.2.
102
103=cut
104