Move documentation comments for public API to the public header

This makes the documentation more accessible, as the header now contains
all information regarding the usage of the API, and it is not necessary to
generate the Doxygen documentation anymore for that.

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);
 
 /**@}*/