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_get_affine_coordinates, EC_POINT_get_affine_coordinates_GFp, 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_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_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_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); 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 function EC_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() is a deprecated synonym for EC_POINT_set_affine_coordinates() and the function EC_POINT_get_affine_coordinates_GFp() is a deprecated synonym 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. 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)).

Conversion to Jacobian projective from affine coordinates is simple. The coordinate (x, y) is mapped to (x, y, 1). To set or get the projective coordinates use 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() is a deprecated synonym 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_get_affine_coordinates(), EC_POINT_get_affine_coordinates_GFp(), EC_POINT_set_compressed_coordinates(), EC_POINT_set_compressed_coordinates_GFp(), 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_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.