Commit 04ecdb3d authored by Michael Hamburg's avatar Michael Hamburg

documentation for decaf

parent b3f7d979
......@@ -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;
......
......@@ -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);
}
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment