secure/lib/libcrypto/man/man3/EC_GROUP_new.3

   1 .\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.40)
   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 .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 "EC_GROUP_NEW 3"
 136 .TH EC_GROUP_NEW 3 "2020-03-31" "1.1.1f" "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 EC_GROUP_get_ecparameters, EC_GROUP_get_ecpkparameters, EC_GROUP_new, EC_GROUP_new_from_ecparameters, EC_GROUP_new_from_ecpkparameters, EC_GROUP_free, EC_GROUP_clear_free, EC_GROUP_new_curve_GFp, EC_GROUP_new_curve_GF2m, EC_GROUP_new_by_curve_name, EC_GROUP_set_curve, EC_GROUP_get_curve, EC_GROUP_set_curve_GFp, EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m, EC_GROUP_get_curve_GF2m, EC_get_builtin_curves \- Functions for creating and destroying EC_GROUP objects
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/ec.h>
 147 \&
 148 \& EC_GROUP *EC_GROUP_new(const EC_METHOD *meth);
 149 \& EC_GROUP *EC_GROUP_new_from_ecparameters(const ECPARAMETERS *params)
 150 \& EC_GROUP *EC_GROUP_new_from_ecpkparameters(const ECPKPARAMETERS *params)
 151 \& void EC_GROUP_free(EC_GROUP *group);
 152 \& void EC_GROUP_clear_free(EC_GROUP *group);
 153 \&
 154 \& EC_GROUP *EC_GROUP_new_curve_GFp(const BIGNUM *p, const BIGNUM *a,
 155 \&                                  const BIGNUM *b, BN_CTX *ctx);
 156 \& EC_GROUP *EC_GROUP_new_curve_GF2m(const BIGNUM *p, const BIGNUM *a,
 157 \&                                   const BIGNUM *b, BN_CTX *ctx);
 158 \& EC_GROUP *EC_GROUP_new_by_curve_name(int nid);
 159 \&
 160 \& int EC_GROUP_set_curve(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a,
 161 \&                        const BIGNUM *b, BN_CTX *ctx);
 162 \& int EC_GROUP_get_curve(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b,
 163 \&                        BN_CTX *ctx);
 164 \& int EC_GROUP_set_curve_GFp(EC_GROUP *group, const BIGNUM *p,
 165 \&                            const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);
 166 \& int EC_GROUP_get_curve_GFp(const EC_GROUP *group, BIGNUM *p,
 167 \&                            BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
 168 \& int EC_GROUP_set_curve_GF2m(EC_GROUP *group, const BIGNUM *p,
 169 \&                             const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);
 170 \& int EC_GROUP_get_curve_GF2m(const EC_GROUP *group, BIGNUM *p,
 171 \&                             BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
 172 \&
 173 \& ECPARAMETERS *EC_GROUP_get_ecparameters(const EC_GROUP *group, ECPARAMETERS *params)
 174 \& ECPKPARAMETERS *EC_GROUP_get_ecpkparameters(const EC_GROUP *group, ECPKPARAMETERS *params)
 175 \&
 176 \& size_t EC_get_builtin_curves(EC_builtin_curve *r, size_t nitems);
 177 .Ve
 178 .SH "DESCRIPTION"
 179 .IX Header "DESCRIPTION"
 180 Within the library there are two forms of elliptic curve that are of interest.
 181 The first form is those defined over the prime field Fp. The elements of Fp are
 182 the integers 0 to p\-1, where p is a prime number. This gives us a revised
 183 elliptic curve equation as follows:
 184 .PP
 185 y^2 mod p = x^3 +ax + b mod p
 186 .PP
 187 The second form is those defined over a binary field F2^m where the elements of
 188 the field are integers of length at most m bits. For this form the elliptic
 189 curve equation is modified to:
 190 .PP
 191 y^2 + xy = x^3 + ax^2 + b (where b != 0)
 192 .PP
 193 Operations in a binary field are performed relative to an \fBirreducible
 194 polynomial\fR. All such curves with OpenSSL use a trinomial or a pentanomial for
 195 this parameter.
 196 .PP
 197 A new curve can be constructed by calling \fBEC_GROUP_new()\fR, using the
 198 implementation provided by \fBmeth\fR (see \fBEC_GFp_simple_method\fR\|(3)). It is then
 199 necessary to call \fBEC_GROUP_set_curve()\fR to set the curve parameters.
 200 \&\fBEC_GROUP_new_from_ecparameters()\fR will create a group from the specified
 201 \&\fBparams\fR and \fBEC_GROUP_new_from_ecpkparameters()\fR will create a group from the
 202 specific \s-1PK\s0 \fBparams\fR.
 203 .PP
 204 \&\fBEC_GROUP_set_curve()\fR sets the curve parameters \fBp\fR, \fBa\fR and \fBb\fR. For a curve
 205 over Fp \fBp\fR is the prime for the field. For a curve over F2^m \fBp\fR represents
 206 the irreducible polynomial \- each bit represents a term in the polynomial.
 207 Therefore there will either be three or five bits set dependent on whether the
 208 polynomial is a trinomial or a pentanomial.
 209 In either case, \fBa\fR and \fBb\fR represents the coefficients a and b from the
 210 relevant equation introduced above.
 211 .PP
 212 \&\fBEC_group_get_curve()\fR obtains the previously set curve parameters.
 213 .PP
 214 \&\fBEC_GROUP_set_curve_GFp()\fR and \fBEC_GROUP_set_curve_GF2m()\fR are synonyms for
 215 \&\fBEC_GROUP_set_curve()\fR. They are defined for backwards compatibility only and
 216 should not be used.
 217 .PP
 218 \&\fBEC_GROUP_get_curve_GFp()\fR and \fBEC_GROUP_get_curve_GF2m()\fR are synonyms for
 219 \&\fBEC_GROUP_get_curve()\fR. They are defined for backwards compatibility only and
 220 should not be used.
 221 .PP
 222 The functions \fBEC_GROUP_new_curve_GFp()\fR and \fBEC_GROUP_new_curve_GF2m()\fR are
 223 shortcuts for calling \fBEC_GROUP_new()\fR and then the \fBEC_GROUP_set_curve()\fR function.
 224 An appropriate default implementation method will be used.
 225 .PP
 226 Whilst the library can be used to create any curve using the functions described
 227 above, there are also a number of predefined curves that are available. In order
 228 to obtain a list of all of the predefined curves, call the function
 229 \&\fBEC_get_builtin_curves()\fR. The parameter \fBr\fR should be an array of
 230 EC_builtin_curve structures of size \fBnitems\fR. The function will populate the
 231 \&\fBr\fR array with information about the builtin curves. If \fBnitems\fR is less than
 232 the total number of curves available, then the first \fBnitems\fR curves will be
 233 returned. Otherwise the total number of curves will be provided. The return
 234 value is the total number of curves available (whether that number has been
 235 populated in \fBr\fR or not). Passing a \s-1NULL\s0 \fBr\fR, or setting \fBnitems\fR to 0 will
 236 do nothing other than return the total number of curves available.
 237 The EC_builtin_curve structure is defined as follows:
 238 .PP
 239 .Vb 4
 240 \& typedef struct {
 241 \&        int nid;
 242 \&        const char *comment;
 243 \&        } EC_builtin_curve;
 244 .Ve
 245 .PP
 246 Each EC_builtin_curve item has a unique integer id (\fBnid\fR), and a human
 247 readable comment string describing the curve.
 248 .PP
 249 In order to construct a builtin curve use the function
 250 \&\fBEC_GROUP_new_by_curve_name()\fR and provide the \fBnid\fR of the curve to
 251 be constructed.
 252 .PP
 253 \&\fBEC_GROUP_free()\fR frees the memory associated with the \s-1EC_GROUP.\s0
 254 If \fBgroup\fR is \s-1NULL\s0 nothing is done.
 255 .PP
 256 \&\fBEC_GROUP_clear_free()\fR destroys any sensitive data held within the \s-1EC_GROUP\s0 and
 257 then frees its memory. If \fBgroup\fR is \s-1NULL\s0 nothing is done.
 258 .SH "RETURN VALUES"
 259 .IX Header "RETURN VALUES"
 260 All EC_GROUP_new* functions return a pointer to the newly constructed group, or
 261 \&\s-1NULL\s0 on error.
 262 .PP
 263 \&\fBEC_get_builtin_curves()\fR returns the number of builtin curves that are available.
 264 .PP
 265 \&\fBEC_GROUP_set_curve_GFp()\fR, \fBEC_GROUP_get_curve_GFp()\fR, \fBEC_GROUP_set_curve_GF2m()\fR,
 266 \&\fBEC_GROUP_get_curve_GF2m()\fR return 1 on success or 0 on error.
 267 .SH "SEE ALSO"
 268 .IX Header "SEE ALSO"
 269 \&\fBcrypto\fR\|(7), \fBEC_GROUP_copy\fR\|(3),
 270 \&\fBEC_POINT_new\fR\|(3), \fBEC_POINT_add\fR\|(3), \fBEC_KEY_new\fR\|(3),
 271 \&\fBEC_GFp_simple_method\fR\|(3), \fBd2i_ECPKParameters\fR\|(3)
 272 .SH "COPYRIGHT"
 273 .IX Header "COPYRIGHT"
 274 Copyright 2013\-2019 The OpenSSL Project Authors. All Rights Reserved.
 275 .PP
 276 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 277 this file except in compliance with the License.  You can obtain a copy
 278 in the file \s-1LICENSE\s0 in the source distribution or at
 279 <https://www.openssl.org/source/license.html>.