From 229f3219f80c9369ed9624242c0436ae6d293201 Mon Sep 17 00:00:00 2001 From: Werner Koch Date: Fri, 15 Mar 2013 14:43:19 +0100 Subject: mpi: Add functions to manipulate an EC context. * src/gcrypt.h.in (gcry_mpi_ec_p_new): Remove. (gcry_mpi_ec_new): New. (gcry_mpi_ec_get_mpi): New. (gcry_mpi_ec_get_point): New. (gcry_mpi_ec_set_mpi): New. (gcry_mpi_ec_set_point): New. * src/visibility.c (gcry_mpi_ec_p_new): Remove. * mpi/ec.c (_gcry_mpi_ec_p_new): Make it an internal function and change to return an error code. (_gcry_mpi_ec_get_mpi): New. (_gcry_mpi_ec_get_point): New. (_gcry_mpi_ec_set_mpi): New. (_gcry_mpi_ec_set_point): New. * src/mpi.h: Add new prototypes. * src/ec-context.h: New. * mpi/ec.c: Include that header. (mpi_ec_ctx_s): Move to ec-context.h, add new fields, and put some fields into an inner struct. (point_copy): New. * cipher/ecc.c (fill_in_curve): Allow passing NULL for R_NBITS. (mpi_from_keyparam, point_from_keyparam): New. (_gcry_mpi_ec_new): New. * tests/t-mpi-point.c (test-curve): New. (ec_p_new): New. Use it instead of the removed gcry_mpi_ec_p_new. (get_and_cmp_mpi, get_and_cmp_point): New. (context_param): New test. (basic_ec_math_simplified): New test. (main): Call new tests. * src/context.c (_gcry_ctx_get_pointer): Check for a NULL CTX. -- gcry_mpi_ec_p_new() was a specialized version of the more general new gcry_mpi_ec_new(). It was added to master only a few days ago, thus there should be no problem to remove it. A replacement can easily be written (cf. t-mpi-point.c). Note that gcry_mpi_ec_set_mpi and gcry_mpi_ec_set_point have not yet been tested. --- doc/gcrypt.texi | 82 ++++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 69 insertions(+), 13 deletions(-) (limited to 'doc') diff --git a/doc/gcrypt.texi b/doc/gcrypt.texi index a56d5278..4d48eb4c 100644 --- a/doc/gcrypt.texi +++ b/doc/gcrypt.texi @@ -2058,6 +2058,7 @@ and no @var{x-mpi}. @node ECC key parameters @subsection ECC key parameters +@anchor{ecc_keyparam} @noindent An ECC private key is described by this S-expression: @@ -2084,7 +2085,7 @@ Base point @math{g}. @item n-mpi Order of @math{g} @item q-point -The point representing the public key @math{Q = dP}. +The point representing the public key @math{Q = dG}. @item d-mpi The private key @math{d} @end table @@ -3919,16 +3920,71 @@ some extra memory allocations and copies. Returns @var{point} or the newly allocated point object. @end deftypefun -@anchor{gcry_mpi_ec_p_new} -@deftypefun gcry_ctx_t gcry_mpi_ec_p_new (@w{gcry_mpi_t @var{p}}, @ - @w{gcry_mpi_t @var{a}} +@anchor{gcry_mpi_ec_new} +@deftypefun gpg_error_t gcry_mpi_ec_p_new (@w{gpg_ctx_t *@var{r_ctx}}, @ + @w{gcry_sexp_t @var{keyparam}}, @w{const char *@var{curvename}}) -Allocate a new context for elliptic curve operations based on the -field GF(p). @var{p} is the prime specifying this field, @var{a} is -the first coefficient of the Weierstrass equation. The function -returns a context object which eventually needs to be released using -@ref{gcry_ctx_release}. On error this function returns @code{NULL} -and sets @code{errno}. +Allocate a new context for elliptic curve operations. If +@var{keyparam} is given it specifies the parameters of the curve +(@pxref{ecc_keyparam}). If @var{curvename} is given in addition to +@var{keyparam} and the key parameters do not include a named curve +reference, the string @var{curvename} is used to fill in missing +parameters. If only @var{curvename} is given, the context is +initialized for this named curve. + +If a parameter specifying a point (e.g. @code{g} or @code{q}) is not +found, the parser looks for a non-encoded point by appending +@code{.x}, @code{.y}, and @code{.z} to the parameter name and looking +them all up to create a point. A parameter with the suffix @code{.z} +is optional and defaults to 1. + +On success the function returns 0 and stores the new context object at +@var{r_ctx}; this object eventually needs to be released +(@pxref{gcry_ctx_release}). On error the function stores @code{NULL} at +@var{r_ctx} and returns an error code. +@end deftypefun + +@deftypefun gcry_mpi_t gcry_mpi_ec_get_mpi ( @ + @w{const char *@var{name}}, @w{gcry_ctx_t @var{ctx}}, @w{int @var{copy}}) + +Return the MPI with @var{name} from the context @var{ctx}. If not +found @code{NULL} is returned. If the returned MPI may later be +modified, it is suggested to pass @code{1} to @var{copy}, so that the +function guarantees that a modifiable copy of the MPI is returned. If +@code{0} is used for @var{copy}, this function may return a constant +flagged MPI. In any case @code{gcry_mpi_release} needs to be called +to release the result. For valid names @ref{ecc_keyparam}. +@end deftypefun + +@deftypefun gcry_mpi_point_t gcry_mpi_ec_get_point ( @ + @w{const char *@var{name}}, @w{gcry_ctx_t @var{ctx}}, @w{int @var{copy}}) + +Return the point with @var{name} from the context @var{ctx}. If not +found @code{NULL} is returned. If the returned MPI may later be +modified, it is suggested to pass @code{1} to @var{copy}, so that the +function guarantees that a modifiable copy of the MPI is returned. If +@code{0} is used for @var{copy}, this function may return a constant +flagged point. In any case @code{gcry_mpi_point_release} needs to be +called to release the result. +@end deftypefun + +@deftypefun gpg_error_t gcry_mpi_ec_set_mpi ( @ + @w{const char *@var{name}}, @w{gcry_mpi_t @var{newvalue}}, @ + @w{gcry_ctx_t @var{ctx}}) + +Store the MPI @var{newvalue} at @var{name} into the context @var{ctx}. +On success @code{0} is returned; on error an error code. Valid names +are the MPI parameters of an elliptic curve (@pxref{ecc_keyparam}). +@end deftypefun + +@deftypefun gpg_error_t gcry_mpi_ec_set_point ( @ + @w{const char *@var{name}}, @w{gcry_mpi_point_t @var{newvalue}}, @ + @w{gcry_ctx_t @var{ctx}}) + +Store the point @var{newvalue} at @var{name} into the context +@var{ctx}. On success @code{0} is returned; on error an error code. +Valid names are the point parameters of an elliptic curve +(@pxref{ecc_keyparam}). @end deftypefun @deftypefun int gcry_mpi_ec_get_affine ( @ @@ -3938,9 +3994,9 @@ and sets @code{errno}. Compute the affine coordinates from the projective coordinates in @var{point} and store them into @var{x} and @var{y}. If one coordinate is not required, @code{NULL} may be passed to @var{x} or -@var{y}. @var{ctx} is the context object which for example may have -been created using @ref{gcry_mpi_ec_p_new}. Returns 0 on success or -not 0 if @var{point} is at infinity. +@var{y}. @var{ctx} is the context object which has been created using +@code{gcry_mpi_ec_new}. Returns 0 on success or not 0 if @var{point} +is at infinity. @end deftypefun @deftypefun void gcry_mpi_ec_dup ( @ -- cgit v1.2.1