summaryrefslogtreecommitdiffstats
path: root/include
diff options
context:
space:
mode:
authorMatthias Schiffer <mschiffer@universe-factory.net>2012-12-23 19:17:28 +0100
committerMatthias Schiffer <mschiffer@universe-factory.net>2012-12-23 19:17:28 +0100
commit9d875f041854593e5b19bc63961da102f9fd754e (patch)
tree08a013f0fea40d6c821887cfd62db7969e35821f /include
parent9c832519c6b4b3a001b82e832c345791221db399 (diff)
downloadlibuecc-9d875f041854593e5b19bc63961da102f9fd754e.tar
libuecc-9d875f041854593e5b19bc63961da102f9fd754e.zip
Lots of code documentation
Diffstat (limited to 'include')
-rw-r--r--include/libuecc/ecc.h92
1 files changed, 86 insertions, 6 deletions
diff --git a/include/libuecc/ecc.h b/include/libuecc/ecc.h
index 2f2c0d9..1cc2100 100644
--- a/include/libuecc/ecc.h
+++ b/include/libuecc/ecc.h
@@ -31,15 +31,28 @@
#define DEPRECATED __attribute__((deprecated))
#endif
-
+/**
+ * A 256 bit integer
+ *
+ * All functions of libuecc treat \ref ecc_int256_t as unsigned little-endian.
+ */
typedef union _ecc_int256 {
+ /** Data bytes */
unsigned char p[32];
- /* old name */
+ /**
+ * Old name of p
+ * \deprecated Use \ref ecc_int256_t::p instead.
+ */
unsigned char s[32] DEPRECATED;
} ecc_int256_t;
-/* a point on the curve unpacked for efficient calculation */
+/**
+ * A point on the curve unpacked for efficient calculation
+ *
+ * The internal representation of an unpacked point isn't unique, so for serialization
+ * it should always be packed.
+ */
typedef struct _ecc_25519_work {
unsigned int X[32];
unsigned int Y[32];
@@ -47,6 +60,10 @@ typedef struct _ecc_25519_work {
unsigned int T[32];
} ecc_25519_work_t;
+/**
+ * \defgroup curve_ops Operations on points of the Elliptic Curve
+ * @{
+ */
void ecc_25519_load_xy(ecc_25519_work_t *out, const ecc_int256_t *x, const ecc_int256_t *y);
void ecc_25519_store_xy(ecc_int256_t *x, ecc_int256_t *y, const ecc_25519_work_t *in);
@@ -55,12 +72,18 @@ void ecc_25519_load_packed(ecc_25519_work_t *out, const ecc_int256_t *in);
void ecc_25519_store_packed(ecc_int256_t *out, const ecc_25519_work_t *in);
int ecc_25519_is_identity(const ecc_25519_work_t *in);
-void ecc_25519_add(ecc_25519_work_t *out, const ecc_25519_work_t *in1, const ecc_25519_work_t *in2);
void ecc_25519_double(ecc_25519_work_t *out, const ecc_25519_work_t *in);
+void ecc_25519_add(ecc_25519_work_t *out, const ecc_25519_work_t *in1, const ecc_25519_work_t *in2);
void ecc_25519_scalarmult(ecc_25519_work_t *out, const ecc_int256_t *n, const ecc_25519_work_t *base);
void ecc_25519_scalarmult_base(ecc_25519_work_t *out, const ecc_int256_t *n);
-/* operations on elements of the prime field F_q for q = 2^252 + 27742317777372353535851937790883648493 */
+/**@}*/
+
+/**
+ * \defgroup gf_ops Prime field operations for the order of the base point of the Elliptic Curve
+ * @{
+ */
+
extern const ecc_int256_t ecc_25519_gf_order;
int ecc_25519_gf_is_zero(const ecc_int256_t *in);
@@ -69,42 +92,99 @@ void ecc_25519_gf_sub(ecc_int256_t *out, const ecc_int256_t *in1, const ecc_int2
void ecc_25519_gf_reduce(ecc_int256_t *out, const ecc_int256_t *in);
void ecc_25519_gf_mult(ecc_int256_t *out, const ecc_int256_t *in1, const ecc_int256_t *in2);
void ecc_25519_gf_recip(ecc_int256_t *out, const ecc_int256_t *in);
-
void ecc_25519_gf_sanitize_secret(ecc_int256_t *out, const ecc_int256_t *in);
+/**@}*/
+
/* declarations for the old names */
+
+/**
+ * Old name of \ref ecc_int256_t
+ * \deprecated Use \ref ecc_int256_t instead.
+ */
typedef ecc_int256_t ecc_secret_key_256 DEPRECATED;
+
+/**
+ * Old name of \ref ecc_int256_t
+ * \deprecated Use \ref ecc_int256_t instead.
+ */
typedef ecc_int256_t ecc_public_key_256 DEPRECATED;
+
+/**
+ * Old name of \ref ecc_25519_work_t
+ * \deprecated Use \ref ecc_25519_work_t instead.
+ */
typedef ecc_25519_work_t ecc_25519_work DEPRECATED;
+
+/**
+ * Loads a packed point into its unpacked representation
+ *
+ * \deprecated Use \ref ecc_25519_load_packed instead.
+ */
DEPRECATED static inline void ecc_25519_load(ecc_25519_work_t *out, const ecc_int256_t *in) {
ecc_25519_load_packed(out, in);
}
+/**
+ * Stores a point into its packed representation
+ *
+ * \deprecated Use \ref ecc_25519_store_packed instead.
+ */
DEPRECATED static inline void ecc_25519_store(ecc_int256_t *out, const ecc_25519_work_t *in) {
ecc_25519_store_packed(out, in);
}
+/**
+ * Checks if an integer is equal to zero (after reduction)
+ *
+ * \deprecated Use \ref ecc_25519_gf_is_zero instead.
+ */
DEPRECATED static inline int ecc_25519_secret_is_zero(const ecc_int256_t *in) {
return ecc_25519_gf_is_zero(in);
}
+/**
+ * Adds two integers as Galois field elements
+ *
+ * \deprecated Use \ref ecc_25519_gf_add instead.
+ */
DEPRECATED static inline void ecc_25519_secret_add(ecc_int256_t *out, const ecc_int256_t *in1, const ecc_int256_t *in2) {
ecc_25519_gf_add(out, in1, in2);
}
+/**
+ * Subtracts two integers as Galois field elements
+ *
+ * \deprecated Use \ref ecc_25519_gf_sub instead.
+ */
DEPRECATED static inline void ecc_25519_secret_sub(ecc_int256_t *out, const ecc_int256_t *in1, const ecc_int256_t *in2) {
ecc_25519_gf_sub(out, in1, in2);
}
+/**
+ * Reduces an integer to a unique representation in the range \f$ [0,q-1] \f$
+ *
+ * \deprecated Use \ref ecc_25519_gf_reduce instead.
+ */
DEPRECATED static inline void ecc_25519_secret_reduce(ecc_int256_t *out, const ecc_int256_t *in) {
ecc_25519_gf_reduce(out, in);
}
+/**
+ * Multiplies to integers as Galois field elements
+ *
+ * \deprecated Use \ref ecc_25519_gf_mult instead.
+ */
DEPRECATED static inline void ecc_25519_secret_mult(ecc_int256_t *out, const ecc_int256_t *in1, const ecc_int256_t *in2) {
ecc_25519_gf_mult(out, in1, in2);
}
+/**
+ * Ensures some properties of a Galois field element to make it fit for use as a secret key
+ *
+ * \deprecated Use \ref ecc_25519_gf_sanitize_secret instead.
+ */
DEPRECATED static inline void ecc_25519_secret_sanitize(ecc_int256_t *out, const ecc_int256_t *in) {
ecc_25519_gf_sanitize_secret(out, in);
}