secure/lib/libssl/man/SSL_CTX_set1_curves.3

   1 .\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
   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 turned on, 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 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{
  60 .    if \nF \{
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "SSL_CTX_set1_curves 3"
 136 .TH SSL_CTX_set1_curves 3 "2016-05-03" "1.0.2h" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 SSL_CTX_set1_curves, SSL_CTX_set1_curves_list, SSL_set1_curves,
 143 SSL_set1_curves_list, SSL_get1_curves, SSL_get_shared_curve,
 144 SSL_CTX_set_ecdh_auto, SSL_set_ecdh_auto \- EC supported curve functions
 145 .SH "SYNOPSIS"
 146 .IX Header "SYNOPSIS"
 147 .Vb 1
 148 \& #include <openssl/ssl.h>
 149 \&
 150 \& int SSL_CTX_set1_curves(SSL_CTX *ctx, int *clist, int clistlen);
 151 \& int SSL_CTX_set1_curves_list(SSL_CTX *ctx, char *list);
 152 \&
 153 \& int SSL_set1_curves(SSL *ssl, int *clist, int clistlen);
 154 \& int SSL_set1_curves_list(SSL *ssl, char *list);
 155 \&
 156 \& int SSL_get1_curves(SSL *ssl, int *curves);
 157 \& int SSL_get_shared_curve(SSL *s, int n);
 158 \&
 159 \& int SSL_CTX_set_ecdh_auto(SSL_CTX *ctx, int onoff);
 160 \& int SSL_set_ecdh_auto(SSL *s, int onoff);
 161 .Ve
 162 .SH "DESCRIPTION"
 163 .IX Header "DESCRIPTION"
 164 \&\fISSL_CTX_set1_curves()\fR sets the supported curves for \fBctx\fR to \fBclistlen\fR
 165 curves in the array \fBclist\fR. The array consist of all NIDs of curves in
 166 preference order. For a \s-1TLS\s0 client the curves are used directly in the
 167 supported curves extension. For a \s-1TLS\s0 server the curves are used to
 168 determine the set of shared curves.
 169 .PP
 170 \&\fISSL_CTX_set1_curves_list()\fR sets the supported curves for \fBctx\fR to
 171 string \fBlist\fR. The string is a colon separated list of curve NIDs or
 172 names, for example \*(L"P\-521:P\-384:P\-256\*(R".
 173 .PP
 174 \&\fISSL_set1_curves()\fR and \fISSL_set1_curves_list()\fR are similar except they set
 175 supported curves for the \s-1SSL\s0 structure \fBssl\fR.
 176 .PP
 177 \&\fISSL_get1_curves()\fR returns the set of supported curves sent by a client
 178 in the supported curves extension. It returns the total number of
 179 supported curves. The \fBcurves\fR parameter can be \fB\s-1NULL\s0\fR to simply
 180 return the number of curves for memory allocation purposes. The
 181 \&\fBcurves\fR array is in the form of a set of curve NIDs in preference
 182 order. It can return zero if the client did not send a supported curves
 183 extension.
 184 .PP
 185 \&\fISSL_get_shared_curve()\fR returns shared curve \fBn\fR for a server-side
 186 \&\s-1SSL \s0\fBssl\fR. If \fBn\fR is \-1 then the total number of shared curves is
 187 returned, which may be zero. Other than for diagnostic purposes,
 188 most applications will only be interested in the first shared curve
 189 so \fBn\fR is normally set to zero. If the value \fBn\fR is out of range,
 190 NID_undef is returned.
 191 .PP
 192 \&\fISSL_CTX_set_ecdh_auto()\fR and \fISSL_set_ecdh_auto()\fR set automatic curve
 193 selection for server \fBctx\fR or \fBssl\fR to \fBonoff\fR. If \fBonoff\fR is 1 then
 194 the highest preference curve is automatically used for \s-1ECDH\s0 temporary
 195 keys used during key exchange.
 196 .PP
 197 All these functions are implemented as macros.
 198 .SH "NOTES"
 199 .IX Header "NOTES"
 200 If an application wishes to make use of several of these functions for
 201 configuration purposes either on a command line or in a file it should
 202 consider using the \s-1SSL_CONF\s0 interface instead of manually parsing options.
 203 .PP
 204 The functions \fISSL_CTX_set_ecdh_auto()\fR and \fISSL_set_ecdh_auto()\fR can be used to
 205 make a server always choose the most appropriate curve for a client. If set
 206 it will override any temporary \s-1ECDH\s0 parameters set by a server. Previous
 207 versions of OpenSSL could effectively only use a single \s-1ECDH\s0 curve set
 208 using a function such as \fISSL_CTX_set_ecdh_tmp()\fR. Newer applications should
 209 just call:
 210 .PP
 211 .Vb 1
 212 \& SSL_CTX_set_ecdh_auto(ctx, 1);
 213 .Ve
 214 .PP
 215 and they will automatically support \s-1ECDH\s0 using the most appropriate shared
 216 curve.
 217 .SH "RETURN VALUES"
 218 .IX Header "RETURN VALUES"
 219 \&\fISSL_CTX_set1_curves()\fR, \fISSL_CTX_set1_curves_list()\fR, \fISSL_set1_curves()\fR,
 220 \&\fISSL_set1_curves_list()\fR, \fISSL_CTX_set_ecdh_auto()\fR and \fISSL_set_ecdh_auto()\fR
 221 return 1 for success and 0 for failure.
 222 .PP
 223 \&\fISSL_get1_curves()\fR returns the number of curves, which may be zero.
 224 .PP
 225 \&\fISSL_get_shared_curve()\fR returns the \s-1NID\s0 of shared curve \fBn\fR or NID_undef if there
 226 is no shared curve \fBn\fR; or the total number of shared curves if \fBn\fR
 227 is \-1.
 228 .PP
 229 When called on a client \fBssl\fR, \fISSL_get_shared_curve()\fR has no meaning and
 230 returns \-1.
 231 .SH "SEE ALSO"
 232 .IX Header "SEE ALSO"
 233 \&\fISSL_CTX_add_extra_chain_cert\fR\|(3)
 234 .SH "HISTORY"
 235 .IX Header "HISTORY"
 236 These functions were first added to OpenSSL 1.0.2.