.\" $OpenBSD: EC_POINT_new.3,v 1.11 2019/08/19 13:08:26 schwarze Exp $
.\" full merge up to: OpenSSL ddc1caac Mar 6 14:00:24 2018 -0500
.\"
.\" This file was written by Matt Caswell <matt@openssl.org>.
.\" Copyright (c) 2013, 2016 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: August 19 2019 $
.Dt EC_POINT_NEW 3
.Os
.Sh NAME
.Nm EC_POINT_new ,
.Nm EC_POINT_free ,
.Nm EC_POINT_clear_free ,
.Nm EC_POINT_copy ,
.Nm EC_POINT_dup ,
.Nm EC_POINT_method_of ,
.Nm EC_POINT_set_to_infinity ,
.Nm EC_POINT_set_affine_coordinates_GFp ,
.Nm EC_POINT_set_affine_coordinates_GF2m ,
.Nm EC_POINT_get_affine_coordinates_GFp ,
.Nm EC_POINT_get_affine_coordinates_GF2m ,
.Nm EC_POINT_set_Jprojective_coordinates_GFp ,
.Nm EC_POINT_get_Jprojective_coordinates_GFp ,
.Nm EC_POINT_set_compressed_coordinates_GFp ,
.Nm EC_POINT_set_compressed_coordinates_GF2m ,
.Nm EC_POINT_point2oct ,
.Nm EC_POINT_oct2point ,
.Nm EC_POINT_point2bn ,
.Nm EC_POINT_bn2point ,
.Nm EC_POINT_point2hex ,
.Nm EC_POINT_hex2point
.Nd create, destroy, and manipulate EC_POINT objects
.Sh SYNOPSIS
.In openssl/ec.h
.In openssl/bn.h
.Ft EC_POINT *
.Fo EC_POINT_new
.Fa "const EC_GROUP *group"
.Fc
.Ft void
.Fo EC_POINT_free
.Fa "EC_POINT *point"
.Fc
.Ft void
.Fo EC_POINT_clear_free
.Fa "EC_POINT *point"
.Fc
.Ft int
.Fo EC_POINT_copy
.Fa "EC_POINT *dst"
.Fa "const EC_POINT *src"
.Fc
.Ft EC_POINT *
.Fo EC_POINT_dup
.Fa "const EC_POINT *src"
.Fa "const EC_GROUP *group"
.Fc
.Ft const EC_METHOD *
.Fo EC_POINT_method_of
.Fa "const EC_POINT *point"
.Fc
.Ft int
.Fo EC_POINT_set_to_infinity
.Fa "const EC_GROUP *group"
.Fa "EC_POINT *point"
.Fc
.Ft int
.Fo EC_POINT_set_affine_coordinates_GFp
.Fa "const EC_GROUP *group"
.Fa "EC_POINT *p"
.Fa "const BIGNUM *x"
.Fa "const BIGNUM *y"
.Fa "BN_CTX *ctx"
.Fc
.Ft int
.Fo EC_POINT_set_affine_coordinates_GF2m
.Fa "const EC_GROUP *group"
.Fa "EC_POINT *p"
.Fa "const BIGNUM *x"
.Fa "const BIGNUM *y"
.Fa "BN_CTX *ctx"
.Fc
.Ft int
.Fo EC_POINT_get_affine_coordinates_GFp
.Fa "const EC_GROUP *group"
.Fa "const EC_POINT *p"
.Fa "BIGNUM *x"
.Fa "BIGNUM *y"
.Fa "BN_CTX *ctx"
.Fc
.Ft int
.Fo EC_POINT_get_affine_coordinates_GF2m
.Fa "const EC_GROUP *group"
.Fa "const EC_POINT *p"
.Fa "BIGNUM *x"
.Fa "BIGNUM *y"
.Fa "BN_CTX *ctx"
.Fc
.Ft int
.Fo EC_POINT_set_Jprojective_coordinates_GFp
.Fa "const EC_GROUP *group"
.Fa "EC_POINT *p"
.Fa "const BIGNUM *x"
.Fa "const BIGNUM *y"
.Fa "const BIGNUM *z"
.Fa "BN_CTX *ctx"
.Fc
.Ft int
.Fo EC_POINT_get_Jprojective_coordinates_GFp
.Fa "const EC_GROUP *group"
.Fa "const EC_POINT *p"
.Fa "BIGNUM *x"
.Fa "BIGNUM *y"
.Fa "BIGNUM *z"
.Fa "BN_CTX *ctx"
.Fc
.Ft int
.Fo EC_POINT_set_compressed_coordinates_GFp
.Fa "const EC_GROUP *group"
.Fa "EC_POINT *p"
.Fa "const BIGNUM *x"
.Fa "int y_bit"
.Fa "BN_CTX *ctx"
.Fc
.Ft int
.Fo EC_POINT_set_compressed_coordinates_GF2m
.Fa "const EC_GROUP *group"
.Fa "EC_POINT *p"
.Fa "const BIGNUM *x"
.Fa "int y_bit"
.Fa "BN_CTX *ctx"
.Fc
.Ft size_t
.Fo EC_POINT_point2oct
.Fa "const EC_GROUP *group"
.Fa "const EC_POINT *p"
.Fa "point_conversion_form_t form"
.Fa "unsigned char *buf"
.Fa "size_t len"
.Fa "BN_CTX *ctx"
.Fc
.Ft int
.Fo EC_POINT_oct2point
.Fa "const EC_GROUP *group"
.Fa "EC_POINT *p"
.Fa "const unsigned char *buf"
.Fa "size_t len"
.Fa "BN_CTX *ctx"
.Fc
.Ft BIGNUM *
.Fo EC_POINT_point2bn
.Fa "const EC_GROUP *"
.Fa "const EC_POINT *"
.Fa "point_conversion_form_t form"
.Fa "BIGNUM *"
.Fa "BN_CTX *"
.Fc
.Ft EC_POINT *
.Fo EC_POINT_bn2point
.Fa "const EC_GROUP *"
.Fa "const BIGNUM *"
.Fa "EC_POINT *"
.Fa "BN_CTX *"
.Fc
.Ft char *
.Fo EC_POINT_point2hex
.Fa "const EC_GROUP *"
.Fa "const EC_POINT *"
.Fa "point_conversion_form_t form"
.Fa "BN_CTX *"
.Fc
.Ft EC_POINT *
.Fo EC_POINT_hex2point
.Fa "const EC_GROUP *"
.Fa "const char *"
.Fa "EC_POINT *"
.Fa "BN_CTX *"
.Fc
.Sh DESCRIPTION
An
.Vt EC_POINT
represents a point on a curve.
A curve is represented by an
.Vt EC_GROUP
object created by the functions described in
.Xr EC_GROUP_new 3 .
.Pp
A new point is constructed by calling the function
.Fn EC_POINT_new
and providing the
.Fa group
object that the point relates to.
.Pp
.Fn EC_POINT_free
frees the memory associated with the
.Vt EC_POINT .
If
.Fa point
is a
.Dv NULL
pointer, no action occurs.
.Pp
.Fn EC_POINT_clear_free
destroys any sensitive data held within the
.Vt EC_POINT
and then frees its memory.
If
.Fa point
is a
.Dv NULL
pointer, no action occurs.
.Pp
.Fn EC_POINT_copy
copies the point
.Fa src
into
.Fa dst .
Both
.Fa src
and
.Fa dst
must use the same
.Vt EC_METHOD .
.Pp
.Fn EC_POINT_dup
creates a new
.Vt EC_POINT
object and copies the content from
.Fa src
to the newly created
.Vt EC_POINT
object.
.Pp
.Fn EC_POINT_method_of
obtains the
.Vt EC_METHOD
associated with
.Fa point .
.Pp
A valid point on a curve is the special point at infinity.
A point is set to be at infinity by calling
.Fn EC_POINT_set_to_infinity .
.Pp
The affine coordinates for a point describe a point in terms of its
.Fa x
and
.Fa y
position.
The functions
.Fn EC_POINT_set_affine_coordinates_GFp
and
.Fn EC_POINT_set_affine_coordinates_GF2m
set the
.Fa x
and
.Fa y
coordinates for the point
.Fa p
defined over the curve given in
.Fa group .
The functions
.Fn EC_POINT_get_affine_coordinates_GFp
and
.Fn EC_POINT_get_affine_coordinates_GF2m
set
.Fa x
and
.Fa y ,
either of which may be
.Dv NULL ,
to the corresponding coordinates of
.Fa p .
.Pp
As well as the affine coordinates, a point can alternatively be
described in terms of its Jacobian projective coordinates (for Fp
curves only).
Jacobian projective coordinates are expressed as three values
.Fa x ,
.Fa y ,
and
.Fa z .
Working in this coordinate system provides more efficient point
multiplication operations.
A mapping exists between Jacobian projective coordinates and affine
coordinates.
A Jacobian projective coordinate
.Pq Fa x , y , z
can be written as an affine coordinate as
.Pp
.Dl (x/(z^2), y/(z^3)) .
.Pp
Conversion to Jacobian projective from affine coordinates is simple.
The coordinate
.Pq Fa x , y
is mapped to
.Pq Fa x , y , No 1 .
To set or get the projective coordinates use
.Fn EC_POINT_set_Jprojective_coordinates_GFp
and
.Fn EC_POINT_get_Jprojective_coordinates_GFp ,
respectively.
.Pp
Points can also be described in terms of their compressed coordinates.
For a point
.Pq Fa x , y ,
for any given value for
.Fa x
such that the point is on the curve, there will only ever be two
possible values for
.Fa y .
Therefore a point can be set using the
.Fn EC_POINT_set_compressed_coordinates_GFp
and
.Fn EC_POINT_set_compressed_coordinates_GF2m
functions where
.Fa x
is the x coordinate and
.Fa y_bit
is a value 0 or 1 to identify which of the two possible values for y
should be used.
.Pp
In addition
.Vt EC_POINT Ns s
can be converted to and from various external representations.
Supported representations are octet strings,
.Vt BIGNUM Ns s ,
and hexadecimal.
The format of the external representation is described by the
point_conversion_form.
See
.Xr EC_GROUP_copy 3
for a description of point_conversion_form.
Octet strings are stored in a buffer along with an associated buffer
length.
A point held in a
.Vt BIGNUM
is calculated by converting the point to an octet string and then
converting that octet string into a
.Vt BIGNUM
integer.
Points in hexadecimal format are stored in a NUL terminated character
string where each character is one of the printable values 0-9 or A-F
(or a-f).
.Pp
The functions
.Fn EC_POINT_point2oct ,
.Fn EC_POINT_oct2point ,
.Fn EC_POINT_point2bn ,
.Fn EC_POINT_bn2point ,
.Fn EC_POINT_point2hex ,
and
.Fn EC_POINT_hex2point
convert from and to
.Vt EC_POINT Ns s
for the formats octet string,
.Vt BIGNUM ,
and hexadecimal, respectively.
.Pp
The function
.Fn EC_POINT_point2oct
must be supplied with a
.Fa buf
long enough to store the octet string.
The return value provides the number of octets stored.
Calling the function with a
.Dv NULL
.Fa buf
will not perform the conversion but will still return the required
buffer length.
.Pp
The function
.Fn EC_POINT_point2hex
will allocate sufficient memory to store the hexadecimal string.
It is the caller's responsibility to free this memory with a subsequent
call to
.Xr free 3 .
.Sh RETURN VALUES
.Fn EC_POINT_new
and
.Fn EC_POINT_dup
return the newly allocated
.Vt EC_POINT
or
.Dv NULL
on error.
.Pp
The following functions return 1 on success or 0 on error:
.Fn EC_POINT_copy ,
.Fn EC_POINT_set_to_infinity ,
.Fn EC_POINT_set_Jprojective_coordinates_GFp ,
.Fn EC_POINT_get_Jprojective_coordinates_GFp ,
.Fn EC_POINT_set_affine_coordinates_GFp ,
.Fn EC_POINT_get_affine_coordinates_GFp ,
.Fn EC_POINT_set_compressed_coordinates_GFp ,
.Fn EC_POINT_set_affine_coordinates_GF2m ,
.Fn EC_POINT_get_affine_coordinates_GF2m ,
.Fn EC_POINT_set_compressed_coordinates_GF2m ,
and
.Fn EC_POINT_oct2point .
.Pp
.Fn EC_POINT_method_of
returns the
.Vt EC_METHOD
associated with the supplied
.Vt EC_POINT .
.Pp
.Fn EC_POINT_point2oct
returns the length of the required buffer, or 0 on error.
.Pp
.Fn EC_POINT_point2bn
returns the pointer to the
.Vt BIGNUM
supplied or
.Dv NULL
on error.
.Pp
.Fn EC_POINT_bn2point
returns the pointer to the
.Vt EC_POINT
supplied or
.Dv NULL
on error.
.Pp
.Fn EC_POINT_point2hex
returns a pointer to the hex string or
.Dv NULL
on error.
.Pp
.Fn EC_POINT_hex2point
returns the pointer to the
.Vt EC_POINT
supplied or
.Dv NULL
on error.
.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_add 3 ,
.Xr ECDH_compute_key 3
.Sh HISTORY
.Fn EC_POINT_new ,
.Fn EC_POINT_free ,
.Fn EC_POINT_clear_free ,
.Fn EC_POINT_copy ,
.Fn EC_POINT_method_of ,
.Fn EC_POINT_set_to_infinity ,
.Fn EC_POINT_set_affine_coordinates_GFp ,
.Fn EC_POINT_get_affine_coordinates_GFp ,
.Fn EC_POINT_set_Jprojective_coordinates_GFp ,
.Fn EC_POINT_get_Jprojective_coordinates_GFp ,
.Fn EC_POINT_set_compressed_coordinates_GFp ,
.Fn EC_POINT_point2oct ,
and
.Fn EC_POINT_oct2point
first appeared in OpenSSL 0.9.7 and have been available since
.Ox 3.2 .
.Pp
.Fn EC_POINT_dup ,
.Fn EC_POINT_set_affine_coordinates_GF2m ,
.Fn EC_POINT_get_affine_coordinates_GF2m ,
.Fn EC_POINT_set_compressed_coordinates_GF2m ,
.Fn EC_POINT_point2bn ,
.Fn EC_POINT_bn2point ,
.Fn EC_POINT_point2hex ,
and
.Fn EC_POINT_hex2point
first appeared in OpenSSL 0.9.8 and have been available since
.Ox 4.5 .