documentation for decaf

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;

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);
 }