Debian Codegraph @

upstream/debian-unstable/man3/EC_POINT_add.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "EC_POINT_ADD 3SSL"
58 .TH EC_POINT_ADD 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 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
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& #include <openssl/ec.h>
69 \&
70 \& int EC_POINT_add(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a,
71 \& const EC_POINT *b, BN_CTX *ctx);
72 \& int EC_POINT_dbl(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, BN_CTX *ctx);
73 \& int EC_POINT_invert(const EC_GROUP *group, EC_POINT *a, BN_CTX *ctx);
74 \& int EC_POINT_is_at_infinity(const EC_GROUP *group, const EC_POINT *p);
75 \& int EC_POINT_is_on_curve(const EC_GROUP *group, const EC_POINT *point, BN_CTX *ctx);
76 \& int EC_POINT_cmp(const EC_GROUP *group, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx);
77 \& int EC_POINT_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n,
78 \& const EC_POINT *q, const BIGNUM *m, BN_CTX *ctx);
79 .Ve
80 .PP
81 The following functions have been deprecated since OpenSSL 3.0, and can be
82 hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value,
83 see \fBopenssl_user_macros\fR\|(7):
84 .PP
85 .Vb 7
86 \& int EC_POINT_make_affine(const EC_GROUP *group, EC_POINT *point, BN_CTX *ctx);
87 \& int EC_POINTs_make_affine(const EC_GROUP *group, size_t num,
88 \& EC_POINT *points[], BN_CTX *ctx);
89 \& int EC_POINTs_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, size_t num,
90 \& const EC_POINT *p[], const BIGNUM *m[], BN_CTX *ctx);
91 \& int EC_GROUP_precompute_mult(EC_GROUP *group, BN_CTX *ctx);
92 \& int EC_GROUP_have_precompute_mult(const EC_GROUP *group);
93 .Ve
94 .SH DESCRIPTION
95 .IX Header "DESCRIPTION"
96 EC_POINT_add adds the two points \fBa\fR and \fBb\fR and places the result in \fBr\fR. Similarly EC_POINT_dbl doubles the point \fBa\fR and places the
97 result in \fBr\fR. In both cases it is valid for \fBr\fR to be one of \fBa\fR or \fBb\fR.
98 .PP
99 EC_POINT_invert calculates the inverse of the supplied point \fBa\fR. The result is placed back in \fBa\fR.
100 .PP
101 The function EC_POINT_is_at_infinity tests whether the supplied point is at infinity or not.
102 .PP
103 EC_POINT_is_on_curve tests whether the supplied point is on the curve or not.
104 .PP
105 EC_POINT_cmp compares the two supplied points and tests whether or not they are equal.
106 .PP
107 The functions EC_POINT_make_affine and EC_POINTs_make_affine force the internal representation of the EC_POINT(s) into the affine
108 coordinate system. In the case of EC_POINTs_make_affine the value \fBnum\fR provides the number of points in the array \fBpoints\fR to be
109 forced. These functions were deprecated in OpenSSL 3.0 and should no longer be used.
110 Modern versions automatically perform this conversion when needed.
111 .PP
112 EC_POINT_mul calculates the value generator * \fBn\fR + \fBq\fR * \fBm\fR and stores the result in \fBr\fR.
113 The value \fBn\fR may be NULL in which case the result is just \fBq\fR * \fBm\fR (variable point multiplication). Alternatively, both \fBq\fR and \fBm\fR may be NULL, and \fBn\fR non-NULL, in which case the result is just generator * \fBn\fR (fixed point multiplication).
114 When performing a single fixed or variable point multiplication, the underlying implementation uses a constant time algorithm, when the input scalar (either \fBn\fR or \fBm\fR) is in the range [0, ec_group_order).
115 .PP
116 Although deprecated in OpenSSL 3.0 and should no longer be used,
117 EC_POINTs_mul calculates the value generator * \fBn\fR + \fBq[0]\fR * \fBm[0]\fR + ... + \fBq[num\-1]\fR * \fBm[num\-1]\fR. As for EC_POINT_mul the value \fBn\fR may be NULL or \fBnum\fR may be zero.
118 When performing a fixed point multiplication (\fBn\fR is non-NULL and \fBnum\fR is 0) or a variable point multiplication (\fBn\fR is NULL and \fBnum\fR is 1), the underlying implementation uses a constant time algorithm, when the input scalar (either \fBn\fR or \fBm[0]\fR) is in the range [0, ec_group_order).
119 Modern versions should instead use \fBEC_POINT_mul()\fR, combined (if needed) with \fBEC_POINT_add()\fR in such rare circumstances.
120 .PP
121 The function EC_GROUP_precompute_mult stores multiples of the generator for faster point multiplication, whilst
122 EC_GROUP_have_precompute_mult tests whether precomputation has already been done. See \fBEC_GROUP_copy\fR\|(3) for information
123 about the generator. Precomputation functionality was deprecated in OpenSSL 3.0.
124 Users of \fBEC_GROUP_precompute_mult()\fR and \fBEC_GROUP_have_precompute_mult()\fR should
125 switch to named curves which OpenSSL has hardcoded lookup tables for.
126 .SH "RETURN VALUES"
127 .IX Header "RETURN VALUES"
128 The following functions return 1 on success or 0 on error: EC_POINT_add, EC_POINT_dbl, EC_POINT_invert, EC_POINT_make_affine,
129 EC_POINTs_make_affine, EC_POINTs_make_affine, EC_POINT_mul, EC_POINTs_mul and EC_GROUP_precompute_mult.
130 .PP
131 EC_POINT_is_at_infinity returns 1 if the point is at infinity, or 0 otherwise.
132 .PP
133 EC_POINT_is_on_curve returns 1 if the point is on the curve, 0 if not, or \-1 on error.
134 .PP
135 EC_POINT_cmp returns 1 if the points are not equal, 0 if they are, or \-1 on error.
136 .PP
137 EC_GROUP_have_precompute_mult return 1 if a precomputation has been done, or 0 if not.
138 .SH "SEE ALSO"
139 .IX Header "SEE ALSO"
140 \&\fBcrypto\fR\|(7), \fBEC_GROUP_new\fR\|(3), \fBEC_GROUP_copy\fR\|(3),
141 \&\fBEC_POINT_new\fR\|(3), \fBEC_KEY_new\fR\|(3),
142 \&\fBEC_GFp_simple_method\fR\|(3), \fBd2i_ECPKParameters\fR\|(3)
143 .SH HISTORY
144 .IX Header "HISTORY"
145 \&\fBEC_POINT_make_affine()\fR, \fBEC_POINTs_make_affine()\fR, \fBEC_POINTs_mul()\fR,
146 \&\fBEC_GROUP_precompute_mult()\fR, and \fBEC_GROUP_have_precompute_mult()\fR
147 were deprecated in OpenSSL 3.0.
148 .SH COPYRIGHT
149 .IX Header "COPYRIGHT"
150 Copyright 2013\-2023 The OpenSSL Project Authors. All Rights Reserved.
151 .PP
152 Licensed under the Apache License 2.0 (the "License"). You may not use
153 this file except in compliance with the License. You can obtain a copy
154 in the file LICENSE in the source distribution or at
155 <https://www.openssl.org/source/license.html>.