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

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

1 files changed, 97 insertions, 47 deletions

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;
    };
 
 }