Sortix 1.1dev nightly manual
This manual documents Sortix 1.1dev nightly, a development build that has not been officially released. You can instead view this document in the latest official manual.
EC_POINT_NEW(3) | Library Functions Manual | EC_POINT_NEW(3) |
NAME
EC_POINT_new
,
EC_POINT_free
,
EC_POINT_clear_free
,
EC_POINT_copy
,
EC_POINT_dup
,
EC_POINT_method_of
,
EC_POINT_set_to_infinity
,
EC_POINT_set_affine_coordinates
,
EC_POINT_set_affine_coordinates_GFp
,
EC_POINT_set_affine_coordinates_GF2m
,
EC_POINT_get_affine_coordinates
,
EC_POINT_get_affine_coordinates_GFp
,
EC_POINT_get_affine_coordinates_GF2m
,
EC_POINT_set_Jprojective_coordinates_GFp
,
EC_POINT_get_Jprojective_coordinates_GFp
,
EC_POINT_set_compressed_coordinates
,
EC_POINT_set_compressed_coordinates_GFp
,
EC_POINT_set_compressed_coordinates_GF2m
,
EC_POINT_point2oct
,
EC_POINT_oct2point
,
EC_POINT_point2bn
,
EC_POINT_bn2point
,
EC_POINT_point2hex
,
EC_POINT_hex2point
—
create, destroy, and manipulate EC_POINT
objects
SYNOPSIS
#include
<openssl/ec.h>
#include
<openssl/bn.h>
EC_POINT *
EC_POINT_new
(const
EC_GROUP *group);
void
EC_POINT_free
(EC_POINT
*point);
void
EC_POINT_clear_free
(EC_POINT
*point);
int
EC_POINT_copy
(EC_POINT
*dst, const EC_POINT *src);
EC_POINT *
EC_POINT_dup
(const
EC_POINT *src, const EC_GROUP *group);
const EC_METHOD *
EC_POINT_method_of
(const
EC_POINT *point);
int
EC_POINT_set_to_infinity
(const
EC_GROUP *group, EC_POINT *point);
int
EC_POINT_set_affine_coordinates
(const
EC_GROUP *group, EC_POINT *p,
const BIGNUM *x,
const BIGNUM *y,
BN_CTX *ctx);
int
EC_POINT_set_affine_coordinates_GFp
(const
EC_GROUP *group, EC_POINT *p,
const BIGNUM *x,
const BIGNUM *y,
BN_CTX *ctx);
int
EC_POINT_set_affine_coordinates_GF2m
(const
EC_GROUP *group, EC_POINT *p,
const BIGNUM *x,
const BIGNUM *y,
BN_CTX *ctx);
int
EC_POINT_get_affine_coordinates
(const
EC_GROUP *group, const EC_POINT *p,
BIGNUM *x, BIGNUM
*y, BN_CTX *ctx);
int
EC_POINT_get_affine_coordinates_GFp
(const
EC_GROUP *group, const EC_POINT *p,
BIGNUM *x, BIGNUM
*y, BN_CTX *ctx);
int
EC_POINT_get_affine_coordinates_GF2m
(const
EC_GROUP *group, const EC_POINT *p,
BIGNUM *x, BIGNUM
*y, BN_CTX *ctx);
int
EC_POINT_set_Jprojective_coordinates_GFp
(const
EC_GROUP *group, EC_POINT *p,
const BIGNUM *x,
const BIGNUM *y,
const BIGNUM *z,
BN_CTX *ctx);
int
EC_POINT_get_Jprojective_coordinates_GFp
(const
EC_GROUP *group, const EC_POINT *p,
BIGNUM *x, BIGNUM
*y, BIGNUM *z,
BN_CTX *ctx);
int
EC_POINT_set_compressed_coordinates
(const
EC_GROUP *group, EC_POINT *p,
const BIGNUM *x,
int y_bit, BN_CTX
*ctx);
int
EC_POINT_set_compressed_coordinates_GFp
(const
EC_GROUP *group, EC_POINT *p,
const BIGNUM *x,
int y_bit, BN_CTX
*ctx);
int
EC_POINT_set_compressed_coordinates_GF2m
(const
EC_GROUP *group, EC_POINT *p,
const BIGNUM *x,
int y_bit, BN_CTX
*ctx);
size_t
EC_POINT_point2oct
(const
EC_GROUP *group, const EC_POINT *p,
point_conversion_form_t form,
unsigned char *buf,
size_t len, BN_CTX
*ctx);
int
EC_POINT_oct2point
(const
EC_GROUP *group, EC_POINT *p,
const unsigned char *buf,
size_t len, BN_CTX
*ctx);
BIGNUM *
EC_POINT_point2bn
(const
EC_GROUP *, const EC_POINT *,
point_conversion_form_t form,
BIGNUM *, BN_CTX
*);
EC_POINT *
EC_POINT_bn2point
(const
EC_GROUP *, const BIGNUM *,
EC_POINT *, BN_CTX
*);
char *
EC_POINT_point2hex
(const
EC_GROUP *, const EC_POINT *,
point_conversion_form_t form,
BN_CTX *);
EC_POINT *
EC_POINT_hex2point
(const
EC_GROUP *, const char *,
EC_POINT *, BN_CTX
*);
DESCRIPTION
An EC_POINT represents a point on a curve. A curve is represented by an EC_GROUP object created by the functions described in EC_GROUP_new(3). A new point is constructed by calling the functionEC_POINT_new
() and providing the
group object that the point relates to.
EC_POINT_free
() frees the memory associated
with the EC_POINT. If
point is a
NULL
pointer, no action occurs.
EC_POINT_clear_free
() destroys any sensitive
data held within the EC_POINT and then frees
its memory. If point is a
NULL
pointer, no action occurs.
EC_POINT_copy
() copies the point
src into
dst. Both
src and dst
must use the same EC_METHOD.
EC_POINT_dup
() creates a new
EC_POINT object and copies the content from
src to the newly created
EC_POINT object.
EC_POINT_method_of
() obtains the
EC_METHOD associated with
point.
A valid point on a curve is the special point at infinity. A point is set to be
at infinity by calling
EC_POINT_set_to_infinity
().
The affine coordinates for a point describe a point in terms of its
x and y
position. The function
EC_POINT_set_affine_coordinates
() sets the
x and y
coordinates for the point p defined over the
curve given in group. The function
EC_POINT_get_affine_coordinates
() sets
x and y,
either of which may be NULL
, to the
corresponding coordinates of p.
The functions
EC_POINT_set_affine_coordinates_GFp
() and
EC_POINT_set_affine_coordinates_GF2m
() are
deprecated synonyms for
EC_POINT_set_affine_coordinates
() and the
functions
EC_POINT_get_affine_coordinates_GFp
() and
EC_POINT_get_affine_coordinates_GF2m
() are
deprecated synonyms for
EC_POINT_get_affine_coordinates
().
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
x, y, and
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 (x,
y, z) can be
written as an affine coordinate as
(x/(z^2), y/(z^3)).
EC_POINT_set_Jprojective_coordinates_GFp
()
and
EC_POINT_get_Jprojective_coordinates_GFp
(),
respectively.
Points can also be described in terms of their compressed coordinates. For a
point (x,
y), for any given value for
x such that the point is on the curve, there
will only ever be two possible values for y.
Therefore, a point can be set using the
EC_POINT_set_compressed_coordinates
()
function where x is the x coordinate and
y_bit is a value 0 or 1 to identify which of
the two possible values for y should be used.
The functions
EC_POINT_set_compressed_coordinates_GFp
()
and
EC_POINT_set_compressed_coordinates_GF2m
()
are deprecated synonyms for
EC_POINT_set_compressed_coordinates
().
In addition EC_POINTs can be converted to and
from various external representations. Supported representations are octet
strings, BIGNUMs, and hexadecimal. The format
of the external representation is described by the point_conversion_form. See
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
BIGNUM is calculated by converting the point
to an octet string and then converting that octet string into a
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).
The functions EC_POINT_point2oct
(),
EC_POINT_oct2point
(),
EC_POINT_point2bn
(),
EC_POINT_bn2point
(),
EC_POINT_point2hex
(), and
EC_POINT_hex2point
() convert from and to
EC_POINTs for the formats octet string,
BIGNUM, and hexadecimal, respectively.
The function EC_POINT_point2oct
() must be
supplied with a buf long enough to store the
octet string. The return value provides the number of octets stored. Calling
the function with a NULL
buf will not perform the conversion but will
still return the required buffer length.
The function 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
free(3).
RETURN VALUES
EC_POINT_new
() and
EC_POINT_dup
() return the newly allocated
EC_POINT or
NULL
on error.
The following functions return 1 on success or 0 on error:
EC_POINT_copy
(),
EC_POINT_set_to_infinity
(),
EC_POINT_set_Jprojective_coordinates_GFp
(),
EC_POINT_get_Jprojective_coordinates_GFp
(),
EC_POINT_set_affine_coordinates
(),
EC_POINT_set_affine_coordinates_GFp
(),
EC_POINT_set_affine_coordinates_GF2m
(),
EC_POINT_get_affine_coordinates
(),
EC_POINT_get_affine_coordinates_GFp
(),
EC_POINT_get_affine_coordinates_GF2m
(),
EC_POINT_set_compressed_coordinates
(),
EC_POINT_set_compressed_coordinates_GFp
(),
EC_POINT_set_compressed_coordinates_GF2m
(),
and EC_POINT_oct2point
().
EC_POINT_method_of
() returns the
EC_METHOD associated with the supplied
EC_POINT.
EC_POINT_point2oct
() returns the length of
the required buffer, or 0 on error.
EC_POINT_point2bn
() returns the pointer to
the BIGNUM supplied or
NULL
on error.
EC_POINT_bn2point
() returns the pointer to
the EC_POINT supplied or
NULL
on error.
EC_POINT_point2hex
() returns a pointer to the
hex string or NULL
on error.
EC_POINT_hex2point
() returns the pointer to
the EC_POINT supplied or
NULL
on error.
SEE ALSO
d2i_ECPKParameters(3), EC_GFp_simple_method(3), EC_GROUP_copy(3), EC_GROUP_new(3), EC_KEY_new(3), EC_POINT_add(3), ECDH_compute_key(3)HISTORY
EC_POINT_new
(),
EC_POINT_free
(),
EC_POINT_clear_free
(),
EC_POINT_copy
(),
EC_POINT_method_of
(),
EC_POINT_set_to_infinity
(),
EC_POINT_set_affine_coordinates_GFp
(),
EC_POINT_get_affine_coordinates_GFp
(),
EC_POINT_set_Jprojective_coordinates_GFp
(),
EC_POINT_get_Jprojective_coordinates_GFp
(),
EC_POINT_set_compressed_coordinates_GFp
(),
EC_POINT_point2oct
(), and
EC_POINT_oct2point
() first appeared in
OpenSSL 0.9.7 and have been available since OpenBSD
3.2.
EC_POINT_dup
(),
EC_POINT_set_affine_coordinates_GF2m
(),
EC_POINT_get_affine_coordinates_GF2m
(),
EC_POINT_set_compressed_coordinates_GF2m
(),
EC_POINT_point2bn
(),
EC_POINT_bn2point
(),
EC_POINT_point2hex
(), and
EC_POINT_hex2point
() first appeared in
OpenSSL 0.9.8 and have been available since OpenBSD
4.5.
EC_POINT_set_affine_coordinates
(),
EC_POINT_get_affine_coordinates
(), and
EC_POINT_set_compressed_coordinates
() first
appeared in OpenSSL 1.1.1 and have been available since
OpenBSD 7.0.May 13, 2021 | Debian |