1.\" $OpenBSD: EC_POINT_new.3,v 1.13 2021/05/13 05:52:28 tb Exp $ 2.\" full merge up to: OpenSSL 50db8163 Jul 30 16:56:41 2018 +0100 3.\" 4.\" This file was written by Matt Caswell <matt@openssl.org>. 5.\" Copyright (c) 2013, 2016 The OpenSSL Project. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in 16.\" the documentation and/or other materials provided with the 17.\" distribution. 18.\" 19.\" 3. All advertising materials mentioning features or use of this 20.\" software must display the following acknowledgment: 21.\" "This product includes software developed by the OpenSSL Project 22.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 23.\" 24.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 25.\" endorse or promote products derived from this software without 26.\" prior written permission. For written permission, please contact 27.\" openssl-core@openssl.org. 28.\" 29.\" 5. Products derived from this software may not be called "OpenSSL" 30.\" nor may "OpenSSL" appear in their names without prior written 31.\" permission of the OpenSSL Project. 32.\" 33.\" 6. Redistributions of any form whatsoever must retain the following 34.\" acknowledgment: 35.\" "This product includes software developed by the OpenSSL Project 36.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 37.\" 38.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 39.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 40.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 41.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 42.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 43.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 44.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 45.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 46.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 47.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 48.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 49.\" OF THE POSSIBILITY OF SUCH DAMAGE. 50.\" 51.Dd $Mdocdate: May 13 2021 $ 52.Dt EC_POINT_NEW 3 53.Os 54.Sh NAME 55.Nm EC_POINT_new , 56.Nm EC_POINT_free , 57.Nm EC_POINT_clear_free , 58.Nm EC_POINT_copy , 59.Nm EC_POINT_dup , 60.Nm EC_POINT_method_of , 61.Nm EC_POINT_set_to_infinity , 62.Nm EC_POINT_set_affine_coordinates , 63.Nm EC_POINT_set_affine_coordinates_GFp , 64.Nm EC_POINT_set_affine_coordinates_GF2m , 65.Nm EC_POINT_get_affine_coordinates , 66.Nm EC_POINT_get_affine_coordinates_GFp , 67.Nm EC_POINT_get_affine_coordinates_GF2m , 68.Nm EC_POINT_set_Jprojective_coordinates_GFp , 69.Nm EC_POINT_get_Jprojective_coordinates_GFp , 70.Nm EC_POINT_set_compressed_coordinates , 71.Nm EC_POINT_set_compressed_coordinates_GFp , 72.Nm EC_POINT_set_compressed_coordinates_GF2m , 73.Nm EC_POINT_point2oct , 74.Nm EC_POINT_oct2point , 75.Nm EC_POINT_point2bn , 76.Nm EC_POINT_bn2point , 77.Nm EC_POINT_point2hex , 78.Nm EC_POINT_hex2point 79.Nd create, destroy, and manipulate EC_POINT objects 80.Sh SYNOPSIS 81.In openssl/ec.h 82.In openssl/bn.h 83.Ft EC_POINT * 84.Fo EC_POINT_new 85.Fa "const EC_GROUP *group" 86.Fc 87.Ft void 88.Fo EC_POINT_free 89.Fa "EC_POINT *point" 90.Fc 91.Ft void 92.Fo EC_POINT_clear_free 93.Fa "EC_POINT *point" 94.Fc 95.Ft int 96.Fo EC_POINT_copy 97.Fa "EC_POINT *dst" 98.Fa "const EC_POINT *src" 99.Fc 100.Ft EC_POINT * 101.Fo EC_POINT_dup 102.Fa "const EC_POINT *src" 103.Fa "const EC_GROUP *group" 104.Fc 105.Ft const EC_METHOD * 106.Fo EC_POINT_method_of 107.Fa "const EC_POINT *point" 108.Fc 109.Ft int 110.Fo EC_POINT_set_to_infinity 111.Fa "const EC_GROUP *group" 112.Fa "EC_POINT *point" 113.Fc 114.Ft int 115.Fo EC_POINT_set_affine_coordinates 116.Fa "const EC_GROUP *group" 117.Fa "EC_POINT *p" 118.Fa "const BIGNUM *x" 119.Fa "const BIGNUM *y" 120.Fa "BN_CTX *ctx" 121.Fc 122.Ft int 123.Fo EC_POINT_set_affine_coordinates_GFp 124.Fa "const EC_GROUP *group" 125.Fa "EC_POINT *p" 126.Fa "const BIGNUM *x" 127.Fa "const BIGNUM *y" 128.Fa "BN_CTX *ctx" 129.Fc 130.Ft int 131.Fo EC_POINT_set_affine_coordinates_GF2m 132.Fa "const EC_GROUP *group" 133.Fa "EC_POINT *p" 134.Fa "const BIGNUM *x" 135.Fa "const BIGNUM *y" 136.Fa "BN_CTX *ctx" 137.Fc 138.Ft int 139.Fo EC_POINT_get_affine_coordinates 140.Fa "const EC_GROUP *group" 141.Fa "const EC_POINT *p" 142.Fa "BIGNUM *x" 143.Fa "BIGNUM *y" 144.Fa "BN_CTX *ctx" 145.Fc 146.Ft int 147.Fo EC_POINT_get_affine_coordinates_GFp 148.Fa "const EC_GROUP *group" 149.Fa "const EC_POINT *p" 150.Fa "BIGNUM *x" 151.Fa "BIGNUM *y" 152.Fa "BN_CTX *ctx" 153.Fc 154.Ft int 155.Fo EC_POINT_get_affine_coordinates_GF2m 156.Fa "const EC_GROUP *group" 157.Fa "const EC_POINT *p" 158.Fa "BIGNUM *x" 159.Fa "BIGNUM *y" 160.Fa "BN_CTX *ctx" 161.Fc 162.Ft int 163.Fo EC_POINT_set_Jprojective_coordinates_GFp 164.Fa "const EC_GROUP *group" 165.Fa "EC_POINT *p" 166.Fa "const BIGNUM *x" 167.Fa "const BIGNUM *y" 168.Fa "const BIGNUM *z" 169.Fa "BN_CTX *ctx" 170.Fc 171.Ft int 172.Fo EC_POINT_get_Jprojective_coordinates_GFp 173.Fa "const EC_GROUP *group" 174.Fa "const EC_POINT *p" 175.Fa "BIGNUM *x" 176.Fa "BIGNUM *y" 177.Fa "BIGNUM *z" 178.Fa "BN_CTX *ctx" 179.Fc 180.Ft int 181.Fo EC_POINT_set_compressed_coordinates 182.Fa "const EC_GROUP *group" 183.Fa "EC_POINT *p" 184.Fa "const BIGNUM *x" 185.Fa "int y_bit" 186.Fa "BN_CTX *ctx" 187.Fc 188.Ft int 189.Fo EC_POINT_set_compressed_coordinates_GFp 190.Fa "const EC_GROUP *group" 191.Fa "EC_POINT *p" 192.Fa "const BIGNUM *x" 193.Fa "int y_bit" 194.Fa "BN_CTX *ctx" 195.Fc 196.Ft int 197.Fo EC_POINT_set_compressed_coordinates_GF2m 198.Fa "const EC_GROUP *group" 199.Fa "EC_POINT *p" 200.Fa "const BIGNUM *x" 201.Fa "int y_bit" 202.Fa "BN_CTX *ctx" 203.Fc 204.Ft size_t 205.Fo EC_POINT_point2oct 206.Fa "const EC_GROUP *group" 207.Fa "const EC_POINT *p" 208.Fa "point_conversion_form_t form" 209.Fa "unsigned char *buf" 210.Fa "size_t len" 211.Fa "BN_CTX *ctx" 212.Fc 213.Ft int 214.Fo EC_POINT_oct2point 215.Fa "const EC_GROUP *group" 216.Fa "EC_POINT *p" 217.Fa "const unsigned char *buf" 218.Fa "size_t len" 219.Fa "BN_CTX *ctx" 220.Fc 221.Ft BIGNUM * 222.Fo EC_POINT_point2bn 223.Fa "const EC_GROUP *" 224.Fa "const EC_POINT *" 225.Fa "point_conversion_form_t form" 226.Fa "BIGNUM *" 227.Fa "BN_CTX *" 228.Fc 229.Ft EC_POINT * 230.Fo EC_POINT_bn2point 231.Fa "const EC_GROUP *" 232.Fa "const BIGNUM *" 233.Fa "EC_POINT *" 234.Fa "BN_CTX *" 235.Fc 236.Ft char * 237.Fo EC_POINT_point2hex 238.Fa "const EC_GROUP *" 239.Fa "const EC_POINT *" 240.Fa "point_conversion_form_t form" 241.Fa "BN_CTX *" 242.Fc 243.Ft EC_POINT * 244.Fo EC_POINT_hex2point 245.Fa "const EC_GROUP *" 246.Fa "const char *" 247.Fa "EC_POINT *" 248.Fa "BN_CTX *" 249.Fc 250.Sh DESCRIPTION 251An 252.Vt EC_POINT 253represents a point on a curve. 254A curve is represented by an 255.Vt EC_GROUP 256object created by the functions described in 257.Xr EC_GROUP_new 3 . 258.Pp 259A new point is constructed by calling the function 260.Fn EC_POINT_new 261and providing the 262.Fa group 263object that the point relates to. 264.Pp 265.Fn EC_POINT_free 266frees the memory associated with the 267.Vt EC_POINT . 268If 269.Fa point 270is a 271.Dv NULL 272pointer, no action occurs. 273.Pp 274.Fn EC_POINT_clear_free 275destroys any sensitive data held within the 276.Vt EC_POINT 277and then frees its memory. 278If 279.Fa point 280is a 281.Dv NULL 282pointer, no action occurs. 283.Pp 284.Fn EC_POINT_copy 285copies the point 286.Fa src 287into 288.Fa dst . 289Both 290.Fa src 291and 292.Fa dst 293must use the same 294.Vt EC_METHOD . 295.Pp 296.Fn EC_POINT_dup 297creates a new 298.Vt EC_POINT 299object and copies the content from 300.Fa src 301to the newly created 302.Vt EC_POINT 303object. 304.Pp 305.Fn EC_POINT_method_of 306obtains the 307.Vt EC_METHOD 308associated with 309.Fa point . 310.Pp 311A valid point on a curve is the special point at infinity. 312A point is set to be at infinity by calling 313.Fn EC_POINT_set_to_infinity . 314.Pp 315The affine coordinates for a point describe a point in terms of its 316.Fa x 317and 318.Fa y 319position. 320The function 321.Fn EC_POINT_set_affine_coordinates 322sets the 323.Fa x 324and 325.Fa y 326coordinates for the point 327.Fa p 328defined over the curve given in 329.Fa group . 330The function 331.Fn EC_POINT_get_affine_coordinates 332sets 333.Fa x 334and 335.Fa y , 336either of which may be 337.Dv NULL , 338to the corresponding coordinates of 339.Fa p . 340.Pp 341The functions 342.Fn EC_POINT_set_affine_coordinates_GFp 343and 344.Fn EC_POINT_set_affine_coordinates_GF2m 345are deprecated synonyms for 346.Fn EC_POINT_set_affine_coordinates 347and the functions 348.Fn EC_POINT_get_affine_coordinates_GFp 349and 350.Fn EC_POINT_get_affine_coordinates_GF2m 351are deprecated synonyms for 352.Fn EC_POINT_get_affine_coordinates . 353.Pp 354As well as the affine coordinates, a point can alternatively be 355described in terms of its Jacobian projective coordinates (for Fp 356curves only). 357Jacobian projective coordinates are expressed as three values 358.Fa x , 359.Fa y , 360and 361.Fa z . 362Working in this coordinate system provides more efficient point 363multiplication operations. 364A mapping exists between Jacobian projective coordinates and affine 365coordinates. 366A Jacobian projective coordinate 367.Pq Fa x , y , z 368can be written as an affine coordinate as 369.Pp 370.Dl (x/(z^2), y/(z^3)) . 371.Pp 372Conversion to Jacobian projective from affine coordinates is simple. 373The coordinate 374.Pq Fa x , y 375is mapped to 376.Pq Fa x , y , No 1 . 377To set or get the projective coordinates use 378.Fn EC_POINT_set_Jprojective_coordinates_GFp 379and 380.Fn EC_POINT_get_Jprojective_coordinates_GFp , 381respectively. 382.Pp 383Points can also be described in terms of their compressed coordinates. 384For a point 385.Pq Fa x , y , 386for any given value for 387.Fa x 388such that the point is on the curve, there will only ever be two 389possible values for 390.Fa y . 391Therefore, a point can be set using the 392.Fn EC_POINT_set_compressed_coordinates 393function where 394.Fa x 395is the x coordinate and 396.Fa y_bit 397is a value 0 or 1 to identify which of the two possible values for y 398should be used. 399.Pp 400The functions 401.Fn EC_POINT_set_compressed_coordinates_GFp 402and 403.Fn EC_POINT_set_compressed_coordinates_GF2m 404are deprecated synonyms for 405.Fn EC_POINT_set_compressed_coordinates . 406.Pp 407In addition 408.Vt EC_POINT Ns s 409can be converted to and from various external representations. 410Supported representations are octet strings, 411.Vt BIGNUM Ns s , 412and hexadecimal. 413The format of the external representation is described by the 414point_conversion_form. 415See 416.Xr EC_GROUP_copy 3 417for a description of point_conversion_form. 418Octet strings are stored in a buffer along with an associated buffer 419length. 420A point held in a 421.Vt BIGNUM 422is calculated by converting the point to an octet string and then 423converting that octet string into a 424.Vt BIGNUM 425integer. 426Points in hexadecimal format are stored in a NUL terminated character 427string where each character is one of the printable values 0-9 or A-F 428(or a-f). 429.Pp 430The functions 431.Fn EC_POINT_point2oct , 432.Fn EC_POINT_oct2point , 433.Fn EC_POINT_point2bn , 434.Fn EC_POINT_bn2point , 435.Fn EC_POINT_point2hex , 436and 437.Fn EC_POINT_hex2point 438convert from and to 439.Vt EC_POINT Ns s 440for the formats octet string, 441.Vt BIGNUM , 442and hexadecimal, respectively. 443.Pp 444The function 445.Fn EC_POINT_point2oct 446must be supplied with a 447.Fa buf 448long enough to store the octet string. 449The return value provides the number of octets stored. 450Calling the function with a 451.Dv NULL 452.Fa buf 453will not perform the conversion but will still return the required 454buffer length. 455.Pp 456The function 457.Fn EC_POINT_point2hex 458will allocate sufficient memory to store the hexadecimal string. 459It is the caller's responsibility to free this memory with a subsequent 460call to 461.Xr free 3 . 462.Sh RETURN VALUES 463.Fn EC_POINT_new 464and 465.Fn EC_POINT_dup 466return the newly allocated 467.Vt EC_POINT 468or 469.Dv NULL 470on error. 471.Pp 472The following functions return 1 on success or 0 on error: 473.Fn EC_POINT_copy , 474.Fn EC_POINT_set_to_infinity , 475.Fn EC_POINT_set_Jprojective_coordinates_GFp , 476.Fn EC_POINT_get_Jprojective_coordinates_GFp , 477.Fn EC_POINT_set_affine_coordinates , 478.Fn EC_POINT_set_affine_coordinates_GFp , 479.Fn EC_POINT_set_affine_coordinates_GF2m , 480.Fn EC_POINT_get_affine_coordinates , 481.Fn EC_POINT_get_affine_coordinates_GFp , 482.Fn EC_POINT_get_affine_coordinates_GF2m , 483.Fn EC_POINT_set_compressed_coordinates , 484.Fn EC_POINT_set_compressed_coordinates_GFp , 485.Fn EC_POINT_set_compressed_coordinates_GF2m , 486and 487.Fn EC_POINT_oct2point . 488.Pp 489.Fn EC_POINT_method_of 490returns the 491.Vt EC_METHOD 492associated with the supplied 493.Vt EC_POINT . 494.Pp 495.Fn EC_POINT_point2oct 496returns the length of the required buffer, or 0 on error. 497.Pp 498.Fn EC_POINT_point2bn 499returns the pointer to the 500.Vt BIGNUM 501supplied or 502.Dv NULL 503on error. 504.Pp 505.Fn EC_POINT_bn2point 506returns the pointer to the 507.Vt EC_POINT 508supplied or 509.Dv NULL 510on error. 511.Pp 512.Fn EC_POINT_point2hex 513returns a pointer to the hex string or 514.Dv NULL 515on error. 516.Pp 517.Fn EC_POINT_hex2point 518returns the pointer to the 519.Vt EC_POINT 520supplied or 521.Dv NULL 522on error. 523.Sh SEE ALSO 524.Xr d2i_ECPKParameters 3 , 525.Xr EC_GFp_simple_method 3 , 526.Xr EC_GROUP_copy 3 , 527.Xr EC_GROUP_new 3 , 528.Xr EC_KEY_new 3 , 529.Xr EC_POINT_add 3 , 530.Xr ECDH_compute_key 3 531.Sh HISTORY 532.Fn EC_POINT_new , 533.Fn EC_POINT_free , 534.Fn EC_POINT_clear_free , 535.Fn EC_POINT_copy , 536.Fn EC_POINT_method_of , 537.Fn EC_POINT_set_to_infinity , 538.Fn EC_POINT_set_affine_coordinates_GFp , 539.Fn EC_POINT_get_affine_coordinates_GFp , 540.Fn EC_POINT_set_Jprojective_coordinates_GFp , 541.Fn EC_POINT_get_Jprojective_coordinates_GFp , 542.Fn EC_POINT_set_compressed_coordinates_GFp , 543.Fn EC_POINT_point2oct , 544and 545.Fn EC_POINT_oct2point 546first appeared in OpenSSL 0.9.7 and have been available since 547.Ox 3.2 . 548.Pp 549.Fn EC_POINT_dup , 550.Fn EC_POINT_set_affine_coordinates_GF2m , 551.Fn EC_POINT_get_affine_coordinates_GF2m , 552.Fn EC_POINT_set_compressed_coordinates_GF2m , 553.Fn EC_POINT_point2bn , 554.Fn EC_POINT_bn2point , 555.Fn EC_POINT_point2hex , 556and 557.Fn EC_POINT_hex2point 558first appeared in OpenSSL 0.9.8 and have been available since 559.Ox 4.5 . 560.Pp 561.Fn EC_POINT_set_affine_coordinates , 562.Fn EC_POINT_get_affine_coordinates , 563and 564.Fn EC_POINT_set_compressed_coordinates 565first appeared in OpenSSL 1.1.1 and have been available since 566.Ox 7.0 . 567