xref: /openssl/doc/man3/EC_POINT_add.pod (revision da1c088f) 
1=pod
2
3=head1 NAME
4
5EC_POINT_add, EC_POINT_dbl, EC_POINT_invert, EC_POINT_is_at_infinity, EC_POINT_is_on_curve, EC_POINT_cmp, EC_POINT_make_affine, EC_POINTs_make_affine, EC_POINTs_mul, EC_POINT_mul, EC_GROUP_precompute_mult, EC_GROUP_have_precompute_mult - Functions for performing mathematical operations and tests on EC_POINT objects
6
7=head1 SYNOPSIS
8
9 #include <openssl/ec.h>
10
11 int EC_POINT_add(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a,
12                  const EC_POINT *b, BN_CTX *ctx);
13 int EC_POINT_dbl(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, BN_CTX *ctx);
14 int EC_POINT_invert(const EC_GROUP *group, EC_POINT *a, BN_CTX *ctx);
15 int EC_POINT_is_at_infinity(const EC_GROUP *group, const EC_POINT *p);
16 int EC_POINT_is_on_curve(const EC_GROUP *group, const EC_POINT *point, BN_CTX *ctx);
17 int EC_POINT_cmp(const EC_GROUP *group, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx);
18 int EC_POINT_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n,
19                  const EC_POINT *q, const BIGNUM *m, BN_CTX *ctx);
20
21The following functions have been deprecated since OpenSSL 3.0, and can be
22hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value,
23see L<openssl_user_macros(7)>:
24
25 int EC_POINT_make_affine(const EC_GROUP *group, EC_POINT *point, BN_CTX *ctx);
26 int EC_POINTs_make_affine(const EC_GROUP *group, size_t num,
27                           EC_POINT *points[], BN_CTX *ctx);
28 int EC_POINTs_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, size_t num,
29                   const EC_POINT *p[], const BIGNUM *m[], BN_CTX *ctx);
30 int EC_GROUP_precompute_mult(EC_GROUP *group, BN_CTX *ctx);
31 int EC_GROUP_have_precompute_mult(const EC_GROUP *group);
32
33=head1 DESCRIPTION
34
35EC_POINT_add adds the two points B<a> and B<b> and places the result in B<r>. Similarly EC_POINT_dbl doubles the point B<a> and places the
36result in B<r>. In both cases it is valid for B<r> to be one of B<a> or B<b>.
37
38EC_POINT_invert calculates the inverse of the supplied point B<a>. The result is placed back in B<a>.
39
40The function EC_POINT_is_at_infinity tests whether the supplied point is at infinity or not.
41
42EC_POINT_is_on_curve tests whether the supplied point is on the curve or not.
43
44EC_POINT_cmp compares the two supplied points and tests whether or not they are equal.
45
46The functions EC_POINT_make_affine and EC_POINTs_make_affine force the internal representation of the EC_POINT(s) into the affine
47coordinate system. In the case of EC_POINTs_make_affine the value B<num> provides the number of points in the array B<points> to be
48forced. These functions were deprecated in OpenSSL 3.0 and should no longer be used.
49Modern versions automatically perform this conversion when needed.
50
51EC_POINT_mul calculates the value generator * B<n> + B<q> * B<m> and stores the result in B<r>.
52The value B<n> may be NULL in which case the result is just B<q> * B<m> (variable point multiplication). Alternatively, both B<q> and B<m> may be NULL, and B<n> non-NULL, in which case the result is just generator * B<n> (fixed point multiplication).
53When performing a single fixed or variable point multiplication, the underlying implementation uses a constant time algorithm, when the input scalar (either B<n> or B<m>) is in the range [0, ec_group_order).
54
55Although deprecated in OpenSSL 3.0 and should no longer be used,
56EC_POINTs_mul calculates the value generator * B<n> + B<q[0]> * B<m[0]> + ... + B<q[num-1]> * B<m[num-1]>. As for EC_POINT_mul the value B<n> may be NULL or B<num> may be zero.
57When performing a fixed point multiplication (B<n> is non-NULL and B<num> is 0) or a variable point multiplication (B<n> is NULL and B<num> is 1), the underlying implementation uses a constant time algorithm, when the input scalar (either B<n> or B<m[0]>) is in the range [0, ec_group_order).
58Modern versions should instead use EC_POINT_mul(), combined (if needed) with EC_POINT_add() in such rare circumstances.
59
60The function EC_GROUP_precompute_mult stores multiples of the generator for faster point multiplication, whilst
61EC_GROUP_have_precompute_mult tests whether precomputation has already been done. See L<EC_GROUP_copy(3)> for information
62about the generator. Precomputation functionality was deprecated in OpenSSL 3.0.
63Users of EC_GROUP_precompute_mult() and EC_GROUP_have_precompute_mult() should
64switch to named curves which OpenSSL has hardcoded lookup tables for.
65
66=head1 RETURN VALUES
67
68The following functions return 1 on success or 0 on error: EC_POINT_add, EC_POINT_dbl, EC_POINT_invert, EC_POINT_make_affine,
69EC_POINTs_make_affine, EC_POINTs_make_affine, EC_POINT_mul, EC_POINTs_mul and EC_GROUP_precompute_mult.
70
71EC_POINT_is_at_infinity returns 1 if the point is at infinity, or 0 otherwise.
72
73EC_POINT_is_on_curve returns 1 if the point is on the curve, 0 if not, or -1 on error.
74
75EC_POINT_cmp returns 1 if the points are not equal, 0 if they are, or -1 on error.
76
77EC_GROUP_have_precompute_mult return 1 if a precomputation has been done, or 0 if not.
78
79=head1 SEE ALSO
80
81L<crypto(7)>, L<EC_GROUP_new(3)>, L<EC_GROUP_copy(3)>,
82L<EC_POINT_new(3)>, L<EC_KEY_new(3)>,
83L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)>
84
85=head1 HISTORY
86
87EC_POINT_make_affine(), EC_POINTs_make_affine(), EC_POINTs_mul(),
88EC_GROUP_precompute_mult(), and EC_GROUP_have_precompute_mult()
89were deprecated in OpenSSL 3.0.
90
91=head1 COPYRIGHT
92
93Copyright 2013-2023 The OpenSSL Project Authors. All Rights Reserved.
94
95Licensed under the Apache License 2.0 (the "License").  You may not use
96this file except in compliance with the License.  You can obtain a copy
97in the file LICENSE in the source distribution or at
98L<https://www.openssl.org/source/license.html>.
99
100=cut
101