1.\" $OpenBSD: EC_POINT_new.3,v 1.14 2023/04/27 09:39:52 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: April 27 2023 $ 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_get_affine_coordinates , 65.Nm EC_POINT_get_affine_coordinates_GFp , 66.Nm EC_POINT_set_Jprojective_coordinates_GFp , 67.Nm EC_POINT_get_Jprojective_coordinates_GFp , 68.Nm EC_POINT_set_compressed_coordinates , 69.Nm EC_POINT_set_compressed_coordinates_GFp , 70.Nm EC_POINT_point2oct , 71.Nm EC_POINT_oct2point , 72.Nm EC_POINT_point2bn , 73.Nm EC_POINT_bn2point , 74.Nm EC_POINT_point2hex , 75.Nm EC_POINT_hex2point 76.Nd create, destroy, and manipulate EC_POINT objects 77.Sh SYNOPSIS 78.In openssl/ec.h 79.In openssl/bn.h 80.Ft EC_POINT * 81.Fo EC_POINT_new 82.Fa "const EC_GROUP *group" 83.Fc 84.Ft void 85.Fo EC_POINT_free 86.Fa "EC_POINT *point" 87.Fc 88.Ft void 89.Fo EC_POINT_clear_free 90.Fa "EC_POINT *point" 91.Fc 92.Ft int 93.Fo EC_POINT_copy 94.Fa "EC_POINT *dst" 95.Fa "const EC_POINT *src" 96.Fc 97.Ft EC_POINT * 98.Fo EC_POINT_dup 99.Fa "const EC_POINT *src" 100.Fa "const EC_GROUP *group" 101.Fc 102.Ft const EC_METHOD * 103.Fo EC_POINT_method_of 104.Fa "const EC_POINT *point" 105.Fc 106.Ft int 107.Fo EC_POINT_set_to_infinity 108.Fa "const EC_GROUP *group" 109.Fa "EC_POINT *point" 110.Fc 111.Ft int 112.Fo EC_POINT_set_affine_coordinates 113.Fa "const EC_GROUP *group" 114.Fa "EC_POINT *p" 115.Fa "const BIGNUM *x" 116.Fa "const BIGNUM *y" 117.Fa "BN_CTX *ctx" 118.Fc 119.Ft int 120.Fo EC_POINT_set_affine_coordinates_GFp 121.Fa "const EC_GROUP *group" 122.Fa "EC_POINT *p" 123.Fa "const BIGNUM *x" 124.Fa "const BIGNUM *y" 125.Fa "BN_CTX *ctx" 126.Fc 127.Ft int 128.Fo EC_POINT_get_affine_coordinates 129.Fa "const EC_GROUP *group" 130.Fa "const EC_POINT *p" 131.Fa "BIGNUM *x" 132.Fa "BIGNUM *y" 133.Fa "BN_CTX *ctx" 134.Fc 135.Ft int 136.Fo EC_POINT_get_affine_coordinates_GFp 137.Fa "const EC_GROUP *group" 138.Fa "const EC_POINT *p" 139.Fa "BIGNUM *x" 140.Fa "BIGNUM *y" 141.Fa "BN_CTX *ctx" 142.Fc 143.Ft int 144.Fo EC_POINT_set_Jprojective_coordinates_GFp 145.Fa "const EC_GROUP *group" 146.Fa "EC_POINT *p" 147.Fa "const BIGNUM *x" 148.Fa "const BIGNUM *y" 149.Fa "const BIGNUM *z" 150.Fa "BN_CTX *ctx" 151.Fc 152.Ft int 153.Fo EC_POINT_get_Jprojective_coordinates_GFp 154.Fa "const EC_GROUP *group" 155.Fa "const EC_POINT *p" 156.Fa "BIGNUM *x" 157.Fa "BIGNUM *y" 158.Fa "BIGNUM *z" 159.Fa "BN_CTX *ctx" 160.Fc 161.Ft int 162.Fo EC_POINT_set_compressed_coordinates 163.Fa "const EC_GROUP *group" 164.Fa "EC_POINT *p" 165.Fa "const BIGNUM *x" 166.Fa "int y_bit" 167.Fa "BN_CTX *ctx" 168.Fc 169.Ft int 170.Fo EC_POINT_set_compressed_coordinates_GFp 171.Fa "const EC_GROUP *group" 172.Fa "EC_POINT *p" 173.Fa "const BIGNUM *x" 174.Fa "int y_bit" 175.Fa "BN_CTX *ctx" 176.Fc 177.Ft size_t 178.Fo EC_POINT_point2oct 179.Fa "const EC_GROUP *group" 180.Fa "const EC_POINT *p" 181.Fa "point_conversion_form_t form" 182.Fa "unsigned char *buf" 183.Fa "size_t len" 184.Fa "BN_CTX *ctx" 185.Fc 186.Ft int 187.Fo EC_POINT_oct2point 188.Fa "const EC_GROUP *group" 189.Fa "EC_POINT *p" 190.Fa "const unsigned char *buf" 191.Fa "size_t len" 192.Fa "BN_CTX *ctx" 193.Fc 194.Ft BIGNUM * 195.Fo EC_POINT_point2bn 196.Fa "const EC_GROUP *" 197.Fa "const EC_POINT *" 198.Fa "point_conversion_form_t form" 199.Fa "BIGNUM *" 200.Fa "BN_CTX *" 201.Fc 202.Ft EC_POINT * 203.Fo EC_POINT_bn2point 204.Fa "const EC_GROUP *" 205.Fa "const BIGNUM *" 206.Fa "EC_POINT *" 207.Fa "BN_CTX *" 208.Fc 209.Ft char * 210.Fo EC_POINT_point2hex 211.Fa "const EC_GROUP *" 212.Fa "const EC_POINT *" 213.Fa "point_conversion_form_t form" 214.Fa "BN_CTX *" 215.Fc 216.Ft EC_POINT * 217.Fo EC_POINT_hex2point 218.Fa "const EC_GROUP *" 219.Fa "const char *" 220.Fa "EC_POINT *" 221.Fa "BN_CTX *" 222.Fc 223.Sh DESCRIPTION 224An 225.Vt EC_POINT 226represents a point on a curve. 227A curve is represented by an 228.Vt EC_GROUP 229object created by the functions described in 230.Xr EC_GROUP_new 3 . 231.Pp 232A new point is constructed by calling the function 233.Fn EC_POINT_new 234and providing the 235.Fa group 236object that the point relates to. 237.Pp 238.Fn EC_POINT_free 239frees the memory associated with the 240.Vt EC_POINT . 241If 242.Fa point 243is a 244.Dv NULL 245pointer, no action occurs. 246.Pp 247.Fn EC_POINT_clear_free 248destroys any sensitive data held within the 249.Vt EC_POINT 250and then frees its memory. 251If 252.Fa point 253is a 254.Dv NULL 255pointer, no action occurs. 256.Pp 257.Fn EC_POINT_copy 258copies the point 259.Fa src 260into 261.Fa dst . 262Both 263.Fa src 264and 265.Fa dst 266must use the same 267.Vt EC_METHOD . 268.Pp 269.Fn EC_POINT_dup 270creates a new 271.Vt EC_POINT 272object and copies the content from 273.Fa src 274to the newly created 275.Vt EC_POINT 276object. 277.Pp 278.Fn EC_POINT_method_of 279obtains the 280.Vt EC_METHOD 281associated with 282.Fa point . 283.Pp 284A valid point on a curve is the special point at infinity. 285A point is set to be at infinity by calling 286.Fn EC_POINT_set_to_infinity . 287.Pp 288The affine coordinates for a point describe a point in terms of its 289.Fa x 290and 291.Fa y 292position. 293The function 294.Fn EC_POINT_set_affine_coordinates 295sets the 296.Fa x 297and 298.Fa y 299coordinates for the point 300.Fa p 301defined over the curve given in 302.Fa group . 303The function 304.Fn EC_POINT_get_affine_coordinates 305sets 306.Fa x 307and 308.Fa y , 309either of which may be 310.Dv NULL , 311to the corresponding coordinates of 312.Fa p . 313.Pp 314The functions 315.Fn EC_POINT_set_affine_coordinates_GFp 316is a deprecated synonym for 317.Fn EC_POINT_set_affine_coordinates 318and the function 319.Fn EC_POINT_get_affine_coordinates_GFp 320is a deprecated synonym for 321.Fn EC_POINT_get_affine_coordinates . 322.Pp 323As well as the affine coordinates, a point can alternatively be 324described in terms of its Jacobian projective coordinates. 325Jacobian projective coordinates are expressed as three values 326.Fa x , 327.Fa y , 328and 329.Fa z . 330Working in this coordinate system provides more efficient point 331multiplication operations. 332A mapping exists between Jacobian projective coordinates and affine 333coordinates. 334A Jacobian projective coordinate 335.Pq Fa x , y , z 336can be written as an affine coordinate as 337.Pp 338.Dl (x/(z^2), y/(z^3)) . 339.Pp 340Conversion to Jacobian projective from affine coordinates is simple. 341The coordinate 342.Pq Fa x , y 343is mapped to 344.Pq Fa x , y , No 1 . 345To set or get the projective coordinates use 346.Fn EC_POINT_set_Jprojective_coordinates_GFp 347and 348.Fn EC_POINT_get_Jprojective_coordinates_GFp , 349respectively. 350.Pp 351Points can also be described in terms of their compressed coordinates. 352For a point 353.Pq Fa x , y , 354for any given value for 355.Fa x 356such that the point is on the curve, there will only ever be two 357possible values for 358.Fa y . 359Therefore, a point can be set using the 360.Fn EC_POINT_set_compressed_coordinates 361function where 362.Fa x 363is the x coordinate and 364.Fa y_bit 365is a value 0 or 1 to identify which of the two possible values for y 366should be used. 367.Pp 368The functions 369.Fn EC_POINT_set_compressed_coordinates_GFp 370is a deprecated synonym for 371.Fn EC_POINT_set_compressed_coordinates . 372.Pp 373In addition 374.Vt EC_POINT Ns s 375can be converted to and from various external representations. 376Supported representations are octet strings, 377.Vt BIGNUM Ns s , 378and hexadecimal. 379The format of the external representation is described by the 380point_conversion_form. 381See 382.Xr EC_GROUP_copy 3 383for a description of point_conversion_form. 384Octet strings are stored in a buffer along with an associated buffer 385length. 386A point held in a 387.Vt BIGNUM 388is calculated by converting the point to an octet string and then 389converting that octet string into a 390.Vt BIGNUM 391integer. 392Points in hexadecimal format are stored in a NUL terminated character 393string where each character is one of the printable values 0-9 or A-F 394(or a-f). 395.Pp 396The functions 397.Fn EC_POINT_point2oct , 398.Fn EC_POINT_oct2point , 399.Fn EC_POINT_point2bn , 400.Fn EC_POINT_bn2point , 401.Fn EC_POINT_point2hex , 402and 403.Fn EC_POINT_hex2point 404convert from and to 405.Vt EC_POINT Ns s 406for the formats octet string, 407.Vt BIGNUM , 408and hexadecimal, respectively. 409.Pp 410The function 411.Fn EC_POINT_point2oct 412must be supplied with a 413.Fa buf 414long enough to store the octet string. 415The return value provides the number of octets stored. 416Calling the function with a 417.Dv NULL 418.Fa buf 419will not perform the conversion but will still return the required 420buffer length. 421.Pp 422The function 423.Fn EC_POINT_point2hex 424will allocate sufficient memory to store the hexadecimal string. 425It is the caller's responsibility to free this memory with a subsequent 426call to 427.Xr free 3 . 428.Sh RETURN VALUES 429.Fn EC_POINT_new 430and 431.Fn EC_POINT_dup 432return the newly allocated 433.Vt EC_POINT 434or 435.Dv NULL 436on error. 437.Pp 438The following functions return 1 on success or 0 on error: 439.Fn EC_POINT_copy , 440.Fn EC_POINT_set_to_infinity , 441.Fn EC_POINT_set_Jprojective_coordinates_GFp , 442.Fn EC_POINT_get_Jprojective_coordinates_GFp , 443.Fn EC_POINT_set_affine_coordinates , 444.Fn EC_POINT_set_affine_coordinates_GFp , 445.Fn EC_POINT_get_affine_coordinates , 446.Fn EC_POINT_get_affine_coordinates_GFp , 447.Fn EC_POINT_set_compressed_coordinates , 448.Fn EC_POINT_set_compressed_coordinates_GFp , 449and 450.Fn EC_POINT_oct2point . 451.Pp 452.Fn EC_POINT_method_of 453returns the 454.Vt EC_METHOD 455associated with the supplied 456.Vt EC_POINT . 457.Pp 458.Fn EC_POINT_point2oct 459returns the length of the required buffer, or 0 on error. 460.Pp 461.Fn EC_POINT_point2bn 462returns the pointer to the 463.Vt BIGNUM 464supplied or 465.Dv NULL 466on error. 467.Pp 468.Fn EC_POINT_bn2point 469returns the pointer to the 470.Vt EC_POINT 471supplied or 472.Dv NULL 473on error. 474.Pp 475.Fn EC_POINT_point2hex 476returns a pointer to the hex string or 477.Dv NULL 478on error. 479.Pp 480.Fn EC_POINT_hex2point 481returns the pointer to the 482.Vt EC_POINT 483supplied or 484.Dv NULL 485on error. 486.Sh SEE ALSO 487.Xr d2i_ECPKParameters 3 , 488.Xr EC_GFp_simple_method 3 , 489.Xr EC_GROUP_copy 3 , 490.Xr EC_GROUP_new 3 , 491.Xr EC_KEY_new 3 , 492.Xr EC_POINT_add 3 , 493.Xr ECDH_compute_key 3 494.Sh HISTORY 495.Fn EC_POINT_new , 496.Fn EC_POINT_free , 497.Fn EC_POINT_clear_free , 498.Fn EC_POINT_copy , 499.Fn EC_POINT_method_of , 500.Fn EC_POINT_set_to_infinity , 501.Fn EC_POINT_set_affine_coordinates_GFp , 502.Fn EC_POINT_get_affine_coordinates_GFp , 503.Fn EC_POINT_set_Jprojective_coordinates_GFp , 504.Fn EC_POINT_get_Jprojective_coordinates_GFp , 505.Fn EC_POINT_set_compressed_coordinates_GFp , 506.Fn EC_POINT_point2oct , 507and 508.Fn EC_POINT_oct2point 509first appeared in OpenSSL 0.9.7 and have been available since 510.Ox 3.2 . 511.Pp 512.Fn EC_POINT_dup , 513.Fn EC_POINT_point2bn , 514.Fn EC_POINT_bn2point , 515.Fn EC_POINT_point2hex , 516and 517.Fn EC_POINT_hex2point 518first appeared in OpenSSL 0.9.8 and have been available since 519.Ox 4.5 . 520.Pp 521.Fn EC_POINT_set_affine_coordinates , 522.Fn EC_POINT_get_affine_coordinates , 523and 524.Fn EC_POINT_set_compressed_coordinates 525first appeared in OpenSSL 1.1.1 and have been available since 526.Ox 7.0 . 527