1.\" $OpenBSD: EC_POINT_add.3,v 1.11 2018/07/16 17:37:25 tb Exp $ 2.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 3.\" 4.\" This file was written by Matt Caswell <matt@openssl.org>. 5.\" Copyright (c) 2013 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: July 16 2018 $ 52.Dt EC_POINT_ADD 3 53.Os 54.Sh NAME 55.Nm EC_POINT_add , 56.Nm EC_POINT_dbl , 57.Nm EC_POINT_invert , 58.Nm EC_POINT_is_at_infinity , 59.Nm EC_POINT_is_on_curve , 60.Nm EC_POINT_cmp , 61.Nm EC_POINT_make_affine , 62.Nm EC_POINTs_make_affine , 63.Nm EC_POINTs_mul , 64.Nm EC_POINT_mul , 65.Nm EC_GROUP_precompute_mult , 66.Nm EC_GROUP_have_precompute_mult 67.Nd perform mathematical operations and tests on EC_POINT objects 68.Sh SYNOPSIS 69.In openssl/ec.h 70.In openssl/bn.h 71.Ft int 72.Fo EC_POINT_add 73.Fa "const EC_GROUP *group" 74.Fa "EC_POINT *r" 75.Fa "const EC_POINT *a" 76.Fa "const EC_POINT *b" 77.Fa "BN_CTX *ctx" 78.Fc 79.Ft int 80.Fo EC_POINT_dbl 81.Fa "const EC_GROUP *group" 82.Fa "EC_POINT *r" 83.Fa "const EC_POINT *a" 84.Fa "BN_CTX *ctx" 85.Fc 86.Ft int 87.Fo EC_POINT_invert 88.Fa "const EC_GROUP *group" 89.Fa "EC_POINT *a" 90.Fa "BN_CTX *ctx" 91.Fc 92.Ft int 93.Fo EC_POINT_is_at_infinity 94.Fa "const EC_GROUP *group" 95.Fa "const EC_POINT *p" 96.Fc 97.Ft int 98.Fo EC_POINT_is_on_curve 99.Fa "const EC_GROUP *group" 100.Fa "const EC_POINT *point" 101.Fa "BN_CTX *ctx" 102.Fc 103.Ft int 104.Fo EC_POINT_cmp 105.Fa "const EC_GROUP *group" 106.Fa "const EC_POINT *a" 107.Fa "const EC_POINT *b" 108.Fa "BN_CTX *ctx" 109.Fc 110.Ft int 111.Fo EC_POINT_make_affine 112.Fa "const EC_GROUP *group" 113.Fa "EC_POINT *point" 114.Fa "BN_CTX *ctx" 115.Fc 116.Ft int 117.Fo EC_POINTs_make_affine 118.Fa "const EC_GROUP *group" 119.Fa "size_t num" 120.Fa "EC_POINT *points[]" 121.Fa "BN_CTX *ctx" 122.Fc 123.Ft int 124.Fo EC_POINTs_mul 125.Fa "const EC_GROUP *group" 126.Fa "EC_POINT *r" 127.Fa "const BIGNUM *n" 128.Fa "size_t num" 129.Fa "const EC_POINT *p[]" 130.Fa "const BIGNUM *m[]" 131.Fa "BN_CTX *ctx" 132.Fc 133.Ft int 134.Fo EC_POINT_mul 135.Fa "const EC_GROUP *group" 136.Fa "EC_POINT *r" 137.Fa "const BIGNUM *n" 138.Fa "const EC_POINT *q" 139.Fa "const BIGNUM *m" 140.Fa "BN_CTX *ctx" 141.Fc 142.Ft int 143.Fo EC_GROUP_precompute_mult 144.Fa "EC_GROUP *group" 145.Fa "BN_CTX *ctx" 146.Fc 147.Ft int 148.Fo EC_GROUP_have_precompute_mult 149.Fa "const EC_GROUP *group" 150.Fc 151.Sh DESCRIPTION 152These functions operate on 153.Vt EC_POINT 154objects created by 155.Xr EC_POINT_new 3 . 156.Pp 157.Fn EC_POINT_add 158adds the two points 159.Fa a 160and 161.Fa b 162and places the result in 163.Fa r . 164Similarly 165.Fn EC_POINT_dbl 166doubles the point 167.Fa a 168and places the result in 169.Fa r . 170In both cases it is valid for 171.Fa r 172to be one of 173.Fa a 174or 175.Fa b . 176.Pp 177.Fn EC_POINT_invert 178calculates the inverse of the supplied point 179.Fa a . 180The result is placed back in 181.Fa a . 182.Pp 183The function 184.Fn EC_POINT_is_at_infinity 185tests whether the supplied point is at infinity or not. 186.Pp 187.Fn EC_POINT_is_on_curve 188tests whether the supplied point is on the curve or not. 189.Pp 190.Fn EC_POINT_cmp 191compares the two supplied points and tests whether or not they are 192equal. 193.Pp 194The functions 195.Fn EC_POINT_make_affine 196and 197.Fn EC_POINTs_make_affine 198force the internal representation of the 199.Vt EC_POINT Ns s 200into the affine coordinate system. 201In the case of 202.Fn EC_POINTs_make_affine , 203the value 204.Fa num 205provides the number of points in the array 206.Fa points 207to be forced. 208.Pp 209.Fn EC_POINT_mul 210calculates the value 211.Pp 212.D1 generator * n + q * m 213.Pp 214and stores the result in 215.Fa r . 216The value 217.Fa n 218may be 219.Dv NULL , 220in which case the result is just 221.Pp 222.Dl q * m. 223.Pp 224.Fn EC_POINTs_mul 225only supports the values 0 and 1 for 226.Fa num . 227If it is 1, then 228.Fn EC_POINTs_mul 229calculates the value 230.Pp 231.Dl generator * n + q[0] * m[0]. 232.Pp 233If 234.Fa num 235is 0 then 236.Fa q 237and 238.Fa m 239must be 240.Dv NULL , 241and the result is just 242.Pp 243.Dl generator * n . 244.Pp 245As for 246.Fn EC_POINT_mul , 247the value 248.Fa n 249may be 250.Dv NULL . 251.Pp 252The function 253.Fn EC_GROUP_precompute_mult 254stores multiples of the generator for faster point multiplication, 255whilst 256.Fn EC_GROUP_have_precompute_mult 257tests whether precomputation has already been done. 258See 259.Xr EC_GROUP_copy 3 260for information about the generator. 261.Sh RETURN VALUES 262The following functions return 1 on success or 0 on error: 263.Fn EC_POINT_add , 264.Fn EC_POINT_dbl , 265.Fn EC_POINT_invert , 266.Fn EC_POINT_make_affine , 267.Fn EC_POINTs_make_affine , 268.Fn EC_POINTs_make_affine , 269.Fn EC_POINT_mul , 270.Fn EC_POINTs_mul , 271and 272.Fn EC_GROUP_precompute_mult . 273.Pp 274.Fn EC_POINT_is_at_infinity 275returns 1 if the point is at infinity or 0 otherwise. 276.Pp 277.Fn EC_POINT_is_on_curve 278returns 1 if the point is on the curve, 0 if not, or -1 on error. 279.Pp 280.Fn EC_POINT_cmp 281returns 1 if the points are not equal, 0 if they are, or -1 on error. 282.Pp 283.Fn EC_GROUP_have_precompute_mult 284returns 1 if a precomputation has been done or 0 if not. 285.Sh SEE ALSO 286.Xr d2i_ECPKParameters 3 , 287.Xr EC_GFp_simple_method 3 , 288.Xr EC_GROUP_copy 3 , 289.Xr EC_GROUP_new 3 , 290.Xr EC_KEY_new 3 , 291.Xr EC_POINT_new 3 292.Sh HISTORY 293.Fn EC_POINT_add , 294.Fn EC_POINT_dbl , 295.Fn EC_POINT_invert , 296.Fn EC_POINT_is_at_infinity , 297.Fn EC_POINT_is_on_curve , 298.Fn EC_POINT_cmp , 299.Fn EC_POINT_make_affine , 300.Fn EC_POINTs_make_affine , 301.Fn EC_POINTs_mul , 302.Fn EC_POINT_mul , 303and 304.Fn EC_GROUP_precompute_mult 305first appeared in OpenSSL 0.9.7 and have been available since 306.Ox 3.2 . 307.Pp 308.Fn EC_GROUP_have_precompute_mult 309first appeared in OpenSSL 0.9.8 and has been available since 310.Ox 4.5 . 311