propagate from branch 'net.randombit.botan' (head 294e2082ce9231d6165276e2f2a4153a0116aca3)

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

15 files changed, 219 insertions, 80 deletions

diff --git a/src/engine/aes_isa_eng/aes_isa_engine.h b/src/engine/aes_isa_eng/aes_isa_engine.h
index 5f22e4105..3c4d3e936 100644
--- a/src/engine/aes_isa_eng/aes_isa_engine.h
+++ b/src/engine/aes_isa_eng/aes_isa_engine.h
@@ -1,4 +1,4 @@
-/**
+/*
 * Engine for AES instructions
 * (C) 2009 Jack Lloyd
 *
@@ -12,11 +12,15 @@
 
 namespace Botan {
 
+/**
+* Engine for implementations that hook into CPU-specific
+* AES implementations (eg AES-NI, VIA C7, or AMD Geode)
+*/
 class AES_ISA_Engine : public Engine
    {
    public:
       std::string provider_name() const { return "aes_isa"; }
-   private:
+
       BlockCipher* find_block_cipher(const SCAN_Name&,
                                      Algorithm_Factory&) const;
    };
diff --git a/src/engine/amd64_eng/amd64_engine.cpp b/src/engine/amd64_eng/amd64_engine.cpp
index 6de1484fb..262bd5809 100644
--- a/src/engine/amd64_eng/amd64_engine.cpp
+++ b/src/engine/amd64_eng/amd64_engine.cpp
@@ -1,4 +1,4 @@
-/**
+/*
 * AMD64 Assembly Implementation Engine
 * (C) 1999-2008 Jack Lloyd
 *
diff --git a/src/engine/amd64_eng/amd64_engine.h b/src/engine/amd64_eng/amd64_engine.h
index dc6f3e993..dc3d4cefc 100644
--- a/src/engine/amd64_eng/amd64_engine.h
+++ b/src/engine/amd64_eng/amd64_engine.h
@@ -1,4 +1,4 @@
-/**
+/*
 * x86-64 Assembly Implementation Engines
 * (C) 1999-2008 Jack Lloyd
 *
@@ -12,11 +12,14 @@
 
 namespace Botan {
 
+/**
+* Engine for implementations that are x86-64 specific
+*/
 class AMD64_Assembler_Engine : public Engine
    {
    public:
       std::string provider_name() const { return "amd64"; }
-   private:
+
       HashFunction* find_hash(const SCAN_Name& reqeust,
                               Algorithm_Factory&) const;
    };
diff --git a/src/engine/def_engine/default_engine.h b/src/engine/def_engine/default_engine.h
index 1e40cfe46..f7e6d9746 100644
--- a/src/engine/def_engine/default_engine.h
+++ b/src/engine/def_engine/default_engine.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * Default Engine
 */
 class Default_Engine : public Engine
@@ -35,12 +35,9 @@ class Default_Engine : public Engine
       Modular_Exponentiator* mod_exp(const BigInt& n,
                                      Power_Mod::Usage_Hints) const;
 
-      virtual bool can_add_algorithms() { return true; }
-
       Keyed_Filter* get_cipher(const std::string&, Cipher_Dir,
                                Algorithm_Factory&);
 
-   private:
       BlockCipher* find_block_cipher(const SCAN_Name&,
                                      Algorithm_Factory&) const;
 
diff --git a/src/engine/def_engine/lookup_hash.cpp b/src/engine/def_engine/lookup_hash.cpp
index 1d96d4f3f..47c6c0a56 100644
--- a/src/engine/def_engine/lookup_hash.cpp
+++ b/src/engine/def_engine/lookup_hash.cpp
@@ -26,10 +26,6 @@
   #include <botan/bmw_512.h>
 #endif
 
-#if defined(BOTAN_HAS_FORK_256)
-  #include <botan/fork256.h>
-#endif
-
 #if defined(BOTAN_HAS_GOST_34_11)
   #include <botan/gost_3411.h>
 #endif
@@ -116,11 +112,6 @@ Default_Engine::find_hash(const SCAN_Name& request,
       return new BMW_512;
 #endif
 
-#if defined(BOTAN_HAS_FORK_256)
-   if(request.algo_name() == "FORK-256")
-      return new FORK_256;
-#endif
-
 #if defined(BOTAN_HAS_GOST_34_11)
    if(request.algo_name() == "GOST-34.11")
       return new GOST_34_11;
diff --git a/src/engine/engine.cpp b/src/engine/engine.cpp
new file mode 100644
index 000000000..958d4148f
--- /dev/null
+++ b/src/engine/engine.cpp
@@ -0,0 +1,84 @@
+/*
+* Engine
+* (C) 2010 Jack Lloyd
+*
+* Distributed under the terms of the Botan license
+*/
+
+#include <botan/engine.h>
+
+namespace Botan {
+
+BlockCipher*
+Engine::find_block_cipher(const SCAN_Name&,
+                          Algorithm_Factory&) const
+   {
+   return 0;
+   }
+
+StreamCipher*
+Engine::find_stream_cipher(const SCAN_Name&,
+                           Algorithm_Factory&) const
+   {
+   return 0;
+   }
+
+HashFunction*
+Engine::find_hash(const SCAN_Name&,
+                  Algorithm_Factory&) const
+   {
+   return 0;
+   }
+
+MessageAuthenticationCode*
+Engine::find_mac(const SCAN_Name&,
+                 Algorithm_Factory&) const
+   {
+   return 0;
+   }
+
+Modular_Exponentiator*
+Engine::mod_exp(const BigInt&,
+                Power_Mod::Usage_Hints) const
+   {
+   return 0;
+   }
+
+Keyed_Filter* Engine::get_cipher(const std::string&,
+                                 Cipher_Dir,
+                                 Algorithm_Factory&)
+   {
+   return 0;
+   }
+
+PK_Ops::Key_Agreement*
+Engine::get_key_agreement_op(const Private_Key&) const
+   {
+   return 0;
+   }
+
+PK_Ops::Signature*
+Engine::get_signature_op(const Private_Key&) const
+   {
+   return 0;
+   }
+
+PK_Ops::Verification*
+Engine::get_verify_op(const Public_Key&) const
+   {
+   return 0;
+   }
+
+PK_Ops::Encryption*
+Engine::get_encryption_op(const Public_Key&) const
+   {
+   return 0;
+   }
+
+PK_Ops::Decryption*
+Engine::get_decryption_op(const Private_Key&) const
+   {
+   return 0;
+   }
+
+}
diff --git a/src/engine/engine.h b/src/engine/engine.h
index 69592886c..c9bcd6126 100644
--- a/src/engine/engine.h
+++ b/src/engine/engine.h
@@ -26,67 +26,117 @@ namespace Botan {
 class Algorithm_Factory;
 class Keyed_Filter;
 
-/*
-* Engine Base Class
+/**
+* Base class for all engines. All non-pure virtual functions simply
+* return NULL, indicating the algorithm in question is not
+* supported. Subclasses can reimplement whichever function(s)
+* they want to hook in a particular type.
 */
 class BOTAN_DLL Engine
    {
    public:
       virtual ~Engine() {}
 
+      /**
+      * @return name of this engine
+      */
       virtual std::string provider_name() const = 0;
 
-      // Lookup functions
+      /**
+      * @param algo_spec the algorithm name/specification
+      * @param af an algorithm factory object
+      * @return newly allocated object, or NULL
+      */
       virtual BlockCipher*
-         find_block_cipher(const SCAN_Name&, Algorithm_Factory&) const
-         { return 0; }
-
+         find_block_cipher(const SCAN_Name& algo_spec,
+                           Algorithm_Factory& af) const;
+
+      /**
+      * @param algo_spec the algorithm name/specification
+      * @param af an algorithm factory object
+      * @return newly allocated object, or NULL
+      */
       virtual StreamCipher*
-         find_stream_cipher(const SCAN_Name&, Algorithm_Factory&) const
-         { return 0; }
-
+         find_stream_cipher(const SCAN_Name& algo_spec,
+                            Algorithm_Factory& af) const;
+
+      /**
+      * @param algo_spec the algorithm name/specification
+      * @param af an algorithm factory object
+      * @return newly allocated object, or NULL
+      */
       virtual HashFunction*
-         find_hash(const SCAN_Name&, Algorithm_Factory&) const
-         { return 0; }
-
+         find_hash(const SCAN_Name& algo_spec,
+                   Algorithm_Factory& af) const;
+
+      /**
+      * @param algo_spec the algorithm name/specification
+      * @param af an algorithm factory object
+      * @return newly allocated object, or NULL
+      */
       virtual MessageAuthenticationCode*
-         find_mac(const SCAN_Name&, Algorithm_Factory&) const
-         { return 0; }
-
+         find_mac(const SCAN_Name& algo_spec,
+                  Algorithm_Factory& af) const;
+
+      /**
+      * @param n the modulus
+      * @param hints any use hints
+      * @return newly allocated object, or NULL
+      */
       virtual Modular_Exponentiator*
-         mod_exp(const BigInt&, Power_Mod::Usage_Hints) const
-         { return 0; }
-
-      virtual Keyed_Filter* get_cipher(const std::string&,
-                                       Cipher_Dir,
-                                       Algorithm_Factory&)
-         { return 0; }
-
+         mod_exp(const BigInt& n,
+                 Power_Mod::Usage_Hints hints) const;
+
+      /**
+      * Return a new cipher object
+      * @param algo_spec the algorithm name/specification
+      * @param dir specifies if encryption or decryption is desired
+      * @param af an algorithm factory object
+      * @return newly allocated object, or NULL
+      */
+      virtual Keyed_Filter* get_cipher(const std::string& algo_spec,
+                                       Cipher_Dir dir,
+                                       Algorithm_Factory& af);
+
+      /**
+      * Return a new operator object for this key, if possible
+      * @param key the key we want an operator for
+      * @return newly allocated operator object, or NULL
+      */
       virtual PK_Ops::Key_Agreement*
-         get_key_agreement_op(const Private_Key&) const
-         {
-         return 0;
-         }
-
-      virtual PK_Ops::Signature* get_signature_op(const Private_Key&) const
-         {
-         return 0;
-         }
-
-      virtual PK_Ops::Verification* get_verify_op(const Public_Key&) const
-         {
-         return 0;
-         }
-
-      virtual PK_Ops::Encryption* get_encryption_op(const Public_Key&) const
-         {
-         return 0;
-         }
-
-      virtual PK_Ops::Decryption* get_decryption_op(const Private_Key&) const
-         {
-         return 0;
-         }
+         get_key_agreement_op(const Private_Key& key) const;
+
+      /**
+      * Return a new operator object for this key, if possible
+      * @param key the key we want an operator for
+      * @return newly allocated operator object, or NULL
+      */
+      virtual PK_Ops::Signature*
+         get_signature_op(const Private_Key& key) const;
+
+      /**
+      * Return a new operator object for this key, if possible
+      * @param key the key we want an operator for
+      * @return newly allocated operator object, or NULL
+      */
+      virtual PK_Ops::Verification*
+         get_verify_op(const Public_Key& key) const;
+
+      /**
+      * Return a new operator object for this key, if possible
+      * @param key the key we want an operator for
+      * @return newly allocated operator object, or NULL
+      */
+      virtual PK_Ops::Encryption*
+         get_encryption_op(const Public_Key& key) const;
+
+      /**
+      * Return a new operator object for this key, if possible
+      * @param key the key we want an operator for
+      * @return newly allocated operator object, or NULL
+      */
+      virtual PK_Ops::Decryption*
+         get_decryption_op(const Private_Key& key) const;
    };
 
 }
diff --git a/src/engine/gnump/gmp_wrap.h b/src/engine/gnump/gmp_wrap.h
index 82437ceba..52d130d6b 100644
--- a/src/engine/gnump/gmp_wrap.h
+++ b/src/engine/gnump/gmp_wrap.h
@@ -13,8 +13,8 @@
 
 namespace Botan {
 
-/*
-* Lightweight GMP mpz_t Wrapper
+/**
+* Lightweight GMP mpz_t wrapper. For internal use only.
 */
 class GMP_MPZ
    {
diff --git a/src/engine/gnump/gnump_engine.h b/src/engine/gnump/gnump_engine.h
index 1ca5a3548..fe154b914 100644
--- a/src/engine/gnump/gnump_engine.h
+++ b/src/engine/gnump/gnump_engine.h
@@ -12,8 +12,8 @@
 
 namespace Botan {
 
-/*
-* GMP Engine
+/**
+* Engine using GNU MP
 */
 class GMP_Engine : public Engine
    {
diff --git a/src/engine/ia32_eng/ia32_engine.h b/src/engine/ia32_eng/ia32_engine.h
index 517b88aa8..6e0a8a5f4 100644
--- a/src/engine/ia32_eng/ia32_engine.h
+++ b/src/engine/ia32_eng/ia32_engine.h
@@ -1,4 +1,4 @@
-/**
+/*
 * IA-32 Assembly Implementation Engines
 * (C) 1999-2008 Jack Lloyd
 *
@@ -12,11 +12,14 @@
 
 namespace Botan {
 
+/**
+* Engine for x86-32 specific implementations
+*/
 class IA32_Assembler_Engine : public Engine
    {
    public:
       std::string provider_name() const { return "ia32"; }
-   private:
+
       BlockCipher* find_block_cipher(const SCAN_Name&,
                                      Algorithm_Factory&) const;
 
diff --git a/src/engine/info.txt b/src/engine/info.txt
index 32fcf21c2..5f787cebe 100644
--- a/src/engine/info.txt
+++ b/src/engine/info.txt
@@ -4,6 +4,10 @@ define ENGINES
 engine.h
 </header:public>
 
+<source>
+engine.cpp
+</source>
+
 <requires>
 block
 hash
diff --git a/src/engine/openssl/bn_wrap.h b/src/engine/openssl/bn_wrap.h
index 02a229fdd..372f5a329 100644
--- a/src/engine/openssl/bn_wrap.h
+++ b/src/engine/openssl/bn_wrap.h
@@ -13,8 +13,8 @@
 
 namespace Botan {
 
-/*
-* Lightweight OpenSSL BN Wrapper
+/**
+* Lightweight OpenSSL BN wrapper. For internal use only.
 */
 class OSSL_BN
    {
@@ -36,8 +36,8 @@ class OSSL_BN
       ~OSSL_BN();
    };
 
-/*
-* Lightweight OpenSSL BN_CTX Wrapper
+/**
+* Lightweight OpenSSL BN_CTX wrapper. For internal use only.
 */
 class OSSL_BN_CTX
    {
diff --git a/src/engine/openssl/openssl_engine.h b/src/engine/openssl/openssl_engine.h
index 1ee7e4c11..b1f71a160 100644
--- a/src/engine/openssl/openssl_engine.h
+++ b/src/engine/openssl/openssl_engine.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * OpenSSL Engine
 */
 class OpenSSL_Engine : public Engine
@@ -37,7 +37,7 @@ class OpenSSL_Engine : public Engine
 
       Modular_Exponentiator* mod_exp(const BigInt&,
                                      Power_Mod::Usage_Hints) const;
-   private:
+
       BlockCipher* find_block_cipher(const SCAN_Name&,
                                      Algorithm_Factory&) const;
 
diff --git a/src/engine/simd_engine/simd_engine.cpp b/src/engine/simd_engine/simd_engine.cpp
index e889ca161..aa434d669 100644
--- a/src/engine/simd_engine/simd_engine.cpp
+++ b/src/engine/simd_engine/simd_engine.cpp
@@ -1,4 +1,4 @@
-/**
+/*
 * SIMD Engine
 * (C) 1999-2009 Jack Lloyd
 *
diff --git a/src/engine/simd_engine/simd_engine.h b/src/engine/simd_engine/simd_engine.h
index 722b5529b..73f7d2233 100644
--- a/src/engine/simd_engine/simd_engine.h
+++ b/src/engine/simd_engine/simd_engine.h
@@ -1,4 +1,4 @@
-/**
+/*
 * SIMD Assembly Engine
 * (C) 1999-2009 Jack Lloyd
 *
@@ -12,11 +12,14 @@
 
 namespace Botan {
 
+/**
+* Engine for implementations that use some kind of SIMD
+*/
 class SIMD_Engine : public Engine
    {
    public:
       std::string provider_name() const { return "simd"; }
-   private:
+
       BlockCipher* find_block_cipher(const SCAN_Name&,
                                      Algorithm_Factory&) const;