OpenBSD manual page server

NAME

EC_POINT_new, EC_POINT_free, EC_POINT_clear_free, EC_POINT_copy, EC_POINT_dup, 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_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);

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_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.

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().

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_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_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_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_set_to_infinity(), EC_POINT_set_affine_coordinates_GFp(), EC_POINT_get_affine_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.