secure/lib/libcrypto/man/man3/EC_POINT_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_POINT_NEW 3"
 136 .TH EC_POINT_NEW 3 "2020-03-17" "1.1.1e" "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_POINT_set_Jprojective_coordinates_GFp, EC_POINT_point2buf, EC_POINT_new, EC_POINT_free, EC_POINT_clear_free, EC_POINT_copy, EC_POINT_dup, EC_POINT_method_of, EC_POINT_set_to_infinity, EC_POINT_get_Jprojective_coordinates_GFp, EC_POINT_set_affine_coordinates, EC_POINT_get_affine_coordinates, EC_POINT_set_compressed_coordinates, EC_POINT_set_affine_coordinates_GFp, EC_POINT_get_affine_coordinates_GFp, EC_POINT_set_compressed_coordinates_GFp, EC_POINT_set_affine_coordinates_GF2m, EC_POINT_get_affine_coordinates_GF2m, EC_POINT_set_compressed_coordinates_GF2m, EC_POINT_point2oct, EC_POINT_oct2point, EC_POINT_point2bn, EC_POINT_bn2point, EC_POINT_point2hex, EC_POINT_hex2point \&\- Functions for creating, destroying and manipulating EC_POINT objects
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/ec.h>
 147 \&
 148 \& EC_POINT *EC_POINT_new(const EC_GROUP *group);
 149 \& void EC_POINT_free(EC_POINT *point);
 150 \& void EC_POINT_clear_free(EC_POINT *point);
 151 \& int EC_POINT_copy(EC_POINT *dst, const EC_POINT *src);
 152 \& EC_POINT *EC_POINT_dup(const EC_POINT *src, const EC_GROUP *group);
 153 \& const EC_METHOD *EC_POINT_method_of(const EC_POINT *point);
 154 \& int EC_POINT_set_to_infinity(const EC_GROUP *group, EC_POINT *point);
 155 \& int EC_POINT_set_Jprojective_coordinates_GFp(const EC_GROUP *group,
 156 \&                                              EC_POINT *p,
 157 \&                                              const BIGNUM *x, const BIGNUM *y,
 158 \&                                              const BIGNUM *z, BN_CTX *ctx);
 159 \& int EC_POINT_get_Jprojective_coordinates_GFp(const EC_GROUP *group,
 160 \&                                              const EC_POINT *p,
 161 \&                                              BIGNUM *x, BIGNUM *y, BIGNUM *z,
 162 \&                                              BN_CTX *ctx);
 163 \& int EC_POINT_set_affine_coordinates(const EC_GROUP *group, EC_POINT *p,
 164 \&                                     const BIGNUM *x, const BIGNUM *y,
 165 \&                                     BN_CTX *ctx);
 166 \& int EC_POINT_get_affine_coordinates(const EC_GROUP *group, const EC_POINT *p,
 167 \&                                     BIGNUM *x, BIGNUM *y, BN_CTX *ctx);
 168 \& int EC_POINT_set_compressed_coordinates(const EC_GROUP *group, EC_POINT *p,
 169 \&                                         const BIGNUM *x, int y_bit,
 170 \&                                         BN_CTX *ctx);
 171 \& int EC_POINT_set_affine_coordinates_GFp(const EC_GROUP *group, EC_POINT *p,
 172 \&                                         const BIGNUM *x, const BIGNUM *y,
 173 \&                                         BN_CTX *ctx);
 174 \& int EC_POINT_get_affine_coordinates_GFp(const EC_GROUP *group,
 175 \&                                         const EC_POINT *p,
 176 \&                                         BIGNUM *x, BIGNUM *y, BN_CTX *ctx);
 177 \& int EC_POINT_set_compressed_coordinates_GFp(const EC_GROUP *group,
 178 \&                                             EC_POINT *p,
 179 \&                                             const BIGNUM *x, int y_bit,
 180 \&                                             BN_CTX *ctx);
 181 \& int EC_POINT_set_affine_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p,
 182 \&                                          const BIGNUM *x, const BIGNUM *y,
 183 \&                                          BN_CTX *ctx);
 184 \& int EC_POINT_get_affine_coordinates_GF2m(const EC_GROUP *group,
 185 \&                                          const EC_POINT *p,
 186 \&                                          BIGNUM *x, BIGNUM *y, BN_CTX *ctx);
 187 \& int EC_POINT_set_compressed_coordinates_GF2m(const EC_GROUP *group,
 188 \&                                              EC_POINT *p,
 189 \&                                              const BIGNUM *x, int y_bit,
 190 \&                                              BN_CTX *ctx);
 191 \& size_t EC_POINT_point2oct(const EC_GROUP *group, const EC_POINT *p,
 192 \&                           point_conversion_form_t form,
 193 \&                           unsigned char *buf, size_t len, BN_CTX *ctx);
 194 \& size_t EC_POINT_point2buf(const EC_GROUP *group, const EC_POINT *point,
 195 \&                           point_conversion_form_t form,
 196 \&                           unsigned char **pbuf, BN_CTX *ctx);
 197 \& int EC_POINT_oct2point(const EC_GROUP *group, EC_POINT *p,
 198 \&                        const unsigned char *buf, size_t len, BN_CTX *ctx);
 199 \& BIGNUM *EC_POINT_point2bn(const EC_GROUP *group, const EC_POINT *p,
 200 \&                           point_conversion_form_t form, BIGNUM *bn,
 201 \&                           BN_CTX *ctx);
 202 \& EC_POINT *EC_POINT_bn2point(const EC_GROUP *group, const BIGNUM *bn,
 203 \&                             EC_POINT *p, BN_CTX *ctx);
 204 \& char *EC_POINT_point2hex(const EC_GROUP *group, const EC_POINT *p,
 205 \&                          point_conversion_form_t form, BN_CTX *ctx);
 206 \& EC_POINT *EC_POINT_hex2point(const EC_GROUP *group, const char *hex,
 207 \&                              EC_POINT *p, BN_CTX *ctx);
 208 .Ve
 209 .SH "DESCRIPTION"
 210 .IX Header "DESCRIPTION"
 211 An \fB\s-1EC_POINT\s0\fR structure represents a point on a curve. A new point is
 212 constructed by calling the function \fBEC_POINT_new()\fR and providing the
 213 \&\fBgroup\fR object that the point relates to.
 214 .PP
 215 \&\fBEC_POINT_free()\fR frees the memory associated with the \fB\s-1EC_POINT\s0\fR.
 216 if \fBpoint\fR is \s-1NULL\s0 nothing is done.
 217 .PP
 218 \&\fBEC_POINT_clear_free()\fR destroys any sensitive data held within the \s-1EC_POINT\s0 and
 219 then frees its memory. If \fBpoint\fR is \s-1NULL\s0 nothing is done.
 220 .PP
 221 \&\fBEC_POINT_copy()\fR copies the point \fBsrc\fR into \fBdst\fR. Both \fBsrc\fR and \fBdst\fR
 222 must use the same \fB\s-1EC_METHOD\s0\fR.
 223 .PP
 224 \&\fBEC_POINT_dup()\fR creates a new \fB\s-1EC_POINT\s0\fR object and copies the content from
 225 \&\fBsrc\fR to the newly created \fB\s-1EC_POINT\s0\fR object.
 226 .PP
 227 \&\fBEC_POINT_method_of()\fR obtains the \fB\s-1EC_METHOD\s0\fR associated with \fBpoint\fR.
 228 .PP
 229 A valid point on a curve is the special point at infinity. A point is set to
 230 be at infinity by calling \fBEC_POINT_set_to_infinity()\fR.
 231 .PP
 232 The affine co-ordinates for a point describe a point in terms of its x and y
 233 position. The function \fBEC_POINT_set_affine_coordinates()\fR sets the \fBx\fR and \fBy\fR
 234 co-ordinates for the point \fBp\fR defined over the curve given in \fBgroup\fR. The
 235 function \fBEC_POINT_get_affine_coordinates()\fR sets \fBx\fR and \fBy\fR, either of which
 236 may be \s-1NULL,\s0 to the corresponding coordinates of \fBp\fR.
 237 .PP
 238 The functions \fBEC_POINT_set_affine_coordinates_GFp()\fR and
 239 \&\fBEC_POINT_set_affine_coordinates_GF2m()\fR are synonyms for
 240 \&\fBEC_POINT_set_affine_coordinates()\fR. They are defined for backwards compatibility
 241 only and should not be used.
 242 .PP
 243 The functions \fBEC_POINT_get_affine_coordinates_GFp()\fR and
 244 \&\fBEC_POINT_get_affine_coordinates_GF2m()\fR are synonyms for
 245 \&\fBEC_POINT_get_affine_coordinates()\fR. They are defined for backwards compatibility
 246 only and should not be used.
 247 .PP
 248 As well as the affine co-ordinates, a point can alternatively be described in
 249 terms of its Jacobian projective co-ordinates (for Fp curves only). Jacobian
 250 projective co-ordinates are expressed as three values x, y and z. Working in
 251 this co-ordinate system provides more efficient point multiplication
 252 operations.  A mapping exists between Jacobian projective co-ordinates and
 253 affine co-ordinates. A Jacobian projective co-ordinate (x, y, z) can be written
 254 as an affine co-ordinate as (x/(z^2), y/(z^3)). Conversion to Jacobian
 255 projective from affine co-ordinates is simple. The co-ordinate (x, y) is mapped
 256 to (x, y, 1). To set or get the projective co-ordinates use
 257 \&\fBEC_POINT_set_Jprojective_coordinates_GFp()\fR and
 258 \&\fBEC_POINT_get_Jprojective_coordinates_GFp()\fR respectively.
 259 .PP
 260 Points can also be described in terms of their compressed co-ordinates. For a
 261 point (x, y), for any given value for x such that the point is on the curve
 262 there will only ever be two possible values for y. Therefore a point can be set
 263 using the \fBEC_POINT_set_compressed_coordinates()\fR function where \fBx\fR is the x
 264 co-ordinate and \fBy_bit\fR is a value 0 or 1 to identify which of the two
 265 possible values for y should be used.
 266 .PP
 267 The functions \fBEC_POINT_set_compressed_coordinates_GFp()\fR and
 268 \&\fBEC_POINT_set_compressed_coordinates_GF2m()\fR are synonyms for
 269 \&\fBEC_POINT_set_compressed_coordinates()\fR. They are defined for backwards
 270 compatibility only and should not be used.
 271 .PP
 272 In addition \fB\s-1EC_POINT\s0\fR can be converted to and from various external
 273 representations. The octet form is the binary encoding of the \fBECPoint\fR
 274 structure (as defined in \s-1RFC5480\s0 and used in certificates and \s-1TLS\s0 records):
 275 only the content octets are present, the \fB\s-1OCTET STRING\s0\fR tag and length are
 276 not included. \fB\s-1BIGNUM\s0\fR form is the octet form interpreted as a big endian
 277 integer converted to a \fB\s-1BIGNUM\s0\fR structure. Hexadecimal form is the octet
 278 form converted to a \s-1NULL\s0 terminated character string where each character
 279 is one of the printable values 0\-9 or A\-F (or a\-f).
 280 .PP
 281 The functions \fBEC_POINT_point2oct()\fR, \fBEC_POINT_oct2point()\fR, \fBEC_POINT_point2bn()\fR,
 282 \&\fBEC_POINT_bn2point()\fR, \fBEC_POINT_point2hex()\fR and \fBEC_POINT_hex2point()\fR convert from
 283 and to EC_POINTs for the formats: octet, \s-1BIGNUM\s0 and hexadecimal respectively.
 284 .PP
 285 The function \fBEC_POINT_point2oct()\fR encodes the given curve point \fBp\fR as an
 286 octet string into the buffer \fBbuf\fR of size \fBlen\fR, using the specified
 287 conversion form \fBform\fR.
 288 The encoding conforms with Sec. 2.3.3 of the \s-1SECG SEC 1\s0 (\*(L"Elliptic Curve
 289 Cryptography\*(R") standard.
 290 Similarly the function \fBEC_POINT_oct2point()\fR decodes a curve point into \fBp\fR from
 291 the octet string contained in the given buffer \fBbuf\fR of size \fBlen\fR, conforming
 292 to Sec. 2.3.4 of the \s-1SECG SEC 1\s0 (\*(L"Elliptic Curve Cryptography\*(R") standard.
 293 .PP
 294 The functions \fBEC_POINT_point2hex()\fR and \fBEC_POINT_point2bn()\fR convert a point \fBp\fR,
 295 respectively, to the hexadecimal or \s-1BIGNUM\s0 representation of the same
 296 encoding of the function \fBEC_POINT_point2oct()\fR.
 297 Vice versa, similarly to the function \fBEC_POINT_oct2point()\fR, the functions
 298 \&\fBEC_POINT_hex2point()\fR and \fBEC_POINT_point2bn()\fR decode the hexadecimal or
 299 \&\s-1BIGNUM\s0 representation into the \s-1EC_POINT\s0 \fBp\fR.
 300 .PP
 301 Notice that, according to the standard, the octet string encoding of the point
 302 at infinity for a given curve is fixed to a single octet of value zero and that,
 303 vice versa, a single octet of size zero is decoded as the point at infinity.
 304 .PP
 305 The function \fBEC_POINT_point2oct()\fR must be supplied with a buffer long enough to
 306 store the octet form. The return value provides the number of octets stored.
 307 Calling the function with a \s-1NULL\s0 buffer will not perform the conversion but
 308 will still return the required buffer length.
 309 .PP
 310 The function \fBEC_POINT_point2buf()\fR allocates a buffer of suitable length and
 311 writes an \s-1EC_POINT\s0 to it in octet format. The allocated buffer is written to
 312 \&\fB*pbuf\fR and its length is returned. The caller must free up the allocated
 313 buffer with a call to \fBOPENSSL_free()\fR. Since the allocated buffer value is
 314 written to \fB*pbuf\fR the \fBpbuf\fR parameter \fB\s-1MUST NOT\s0\fR be \fB\s-1NULL\s0\fR.
 315 .PP
 316 The function \fBEC_POINT_point2hex()\fR will allocate sufficient memory to store the
 317 hexadecimal string. It is the caller's responsibility to free this memory with
 318 a subsequent call to \fBOPENSSL_free()\fR.
 319 .SH "RETURN VALUES"
 320 .IX Header "RETURN VALUES"
 321 \&\fBEC_POINT_new()\fR and \fBEC_POINT_dup()\fR return the newly allocated \s-1EC_POINT\s0 or \s-1NULL\s0
 322 on error.
 323 .PP
 324 The following functions return 1 on success or 0 on error: \fBEC_POINT_copy()\fR,
 325 \&\fBEC_POINT_set_to_infinity()\fR, \fBEC_POINT_set_Jprojective_coordinates_GFp()\fR,
 326 \&\fBEC_POINT_get_Jprojective_coordinates_GFp()\fR,
 327 \&\fBEC_POINT_set_affine_coordinates_GFp()\fR, \fBEC_POINT_get_affine_coordinates_GFp()\fR,
 328 \&\fBEC_POINT_set_compressed_coordinates_GFp()\fR,
 329 \&\fBEC_POINT_set_affine_coordinates_GF2m()\fR, \fBEC_POINT_get_affine_coordinates_GF2m()\fR,
 330 \&\fBEC_POINT_set_compressed_coordinates_GF2m()\fR and \fBEC_POINT_oct2point()\fR.
 331 .PP
 332 EC_POINT_method_of returns the \s-1EC_METHOD\s0 associated with the supplied \s-1EC_POINT.\s0
 333 .PP
 334 \&\fBEC_POINT_point2oct()\fR and \fBEC_POINT_point2buf()\fR return the length of the required
 335 buffer or 0 on error.
 336 .PP
 337 \&\fBEC_POINT_point2bn()\fR returns the pointer to the \s-1BIGNUM\s0 supplied, or \s-1NULL\s0 on
 338 error.
 339 .PP
 340 \&\fBEC_POINT_bn2point()\fR returns the pointer to the \s-1EC_POINT\s0 supplied, or \s-1NULL\s0 on
 341 error.
 342 .PP
 343 \&\fBEC_POINT_point2hex()\fR returns a pointer to the hex string, or \s-1NULL\s0 on error.
 344 .PP
 345 \&\fBEC_POINT_hex2point()\fR returns the pointer to the \s-1EC_POINT\s0 supplied, or \s-1NULL\s0 on
 346 error.
 347 .SH "SEE ALSO"
 348 .IX Header "SEE ALSO"
 349 \&\fBcrypto\fR\|(7), \fBEC_GROUP_new\fR\|(3), \fBEC_GROUP_copy\fR\|(3),
 350 \&\fBEC_POINT_add\fR\|(3), \fBEC_KEY_new\fR\|(3),
 351 \&\fBEC_GFp_simple_method\fR\|(3), \fBd2i_ECPKParameters\fR\|(3)
 352 .SH "COPYRIGHT"
 353 .IX Header "COPYRIGHT"
 354 Copyright 2013\-2018 The OpenSSL Project Authors. All Rights Reserved.
 355 .PP
 356 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 357 this file except in compliance with the License.  You can obtain a copy
 358 in the file \s-1LICENSE\s0 in the source distribution or at
 359 <https://www.openssl.org/source/license.html>.