diff --git a/ChangeLog b/ChangeLog index 02e69496affadb1648d86f7d523e6aeb15e5d539..d89896aac7ef594e765394af421241c2096f3a4b 100644 --- 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 --- 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