ecc: Change an error code of gcry_ecc_mul_point.

* cipher/ecc-ecdh.c (_gcry_ecc_mul_point): Return
GPG_ERR_UNKNOWN_CURVE.
--

Unknown_curve is more specific than unknown_algorithm.

This patch also adds documentation and renames rthe parameter from
'algo' to 'curveid'.

Signed-off-by: Werner Koch <wk@gnupg.org>

4 files changed, 54 insertions, 18 deletions

diff --git a/cipher/ecc-ecdh.c b/cipher/ecc-ecdh.c
index 39458788..43eb731a 100644
--- a/cipher/ecc-ecdh.c
+++ b/cipher/ecc-ecdh.c
@@ -46,20 +46,20 @@ prepare_ec (mpi_ec_t *r_ec, const char *name)
 }
 
 unsigned int
-_gcry_ecc_get_algo_keylen (int algo)
+_gcry_ecc_get_algo_keylen (int curveid)
 {
   unsigned int len = 0;
 
-  if (algo == GCRY_ECC_CURVE25519)
+  if (curveid == GCRY_ECC_CURVE25519)
     len = ECC_CURVE25519_BYTES;
-  else if (algo == GCRY_ECC_CURVE448)
+  else if (curveid == GCRY_ECC_CURVE448)
     len = ECC_CURVE448_BYTES;
 
   return len;
 }
 
 gpg_error_t
-_gcry_ecc_mul_point (int algo, unsigned char *result,
+_gcry_ecc_mul_point (int curveid, unsigned char *result,
                      const unsigned char *scalar, const unsigned char *point)
 {
   unsigned int nbits;
@@ -73,12 +73,12 @@ _gcry_ecc_mul_point (int algo, unsigned char *result,
   unsigned int len;
   unsigned char *buf;
 
-  if (algo == GCRY_ECC_CURVE25519)
+  if (curveid == GCRY_ECC_CURVE25519)
     curve = "Curve25519";
-  else if (algo == GCRY_ECC_CURVE448)
+  else if (curveid == GCRY_ECC_CURVE448)
     curve = "X448";
   else
-    return gpg_error (GPG_ERR_UNKNOWN_ALGORITHM);
+    return gpg_error (GPG_ERR_UNKNOWN_CURVE);
 
   err = prepare_ec (&ec, curve);
   if (err)
diff --git a/doc/gcrypt.texi b/doc/gcrypt.texi
index 9c0a3463..11c1549f 100644
--- a/doc/gcrypt.texi
+++ b/doc/gcrypt.texi
@@ -2135,6 +2135,7 @@ S-expressions.
 * Available algorithms::        Algorithms supported by the library.
 * Used S-expressions::          Introduction into the used S-expression.
 * Cryptographic Functions::     Functions for performing the cryptographic actions.
+* Dedicated ECC Functions::     Dedicated functions for elliptic curves.
 * General public-key related Functions::  General functions, not implementing any cryptography.
 @end menu
 
@@ -2142,8 +2143,7 @@ S-expressions.
 @section Available algorithms
 
 Libgcrypt supports the RSA (Rivest-Shamir-Adleman) algorithms as well
-as DSA (Digital Signature Algorithm) and Elgamal.  The versatile
-interface allows to add more algorithms in the future.
+as DSA (Digital Signature Algorithm), Elgamal, ECDSA, ECDH, and EdDSA.
 
 @node Used S-expressions
 @section Used S-expressions
@@ -2151,7 +2151,7 @@ interface allows to add more algorithms in the future.
 Libgcrypt's API for asymmetric cryptography is based on data structures
 called S-expressions (see
 @uref{http://people.csail.mit.edu/@/rivest/@/sexp.html}) and does not work
-with contexts as most of the other building blocks of Libgcrypt do.
+with contexts/handles as most of the other building blocks of Libgcrypt do.
 
 @noindent
 The following information are stored in S-expressions:
@@ -2797,6 +2797,42 @@ to indicate that the signature does not match the provided data.
 @end deftypefun
 @c end gcry_pk_verify
 
+
+@node Dedicated ECC Functions
+@section Dedicated functions for elliptic curves.
+
+@noindent
+The S-expression based interface is for certain operations on elliptic
+curves not optimal.  Thus a few special functions are implemented to
+support common operations on curves with one of these assigned curve
+ids:
+
+@table @code
+@item GCRY_ECC_CURVE25519
+@item GCRY_ECC_CURVE448
+@end table
+
+@deftypefun @w{unsigned int} gcry_ecc_get_algo_keylen (@w{int @var{curveid}});
+
+Returns the length in bytes of a point on the curve with the id
+@var{curveid}.  0 is returned for curves which have no assigned id.
+@end deftypefun
+
+
+@deftypefun gpg_error_t gcry_ecc_mul_point @
+            (@w{int @var{curveid}}, @
+            @w{unsigned char *@var{result}}, @
+            @w{const unsigned char *@var{scalar}}, @
+            @w{const unsigned char *@var{point}})
+
+This function computes the scalar multiplication on the Montgomery
+form of the curve with id @var{curveid}.  If @var{point} is NULL the
+base point of the curve is used.  The caller needs to provide a large
+enough buffer for @var{result} and a valid @var{scalar} and
+@var{point}.
+@end deftypefun
+
+
 @node General public-key related Functions
 @section General public-key related Functions
 
diff --git a/src/gcrypt.h.in b/src/gcrypt.h.in
index 5668e625..e77b6e74 100644
--- a/src/gcrypt.h.in
+++ b/src/gcrypt.h.in
@@ -946,7 +946,7 @@ enum gcry_cipher_algos
     GCRY_CIPHER_SALSA20R12  = 314,
     GCRY_CIPHER_GOST28147   = 315,
     GCRY_CIPHER_CHACHA20    = 316,
-    GCRY_CIPHER_GOST28147_MESH   = 317, /* GOST 28247 with optional CryptoPro keymeshing */
+    GCRY_CIPHER_GOST28147_MESH   = 317, /* With CryptoPro key meshing.  */
     GCRY_CIPHER_SM4         = 318
   };
 
@@ -1215,11 +1215,11 @@ enum gcry_ecc_curves
   };
 
 /* Get the length of point to prepare buffer for the result.  */
-unsigned int gcry_ecc_get_algo_keylen (int algo);
+unsigned int gcry_ecc_get_algo_keylen (int curveid);
 
 /* Convenience function to compute scalar multiplication of the
-   Montgomery form of curve.  */
-gpg_error_t gcry_ecc_mul_point (int algo, unsigned char *result,
+ * Montgomery form of curve.  */
+gpg_error_t gcry_ecc_mul_point (int curveid, unsigned char *result,
                                 const unsigned char *scalar,
                                 const unsigned char *point);
 
diff --git a/src/visibility.c b/src/visibility.c
index 4ea2d99e..06bb9226 100644
--- a/src/visibility.c
+++ b/src/visibility.c
@@ -1113,16 +1113,16 @@ gcry_pubkey_get_sexp (gcry_sexp_t *r_sexp, int mode, gcry_ctx_t ctx)
 }
 
 unsigned int
-gcry_ecc_get_algo_keylen (int algo)
+gcry_ecc_get_algo_keylen (int curveid)
 {
-  return _gcry_ecc_get_algo_keylen (algo);
+  return _gcry_ecc_get_algo_keylen (curveid);
 }
 
 gpg_error_t
-gcry_ecc_mul_point (int algo, unsigned char *result,
+gcry_ecc_mul_point (int curveid, unsigned char *result,
                     const unsigned char *scalar, const unsigned char *point)
 {
-  return _gcry_ecc_mul_point (algo, result, scalar, point);
+  return _gcry_ecc_mul_point (curveid, result, scalar, point);
 }
 
 gcry_error_t