]>
Commit | Line | Data |
---|---|---|
aafbe1cc MC |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
bb9ad09e | 5 | EC_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 |
aafbe1cc MC |
6 | |
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/ec.h> | |
aafbe1cc | 10 | |
e9b77246 BB |
11 | int EC_POINT_add(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, |
12 | const EC_POINT *b, BN_CTX *ctx); | |
aafbe1cc MC |
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); | |
e9b77246 BB |
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); | |
aafbe1cc | 20 | |
3dbf8243 MC |
21 | The following functions have been deprecated since OpenSSL 3.0, and can be |
22 | hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, | |
23 | see L<openssl_user_macros(7)>: | |
4fcd15c1 | 24 | |
c2f2db9b BB |
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); | |
4fcd15c1 BB |
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); | |
6b4eb933 BB |
30 | int EC_GROUP_precompute_mult(EC_GROUP *group, BN_CTX *ctx); |
31 | int EC_GROUP_have_precompute_mult(const EC_GROUP *group); | |
aafbe1cc MC |
32 | |
33 | =head1 DESCRIPTION | |
34 | ||
35 | EC_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 | |
36 | result in B<r>. In both cases it is valid for B<r> to be one of B<a> or B<b>. | |
37 | ||
38 | EC_POINT_invert calculates the inverse of the supplied point B<a>. The result is placed back in B<a>. | |
39 | ||
40 | The function EC_POINT_is_at_infinity tests whether the supplied point is at infinity or not. | |
41 | ||
42 | EC_POINT_is_on_curve tests whether the supplied point is on the curve or not. | |
43 | ||
44 | EC_POINT_cmp compares the two supplied points and tests whether or not they are equal. | |
45 | ||
46 | The functions EC_POINT_make_affine and EC_POINTs_make_affine force the internal representation of the EC_POINT(s) into the affine | |
47 | co-ordinate 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 | |
c2f2db9b BB |
48 | forced. These functions were deprecated in OpenSSL 3.0 and should no longer be used. |
49 | Modern versions automatically perform this conversion when needed. | |
aafbe1cc | 50 | |
4fcd15c1 | 51 | EC_POINT_mul calculates the value generator * B<n> + B<q> * B<m> and stores the result in B<r>. |
fe2d3975 BB |
52 | The 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). |
53 | When 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). | |
aafbe1cc | 54 | |
4fcd15c1 | 55 | Although deprecated in OpenSSL 3.0 and should no longer be used, |
fe2d3975 BB |
56 | EC_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. |
57 | When 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). | |
4fcd15c1 | 58 | Modern versions should instead use EC_POINT_mul(), combined (if needed) with EC_POINT_add() in such rare circumstances. |
aafbe1cc MC |
59 | |
60 | The function EC_GROUP_precompute_mult stores multiples of the generator for faster point multiplication, whilst | |
9b86974e | 61 | EC_GROUP_have_precompute_mult tests whether precomputation has already been done. See L<EC_GROUP_copy(3)> for information |
6b4eb933 BB |
62 | about the generator. Precomputation functionality was deprecated in OpenSSL 3.0. |
63 | Users of EC_GROUP_precompute_mult() and EC_GROUP_have_precompute_mult() should | |
64 | switch to named curves which OpenSSL has hardcoded lookup tables for. | |
aafbe1cc MC |
65 | |
66 | =head1 RETURN VALUES | |
67 | ||
68 | The following functions return 1 on success or 0 on error: EC_POINT_add, EC_POINT_dbl, EC_POINT_invert, EC_POINT_make_affine, | |
69 | EC_POINTs_make_affine, EC_POINTs_make_affine, EC_POINT_mul, EC_POINTs_mul and EC_GROUP_precompute_mult. | |
70 | ||
71 | EC_POINT_is_at_infinity returns 1 if the point is at infinity, or 0 otherwise. | |
72 | ||
73 | EC_POINT_is_on_curve returns 1 if the point is on the curve, 0 if not, or -1 on error. | |
74 | ||
75 | EC_POINT_cmp returns 1 if the points are not equal, 0 if they are, or -1 on error. | |
76 | ||
77 | EC_GROUP_have_precompute_mult return 1 if a precomputation has been done, or 0 if not. | |
78 | ||
79 | =head1 SEE ALSO | |
80 | ||
9e183d22 | 81 | L<crypto(7)>, L<EC_GROUP_new(3)>, L<EC_GROUP_copy(3)>, |
9b86974e RS |
82 | L<EC_POINT_new(3)>, L<EC_KEY_new(3)>, |
83 | L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)> | |
aafbe1cc | 84 | |
4fcd15c1 BB |
85 | =head1 HISTORY |
86 | ||
c2f2db9b BB |
87 | EC_POINT_make_affine(), EC_POINTs_make_affine(), EC_POINTs_mul(), |
88 | EC_GROUP_precompute_mult(), and EC_GROUP_have_precompute_mult() | |
6b4eb933 | 89 | were deprecated in OpenSSL 3.0. |
4fcd15c1 | 90 | |
e2f92610 RS |
91 | =head1 COPYRIGHT |
92 | ||
00c405b3 | 93 | Copyright 2013-2020 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 94 | |
4746f25a | 95 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
96 | this file except in compliance with the License. You can obtain a copy |
97 | in the file LICENSE in the source distribution or at | |
98 | L<https://www.openssl.org/source/license.html>. | |
99 | ||
100 | =cut |