1289848Sjkim=pod 2289848Sjkim 3289848Sjkim=head1 NAME 4289848Sjkim 5289848SjkimSSL_CTX_set1_curves, SSL_CTX_set1_curves_list, SSL_set1_curves, 6289848SjkimSSL_set1_curves_list, SSL_get1_curves, SSL_get_shared_curve, 7289848SjkimSSL_CTX_set_ecdh_auto, SSL_set_ecdh_auto - EC supported curve functions 8289848Sjkim 9289848Sjkim=head1 SYNOPSIS 10289848Sjkim 11289848Sjkim #include <openssl/ssl.h> 12289848Sjkim 13289848Sjkim int SSL_CTX_set1_curves(SSL_CTX *ctx, int *clist, int clistlen); 14289848Sjkim int SSL_CTX_set1_curves_list(SSL_CTX *ctx, char *list); 15289848Sjkim 16289848Sjkim int SSL_set1_curves(SSL *ssl, int *clist, int clistlen); 17289848Sjkim int SSL_set1_curves_list(SSL *ssl, char *list); 18289848Sjkim 19289848Sjkim int SSL_get1_curves(SSL *ssl, int *curves); 20289848Sjkim int SSL_get_shared_curve(SSL *s, int n); 21289848Sjkim 22289848Sjkim int SSL_CTX_set_ecdh_auto(SSL_CTX *ctx, int onoff); 23289848Sjkim int SSL_set_ecdh_auto(SSL *s, int onoff); 24289848Sjkim 25289848Sjkim=head1 DESCRIPTION 26289848Sjkim 27289848SjkimSSL_CTX_set1_curves() sets the supported curves for B<ctx> to B<clistlen> 28289848Sjkimcurves in the array B<clist>. The array consist of all NIDs of curves in 29289848Sjkimpreference order. For a TLS client the curves are used directly in the 30289848Sjkimsupported curves extension. For a TLS server the curves are used to 31289848Sjkimdetermine the set of shared curves. 32289848Sjkim 33289848SjkimSSL_CTX_set1_curves_list() sets the supported curves for B<ctx> to 34289848Sjkimstring B<list>. The string is a colon separated list of curve NIDs or 35289848Sjkimnames, for example "P-521:P-384:P-256". 36289848Sjkim 37289848SjkimSSL_set1_curves() and SSL_set1_curves_list() are similar except they set 38289848Sjkimsupported curves for the SSL structure B<ssl>. 39289848Sjkim 40289848SjkimSSL_get1_curves() returns the set of supported curves sent by a client 41289848Sjkimin the supported curves extension. It returns the total number of 42289848Sjkimsupported curves. The B<curves> parameter can be B<NULL> to simply 43289848Sjkimreturn the number of curves for memory allocation purposes. The 44289848SjkimB<curves> array is in the form of a set of curve NIDs in preference 45289848Sjkimorder. It can return zero if the client did not send a supported curves 46289848Sjkimextension. 47289848Sjkim 48289848SjkimSSL_get_shared_curve() returns shared curve B<n> for a server-side 49289848SjkimSSL B<ssl>. If B<n> is -1 then the total number of shared curves is 50289848Sjkimreturned, which may be zero. Other than for diagnostic purposes, 51289848Sjkimmost applications will only be interested in the first shared curve 52289848Sjkimso B<n> is normally set to zero. If the value B<n> is out of range, 53289848SjkimNID_undef is returned. 54289848Sjkim 55289848SjkimSSL_CTX_set_ecdh_auto() and SSL_set_ecdh_auto() set automatic curve 56289848Sjkimselection for server B<ctx> or B<ssl> to B<onoff>. If B<onoff> is 1 then 57289848Sjkimthe highest preference curve is automatically used for ECDH temporary 58289848Sjkimkeys used during key exchange. 59289848Sjkim 60289848SjkimAll these functions are implemented as macros. 61289848Sjkim 62289848Sjkim=head1 NOTES 63289848Sjkim 64289848SjkimIf an application wishes to make use of several of these functions for 65289848Sjkimconfiguration purposes either on a command line or in a file it should 66289848Sjkimconsider using the SSL_CONF interface instead of manually parsing options. 67289848Sjkim 68289848SjkimThe functions SSL_CTX_set_ecdh_auto() and SSL_set_ecdh_auto() can be used to 69289848Sjkimmake a server always choose the most appropriate curve for a client. If set 70289848Sjkimit will override any temporary ECDH parameters set by a server. Previous 71289848Sjkimversions of OpenSSL could effectively only use a single ECDH curve set 72289848Sjkimusing a function such as SSL_CTX_set_ecdh_tmp(). Newer applications should 73289848Sjkimjust call: 74289848Sjkim 75289848Sjkim SSL_CTX_set_ecdh_auto(ctx, 1); 76289848Sjkim 77289848Sjkimand they will automatically support ECDH using the most appropriate shared 78289848Sjkimcurve. 79289848Sjkim 80289848Sjkim=head1 RETURN VALUES 81289848Sjkim 82289848SjkimSSL_CTX_set1_curves(), SSL_CTX_set1_curves_list(), SSL_set1_curves(), 83289848SjkimSSL_set1_curves_list(), SSL_CTX_set_ecdh_auto() and SSL_set_ecdh_auto() 84289848Sjkimreturn 1 for success and 0 for failure. 85289848Sjkim 86289848SjkimSSL_get1_curves() returns the number of curves, which may be zero. 87289848Sjkim 88289848SjkimSSL_get_shared_curve() returns the NID of shared curve B<n> or NID_undef if there 89289848Sjkimis no shared curve B<n>; or the total number of shared curves if B<n> 90289848Sjkimis -1. 91289848Sjkim 92289848SjkimWhen called on a client B<ssl>, SSL_get_shared_curve() has no meaning and 93289848Sjkimreturns -1. 94289848Sjkim 95289848Sjkim=head1 SEE ALSO 96289848Sjkim 97289848SjkimL<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)> 98289848Sjkim 99289848Sjkim=head1 HISTORY 100289848Sjkim 101289848SjkimThese functions were first added to OpenSSL 1.0.2. 102289848Sjkim 103289848Sjkim=cut 104