### 12.7 EC functions ¶

Libgcrypt provides an API to access low level functions used by its elliptic curve implementation. These functions allow implementing 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.