propagate from branch 'net.randombit.botan' (head 647eeb4f4cf8fa4cf487cdc463d48f09fe18658e)

            to branch 'net.randombit.botan.c++0x' (head 2539675db91883b11895ddc5244721e93c413321)

2 files changed, 116 insertions, 21 deletions

diff --git a/src/math/numbertheory/curve_gfp.h b/src/math/numbertheory/curve_gfp.h
index 0a91fc52d..8a46a9735 100644
--- a/src/math/numbertheory/curve_gfp.h
+++ b/src/math/numbertheory/curve_gfp.h
@@ -52,14 +52,12 @@ class BOTAN_DLL CurveGFp
       // CurveGFp& operator=(const CurveGFp& other) = default;
 
       /**
-      * Get coefficient a
-      * @return coefficient a
+      * @return curve coefficient a
       */
       const BigInt& get_a() const { return a; }
 
       /**
-      * Get coefficient b
-      * @return coefficient b
+      * @return curve coefficient b
       */
       const BigInt& get_b() const { return b; }
 
@@ -94,11 +92,14 @@ class BOTAN_DLL CurveGFp
       */
       u32bit get_p_words() const { return p_words; }
 
+      /**
+      * @return modular reducer for p
+      */
       const Modular_Reducer& mod_p() const { return reducer_p; }
 
       /**
       * swaps the states of *this and other, does not throw
-      * @param other The curve to swap values with
+      * @param other curve to swap values with
       */
       void swap(CurveGFp& other)
          {
@@ -112,6 +113,11 @@ class BOTAN_DLL CurveGFp
          std::swap(p_dash, other.p_dash);
          }
 
+      /**
+      * Equality operator
+      * @param other curve to compare with
+      * @return true iff this is the same curve as other
+      */
       bool operator==(const CurveGFp& other) const
          {
          return (p == other.p && a == other.a && b == other.b);
@@ -130,6 +136,12 @@ class BOTAN_DLL CurveGFp
       Modular_Reducer reducer_p;
    };
 
+/**
+* Equality operator
+* @param lhs a curve
+* @param rhs a curve
+* @return true iff lhs is not the same as rhs
+*/
 inline bool operator!=(const CurveGFp& lhs, const CurveGFp& rhs)
    {
    return !(lhs == rhs);
diff --git a/src/math/numbertheory/numthry.h b/src/math/numbertheory/numthry.h
index 9a1005413..1ab64b038 100644
--- a/src/math/numbertheory/numthry.h
+++ b/src/math/numbertheory/numthry.h
@@ -15,13 +15,31 @@
 namespace Botan {
 
 /**
-* Fused Arithmetic Operation
+* Fused multiply-add
+* @param a an integer
+* @param b an integer
+* @param c an integer
+* @return (a*b)+c
 */
-BigInt BOTAN_DLL mul_add(const BigInt&, const BigInt&, const BigInt&);
-BigInt BOTAN_DLL sub_mul(const BigInt&, const BigInt&, const BigInt&);
+BigInt BOTAN_DLL mul_add(const BigInt& a,
+                         const BigInt& b,
+                         const BigInt& c);
 
-/*
-* Number Theory Functions
+/**
+* Fused subtract-multiply
+* @param a an integer
+* @param b an integer
+* @param c an integer
+* @return (a-b)*c
+*/
+BigInt BOTAN_DLL sub_mul(const BigInt& a,
+                         const BigInt& b,
+                         const BigInt& c);
+
+/**
+* Return the absolute value
+* @param n an integer
+* @return absolute value of n
 */
 inline BigInt abs(const BigInt& n) { return n.abs(); }
 
@@ -70,8 +88,14 @@ s32bit BOTAN_DLL jacobi(const BigInt& a,
 
 /**
 * Modular exponentation
+* @param b an integer base
+* @param x a positive exponent
+* @param m a positive modulus
+* @return (b^x) % m
 */
-BigInt BOTAN_DLL power_mod(const BigInt&, const BigInt&, const BigInt&);
+BigInt BOTAN_DLL power_mod(const BigInt& b,
+                           const BigInt& x,
+                           const BigInt& m);
 
 /**
 * Compute the square root of x modulo a prime using the
@@ -90,55 +114,114 @@ BigInt BOTAN_DLL ressol(const BigInt& x, const BigInt& p);
 */
 u32bit BOTAN_DLL low_zero_bits(const BigInt& x);
 
-/*
+/**
 * Primality Testing
+* @param n a positive integer to test for primality
+* @param rng a random number generator
+* @param level how hard to test
+* @return true if all primality tests passed, otherwise false
 */
 bool BOTAN_DLL primality_test(const BigInt& n,
                               RandomNumberGenerator& rng,
                               u32bit level = 1);
 
+/**
+* Quickly check for primality
+* @param n a positive integer to test for primality
+* @param rng a random number generator
+* @return true if all primality tests passed, otherwise false
+*/
 inline bool quick_check_prime(const BigInt& n, RandomNumberGenerator& rng)
    { return primality_test(n, rng, 0); }
 
+/**
+* Check for primality
+* @param n a positive integer to test for primality
+* @param rng a random number generator
+* @return true if all primality tests passed, otherwise false
+*/
 inline bool check_prime(const BigInt& n, RandomNumberGenerator& rng)
    { return primality_test(n, rng, 1); }
 
+/**
+* Verify primality - this function is slow but useful if you want to
+* ensure that a possibly malicious entity did not provide you with
+* something that 'looks like' a prime
+* @param n a positive integer to test for primality
+* @param rng a random number generator
+* @return true if all primality tests passed, otherwise false
+*/
 inline bool verify_prime(const BigInt& n, RandomNumberGenerator& rng)
    { return primality_test(n, rng, 2); }
 
-/*
-* Random Number Generation
+/**
+* Randomly generate a prime
+* @param rng a random number generator
+* @param bits how large the resulting prime should be in bits
+* @param coprime a positive integer the result should be coprime to
+* @param equiv a non-negative number that the result should be
+               equivalent to modulo equiv_mod
+* @param equiv_mod the modulus equiv should be checked against
+* @return random prime with the specified criteria
 */
 BigInt BOTAN_DLL random_prime(RandomNumberGenerator& rng,
                               u32bit bits, const BigInt& coprime = 1,
                               u32bit equiv = 1, u32bit equiv_mod = 2);
 
+/**
+* Return a 'safe' prime, of the form p=2*q+1 with q prime
+* @param rng a random number generator
+* @param bits is how long the resulting prime should be
+* @return prime randomly chosen from safe primes of length bits
+*/
 BigInt BOTAN_DLL random_safe_prime(RandomNumberGenerator& rng,
                                    u32bit bits);
 
-/*
-* DSA Parameter Generation
-*/
 class Algorithm_Factory;
 
+/**
+* Generate DSA parameters using the FIPS 186 kosherizer
+* @param rng a random number generator
+* @param af an algorithm factory
+* @param p_out where the prime p will be stored
+* @param q_out where the prime q will be stored
+* @param pbits how long p will be in bits
+* @param qbits how long q will be in bits
+* @return random seed used to generate this parameter set
+*/
 SecureVector<byte> BOTAN_DLL
 generate_dsa_primes(RandomNumberGenerator& rng,
                     Algorithm_Factory& af,
-                    BigInt& p, BigInt& q,
+                    BigInt& p_out, BigInt& q_out,
                     u32bit pbits, u32bit qbits);
 
+/**
+* Generate DSA parameters using the FIPS 186 kosherizer
+* @param rng a random number generator
+* @param af an algorithm factory
+* @param p_out where the prime p will be stored
+* @param q_out where the prime q will be stored
+* @param pbits how long p will be in bits
+* @param qbits how long q will be in bits
+* @param seed the seed used to generate the parameters
+* @return true if seed generated a valid DSA parameter set, otherwise
+          false. p_out and q_out are only valid if true was returned.
+*/
 bool BOTAN_DLL
 generate_dsa_primes(RandomNumberGenerator& rng,
                     Algorithm_Factory& af,
                     BigInt& p_out, BigInt& q_out,
-                    u32bit p_bits, u32bit q_bits,
+                    u32bit pbits, u32bit qbits,
                     const MemoryRegion<byte>& seed);
 
-/*
-* Prime Numbers
+/**
+* The size of the PRIMES[] array
 */
 const u32bit PRIME_TABLE_SIZE = 6541;
 
+/**
+* A const array of all primes less than 65535
+*/
 extern const u16bit BOTAN_DLL PRIMES[];
 
 }