Next: Miscellaneous, Previous: Bit manipulations, Up: MPI library [Contents][Index]

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

Next: Miscellaneous, Previous: Bit manipulations, Up: MPI library [Contents][Index]