12.7 EC functions

Libgcrypt provides an API to access low level functions used by its elliptic curve implementation. These functions allow to implement elliptic curve methods for which no explicit support is available.

Function: gcry_mpi_point_t gcry_mpi_point_new (unsigned int nbits)

Allocate a new point object, initialize it to 0, and allocate enough memory for a points of at least nbits. This pre-allocation yields only a small performance win and is not really necessary because Libgcrypt automatically re-allocates the required memory. Using 0 for nbits is usually the right thing to do.

Function: void gcry_mpi_point_release (gcry_mpi_point_t point)

Release point and free all associated resources. Passing NULL is allowed and ignored.

Function: gcry_mpi_point_t gcry_mpi_point_copy (gcry_mpi_point_t point)

Allocate and return a new point object and initialize it with point. If point is NULL, the function is identical to gcry_mpi_point_new(0).

Function: void gcry_mpi_point_get (gcry_mpi_t x, gcry_mpi_t y, gcry_mpi_t z, gcry_mpi_point_t point)

Store the projective coordinates from point into the MPIs x, y, and z. If a coordinate is not required, NULL may be used for x, y, or z.

Function: void gcry_mpi_point_snatch_get (gcry_mpi_t x, gcry_mpi_t y, gcry_mpi_t z, gcry_mpi_point_t point)

Store the projective coordinates from point into the MPIs x, y, and z. If a coordinate is not required, NULL may be used for x, y, or z. The object point is then released. Using this function instead of gcry_mpi_point_get and gcry_mpi_point_release has the advantage of avoiding some extra memory allocations and copies.

Function: gcry_mpi_point_t gcry_mpi_point_set ( gcry_mpi_point_t point, gcry_mpi_t x, gcry_mpi_t y, gcry_mpi_t z)

Store the projective coordinates from x, y, and z into point. If a coordinate is given as NULL, the value 0 is used. If NULL is used for point, a new point object is allocated and returned. Returns point or the newly allocated point object.

Function: gcry_mpi_point_t gcry_mpi_point_snatch_set ( gcry_mpi_point_t point, gcry_mpi_t x, gcry_mpi_t y, gcry_mpi_t z)

Store the projective coordinates from x, y, and z into point. If a coordinate is given as NULL, the value 0 is used. If NULL is used for point, a new point object is allocated and returned. The MPIs x, y, and z are released. Using this function instead of gcry_mpi_point_set and 3 calls to gcry_mpi_release has the advantage of avoiding some extra memory allocations and copies. Returns point or the newly allocated point object.

Function: gpg_error_t gcry_mpi_ec_new (gcry_ctx_t *r_ctx, gcry_sexp_t keyparam, const char *curvename)

Allocate a new context for elliptic curve operations. If keyparam is given, it specifies the parameters of the curve (see ecc_keyparam). If curvename is given in addition to keyparam and the key parameters do not include a named curve reference, the string curvename is used to fill in missing parameters. If only curvename is given, the context is initialized for this named curve.

If a parameter specifying a point (e.g. g or q) is not found, the parser looks for a non-encoded point by appending .x, .y, and .z to the parameter name and looking them all up to create a point. A parameter with the suffix .z is optional and defaults to 1.

On success the function returns 0 and stores the new context object at r_ctx; this object eventually needs to be released (see gcry_ctx_release). On error the function stores NULL at r_ctx and returns an error code.

Function: gcry_mpi_t gcry_mpi_ec_get_mpi ( const char *name, gcry_ctx_t ctx, int copy)

Return the MPI with name from the context ctx. If not found, NULL is returned. If the returned MPI may later be modified, it is suggested to pass 1 to copy, so that the function guarantees that a modifiable copy of the MPI is returned. If 0 is used for copy, this function may return a constant flagged MPI. In any case gcry_mpi_release needs to be called to release the result. For valid names, see ecc_keyparam. If the public key q is requested but only the private key d is available, q will be recomputed on the fly. If a point parameter is requested, it is returned as an uncompressed encoded point unless these special names are used:

q@eddsa

Return an EdDSA style compressed point. This is only supported for Twisted Edwards curves.

Function: gcry_mpi_point_t gcry_mpi_ec_get_point ( const char *name, gcry_ctx_t ctx, int copy)

Return the point with name from the context ctx. If not found, NULL is returned. If the returned MPI may later be modified, it is suggested to pass 1 to copy, so that the function guarantees that a modifiable copy of the MPI is returned. If 0 is used for copy, this function may return a constant flagged point. In any case gcry_mpi_point_release needs to be called to release the result. If the public key q is requested but only the private key d is available, q will be recomputed on the fly.

Function: gpg_error_t gcry_mpi_ec_set_mpi ( const char *name, gcry_mpi_t newvalue, gcry_ctx_t ctx)

Store the MPI newvalue at name into the context ctx. On success 0 is returned; on error an error code. Valid names are the MPI parameters of an elliptic curve (see ecc_keyparam).

Function: gpg_error_t gcry_mpi_ec_set_point ( const char *name, gcry_mpi_point_t newvalue, gcry_ctx_t ctx)

Store the point newvalue at name into the context ctx. On success 0 is returned; on error an error code. Valid names are the point parameters of an elliptic curve (see ecc_keyparam).

Function: gpg_err_code_t gcry_mpi_ec_decode_point ( mpi_point_t result, gcry_mpi_t value, gcry_ctx_t ctx)

Decode the point given as an MPI in value and store at result. To decide which encoding is used the function takes a context ctx which can be created with gcry_mpi_ec_new. If NULL is given for the context, the function assumes a 0x04 prefixed uncompressed encoding. On error an error code is returned and result might be changed.

Function: int gcry_mpi_ec_get_affine ( gcry_mpi_t x, gcry_mpi_t y, gcry_mpi_point_t point, gcry_ctx_t ctx)

Compute the affine coordinates from the projective coordinates in point and store them into x and y. If one coordinate is not required, NULL may be passed to x or y. ctx is the context object which has been created using gcry_mpi_ec_new. Returns 0 on success or not 0 if point is at infinity.

Note that you can use gcry_mpi_ec_set_point with the value GCRYMPI_CONST_ONE for z to convert affine coordinates back into projective coordinates.

Function: void gcry_mpi_ec_dup ( gcry_mpi_point_t w, gcry_mpi_point_t u, gcry_ctx_t ctx)

Double the point u of the elliptic curve described by ctx and store the result into w.

Function: void gcry_mpi_ec_add ( gcry_mpi_point_t w, gcry_mpi_point_t u, gcry_mpi_point_t v, gcry_ctx_t ctx)

Add the points u and v of the elliptic curve described by ctx and store the result into w.

Function: void gcry_mpi_ec_sub ( gcry_mpi_point_t w, gcry_mpi_point_t u, gcry_mpi_point_t v, gcry_ctx_t ctx)

Subtracts the point v from the point u of the elliptic curve described by ctx and store the result into w. Only Twisted Edwards curves are supported for now.

Function: void gcry_mpi_ec_mul ( gcry_mpi_point_t w, gcry_mpi_t n, gcry_mpi_point_t u, gcry_ctx_t ctx)

Multiply the point u of the elliptic curve described by ctx by n and store the result into w.

Function: int gcry_mpi_ec_curve_point ( gcry_mpi_point_t point, gcry_ctx_t ctx)

Return true if point is on the elliptic curve described by ctx.