From 04ecdb3d3eaf041e29c8d0002aad87f3ff211fc6 Mon Sep 17 00:00:00 2001 From: Michael Hamburg Date: Tue, 27 Jan 2015 13:21:15 -0800 Subject: [PATCH] documentation for decaf --- include/decaf.h | 101 +++++++++++++++++++++++++++++++++++++----------- src/decaf.c | 64 +++++++++++++++--------------- 2 files changed, 111 insertions(+), 54 deletions(-) diff --git a/include/decaf.h b/include/decaf.h index b82444b..6f035dd 100644 --- a/include/decaf.h +++ b/include/decaf.h @@ -29,7 +29,8 @@ typedef struct decaf_point_s { decaf_word_t x[DECAF_LIMBS],y[DECAF_LIMBS],z[DECAF_LIMBS],t[DECAF_LIMBS]; } decaf_point_t[1]; -static const decaf_bool_t DECAF_SUCCESS = -(decaf_bool_t)1, DECAF_FAILURE = 0; +static const decaf_bool_t DECAF_TRUE = -(decaf_bool_t)1, DECAF_FALSE = 0; +static const decaf_bool_t DECAF_SUCCESS = DECAF_TRUE, DECAF_FAILURE = DECAF_FALSE; const decaf_point_t decaf_identity; @@ -42,49 +43,103 @@ extern "C" { #define NONNULL2 __attribute__((nonnull(1,2))) #define NONNULL3 __attribute__((nonnull(1,2,3))) +/** + * @brief Encode a point as a sequence of bytes. + * + * @param [out] ser The byte representation of the point. + * @param [in] pt The point to encode. + */ void decaf_encode ( uint8_t ser[DECAF_SER_BYTES], const decaf_point_t pt ) API_VIS NONNULL2; - + +/** + * @brief Decode a point from a sequence of bytes. + * + * Every point has a unique encoding, so not every + * sequence of bytes is a valid encoding. If an invalid + * encoding is given, the output is undefined. + * + * @param [out] pt The decoded point. + * @param [in] ser The serialized version of the point. + * @retval DECAF_SUCCESS The decoding succeeded. + * @retval DECAF_FAILURE The decoding didn't succeed, because + * ser does not represent a point. + */ decaf_bool_t decaf_decode ( decaf_point_t pt, const uint8_t ser[DECAF_SER_BYTES], decaf_bool_t allow_identity ) API_VIS WARN_UNUSED NONNULL2; - -void decaf_add ( - decaf_point_t a, - const decaf_point_t b, - const decaf_point_t c -) API_VIS NONNULL3; - + +/** + * @brief Copy a point. The input and output may alias, + * in which case this function does nothing. + * + * @param [out] a A copy of the point. + * @param [in] b Any point. + */ void decaf_copy ( decaf_point_t a, const decaf_point_t b ) API_VIS NONNULL2; - + +/** + * @brief Test whether two points are equal. If yes, return + * DECAF_TRUE, else return DECAF_FALSE. + * + * @param [in] a A point. + * @param [in] b Another point. + * @retval DECAF_TRUE The points are equal. + * @retval DECAF_FALSE The points are not equal. + */ decaf_bool_t decaf_eq ( const decaf_point_t a, const decaf_point_t b ) API_VIS WARN_UNUSED NONNULL2; - -void decaf_sub ( - decaf_point_t a, - const decaf_point_t b, - const decaf_point_t c + +/** + * @brief Add two points to produce a third point. The + * input points and output point can be pointers to the same + * memory. + * + * @param [out] sum The sum a+b. + * @param [in] a An addend. + * @param [in] b An addend. + */ +void decaf_add ( + decaf_point_t sum, + const decaf_point_t a, + const decaf_point_t b ) API_VIS NONNULL3; - -void decaf_add_sub ( - decaf_point_t a, - const decaf_point_t b, - const decaf_point_t c, - decaf_bool_t do_sub + +/** + * @brief Subtract two points to produce a third point. The + * input points and output point can be pointers to the same + * memory. + * + * @param [out] sum The difference a-b. + * @param [in] a The minuend. + * @param [in] b The subtrahend. + */ +void decaf_sub ( + decaf_point_t diff, + const decaf_point_t a, + const decaf_point_t b ) API_VIS NONNULL3; +/** + * @brief Multiply a base point by a scalar. + * + * @param [out] scaled The scaled point base*scalar + * @param [in] base The point to be scaled. + * @param [in] scalar The scalar to multilpy by. + * @param [in] scalar_words The number of words in the scalar [TODO] + */ void decaf_scalarmul ( - decaf_point_t a, - const decaf_point_t b, + decaf_point_t scaled, + const decaf_point_t base, const decaf_word_t *scalar, unsigned int scalar_words ) API_VIS NONNULL3; diff --git a/src/decaf.c b/src/decaf.c index 5ec82bd..b4ca128 100644 --- a/src/decaf.c +++ b/src/decaf.c @@ -245,6 +245,37 @@ static decaf_bool_t gf_deser(gf s, const unsigned char ser[DECAF_SER_BYTES]) { return accum; } +/* Constant-time add or subtract */ +sv decaf_add_sub ( + decaf_point_t p, + const decaf_point_t q, + const decaf_point_t r, + decaf_bool_t do_sub +) { + /* Twisted Edward formulas, complete when 4-torsion isn't involved */ + gf a, b, c, d; + gf_sub ( b, q->y, q->x ); + gf_sub ( c, r->y, r->x ); + gf_add ( d, r->y, r->x ); + cond_swap(c,d,do_sub); + gf_mul ( a, c, b ); + gf_add ( b, q->y, q->x ); + gf_mul ( p->y, d, b ); + gf_mul ( b, r->t, q->t ); + gf_mlw ( p->x, b, 2-2*EDWARDS_D ); + gf_add ( b, a, p->y ); + gf_sub ( c, p->y, a ); + gf_mul ( a, q->z, r->z ); + gf_add ( a, a, a ); + gf_add ( p->y, a, p->x ); + gf_sub ( a, a, p->x ); + cond_swap(a,p->y,do_sub); + gf_mul ( p->z, a, p->y ); + gf_mul ( p->x, p->y, c ); + gf_mul ( p->y, a, b ); + gf_mul ( p->t, b, c ); +} + decaf_bool_t decaf_decode ( decaf_point_t p, const unsigned char ser[DECAF_SER_BYTES], @@ -275,39 +306,10 @@ decaf_bool_t decaf_decode ( gf_mul ( p->y,a,p->z ); gf_mul ( p->t,p->x,a ); p->y[0] -= zero; + /* TODO: do something safe if ~succ? */ return succ; } - -void decaf_add_sub ( - decaf_point_t p, - const decaf_point_t q, - const decaf_point_t r, - decaf_bool_t do_sub -) { - /* Twisted Edward formulas, complete when 4-torsion isn't involved */ - gf a, b, c, d; - gf_sub ( b, q->y, q->x ); - gf_sub ( c, r->y, r->x ); - gf_add ( d, r->y, r->x ); - cond_swap(c,d,do_sub); - gf_mul ( a, c, b ); - gf_add ( b, q->y, q->x ); - gf_mul ( p->y, d, b ); - gf_mul ( b, r->t, q->t ); - gf_mlw ( p->x, b, 2-2*EDWARDS_D ); - gf_add ( b, a, p->y ); - gf_sub ( c, p->y, a ); - gf_mul ( a, q->z, r->z ); - gf_add ( a, a, a ); - gf_add ( p->y, a, p->x ); - gf_sub ( a, a, p->x ); - cond_swap(a,p->y,do_sub); - gf_mul ( p->z, a, p->y ); - gf_mul ( p->x, p->y, c ); - gf_mul ( p->y, a, b ); - gf_mul ( p->t, b, c ); -} - + void decaf_sub(decaf_point_t a, const decaf_point_t b, const decaf_point_t c) { decaf_add_sub(a,b,c,-1); }