NAME

EC_POINT_new, EC_POINT_free, EC_POINT_clear_free, EC_POINT_copy, EC_POINT_dup — allocate, free and copy elliptic curve points

SYNOPSIS

/* -lcrypto */
#include <openssl/ec.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 *point, const EC_GROUP *group);

DESCRIPTION

An EC_POINT object holds a point on the elliptic curve represented by an EC_GROUP. The details of the internal representation depend on the group and should never be an application's concern since the EC library has API to set a point's coordinates, EC_POINT_set_affine_coordinates(3).

EC_POINT_new() allocates and initializes an EC_POINT object to be used with the group. Before explicitly setting its coordinates, the returned EC_POINT is invalid.

EC_POINT_free() frees point and all memory associated with it. If point is a NULL pointer, no action occurs.

EC_POINT_clear_free() is intended to destroy sensitive data held in point in addition to freeing all memory associated with it. Since elliptic curve points usually hold public data, this is rarely needed. In LibreSSL, EC_POINT_free() and EC_POINT_clear_free() behave identically.

EC_POINT_copy() copies the internal representation of src into dst. If src and dst are identical, no action occurs. Both src and dst should be the result of EC_POINT_new() with the same group argument, although EC_POINT_copy() cannot check that.

EC_POINT_dup() creates a deep copy of point by combining EC_POINT_new() with EC_GROUP_copy().

RETURN VALUES

EC_POINT_new() returns a newly allocated EC_POINT or NULL on memory allocation failure.

EC_POINT_copy() returns 1 on success or 0 on error. Error conditions include memory allocation failure and that dst is incompatible with the group on which src is defined.

EC_POINT_dup() returns a newly allocated EC_POINT or NULL on failure. Error conditions include memory allocation failure or that group is incompatible with src.

SEE ALSO

BN_CTX_new(3), BN_is_zero(3), crypto(3), d2i_ECPKParameters(3), EC_GROUP_check(3), EC_GROUP_get_curve_name(3), EC_GROUP_new_by_curve_name(3), EC_GROUP_new_curve_GFp(3), EC_KEY_METHOD_new(3), EC_KEY_new(3), EC_POINT_add(3), EC_POINT_get_affine_coordinates(3), EC_POINT_point2oct(3), ECDH_compute_key(3), ECDSA_SIG_new(3)

HISTORY

EC_POINT_new(), EC_POINT_free(), EC_POINT_clear_free(), and EC_POINT_copy() first appeared in OpenSSL 0.9.7 and have been available since OpenBSD 3.2.

EC_POINT_dup() first appeared in OpenSSL 0.9.8 and has been available since OpenBSD 4.5.

BUGS

A fundamental flaw in the OpenSSL API toolkit is that *_new() functions usually create invalid objects that are tricky to turn into valid objects. One specific flaw in the EC library internals is that EC_POINT objects do not hold a reference to the group they live on despite the fact that EC_POINT_new() has a group argument. This is difficult to fix because EC_GROUP objects are not reference counted and because of const qualifiers in the API. This is the root cause for various contortions in the EC library and API and there are security implications because not only does the library not know whether an EC_POINT object represents a valid point, even if it did know that it would still not know on what curve.

The signature of EC_GROUP_dup() is bizarre and the order of point and group is inconsistent with the rest of the EC API.