Updated curve25519_mul documentation.

diff --git a/ChangeLog b/ChangeLog
index 02e69496affadb1648d86f7d523e6aeb15e5d539..d89896aac7ef594e765394af421241c2096f3a4b 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,6 +1,11 @@
 2015-03-10  Niels Möller  <nisse@diamant.hack.org>
 
+       * nettle.texinfo: Update documentation of curve25519_mul. Say that
+       the output is undefined for points belonging to the twist rather
+       than the proper curve.
+
        * curve25519-mul.c (curve25519_mul): Changed return type to void.
+       * curve25519.h (curve25519_mul): Updated prototype.
        * examples/hogweed-benchmark.c (bench_curve25519_mul): Drop check
        of curve25519_mul return value.
        * testsuite/curve25519-dh-test.c (test_a): Likewise.

diff --git a/nettle.texinfo b/nettle.texinfo
index 95d1f77178d48c9c0afb18622ef30a6f8fbe2bd9..80d0f9f4fe679ca81f49551d2502984083ec5edf 100644 (file)
--- a/nettle.texinfo
+++ b/nettle.texinfo
@@ -4216,6 +4216,19 @@ for the curve25519 operations which work with the x-coordinate only).
 The curve25519 functions are defined as operations on octet strings,
 which are interpreted as x-coordinates in little-endian byte order.
 
+Of all the possible input strings, only about half correspond to points
+on curve25519, i.e., a value that can be produced by
+@code{curve25519_mul_g}. The other half corresponds to points on a
+related ``twist curve''. The current implementation of
+@code{curve25519_mul} uses a Montgomery ladder for the scalar
+multiplication, as suggested in the curve25519 literature, and produces
+a well defined output for all possible inputs, no matter if points are
+on the proper curve or on its twist. However, at the time of writing, it
+is not yet ruled out that other implementations could be faster, and
+therefore the behaviour for inputs corresponding to points on the twist
+curve must be considered an implementation idiosyncrasy, and may change
+in future versions.
+
 @defvr Constant CURVE25519_SIZE
 The size of the strings representing curve25519 points and scalars, 32.
 @end defvr
@@ -4231,14 +4244,17 @@ This function is intended to be compatible with the function
 @code{crypto_scalar_mult_base} in the NaCl library.
 @end deftypefun
 
-@c FIXME: Change to void return type
-@deftypefun int curve25519_mul (uint8_t *@var{q}, const uint8_t *@var{n}, const uint8_t *@var{p})
+@deftypefun void curve25519_mul (uint8_t *@var{q}, const uint8_t *@var{n}, const uint8_t *@var{p})
 Computes @math{Q = N P}, where @math{P} is an input point and @math{N}
 is an integer. The input arguments @var{n} and @var{p} and the output
 argument @var{q} use a little-endian representation of the scalar and
 the x-coordinates, respectively. They are all of size
 @code{CURVE25519_SIZE}.
 
+The output value is defined only when the input @var{p} is a string
+produced by @code{curve25519_mul_g}. (See discussion above, about the
+twist curve).
+
 This function is intended to be compatible with the function
 @code{crypto_scalar_mult} in the NaCl library.
 @end deftypefun