Added some docs + Doxyfile

18 files changed, 202 insertions, 34 deletions

diff --git a/src/cm/cm.h b/src/cm/cm.h
index fe54f18..14d4fea 100644
--- a/src/cm/cm.h
+++ b/src/cm/cm.h
@@ -2,6 +2,9 @@
  * ecgen, tool for generating Elliptic curve domain parameters
  * Copyright (C) 2017 J08nY
  */
+/**
+ * @file cm.h
+ */
 #include "io/cli.h"
 
 #ifndef ECGEN_CM_H
diff --git a/src/ecgen.c b/src/ecgen.c
index 4ef3d33..e90ac27 100644
--- a/src/ecgen.c
+++ b/src/ecgen.c
@@ -17,6 +17,12 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301,
  * USA.
  */
+/**
+ * @file ecgen.c
+ * @author J08nY <johny@neuromancer.sk>
+ * @version 0.2
+ * @copyright GPL v2.0
+ */
 #include <pari/pari.h>
 #include "cm/cm.h"
 #include "exhaustive/exhaustive.h"
@@ -24,12 +30,6 @@
 #include "io/input.h"
 #include "io/output.h"
 
-/**
- * @author J08nY <johny@neuromancer.sk>
- * @license GPL v2.0
- * @version 0.2
- */
-
 const char *argp_program_version =
     "ecgen 0.2\n"
     "Copyright (C) 2017 J08nY\n"
@@ -73,6 +73,7 @@ int quit(int status) {
 }
 
 /**
+ * @mainpage
  * Three fundamentally different Elliptic curve generation approaches can be
  * taken.
  *   - Complex Multiplication:
@@ -103,6 +104,10 @@ int quit(int status) {
  *       - using ANSI X9.62 verifiably random method(from seed)
  *       - given input
  *     , until a curve with requested properties appears.
+ *     - Can generate curves repeatedly until one satisfies requested properties:
+ *       - -p / --prime generates curves until a prime order curve is found.
+ *       - -k / --koblitz generates a curve with fixed A = 0 parameter.
+ *
  */
 int main(int argc, char *argv[]) {
 	// Parse cli args
diff --git a/src/exhaustive/exhaustive.h b/src/exhaustive/exhaustive.h
index 93c185a..b4c963c 100644
--- a/src/exhaustive/exhaustive.h
+++ b/src/exhaustive/exhaustive.h
@@ -2,6 +2,9 @@
  * ecgen, tool for generating Elliptic curve domain parameters
  * Copyright (C) 2017 J08nY
  */
+/**
+ * @file exhaustive.h
+ */
 #ifndef ECGEN_GENERATORS_H
 #define ECGEN_GENERATORS_H
 
diff --git a/src/exhaustive/seed.h b/src/exhaustive/seed.h
index 06857fc..2e07dc1 100644
--- a/src/exhaustive/seed.h
+++ b/src/exhaustive/seed.h
@@ -2,6 +2,9 @@
  * ecgen, tool for generating Elliptic curve domain parameters
  * Copyright (C) 2017 J08nY
  */
+/**
+ * @file seed.h
+ */
 #ifndef ECGEN_SEED_H
 #define ECGEN_SEED_H
 
diff --git a/src/invalid/invalid.h b/src/invalid/invalid.h
index 0790af7..d8090c3 100644
--- a/src/invalid/invalid.h
+++ b/src/invalid/invalid.h
@@ -2,6 +2,9 @@
  * ecgen, tool for generating Elliptic curve domain parameters
  * Copyright (C) 2017 J08nY
  */
+/**
+ * @file invalid.h
+ */
 #include "io/cli.h"
 
 #ifndef ECGEN_INVALID_H
diff --git a/src/io/cli.h b/src/io/cli.h
index 152a129..96871ce 100644
--- a/src/io/cli.h
+++ b/src/io/cli.h
@@ -2,6 +2,9 @@
  * ecgen, tool for generating Elliptic curve domain parameters
  * Copyright (C) 2017 J08nY
  */
+/**
+ * @file cli.h
+ */
 #ifndef ECGEN_CLI_H
 #define ECGEN_CLI_H
 
diff --git a/src/io/input.h b/src/io/input.h
index 8cb5b35..b76159d 100644
--- a/src/io/input.h
+++ b/src/io/input.h
@@ -2,6 +2,9 @@
  * ecgen, tool for generating Elliptic curve domain parameters
  * Copyright (C) 2017 J08nY
  */
+/**
+ * @file input.h
+ */
 #ifndef ECGEN_INPUT_H
 #define ECGEN_INPUT_H
 
diff --git a/src/io/output.h b/src/io/output.h
index 5aca4bd..ea9a97e 100644
--- a/src/io/output.h
+++ b/src/io/output.h
@@ -2,6 +2,9 @@
  * ecgen, tool for generating Elliptic curve domain parameters
  * Copyright (C) 2017 J08nY
  */
+/**
+ * @file output.h
+ */
 #ifndef ECGEN_OUTPUT_H
 #define ECGEN_OUTPUT_H
 
diff --git a/src/math/curve.h b/src/math/curve.h
index 20273b7..425d9a6 100644
--- a/src/math/curve.h
+++ b/src/math/curve.h
@@ -2,6 +2,9 @@
  * ecgen, tool for generating Elliptic curve domain parameters
  * Copyright (C) 2017 J08nY
  */
+/**
+ * @file curve.h
+ */
 #ifndef ECGEN_CURVE_H
 #define ECGEN_CURVE_H
 
@@ -10,53 +13,67 @@
 #include "types.h"
 
 /**
+ * GENERATOR(gen_t)
  * Creates a curve GEN in curve_t curve from field, a and b.
  * Always succeeds.
  *
  * @param curve
  * @param config
- * @return
+ * @param ... unused
+ * @return state diff
  */
 int curve_init(curve_t *curve, config_t *config, ...);
 
 /**
+ * GENERATOR(gen_t)
  * Creates a curve GEN in curve_t curve from field, a and b.
  * Succeeds if a curve exists(non-zero discriminant).
  *
  * @param curve
  * @param config
- * @return
+ * @param ... unused
+ * @return state diff
  */
 int curve_nonzero(curve_t *curve, config_t *config, ...);
 
 /**
+ * GENERATOR(gen_t)
  * Creates a curve GEN in curve_t curve from field, a and b. Using the ANSI
  * X9.62 verifiably random algorithm.
  * Succeeds if a curve exists(non-zero discriminant).
  *
  * @param curve
  * @param config
- * @return
+ * @param ... unused
+ * @return state diff
  */
 int curve_seed(curve_t *curve, config_t *config, ...);
 
 /**
- * @param curve
- * @return a t_VEC of curve parameters: field,a,b,order
+ * Serializes curve parameters into a t_VEC:
+ * - prime field:
+ * 	p,a,b,order,(point.x, point.y, point.order)*
+ * - binary field:
+ *  e1,e2,e3,a,b,order,(point.x, point.y, point.order)*
+ *
+ * @param curve to serialize
+ * @return a t_VEC of curve parameters
  */
 GEN curve_params(curve_t *curve);
 
 /**
- *
- * @return
+ * Allocates and zeros out a new curve_t object.
+ * @return new curve
  */
 curve_t *curve_new(void);
 
 /**
+ * Copies parameters from src curve to dest curve, allocates space for points.
+ * Otherwise expects everything to be allocated.
  *
- * @param src
- * @param dest
- * @return
+ * @param src source curve
+ * @param dest destination curve
+ * @return destination curve
  */
 curve_t *curve_copy(curve_t *src, curve_t *dest);
 
diff --git a/src/math/equation.c b/src/math/equation.c
index e153405..47060ad 100644
--- a/src/math/equation.c
+++ b/src/math/equation.c
@@ -20,6 +20,7 @@ int a_random(curve_t *curve, config_t *config, ...) {
 
 int a_input(curve_t *curve, config_t *config, ...) {
 	curve->a = fread_int(in, "a:", config->bits);
+	//TODO check if a is valid int here, if not repeat
 	// TODO change a to a field element here?. a t_INTMOD or a t_FFELT.
 	return 1;
 }
@@ -46,6 +47,7 @@ int b_random(curve_t *curve, config_t *config, ...) {
 
 int b_input(curve_t *curve, config_t *config, ...) {
 	curve->b = fread_int(in, "b:", config->bits);
+	//TODO check if a is valid int here, if not repeat
 	// TODO change b to a field element here?. a t_INTMOD or a t_FFELT.
 	return 1;
 }
diff --git a/src/math/equation.h b/src/math/equation.h
index 72f0634..76b5e06 100644
--- a/src/math/equation.h
+++ b/src/math/equation.h
@@ -2,28 +2,106 @@
  * ecgen, tool for generating Elliptic curve domain parameters
  * Copyright (C) 2017 J08nY
  */
+/**
+ * @file equation.h
+ */
 #ifndef ECGEN_EQUATION_H
 #define ECGEN_EQUATION_H
 
 #include "io/cli.h"
 #include "types.h"
 
+/**
+ * GENERATOR(gen_t)
+ * Creates a random a parameter by selecting a random field
+ * element from the curve field.
+ * Always succeeds.
+ *
+ * @param curve
+ * @param config
+ * @param ...
+ * @return state diff
+ */
 int a_random(curve_t *curve, config_t *config, ...);
 
+/**
+ * GENERATOR(gen_t)
+ * Creates a parameter by reading from input.
+ *
+ * @param curve
+ * @param config
+ * @param ...
+ * @return state diff
+ */
 int a_input(curve_t *curve, config_t *config, ...);
 
+/**
+ * GENERATOR(gen_t)
+ * Creates a parameter set to zero.
+ *
+ * @param curve
+ * @param config
+ * @param ...
+ * @return state diff
+ */
 int a_zero(curve_t *curve, config_t *config, ...);
 
+/**
+ * GENERATOR(gen_t)
+ * Creates a parameter set to one.
+ *
+ * @param curve
+ * @param config
+ * @param ...
+ * @return state diff
+ */
 int a_one(curve_t *curve, config_t *config, ...);
 
 int a_seed(curve_t *curve, config_t *config, ...);
 
+/**
+ * GENERATOR(gen_t)
+ * Creates a random b parameter by selecting a random field
+ * element from the curve field.
+ *
+ * @param curve
+ * @param config
+ * @param ...
+ * @return state diff
+ */
 int b_random(curve_t *curve, config_t *config, ...);
 
+/**
+ * GENERATOR(gen_t)
+ * Creates b parameter by reading from input.
+ *
+ * @param curve
+ * @param config
+ * @param ...
+ * @return state diff
+ */
 int b_input(curve_t *curve, config_t *config, ...);
 
+/**
+ * GENERATOR(gen_t)
+ * Creates b parameter set to zero.
+ *
+ * @param curve
+ * @param config
+ * @param ...
+ * @return state diff
+ */
 int b_zero(curve_t *curve, config_t *config, ...);
 
+/**
+ * GENERATOR(gen_t)
+ * Creates b parameter set to one.
+ *
+ * @param curve
+ * @param config
+ * @param ...
+ * @return state diff
+ */
 int b_one(curve_t *curve, config_t *config, ...);
 
 int b_seed(curve_t *curve, config_t *config, ...);
diff --git a/src/math/field.c b/src/math/field.c
index 4d62c73..cd35990 100644
--- a/src/math/field.c
+++ b/src/math/field.c
@@ -75,6 +75,7 @@ int field_input(curve_t *curve, config_t *config, ...) {
 			gel(v, 1) = gen_1;
 
 			GEN poly = gmul(gtopolyrev(v, -1), gmodulss(1, 2));
+			//TODO check irreducibility here
 
 			GEN field = gerepilecopy(ltop, ffgen(poly, -1));
 			curve->field = field;
diff --git a/src/math/field.h b/src/math/field.h
index 9fde4e5..13cb283 100644
--- a/src/math/field.h
+++ b/src/math/field.h
@@ -2,6 +2,9 @@
  * ecgen, tool for generating Elliptic curve domain parameters
  * Copyright (C) 2017 J08nY
  */
+/**
+ * @file field.h
+ */
 #ifndef ECGEN_FIELD_H
 #define ECGEN_FIELD_H
 
@@ -9,18 +12,27 @@
 #include "types.h"
 
 /**
+ * GENERATOR(gen_t)
+ * Creates a random field.
+ * Always succeeds.
  *
  * @param curve
  * @param config
- * @return
+ * @param ... unused
+ * @return state diff
  */
 int field_random(curve_t *curve, config_t *config, ...);
 
 /**
+ * GENERATOR(gen_t)
+ * Creates a field by reading:
+ *  - a prime number in the prime field case
+ *  - three short exponents of the reduction polynomial in the binary case
  *
  * @param curve
  * @param config
- * @return
+ * @param ... unused
+ * @return state diff
  */
 int field_input(curve_t *curve, config_t *config, ...);
 
@@ -30,7 +42,7 @@ int field_input(curve_t *curve, config_t *config, ...);
  *    returns the vector of powers of middle coefficients of the reduction
  * polynomial.
  *  - char(field) != 2:
- *     returns the field characteristic(p).-
+ *     returns the vector of the field characteristic(p).
  *
  * @param field
  * @return field representation
@@ -38,9 +50,11 @@ int field_input(curve_t *curve, config_t *config, ...);
 GEN field_params(GEN field);
 
 /**
+ * Transforms a field element to an integer.
+ * Uses the polynomial basis of the underlying field in case of a binary field.
  *
- * @param element
- * @return
+ * @param element t_INTMOD, t_INT, t_FFELT to transform
+ * @return t_INT
  */
 GEN field_elementi(GEN element);
 
diff --git a/src/math/order.h b/src/math/order.h
index 1f0baa2..91b0ada 100644
--- a/src/math/order.h
+++ b/src/math/order.h
@@ -2,26 +2,36 @@
  * ecgen, tool for generating Elliptic curve domain parameters
  * Copyright (C) 2017 J08nY
  */
+/**
+ * @file order.h
+ */
 #ifndef ECGEN_ORDER_H
 #define ECGEN_ORDER_H
 
 #include "types.h"
 
 /**
+ * GENERATOR(gen_t)
+ * Calculates the curve order, using a general algorithm.
+ * Always succeeds.
  *
  * @param curve
  * @param cfg
  * @param ...
- * @return
+ * @return state diff
  */
 int order_init(curve_t *curve, config_t *cfg, ...);
 
 /**
+ * GENERATOR(gen_t)
+ * Calculates the curve order, always using the SEA algorithm,
+ * gives up early in case the order is divisible by "something".
+ * Succeeds if the curve has a prime order.
  *
  * @param curve
  * @param cfg
  * @param ...
- * @return
+ * @return state diff
  */
 int order_prime(curve_t *curve, config_t *cfg, ...);
 
diff --git a/src/math/point.h b/src/math/point.h
index ed10bdb..bd7d2dd 100644
--- a/src/math/point.h
+++ b/src/math/point.h
@@ -2,11 +2,15 @@
  * ecgen, tool for generating Elliptic curve domain parameters
  * Copyright (C) 2017 J08nY
  */
+/**
+ * @file point.h
+ */
 #ifndef ECGEN_POINT_H
 #define ECGEN_POINT_H
 
 #include <pari/pari.h>
 #include "types.h"
+
 /**
  *
  * @return
@@ -50,41 +54,48 @@ point_t **points_copy(point_t **src, point_t **dest, size_t num);
 void points_free(point_t ***point);
 
 /**
+ * GENERATOR(gen_t)
  *
  * @param curve
  * @param config
- * @param ...
- * @return
+ * @param ... unused
+ * @return state diff
  */
 int point_random(curve_t *curve, config_t *config, ...);
 
 /**
+ * GENERATOR(gen_t)
  *
  * @param curve
  * @param config
- * @param ...
- * @return
+ * @param ... size_t number of points to generate
+ * @return state diff
  */
 int points_random(curve_t *curve, config_t *config, ...);
 
 /**
+ * GENERATOR(gen_t)
+ *
  * Cauchy:
  *   Let G be a finite group and p be a prime. If p divides the order of G, then
- * G has an element of order p.
+ *   G has an element of order p.
  *
  * @param curve
  * @param config
  * @param ...
- * @return
+ * @return state diff
  */
 int points_prime(curve_t *curve, config_t *config, ...);
 
 /**
+ * GENERATOR(gen_t)
+ * Calculates the minimal set of generators of the curve.(one or two points).
+ * Always succeeds.
  *
  * @param curve
  * @param config
- * @param ...
- * @return
+ * @param ... unused
+ * @return state diff
  */
 int points_generators(curve_t *curve, config_t *config, ...);
 
diff --git a/src/math/poly.h b/src/math/poly.h
index 990c818..c69313f 100644
--- a/src/math/poly.h
+++ b/src/math/poly.h
@@ -2,13 +2,16 @@
  * ecgen, tool for generating Elliptic curve domain parameters
  * Copyright (C) 2017 J08nY
  */
+/**
+ * @file poly.h
+ */
 #ifndef ECGEN_POLY_H
 #define ECGEN_POLY_H
 
 #include <pari/pari.h>
 #include <stdbool.h>
 
-typedef struct polynomial {
+typedef struct polynomial_t {
 	int m;
 	int e1;
 	int e2;
diff --git a/src/math/random.h b/src/math/random.h
index d044b90..34c5bd5 100644
--- a/src/math/random.h
+++ b/src/math/random.h
@@ -2,6 +2,9 @@
  * ecgen, tool for generating Elliptic curve domain parameters
  * Copyright (C) 2017 J08nY
  */
+/**
+ * @file random.h
+ */
 #ifndef ECGEN_RANDOM_H
 #define ECGEN_RANDOM_H
 
diff --git a/src/math/types.h b/src/math/types.h
index 8185078..7124573 100644
--- a/src/math/types.h
+++ b/src/math/types.h
@@ -2,20 +2,23 @@
  * ecgen, tool for generating Elliptic curve domain parameters
  * Copyright (C) 2017 J08nY
  */
+/**
+ * @file types.h
+ */
 #ifndef ECGEN_TYPES_H
 #define ECGEN_TYPES_H
 
 #include <pari/pari.h>
 #include "io/cli.h"
 
-typedef struct seed { GEN seed; } seed_t;
+typedef struct seed_t { GEN seed; } seed_t;
 
 typedef struct point_t {
 	GEN point;
 	GEN order;
 } point_t;
 
-typedef struct curve {
+typedef struct curve_t {
 	seed_t *seed;
 	GEN field;
 	GEN a;