diff options
| -rw-r--r-- | src/math/bigint/bigint.h | 53 | ||||
| -rw-r--r-- | src/math/numbertheory/numthry.h | 60 |
2 files changed, 75 insertions, 38 deletions
diff --git a/src/math/bigint/bigint.h b/src/math/bigint/bigint.h index 997814950..a3a079dcc 100644 --- a/src/math/bigint/bigint.h +++ b/src/math/bigint/bigint.h @@ -68,28 +68,28 @@ class BOTAN_DLL BigInt BigInt& operator/=(const BigInt& y); /** - * %= operator, modulo operator + * Modulo operator * @param y the modulus to reduce this by */ BigInt& operator%=(const BigInt& y); /** - * %= operator + * Modulo operator * @param y the modulus (word) to reduce this by */ word operator%=(word y); /** - * <<= operator - * @param y the number of bits to shift this left by + * Left shift operator + * @param shift the number of bits to shift this left by */ - BigInt& operator<<=(u32bit y); + BigInt& operator<<=(u32bit shift); /** - * >>= operator - * @param y the number of bits to shift this right by + * Right shift operator + * @param shift the number of bits to shift this right by */ - BigInt& operator>>=(u32bit y); + BigInt& operator>>=(u32bit shift); /** * Increment operator @@ -102,12 +102,12 @@ class BOTAN_DLL BigInt BigInt& operator--() { return (*this -= 1); } /** - * ++ operator (postfix) + * Postfix increment operator */ BigInt operator++(int) { BigInt x = (*this); ++(*this); return x; } /** - * -- operator (postfix) + * Postfix decrement operator */ BigInt operator--(int) { BigInt x = (*this); --(*this); return x; } @@ -233,7 +233,7 @@ class BOTAN_DLL BigInt /** * Return the integer as an unsigned 32bit-integer-value. If the - * value is negative OR to big to be stored in 32bits, this + * value is negative OR too big to be stored in a u32bit, this * function will throw an exception. * * @result unsigned 32 bit representation of this @@ -242,13 +242,13 @@ class BOTAN_DLL BigInt /** * Tests if the sign of the integer is negative - * @result true, if the integer has a negative sign + * @result true, iff the integer has a negative sign */ bool is_negative() const { return (sign() == Negative); } /** * Tests if the sign of the integer is positive - * @result true, if the integer has a positive sign + * @result true, iff the integer has a positive sign */ bool is_positive() const { return (sign() == Positive); } @@ -259,13 +259,12 @@ class BOTAN_DLL BigInt Sign sign() const { return (signedness); } /** - * Return the opposite sign of the represented integer value * @result the opposite sign of the represented integer value */ Sign reverse_sign() const; /** - * Flip (mutate) the sign of the integer to its opposite value + * Flip the sign of this BigInt */ void flip_sign(); @@ -287,7 +286,7 @@ class BOTAN_DLL BigInt u32bit size() const { return get_reg().size(); } /** - * Give significant words of the represented integer value + * Return how many words we need to hold this value * @result significant words of the represented integer value */ u32bit sig_words() const @@ -301,14 +300,14 @@ class BOTAN_DLL BigInt } /** - * Give byte-length of the integer - * @result byte-length of the represented integer value + * Give byte length of the integer + * @result byte length of the represented integer value */ u32bit bytes() const; /** - * Get the bit-length of the integer - * @result bit-length of the represented integer value + * Get the bit length of the integer + * @result bit length of the represented integer value */ u32bit bits() const; @@ -429,10 +428,10 @@ class BOTAN_DLL BigInt static SecureVector<byte> encode_1363(const BigInt& n, u32bit bytes); /** - * Swap BigInt-value with given BigInt - * @param bigint the BigInt to swap values with + * Swap this value with another + * @param other BigInt to swap values with */ - void swap(BigInt& bigint); + void swap(BigInt& other); /** * Create empty BigInt @@ -481,14 +480,16 @@ class BOTAN_DLL BigInt /** * Create BigInt of specified size, all zeros * @param sign the sign - * @param n integer value + * @param n size of the internal register in words */ BigInt(Sign sign, u32bit n); /** * Create a number of the specified type and size - * @param type the type of number to create - * @param n the size + * @param type the type of number to create. For Power2, + * will create the integer 2^n + * @param n a size/length parameter, interpretation depends upon + * the value of type */ BigInt(NumberType type, u32bit n); diff --git a/src/math/numbertheory/numthry.h b/src/math/numbertheory/numthry.h index 2d889a68a..146f158b6 100644 --- a/src/math/numbertheory/numthry.h +++ b/src/math/numbertheory/numthry.h @@ -14,8 +14,8 @@ namespace Botan { -/* -* Fused Arithmetic Operations +/** +* Fused Arithmetic Operation */ BigInt BOTAN_DLL mul_add(const BigInt&, const BigInt&, const BigInt&); BigInt BOTAN_DLL sub_mul(const BigInt&, const BigInt&, const BigInt&); @@ -25,27 +25,63 @@ BigInt BOTAN_DLL sub_mul(const BigInt&, const BigInt&, const BigInt&); */ inline BigInt abs(const BigInt& n) { return n.abs(); } -void BOTAN_DLL divide(const BigInt&, const BigInt&, BigInt&, BigInt&); - +/** +* Compute the greatest common divisor +* @param x a positive integer +* @param y a positive integer +* @return gcd(x,y) +*/ BigInt BOTAN_DLL gcd(const BigInt& x, const BigInt& y); + +/** +* Least common multiple +* @param x a positive integer +* @param y a positive integer +* @return z, smallest integer such that z % x == 0 and z % y == 0 +*/ BigInt BOTAN_DLL lcm(const BigInt& x, const BigInt& y); -BigInt BOTAN_DLL square(const BigInt&); -BigInt BOTAN_DLL inverse_mod(const BigInt&, const BigInt&); +/** +* @param x an integer +* @return (x*x) +*/ +BigInt BOTAN_DLL square(const BigInt& x); + +/** +* Modular inversion +* @param x a positive integer +* @param modulus a positive integer +* @return y st (x*y) % modulus == 1 +*/ +BigInt BOTAN_DLL inverse_mod(const BigInt& x, + const BigInt& modulus); + +/** +* Jacobi function +*/ s32bit BOTAN_DLL jacobi(const BigInt&, const BigInt&); +/** +* Modular exponentation +*/ BigInt BOTAN_DLL power_mod(const BigInt&, const BigInt&, const BigInt&); -/* -* Compute the square root of x modulo a prime -* using the Shanks-Tonnelli algorithm +/** +* Compute the square root of x modulo a prime using the +* Shanks-Tonnelli algorithm +* +* @param x the input +* @param p the prime +* @return y such that (y*y)%p == x, or -1 if no such integer */ BigInt BOTAN_DLL ressol(const BigInt& x, const BigInt& p); -/* -* Utility Functions +/** +* @param x an integer +* @return count of the zero bits in x, or, equivalently, the largest +* value of n such that 2^n divides x evently */ -u32bit BOTAN_DLL low_zero_bits(const BigInt&); +u32bit BOTAN_DLL low_zero_bits(const BigInt& x); /* * Primality Testing |