aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--src/math/numbertheory/numthry.h105
-rw-r--r--src/pk_pad/eme.h80
-rw-r--r--src/pk_pad/eme1/eme1.h5
-rw-r--r--src/pk_pad/emsa.h34
-rw-r--r--src/pk_pad/emsa1/emsa1.h3
-rw-r--r--src/pk_pad/hash_id/hash_id.cpp10
-rw-r--r--src/pk_pad/hash_id/hash_id.h18
-rw-r--r--src/pubkey/pkcs8.h3
-rw-r--r--src/utils/cpuid.h18
9 files changed, 226 insertions, 50 deletions
diff --git a/src/math/numbertheory/numthry.h b/src/math/numbertheory/numthry.h
index 9a1005413..adaa403ca 100644
--- a/src/math/numbertheory/numthry.h
+++ b/src/math/numbertheory/numthry.h
@@ -15,13 +15,27 @@
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&);
+
+/**
+* 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&, const BigInt&, const BigInt&);
-/*
-* Number Theory Functions
+/**
+* Return the absolute value
+* @param n an integer
+* @return absolute value of n
*/
inline BigInt abs(const BigInt& n) { return n.abs(); }
@@ -70,8 +84,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,43 +110,99 @@ 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,
@@ -134,11 +210,14 @@ generate_dsa_primes(RandomNumberGenerator& rng,
u32bit p_bits, u32bit q_bits,
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[];
}
diff --git a/src/pk_pad/eme.h b/src/pk_pad/eme.h
index 02b8208ef..1bc3ba3c9 100644
--- a/src/pk_pad/eme.h
+++ b/src/pk_pad/eme.h
@@ -19,22 +19,82 @@ namespace Botan {
class BOTAN_DLL EME
{
public:
- virtual u32bit maximum_input_size(u32bit) const = 0;
+ /**
+ * Return the maximum input size in bytes we can support
+ * @param keybits the size of the key in bits
+ * @return upper bound of input in bytes
+ */
+ virtual u32bit maximum_input_size(u32bit keybits) const = 0;
- SecureVector<byte> encode(const byte[], u32bit, u32bit,
- RandomNumberGenerator&) const;
- SecureVector<byte> encode(const MemoryRegion<byte>&, u32bit,
- RandomNumberGenerator&) const;
+ /**
+ * Encode an input
+ * @param in the plaintext
+ * @param in_length length of plaintext in bytes
+ * @param key_length length of the key in bits
+ * @param rng a random number generator
+ * @return encoded plaintext
+ */
+ SecureVector<byte> encode(const byte in[],
+ u32bit in_length,
+ u32bit key_length,
+ RandomNumberGenerator& rng) const;
- SecureVector<byte> decode(const byte[], u32bit, u32bit) const;
- SecureVector<byte> decode(const MemoryRegion<byte>&, u32bit) const;
+ /**
+ * Encode an input
+ * @param in the plaintext
+ * @param key_length length of the key in bits
+ * @param rng a random number generator
+ * @return encoded plaintext
+ */
+ SecureVector<byte> encode(const MemoryRegion<byte>& in,
+ u32bit key_length,
+ RandomNumberGenerator& rng) const;
+
+ /**
+ * Decode an input
+ * @param in the encoded plaintext
+ * @param in_length length of encoded plaintext in bytes
+ * @param key_length length of the key in bits
+ * @return plaintext
+ */
+ SecureVector<byte> decode(const byte in[],
+ u32bit in_length,
+ u32bit key_length) const;
+
+ /**
+ * Decode an input
+ * @param in the encoded plaintext
+ * @param key_length length of the key in bits
+ * @return plaintext
+ */
+ SecureVector<byte> decode(const MemoryRegion<byte>& in,
+ u32bit key_length) const;
virtual ~EME() {}
private:
- virtual SecureVector<byte> pad(const byte[], u32bit, u32bit,
- RandomNumberGenerator&) const = 0;
+ /**
+ * Encode an input
+ * @param in the plaintext
+ * @param in_length length of plaintext in bytes
+ * @param key_length length of the key in bits
+ * @param rng a random number generator
+ * @return encoded plaintext
+ */
+ virtual SecureVector<byte> pad(const byte in[],
+ u32bit in_length,
+ u32bit key_length,
+ RandomNumberGenerator& rng) const = 0;
- virtual SecureVector<byte> unpad(const byte[], u32bit, u32bit) const = 0;
+ /**
+ * Decode an input
+ * @param in the encoded plaintext
+ * @param in_length length of encoded plaintext in bytes
+ * @param key_length length of the key in bits
+ * @return plaintext
+ */
+ virtual SecureVector<byte> unpad(const byte in[],
+ u32bit in_length,
+ u32bit key_length) const = 0;
};
}
diff --git a/src/pk_pad/eme1/eme1.h b/src/pk_pad/eme1/eme1.h
index d00eeeeb9..0ecdb279e 100644
--- a/src/pk_pad/eme1/eme1.h
+++ b/src/pk_pad/eme1/eme1.h
@@ -23,9 +23,8 @@ class BOTAN_DLL EME1 : public EME
u32bit maximum_input_size(u32bit) const;
/**
- EME1 constructor. Hash will be deleted by ~EME1 (when mgf is deleted)
-
- P is an optional label. Normally empty.
+ * @param hash object to use for hashing (takes ownership)
+ * @param P an optional label. Normally empty.
*/
EME1(HashFunction* hash, const std::string& P = "");
diff --git a/src/pk_pad/emsa.h b/src/pk_pad/emsa.h
index 6d01beb7f..372eb836d 100644
--- a/src/pk_pad/emsa.h
+++ b/src/pk_pad/emsa.h
@@ -19,15 +19,39 @@ namespace Botan {
class BOTAN_DLL EMSA
{
public:
- virtual void update(const byte[], u32bit) = 0;
+ /**
+ * Add more data to the signature computation
+ * @param input some data
+ * @param length length of input in bytes
+ */
+ virtual void update(const byte input[], u32bit length) = 0;
+
+ /**
+ * @return raw hash
+ */
virtual SecureVector<byte> raw_data() = 0;
- virtual SecureVector<byte> encoding_of(const MemoryRegion<byte>&,
- u32bit,
+ /**
+ * Return the encoding of a message
+ * @param msg the result of raw_data()
+ * @param output_bits the desired output bit size
+ * @param rng a random number generator
+ * @return encoded signature
+ */
+ virtual SecureVector<byte> encoding_of(const MemoryRegion<byte>& msg,
+ u32bit output_bits,
RandomNumberGenerator& rng) = 0;
- virtual bool verify(const MemoryRegion<byte>&, const MemoryRegion<byte>&,
- u32bit) = 0;
+ /**
+ * Verify the encoding
+ * @param coded the received (coded) message representative
+ * @param raw the computed (local, uncoded) message representative
+ * @param key_bits the size of the key in bits
+ * @return true if coded is a valid encoding of raw, otherwise false
+ */
+ virtual bool verify(const MemoryRegion<byte>& coded,
+ const MemoryRegion<byte>& raw,
+ u32bit key_bits) = 0;
virtual ~EMSA() {}
};
diff --git a/src/pk_pad/emsa1/emsa1.h b/src/pk_pad/emsa1/emsa1.h
index 28d856525..e95414ad3 100644
--- a/src/pk_pad/emsa1/emsa1.h
+++ b/src/pk_pad/emsa1/emsa1.h
@@ -23,6 +23,9 @@ class BOTAN_DLL EMSA1 : public EMSA
EMSA1(HashFunction* h) : hash(h) {}
~EMSA1() { delete hash; }
protected:
+ /**
+ * @return const pointer to the underlying hash
+ */
const HashFunction* hash_ptr() const { return hash; }
private:
void update(const byte[], u32bit);
diff --git a/src/pk_pad/hash_id/hash_id.cpp b/src/pk_pad/hash_id/hash_id.cpp
index 203c27f14..173f02a6d 100644
--- a/src/pk_pad/hash_id/hash_id.cpp
+++ b/src/pk_pad/hash_id/hash_id.cpp
@@ -54,10 +54,8 @@ const byte TIGER_PKCS_ID[] = {
}
-/**
-* @return HashID as specified by PKCS
-* For details see RFC 3447 section 9.2
-* http://tools.ietf.org/html/rfc3447#section-9.2
+/*
+* HashID as specified by PKCS
*/
MemoryVector<byte> pkcs_hash_id(const std::string& name)
{
@@ -94,8 +92,8 @@ MemoryVector<byte> pkcs_hash_id(const std::string& name)
throw Invalid_Argument("No PKCS #1 identifier for " + name);
}
-/**
-* @return HashID as specified by IEEE 1363/X9.31
+/*
+* HashID as specified by IEEE 1363/X9.31
*/
byte ieee1363_hash_id(const std::string& name)
{
diff --git a/src/pk_pad/hash_id/hash_id.h b/src/pk_pad/hash_id/hash_id.h
index 847d9106c..909cc6b19 100644
--- a/src/pk_pad/hash_id/hash_id.h
+++ b/src/pk_pad/hash_id/hash_id.h
@@ -13,11 +13,21 @@
namespace Botan {
-/*
-* Return the values of various defined HashIDs
+/**
+* Return the PKCS #1 hash identifier
+* @see RFC 3447 section 9.2
+* @param hash_name the name of the hash function
+* @return byte sequence identifying the hash
+* @throw Invalid_Argument if the hash has no known PKCS #1 hash id
+*/
+BOTAN_DLL MemoryVector<byte> pkcs_hash_id(const std::string& hash_name);
+
+/**
+* Return the IEEE 1363 hash identifier
+* @param hash_name the name of the hash function
+* @return byte code identifying the hash, or 0 if not known
*/
-BOTAN_DLL MemoryVector<byte> pkcs_hash_id(const std::string&);
-BOTAN_DLL byte ieee1363_hash_id(const std::string&);
+BOTAN_DLL byte ieee1363_hash_id(const std::string& hash_name);
}
diff --git a/src/pubkey/pkcs8.h b/src/pubkey/pkcs8.h
index 3da96d840..376429d5b 100644
--- a/src/pubkey/pkcs8.h
+++ b/src/pubkey/pkcs8.h
@@ -22,6 +22,9 @@ struct BOTAN_DLL PKCS8_Exception : public Decoding_Error
Decoding_Error("PKCS #8: " + error) {}
};
+/**
+* This namespace contains functions for handling PKCS #8 private keys
+*/
namespace PKCS8 {
/**
diff --git a/src/utils/cpuid.h b/src/utils/cpuid.h
index a41e932fb..dbac89455 100644
--- a/src/utils/cpuid.h
+++ b/src/utils/cpuid.h
@@ -18,15 +18,6 @@ namespace Botan {
class BOTAN_DLL CPUID
{
public:
- enum CPUID_bits {
- CPUID_RDTSC_BIT = 4,
- CPUID_SSE2_BIT = 26,
- CPUID_SSSE3_BIT = 41,
- CPUID_SSE41_BIT = 51,
- CPUID_SSE42_BIT = 52,
- CPUID_INTEL_AES_BIT = 57
- };
-
/**
* Return a best guess of the cache line size
*/
@@ -73,6 +64,15 @@ class BOTAN_DLL CPUID
*/
static bool has_altivec();
private:
+ enum CPUID_bits {
+ CPUID_RDTSC_BIT = 4,
+ CPUID_SSE2_BIT = 26,
+ CPUID_SSSE3_BIT = 41,
+ CPUID_SSE41_BIT = 51,
+ CPUID_SSE42_BIT = 52,
+ CPUID_INTEL_AES_BIT = 57
+ };
+
static u64bit x86_processor_flags();
};
generated by cgit v1.2.3 (git 2.39.1) at 2024-12-02 17:32:43 +0000