1.\" $OpenBSD: EC_POINT_new.3,v 1.11 2019/08/19 13:08:26 schwarze Exp $ 2.\" full merge up to: OpenSSL ddc1caac Mar 6 14:00:24 2018 -0500 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: August 19 2019 $ 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_GFp , 63.Nm EC_POINT_set_affine_coordinates_GF2m , 64.Nm EC_POINT_get_affine_coordinates_GFp , 65.Nm EC_POINT_get_affine_coordinates_GF2m , 66.Nm EC_POINT_set_Jprojective_coordinates_GFp , 67.Nm EC_POINT_get_Jprojective_coordinates_GFp , 68.Nm EC_POINT_set_compressed_coordinates_GFp , 69.Nm EC_POINT_set_compressed_coordinates_GF2m , 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_GFp 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_GF2m 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_GFp 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_GF2m 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_GFp 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_GF2m 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 functions 294.Fn EC_POINT_set_affine_coordinates_GFp 295and 296.Fn EC_POINT_set_affine_coordinates_GF2m 297set the 298.Fa x 299and 300.Fa y 301coordinates for the point 302.Fa p 303defined over the curve given in 304.Fa group . 305The functions 306.Fn EC_POINT_get_affine_coordinates_GFp 307and 308.Fn EC_POINT_get_affine_coordinates_GF2m 309set 310.Fa x 311and 312.Fa y , 313either of which may be 314.Dv NULL , 315to the corresponding coordinates of 316.Fa p . 317.Pp 318As well as the affine coordinates, a point can alternatively be 319described in terms of its Jacobian projective coordinates (for Fp 320curves only). 321Jacobian projective coordinates are expressed as three values 322.Fa x , 323.Fa y , 324and 325.Fa z . 326Working in this coordinate system provides more efficient point 327multiplication operations. 328A mapping exists between Jacobian projective coordinates and affine 329coordinates. 330A Jacobian projective coordinate 331.Pq Fa x , y , z 332can be written as an affine coordinate as 333.Pp 334.Dl (x/(z^2), y/(z^3)) . 335.Pp 336Conversion to Jacobian projective from affine coordinates is simple. 337The coordinate 338.Pq Fa x , y 339is mapped to 340.Pq Fa x , y , No 1 . 341To set or get the projective coordinates use 342.Fn EC_POINT_set_Jprojective_coordinates_GFp 343and 344.Fn EC_POINT_get_Jprojective_coordinates_GFp , 345respectively. 346.Pp 347Points can also be described in terms of their compressed coordinates. 348For a point 349.Pq Fa x , y , 350for any given value for 351.Fa x 352such that the point is on the curve, there will only ever be two 353possible values for 354.Fa y . 355Therefore a point can be set using the 356.Fn EC_POINT_set_compressed_coordinates_GFp 357and 358.Fn EC_POINT_set_compressed_coordinates_GF2m 359functions where 360.Fa x 361is the x coordinate and 362.Fa y_bit 363is a value 0 or 1 to identify which of the two possible values for y 364should be used. 365.Pp 366In addition 367.Vt EC_POINT Ns s 368can be converted to and from various external representations. 369Supported representations are octet strings, 370.Vt BIGNUM Ns s , 371and hexadecimal. 372The format of the external representation is described by the 373point_conversion_form. 374See 375.Xr EC_GROUP_copy 3 376for a description of point_conversion_form. 377Octet strings are stored in a buffer along with an associated buffer 378length. 379A point held in a 380.Vt BIGNUM 381is calculated by converting the point to an octet string and then 382converting that octet string into a 383.Vt BIGNUM 384integer. 385Points in hexadecimal format are stored in a NUL terminated character 386string where each character is one of the printable values 0-9 or A-F 387(or a-f). 388.Pp 389The functions 390.Fn EC_POINT_point2oct , 391.Fn EC_POINT_oct2point , 392.Fn EC_POINT_point2bn , 393.Fn EC_POINT_bn2point , 394.Fn EC_POINT_point2hex , 395and 396.Fn EC_POINT_hex2point 397convert from and to 398.Vt EC_POINT Ns s 399for the formats octet string, 400.Vt BIGNUM , 401and hexadecimal, respectively. 402.Pp 403The function 404.Fn EC_POINT_point2oct 405must be supplied with a 406.Fa buf 407long enough to store the octet string. 408The return value provides the number of octets stored. 409Calling the function with a 410.Dv NULL 411.Fa buf 412will not perform the conversion but will still return the required 413buffer length. 414.Pp 415The function 416.Fn EC_POINT_point2hex 417will allocate sufficient memory to store the hexadecimal string. 418It is the caller's responsibility to free this memory with a subsequent 419call to 420.Xr free 3 . 421.Sh RETURN VALUES 422.Fn EC_POINT_new 423and 424.Fn EC_POINT_dup 425return the newly allocated 426.Vt EC_POINT 427or 428.Dv NULL 429on error. 430.Pp 431The following functions return 1 on success or 0 on error: 432.Fn EC_POINT_copy , 433.Fn EC_POINT_set_to_infinity , 434.Fn EC_POINT_set_Jprojective_coordinates_GFp , 435.Fn EC_POINT_get_Jprojective_coordinates_GFp , 436.Fn EC_POINT_set_affine_coordinates_GFp , 437.Fn EC_POINT_get_affine_coordinates_GFp , 438.Fn EC_POINT_set_compressed_coordinates_GFp , 439.Fn EC_POINT_set_affine_coordinates_GF2m , 440.Fn EC_POINT_get_affine_coordinates_GF2m , 441.Fn EC_POINT_set_compressed_coordinates_GF2m , 442and 443.Fn EC_POINT_oct2point . 444.Pp 445.Fn EC_POINT_method_of 446returns the 447.Vt EC_METHOD 448associated with the supplied 449.Vt EC_POINT . 450.Pp 451.Fn EC_POINT_point2oct 452returns the length of the required buffer, or 0 on error. 453.Pp 454.Fn EC_POINT_point2bn 455returns the pointer to the 456.Vt BIGNUM 457supplied or 458.Dv NULL 459on error. 460.Pp 461.Fn EC_POINT_bn2point 462returns the pointer to the 463.Vt EC_POINT 464supplied or 465.Dv NULL 466on error. 467.Pp 468.Fn EC_POINT_point2hex 469returns a pointer to the hex string or 470.Dv NULL 471on error. 472.Pp 473.Fn EC_POINT_hex2point 474returns the pointer to the 475.Vt EC_POINT 476supplied or 477.Dv NULL 478on error. 479.Sh SEE ALSO 480.Xr d2i_ECPKParameters 3 , 481.Xr EC_GFp_simple_method 3 , 482.Xr EC_GROUP_copy 3 , 483.Xr EC_GROUP_new 3 , 484.Xr EC_KEY_new 3 , 485.Xr EC_POINT_add 3 , 486.Xr ECDH_compute_key 3 487.Sh HISTORY 488.Fn EC_POINT_new , 489.Fn EC_POINT_free , 490.Fn EC_POINT_clear_free , 491.Fn EC_POINT_copy , 492.Fn EC_POINT_method_of , 493.Fn EC_POINT_set_to_infinity , 494.Fn EC_POINT_set_affine_coordinates_GFp , 495.Fn EC_POINT_get_affine_coordinates_GFp , 496.Fn EC_POINT_set_Jprojective_coordinates_GFp , 497.Fn EC_POINT_get_Jprojective_coordinates_GFp , 498.Fn EC_POINT_set_compressed_coordinates_GFp , 499.Fn EC_POINT_point2oct , 500and 501.Fn EC_POINT_oct2point 502first appeared in OpenSSL 0.9.7 and have been available since 503.Ox 3.2 . 504.Pp 505.Fn EC_POINT_dup , 506.Fn EC_POINT_set_affine_coordinates_GF2m , 507.Fn EC_POINT_get_affine_coordinates_GF2m , 508.Fn EC_POINT_set_compressed_coordinates_GF2m , 509.Fn EC_POINT_point2bn , 510.Fn EC_POINT_bn2point , 511.Fn EC_POINT_point2hex , 512and 513.Fn EC_POINT_hex2point 514first appeared in OpenSSL 0.9.8 and have been available since 515.Ox 4.5 . 516