diff options
author | Matthias Schiffer <mschiffer@universe-factory.net> | 2015-10-03 18:41:12 +0200 |
---|---|---|
committer | Matthias Schiffer <mschiffer@universe-factory.net> | 2015-10-03 18:57:27 +0200 |
commit | 320daa4838380eff81ab782d4346c29280c1afa3 (patch) | |
tree | 462cbfe66243cb673ebf25cfc2c0e59017188f71 | |
parent | 55178f5f41436ca17e1d3c8977df69bbcb6f7fcd (diff) | |
download | libuecc-320daa4838380eff81ab782d4346c29280c1afa3.tar libuecc-320daa4838380eff81ab782d4346c29280c1afa3.zip |
Improve documenation of internal functions
-rw-r--r-- | src/ec25519.c | 44 |
1 files changed, 34 insertions, 10 deletions
diff --git a/src/ec25519.c b/src/ec25519.c index 040f521..e419a0a 100644 --- a/src/ec25519.c +++ b/src/ec25519.c @@ -37,6 +37,10 @@ * double operations. * * Doxygen comments for public APIs can be found in the public header file. + * + * Invariant that must be held by all public API: the components of an + * \ref ecc_25519_work_t are always in the range \f$ [0, 2p) \f$. + * Integers in this range will be called \em squeezed in the following. */ #include <libuecc/ecc.h> @@ -74,7 +78,11 @@ static void add(unsigned int out[32], const unsigned int a[32], const unsigned i u += a[31] + b[31]; out[31] = u; } -/** Subtracts two unpacked integers (modulo p) */ +/** + * Subtracts two unpacked integers (modulo p) + * + * b must be \em squeezed. + */ static void sub(unsigned int out[32], const unsigned int a[32], const unsigned int b[32]) { unsigned int j; unsigned int u; @@ -88,7 +96,11 @@ static void sub(unsigned int out[32], const unsigned int a[32], const unsigned i out[31] = u; } -/** Performs carry and reduce on an unpacked integer */ +/** + * Performs carry and reduce on an unpacked integer + * + * The result is not always fully reduced, but it will be significantly smaller than \f$ 2p \f$. + */ static void squeeze(unsigned int a[32]) { unsigned int j; unsigned int u; @@ -103,7 +115,7 @@ static void squeeze(unsigned int a[32]) { /** * Ensures that the output of a previous \ref squeeze is fully reduced * - * After a \ref freeze, only the lower byte of each integer part holds a meaningful value + * After a \ref freeze, only the lower byte of each integer part holds a meaningful value. */ static void freeze(unsigned int a[32]) { static const unsigned int minusp[32] = { @@ -123,7 +135,11 @@ static void freeze(unsigned int a[32]) { for (j = 0; j < 32; j++) a[j] ^= negative & (aorig[j] ^ a[j]); } -/** Multiplies two unpacked integers (modulo p) */ +/** + * Multiplies two unpacked integers (modulo p) + * + * The result will be \em squeezed. + */ static void mult(unsigned int out[32], const unsigned int a[32], const unsigned int b[32]) { unsigned int i; unsigned int j; @@ -138,7 +154,11 @@ static void mult(unsigned int out[32], const unsigned int a[32], const unsigned squeeze(out); } -/** Multiplies an unpacked integer with a small integer (modulo p) */ +/** + * Multiplies an unpacked integer with a small integer (modulo p) + * + * The result will be \em squeezed. + */ static void mult_int(unsigned int out[32], unsigned int n, const unsigned int a[32]) { unsigned int j; unsigned int u; @@ -151,7 +171,11 @@ static void mult_int(unsigned int out[32], unsigned int n, const unsigned int a[ u += out[j]; out[j] = u; } -/** Squares an unpacked integer */ +/** + * Squares an unpacked integer + * + * The result will be sqeezed. + */ static void square(unsigned int out[32], const unsigned int a[32]) { unsigned int i; unsigned int j; @@ -185,9 +209,9 @@ static int check_equal(const unsigned int x[32], const unsigned int y[32]) { } /** - * Checks if an unpacked integer equals zero + * Checks if an unpacked integer equals zero (modulo p) * - * The intergers must be \ref squeeze "squeezed" before. + * The interger must be squeezed before. */ static int check_zero(const unsigned int x[32]) { static const unsigned int p[32] = { @@ -473,7 +497,7 @@ int ecc_25519_load_packed(ecc_25519_work_t *out, const ecc_int256_t *in) { if (!square_root(Y, Y2)) return 0; - /* No squeeze is necessary for subtractions from zero */ + /* No squeeze is necessary after subtractions from zero if the subtrahend is squeezed */ sub(Yt, zero, Y); select(out->Y, Y, Yt, (in->p[31] >> 7) ^ (Y[0] & 1)); @@ -507,7 +531,7 @@ void ecc_25519_negate(ecc_25519_work_t *out, const ecc_25519_work_t *in) { out->Z[i] = in->Z[i]; } - /* No squeeze is necessary for subtractions from zero */ + /* No squeeze is necessary after subtractions from zero if the subtrahend is squeezed */ sub(out->X, zero, in->X); sub(out->T, zero, in->T); } |