From 6ae70daba470db8f236ed87eb138e4df45b563fc Mon Sep 17 00:00:00 2001 From: Michael Hamburg Date: Wed, 28 Jan 2015 16:50:22 -0800 Subject: [PATCH] better docs on Elligator --- include/decaf.h | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/include/decaf.h b/include/decaf.h index 1d803a6..010cfb8 100644 --- a/include/decaf.h +++ b/include/decaf.h @@ -171,17 +171,32 @@ decaf_bool_t decaf_valid ( ) API_VIS WARN_UNUSED NONNULL1; /** - * @brief Elligator-like hash to curve. + * @brief Almost-Elligator-like hash to curve. * - * May be up to 4:1 on [0,(p-1)/2] - * // TODO: check that it isn't more. + * Call this function with the output of a hash to make a hash to the curve. * - * @param [in] ser A serialized point. + * This function runs Elligator2 on the decaf Jacobi quartic model. It then + * uses the isogeny to put the result in twisted Edwards form. As a result, + * it is safe (cannot produce points of order 4), and would be compatible with + * hypothetical other implementations of Decaf using a Montgomery or untwisted + * Edwards model. + * + * Unlike Elligator, this function may be up to 4:1 on [0,(p-1)/2]: + * A factor of 2 due to the isogeny. + * A factor of 2 because we quotient out the 2-torsion. + * // TODO: check that it isn't more, especially for the identity point. + * + * This function isn't quite indifferentiable from a random oracle. + * However, it is suitable for many protocols, including SPEKE and SPAKE2 EE. + * Furthermore, calling it twice with independent seeds and adding the results + * is indifferentiable from a random oracle. + * + * @param [in] hashed_data Output of some hash function. * @param [out] pt The hashed input */ void decaf_nonuniform_map_to_curve ( decaf_point_t pt, - const unsigned char ser[DECAF_SER_BYTES] + const unsigned char hashed_data[DECAF_SER_BYTES] ) API_VIS NONNULL2; #undef API_VIS