1 files changed, 111 insertions, 0 deletions
diff --git a/include/libuecc/ecc.h b/include/libuecc/ecc.h
index 4f6b870..982f7c9 100644
--- a/include/libuecc/ecc.h
+++ b/include/libuecc/ecc.h
@@ -55,22 +55,86 @@ typedef struct _ecc_25519_work {
  * @{
  */
 
+/** The identity element */
 extern const ecc_25519_work_t ecc_25519_work_identity;
+
+/** The ec25519 default base */
 extern const ecc_25519_work_t ecc_25519_work_default_base;
 
+
+
+/** Loads a point with given coordinates into its unpacked representation */
 int ecc_25519_load_xy(ecc_25519_work_t *out, const ecc_int256_t *x, const ecc_int256_t *y);
+
+/**
+ * Stores a point's x and y coordinates
+ *
+ * \param x Returns the x coordinate of the point. May be NULL.
+ * \param y Returns the y coordinate of the point. May be NULL.
+ * \param in The unpacked point to store.
+ */
 void ecc_25519_store_xy(ecc_int256_t *x, ecc_int256_t *y, const ecc_25519_work_t *in);
 
+
+/** Loads a packed point into its unpacked representation */
 int ecc_25519_load_packed(ecc_25519_work_t *out, const ecc_int256_t *in);
+
+/** Stores a point into its packed representation */
 void ecc_25519_store_packed(ecc_int256_t *out, const ecc_25519_work_t *in);
 
+
+/** Checks if a point is the identity element of the Elliptic Curve group */
 int ecc_25519_is_identity(const ecc_25519_work_t *in);
+
+/**
+ * Doubles a point of the Elliptic Curve
+ *
+ * ecc_25519_double(out, in) is equivalent to ecc_25519_add(out, in, in), but faster.
+ *
+ * The same pointer may be given for input and output.
+ */
 void ecc_25519_double(ecc_25519_work_t *out, const ecc_25519_work_t *in);
+
+/**
+ * Adds two points of the Elliptic Curve
+ *
+ * The same pointers may be given for input and output.
+ */
 void ecc_25519_add(ecc_25519_work_t *out, const ecc_25519_work_t *in1, const ecc_25519_work_t *in2);
 
+
+/**
+ * Does a scalar multiplication of a point of the Elliptic Curve with an integer of a given bit length
+ *
+ * To speed up scalar multiplication when it is known that not the whole 256 bits of the scalar
+ * are used. The bit length should always be a constant and not computed at runtime to ensure
+ * that no timing attacks are possible.
+ *
+ * The same pointer may be given for input and output.
+ **/
 void ecc_25519_scalarmult_bits(ecc_25519_work_t *out, const ecc_int256_t *n, const ecc_25519_work_t *base, unsigned bits);
+
+/**
+ * Does a scalar multiplication of a point of the Elliptic Curve with an integer
+ *
+ * The same pointer may be given for input and output.
+ **/
 void ecc_25519_scalarmult(ecc_25519_work_t *out, const ecc_int256_t *n, const ecc_25519_work_t *base);
+
+/**
+ * Does a scalar multiplication of the default base point (generator element) of the Elliptic Curve with an integer of a given bit length
+ *
+ * The order of the base point is \f$ 2^{252} + 27742317777372353535851937790883648493 \f$.
+ *
+ * See the notes about \ref ecc_25519_scalarmult_bits before using this function.
+ */
 void ecc_25519_scalarmult_base_bits(ecc_25519_work_t *out, const ecc_int256_t *n, unsigned bits);
+
+/**
+ * Does a scalar multiplication of the default base point (generator element) of the Elliptic Curve with an integer
+ *
+ * The order of the base point is \f$ 2^{252} + 27742317777372353535851937790883648493 \f$.
+ */
 void ecc_25519_scalarmult_base(ecc_25519_work_t *out, const ecc_int256_t *n);
 
 /**@}*/
@@ -80,14 +144,61 @@ void ecc_25519_scalarmult_base(ecc_25519_work_t *out, const ecc_int256_t *n);
  * @{
  */
 
+/**
+ * The order of the prime field
+ *
+ * The order is \f$ 2^{252} + 27742317777372353535851937790883648493 \f$.
+ */
 extern const ecc_int256_t ecc_25519_gf_order;
 
+
+/** Checks if an integer is equal to zero (after reduction) */
 int ecc_25519_gf_is_zero(const ecc_int256_t *in);
+
+/**
+ * Adds two integers as Galois field elements
+ *
+ * The same pointers may be given for input and output.
+ */
 void ecc_25519_gf_add(ecc_int256_t *out, const ecc_int256_t *in1, const ecc_int256_t *in2);
+
+/**
+ * Subtracts two integers as Galois field elements
+ *
+ * The same pointers may be given for input and output.
+ */
 void ecc_25519_gf_sub(ecc_int256_t *out, const ecc_int256_t *in1, const ecc_int256_t *in2);
+
+/**
+ * Reduces an integer to a unique representation in the range \f$ [0,q-1] \f$
+ *
+ * The same pointer may be given for input and output.
+ */
 void ecc_25519_gf_reduce(ecc_int256_t *out, const ecc_int256_t *in);
+
+/**
+ * Multiplies two integers as Galois field elements
+ *
+ * The same pointers may be given for input and output.
+ */
 void ecc_25519_gf_mult(ecc_int256_t *out, const ecc_int256_t *in1, const ecc_int256_t *in2);
+
+/**
+ * Computes the reciprocal of a Galois field element
+ *
+ * The same pointers may be given for input and output.
+ */
 void ecc_25519_gf_recip(ecc_int256_t *out, const ecc_int256_t *in);
+
+/**
+ * Ensures some properties of a Galois field element to make it fit for use as a secret key
+ *
+ * This sets the 255th bit and clears the 256th and the bottom three bits (so the key
+ * will be a multiple of 8). See Daniel J. Bernsteins paper "Curve25519: new Diffie-Hellman speed records."
+ * for the rationale of this.
+ *
+ * The same pointer may be given for input and output.
+ */
 void ecc_25519_gf_sanitize_secret(ecc_int256_t *out, const ecc_int256_t *in);
 
 /**@}*/