secure/lib/libssl/man/SSL_CTX_set1_curves.3

   1 .\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "SSL_CTX_set1_curves 3"
 132 .TH SSL_CTX_set1_curves 3 "2018-08-14" "1.0.2p" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 SSL_CTX_set1_curves, SSL_CTX_set1_curves_list, SSL_set1_curves,
 139 SSL_set1_curves_list, SSL_get1_curves, SSL_get_shared_curve,
 140 SSL_CTX_set_ecdh_auto, SSL_set_ecdh_auto \- EC supported curve functions
 141 .SH "SYNOPSIS"
 142 .IX Header "SYNOPSIS"
 143 .Vb 1
 144 \& #include <openssl/ssl.h>
 145 \&
 146 \& int SSL_CTX_set1_curves(SSL_CTX *ctx, int *clist, int clistlen);
 147 \& int SSL_CTX_set1_curves_list(SSL_CTX *ctx, char *list);
 148 \&
 149 \& int SSL_set1_curves(SSL *ssl, int *clist, int clistlen);
 150 \& int SSL_set1_curves_list(SSL *ssl, char *list);
 151 \&
 152 \& int SSL_get1_curves(SSL *ssl, int *curves);
 153 \& int SSL_get_shared_curve(SSL *s, int n);
 154 \&
 155 \& int SSL_CTX_set_ecdh_auto(SSL_CTX *ctx, int onoff);
 156 \& int SSL_set_ecdh_auto(SSL *s, int onoff);
 157 .Ve
 158 .SH "DESCRIPTION"
 159 .IX Header "DESCRIPTION"
 160 \&\fISSL_CTX_set1_curves()\fR sets the supported curves for \fBctx\fR to \fBclistlen\fR
 161 curves in the array \fBclist\fR. The array consist of all NIDs of curves in
 162 preference order. For a \s-1TLS\s0 client the curves are used directly in the
 163 supported curves extension. For a \s-1TLS\s0 server the curves are used to
 164 determine the set of shared curves.
 165 .PP
 166 \&\fISSL_CTX_set1_curves_list()\fR sets the supported curves for \fBctx\fR to
 167 string \fBlist\fR. The string is a colon separated list of curve NIDs or
 168 names, for example \*(L"P\-521:P\-384:P\-256\*(R".
 169 .PP
 170 \&\fISSL_set1_curves()\fR and \fISSL_set1_curves_list()\fR are similar except they set
 171 supported curves for the \s-1SSL\s0 structure \fBssl\fR.
 172 .PP
 173 \&\fISSL_get1_curves()\fR returns the set of supported curves sent by a client
 174 in the supported curves extension. It returns the total number of
 175 supported curves. The \fBcurves\fR parameter can be \fB\s-1NULL\s0\fR to simply
 176 return the number of curves for memory allocation purposes. The
 177 \&\fBcurves\fR array is in the form of a set of curve NIDs in preference
 178 order. It can return zero if the client did not send a supported curves
 179 extension.
 180 .PP
 181 \&\fISSL_get_shared_curve()\fR returns shared curve \fBn\fR for a server-side
 182 \&\s-1SSL\s0 \fBssl\fR. If \fBn\fR is \-1 then the total number of shared curves is
 183 returned, which may be zero. Other than for diagnostic purposes,
 184 most applications will only be interested in the first shared curve
 185 so \fBn\fR is normally set to zero. If the value \fBn\fR is out of range,
 186 NID_undef is returned.
 187 .PP
 188 \&\fISSL_CTX_set_ecdh_auto()\fR and \fISSL_set_ecdh_auto()\fR set automatic curve
 189 selection for server \fBctx\fR or \fBssl\fR to \fBonoff\fR. If \fBonoff\fR is 1 then
 190 the highest preference curve is automatically used for \s-1ECDH\s0 temporary
 191 keys used during key exchange.
 192 .PP
 193 All these functions are implemented as macros.
 194 .SH "NOTES"
 195 .IX Header "NOTES"
 196 If an application wishes to make use of several of these functions for
 197 configuration purposes either on a command line or in a file it should
 198 consider using the \s-1SSL_CONF\s0 interface instead of manually parsing options.
 199 .PP
 200 The functions \fISSL_CTX_set_ecdh_auto()\fR and \fISSL_set_ecdh_auto()\fR can be used to
 201 make a server always choose the most appropriate curve for a client. If set
 202 it will override any temporary \s-1ECDH\s0 parameters set by a server. Previous
 203 versions of OpenSSL could effectively only use a single \s-1ECDH\s0 curve set
 204 using a function such as \fISSL_CTX_set_ecdh_tmp()\fR. Newer applications should
 205 just call:
 206 .PP
 207 .Vb 1
 208 \& SSL_CTX_set_ecdh_auto(ctx, 1);
 209 .Ve
 210 .PP
 211 and they will automatically support \s-1ECDH\s0 using the most appropriate shared
 212 curve.
 213 .SH "RETURN VALUES"
 214 .IX Header "RETURN VALUES"
 215 \&\fISSL_CTX_set1_curves()\fR, \fISSL_CTX_set1_curves_list()\fR, \fISSL_set1_curves()\fR,
 216 \&\fISSL_set1_curves_list()\fR, \fISSL_CTX_set_ecdh_auto()\fR and \fISSL_set_ecdh_auto()\fR
 217 return 1 for success and 0 for failure.
 218 .PP
 219 \&\fISSL_get1_curves()\fR returns the number of curves, which may be zero.
 220 .PP
 221 \&\fISSL_get_shared_curve()\fR returns the \s-1NID\s0 of shared curve \fBn\fR or NID_undef if there
 222 is no shared curve \fBn\fR; or the total number of shared curves if \fBn\fR
 223 is \-1.
 224 .PP
 225 When called on a client \fBssl\fR, \fISSL_get_shared_curve()\fR has no meaning and
 226 returns \-1.
 227 .SH "SEE ALSO"
 228 .IX Header "SEE ALSO"
 229 \&\fISSL_CTX_add_extra_chain_cert\fR\|(3)
 230 .SH "HISTORY"
 231 .IX Header "HISTORY"
 232 These functions were first added to OpenSSL 1.0.2.