This is an automated email from the ASF dual-hosted git repository. sandreoli pushed a commit to branch review-mike in repository https://gitbox.apache.org/repos/asf/incubator-milagro-crypto-c.git
commit 43e64fc7decb2a3e5f3414d5ded7b7887d4edbe0 Author: Samuele Andreoli <[email protected]> AuthorDate: Wed Apr 8 23:28:05 2020 +0100 improve documentation --- include/big.h.in | 24 ++++++++++++------------ include/ff.h.in | 8 ++++---- src/ff.c.in | 4 +++- 3 files changed, 19 insertions(+), 17 deletions(-) diff --git a/include/big.h.in b/include/big.h.in index f4c7582..4331947 100644 --- a/include/big.h.in +++ b/include/big.h.in @@ -408,33 +408,33 @@ extern int BIG_XXX_comp(BIG_XXX x,BIG_XXX y); @return -1 is x<y, 0 if x=y, 1 if x>y */ extern int BIG_XXX_dcomp(DBIG_XXX x,DBIG_XXX y); -/** @brief Calculate number of bits in a BIG - output normalised +/** @brief Calculate number of bits in a BIG - output normalised - leaks log2(x) * @param x BIG number @return Number of bits in x */ extern int BIG_XXX_nbits(BIG_XXX x); -/** @brief Calculate number of bits in a DBIG - output normalised +/** @brief Calculate number of bits in a DBIG - output normalised - leaks log2(x) * @param x DBIG number @return Number of bits in x */ extern int BIG_XXX_dnbits(DBIG_XXX x); -/** @brief Reduce x mod n - input and output normalised +/** @brief Reduce x mod n - input and output normalised - leaks log2(x)-log2(n) * Slow but rarely used @param x BIG number to be reduced mod n @param n The modulus */ extern void BIG_XXX_mod(BIG_XXX x,BIG_XXX n); -/** @brief Divide x by n - output normalised +/** @brief Divide x by n - output normalised - leaks log2(x)-log2(n) * Slow but rarely used @param x BIG number to be divided by n @param n The Divisor */ extern void BIG_XXX_sdiv(BIG_XXX x,BIG_XXX n); -/** @brief x=y mod n - output normalised +/** @brief x=y mod n - output normalised - leaks log2(y)-log2(n) * Slow but rarely used. y is destroyed. @param x BIG number, on exit = y mod n @@ -442,7 +442,7 @@ extern void BIG_XXX_sdiv(BIG_XXX x,BIG_XXX n); @param n Modulus */ extern void BIG_XXX_dmod(BIG_XXX x,DBIG_XXX y,BIG_XXX n); -/** @brief x=y/n - output normalised +/** @brief x=y/n - output normalised - leaks log2(y)-log2(n) * Slow but rarely used. y is destroyed. @param x BIG number, on exit = y/n @@ -477,7 +477,7 @@ extern int BIG_XXX_lastbits(BIG_XXX x,int n); @param r A pointer to a Cryptographically Secure Random Number Generator */ extern void BIG_XXX_random(BIG_XXX x,csprng *r); -/** @brief Create an unbiased random BIG from a random number generator, reduced with respect to a modulus +/** @brief Create an unbiased random BIG from a random number generator, reduced with respect to a modulus - leaks log2(n) * Assumes that the random number generator has been suitably initialised @param x BIG number, on exit a random number @@ -496,7 +496,7 @@ extern void BIG_XXX_randomnum(BIG_XXX x,BIG_XXX n,csprng *r); return + or - 1, 3 or 5 */ -/** @brief Calculate x=y*z mod n +/** @brief Calculate x=y*z mod n - leaks log2(x)-log2(n) * Slow method for modular multiplication @param x BIG number, on exit = y*z mod n @@ -505,7 +505,7 @@ extern void BIG_XXX_randomnum(BIG_XXX x,BIG_XXX n,csprng *r); @param n The BIG Modulus */ extern void BIG_XXX_modmul(BIG_XXX x,BIG_XXX y,BIG_XXX z,BIG_XXX n); -/** @brief Calculate x=y/z mod n +/** @brief Calculate x=y/z mod n - leaks log2(x)-log2(n) * Slow method for modular division @param x BIG number, on exit = y/z mod n @@ -514,7 +514,7 @@ extern void BIG_XXX_modmul(BIG_XXX x,BIG_XXX y,BIG_XXX z,BIG_XXX n); @param n The BIG Modulus */ extern void BIG_XXX_moddiv(BIG_XXX x,BIG_XXX y,BIG_XXX z,BIG_XXX n); -/** @brief Calculate x=y^2 mod n +/** @brief Calculate x=y^2 mod n - leaks log2(x)-log2(n) * Slow method for modular squaring @param x BIG number, on exit = y^2 mod n @@ -522,7 +522,7 @@ extern void BIG_XXX_moddiv(BIG_XXX x,BIG_XXX y,BIG_XXX z,BIG_XXX n); @param n The BIG Modulus */ extern void BIG_XXX_modsqr(BIG_XXX x,BIG_XXX y,BIG_XXX n); -/** @brief Calculate x=-y mod n +/** @brief Calculate x=-y mod n - leaks log2(x)-log2(n) * Modular negation @param x BIG number, on exit = -y mod n @@ -530,7 +530,7 @@ extern void BIG_XXX_modsqr(BIG_XXX x,BIG_XXX y,BIG_XXX n); @param n The BIG Modulus */ extern void BIG_XXX_modneg(BIG_XXX x,BIG_XXX y,BIG_XXX n); -/** @brief Calculate jacobi Symbol (x/y) +/** @brief Calculate jacobi Symbol (x/y) - not constant time * @param x BIG number @param y BIG number diff --git a/include/ff.h.in b/include/ff.h.in index 1f2630f..fd24215 100644 --- a/include/ff.h.in +++ b/include/ff.h.in @@ -185,7 +185,7 @@ extern void FF_WWW_fromOctet(BIG_XXX *x,octet *S,int n); @param n size of FF in BIGs */ extern void FF_WWW_mul(BIG_XXX *x,BIG_XXX *y,BIG_XXX *z,int n); -/** @brief Reduce FF mod a modulus +/** @brief Reduce FF mod a modulus - leaks log2(p)-log2(n) * This is slow @param x FF instance to be reduced mod p - on exit = x mod p @@ -201,7 +201,7 @@ extern void FF_WWW_mod(BIG_XXX *x,BIG_XXX *p,int n); @param n size of FF in BIGs */ extern void FF_WWW_sqr(BIG_XXX *x,BIG_XXX *y,int n); -/** @brief Reduces a double-length FF with respect to a given modulus +/** @brief Reduces a double-length FF with respect to a given modulus - leaks log2(y)-log2(z) * This is slow @param x FF instance, on exit = y mod z @@ -232,7 +232,7 @@ extern void FF_WWW_invmod2m(BIG_XXX U[],BIG_XXX a[],int n); @param n size of FF in BIGs */ extern void FF_WWW_random(BIG_XXX *x,csprng *R,int n); -/** @brief Create a random FF less than a given modulus from a random number generator +/** @brief Create a random FF less than a given modulus from a random number generator - leaks log2(y) * @param x FF instance, on exit x is a random number < y @param y FF instance, the modulus @@ -286,7 +286,7 @@ extern void FF_WWW_skpow2(BIG_XXX *r,BIG_XXX *x, BIG_XXX *e, BIG_XXX *y, BIG_XXX @param en size of the exponent in BIGs */ extern void FF_WWW_skpow3(BIG_XXX *r,BIG_XXX *x, BIG_XXX *e, BIG_XXX *y, BIG_XXX *f, BIG_XXX *z, BIG_XXX *g, BIG_XXX *p, int n, int en); -/** @brief Calculate r=x^e mod p +/** @brief Calculate r=x^e mod p. Faster but not constant time * For very short integer exponent @param r FF instance, on exit = x^e mod p diff --git a/src/ff.c.in b/src/ff.c.in index 9828305..65f768f 100644 --- a/src/ff.c.in +++ b/src/ff.c.in @@ -1031,7 +1031,9 @@ void FF_WWW_pow(BIG_XXX r[], BIG_XXX x[], BIG_XXX e[], BIG_XXX p[], int n, int e FF_WWW_redc(r,p,ND,n); } -/* Compute prod(x_i^e_i) mod p. Faster but not constant time */ +/* Compute prod(x_i^e_i) mod p. Faster but not constant time + Only feasible for small values of n (n<=4) +*/ static void FF_WWW_pown(BIG_XXX *r, BIG_XXX *x[], BIG_XXX *e[], BIG_XXX *p, int xlen, int elen, int n) { #ifndef C99
