path: root/lib/libcrypto/man/EC_POINT_add.3

.\"	$OpenBSD: EC_POINT_add.3,v 1.12 2023/04/12 09:55:22 jsg Exp $
.\"	OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
.\"
.\" This file was written by Matt Caswell <matt@openssl.org>.
.\" Copyright (c) 2013 The OpenSSL Project.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\"
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in
.\"    the documentation and/or other materials provided with the
.\"    distribution.
.\"
.\" 3. All advertising materials mentioning features or use of this
.\"    software must display the following acknowledgment:
.\"    "This product includes software developed by the OpenSSL Project
.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
.\"
.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
.\"    endorse or promote products derived from this software without
.\"    prior written permission. For written permission, please contact
.\"    openssl-core@openssl.org.
.\"
.\" 5. Products derived from this software may not be called "OpenSSL"
.\"    nor may "OpenSSL" appear in their names without prior written
.\"    permission of the OpenSSL Project.
.\"
.\" 6. Redistributions of any form whatsoever must retain the following
.\"    acknowledgment:
.\"    "This product includes software developed by the OpenSSL Project
.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
.\" OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd $Mdocdate: April 12 2023 $
.Dt EC_POINT_ADD 3
.Os
.Sh NAME
.Nm EC_POINT_add ,
.Nm EC_POINT_dbl ,
.Nm EC_POINT_invert ,
.Nm EC_POINT_is_at_infinity ,
.Nm EC_POINT_is_on_curve ,
.Nm EC_POINT_cmp ,
.Nm EC_POINT_make_affine ,
.Nm EC_POINTs_make_affine ,
.Nm EC_POINTs_mul ,
.Nm EC_POINT_mul ,
.Nm EC_GROUP_precompute_mult ,
.Nm EC_GROUP_have_precompute_mult
.Nd perform mathematical operations and tests on EC_POINT objects
.Sh SYNOPSIS
.In openssl/ec.h
.In openssl/bn.h
.Ft int
.Fo EC_POINT_add
.Fa "const EC_GROUP *group"
.Fa "EC_POINT *r"
.Fa "const EC_POINT *a"
.Fa "const EC_POINT *b"
.Fa "BN_CTX *ctx"
.Fc
.Ft int
.Fo EC_POINT_dbl
.Fa "const EC_GROUP *group"
.Fa "EC_POINT *r"
.Fa "const EC_POINT *a"
.Fa "BN_CTX *ctx"
.Fc
.Ft int
.Fo EC_POINT_invert
.Fa "const EC_GROUP *group"
.Fa "EC_POINT *a"
.Fa "BN_CTX *ctx"
.Fc
.Ft int
.Fo EC_POINT_is_at_infinity
.Fa "const EC_GROUP *group"
.Fa "const EC_POINT *p"
.Fc
.Ft int
.Fo EC_POINT_is_on_curve
.Fa "const EC_GROUP *group"
.Fa "const EC_POINT *point"
.Fa "BN_CTX *ctx"
.Fc
.Ft int
.Fo EC_POINT_cmp
.Fa "const EC_GROUP *group"
.Fa "const EC_POINT *a"
.Fa "const EC_POINT *b"
.Fa "BN_CTX *ctx"
.Fc
.Ft int
.Fo EC_POINT_make_affine
.Fa "const EC_GROUP *group"
.Fa "EC_POINT *point"
.Fa "BN_CTX *ctx"
.Fc
.Ft int
.Fo EC_POINTs_make_affine
.Fa "const EC_GROUP *group"
.Fa "size_t num"
.Fa "EC_POINT *points[]"
.Fa "BN_CTX *ctx"
.Fc
.Ft int
.Fo EC_POINTs_mul
.Fa "const EC_GROUP *group"
.Fa "EC_POINT *r"
.Fa "const BIGNUM *n"
.Fa "size_t num"
.Fa "const EC_POINT *p[]"
.Fa "const BIGNUM *m[]"
.Fa "BN_CTX *ctx"
.Fc
.Ft int
.Fo EC_POINT_mul
.Fa "const EC_GROUP *group"
.Fa "EC_POINT *r"
.Fa "const BIGNUM *n"
.Fa "const EC_POINT *q"
.Fa "const BIGNUM *m"
.Fa "BN_CTX *ctx"
.Fc
.Ft int
.Fo EC_GROUP_precompute_mult
.Fa "EC_GROUP *group"
.Fa "BN_CTX *ctx"
.Fc
.Ft int
.Fo EC_GROUP_have_precompute_mult
.Fa "const EC_GROUP *group"
.Fc
.Sh DESCRIPTION
These functions operate on
.Vt EC_POINT
objects created by
.Xr EC_POINT_new 3 .
.Pp
.Fn EC_POINT_add
adds the two points
.Fa a
and
.Fa b
and places the result in
.Fa r .
Similarly
.Fn EC_POINT_dbl
doubles the point
.Fa a
and places the result in
.Fa r .
In both cases it is valid for
.Fa r
to be one of
.Fa a
or
.Fa b .
.Pp
.Fn EC_POINT_invert
calculates the inverse of the supplied point
.Fa a .
The result is placed back in
.Fa a .
.Pp
The function
.Fn EC_POINT_is_at_infinity
tests whether the supplied point is at infinity or not.
.Pp
.Fn EC_POINT_is_on_curve
tests whether the supplied point is on the curve or not.
.Pp
.Fn EC_POINT_cmp
compares the two supplied points and tests whether or not they are
equal.
.Pp
The functions
.Fn EC_POINT_make_affine
and
.Fn EC_POINTs_make_affine
force the internal representation of the
.Vt EC_POINT Ns s
into the affine coordinate system.
In the case of
.Fn EC_POINTs_make_affine ,
the value
.Fa num
provides the number of points in the array
.Fa points
to be forced.
.Pp
.Fn EC_POINT_mul
calculates the value
.Pp
.D1 generator * n + q * m
.Pp
and stores the result in
.Fa r .
The value
.Fa n
may be
.Dv NULL ,
in which case the result is just
.Pp
.Dl q * m.
.Pp
.Fn EC_POINTs_mul
only supports the values 0 and 1 for
.Fa num .
If it is 1, then
.Fn EC_POINTs_mul
calculates the value
.Pp
.Dl generator * n + q[0] * m[0].
.Pp
If
.Fa num
is 0 then
.Fa q
and
.Fa m
must be
.Dv NULL ,
and the result is just
.Pp
.Dl generator * n .
.Pp
As for
.Fn EC_POINT_mul ,
the value
.Fa n
may be
.Dv NULL .
.Pp
The function
.Fn EC_GROUP_precompute_mult
stores multiples of the generator for faster point multiplication,
whilst
.Fn EC_GROUP_have_precompute_mult
tests whether precomputation has already been done.
See
.Xr EC_GROUP_copy 3
for information about the generator.
.Sh RETURN VALUES
The following functions return 1 on success or 0 on error:
.Fn EC_POINT_add ,
.Fn EC_POINT_dbl ,
.Fn EC_POINT_invert ,
.Fn EC_POINT_make_affine ,
.Fn EC_POINTs_make_affine ,
.Fn EC_POINT_mul ,
.Fn EC_POINTs_mul ,
and
.Fn EC_GROUP_precompute_mult .
.Pp
.Fn EC_POINT_is_at_infinity
returns 1 if the point is at infinity or 0 otherwise.
.Pp
.Fn EC_POINT_is_on_curve
returns 1 if the point is on the curve, 0 if not, or -1 on error.
.Pp
.Fn EC_POINT_cmp
returns 1 if the points are not equal, 0 if they are, or -1 on error.
.Pp
.Fn EC_GROUP_have_precompute_mult
returns 1 if a precomputation has been done or 0 if not.
.Sh SEE ALSO
.Xr d2i_ECPKParameters 3 ,
.Xr EC_GFp_simple_method 3 ,
.Xr EC_GROUP_copy 3 ,
.Xr EC_GROUP_new 3 ,
.Xr EC_KEY_new 3 ,
.Xr EC_POINT_new 3
.Sh HISTORY
.Fn EC_POINT_add ,
.Fn EC_POINT_dbl ,
.Fn EC_POINT_invert ,
.Fn EC_POINT_is_at_infinity ,
.Fn EC_POINT_is_on_curve ,
.Fn EC_POINT_cmp ,
.Fn EC_POINT_make_affine ,
.Fn EC_POINTs_make_affine ,
.Fn EC_POINTs_mul ,
.Fn EC_POINT_mul ,
and
.Fn EC_GROUP_precompute_mult
first appeared in OpenSSL 0.9.7 and have been available since
.Ox 3.2 .
.Pp
.Fn EC_GROUP_have_precompute_mult
first appeared in OpenSSL 0.9.8 and has been available since
.Ox 4.5 .