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

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

26 files changed, 309 insertions, 208 deletions

diff --git a/src/pubkey/blinding.h b/src/pubkey/blinding.h
index 03c9043dd..712030e4d 100644
--- a/src/pubkey/blinding.h
+++ b/src/pubkey/blinding.h
@@ -13,7 +13,7 @@
 
 namespace Botan {
 
-/*
+/**
 * Blinding Function Object
 */
 class BOTAN_DLL Blinder
diff --git a/src/pubkey/dh/dh.h b/src/pubkey/dh/dh.h
index 738b3f9c4..88b57922d 100644
--- a/src/pubkey/dh/dh.h
+++ b/src/pubkey/dh/dh.h
@@ -56,7 +56,7 @@ class BOTAN_DLL DH_PrivateKey : public DH_PublicKey,
       * Load a DH private key
       * @param alg_id the algorithm id
       * @param key_bits the subject public key
-      * @rng a random number generator
+      * @param rng a random number generator
       */
       DH_PrivateKey(const AlgorithmIdentifier& alg_id,
                     const MemoryRegion<byte>& key_bits,
diff --git a/src/pubkey/dl_algo/dl_algo.h b/src/pubkey/dl_algo/dl_algo.h
index 445f6c3f9..429bfb554 100644
--- a/src/pubkey/dl_algo/dl_algo.h
+++ b/src/pubkey/dl_algo/dl_algo.h
@@ -28,7 +28,7 @@ class BOTAN_DLL DL_Scheme_PublicKey : public virtual Public_Key
 
       /**
       * Get the DL domain parameters of this key.
-      * @return the DL domain parameters of this key
+      * @return DL domain parameters of this key
       */
       const DL_Group& get_domain() const { return group; }
 
@@ -39,25 +39,25 @@ class BOTAN_DLL DL_Scheme_PublicKey : public virtual Public_Key
 
       /**
       * Get the prime p of the underlying DL group.
-      * @return the prime p
+      * @return prime p
       */
       const BigInt& group_p() const { return group.get_p(); }
 
       /**
       * Get the prime q of the underlying DL group.
-      * @return the prime q
+      * @return prime q
       */
       const BigInt& group_q() const { return group.get_q(); }
 
       /**
       * Get the generator g of the underlying DL group.
-      * @return the generator g
+      * @return generator g
       */
       const BigInt& group_g() const { return group.get_g(); }
 
       /**
       * Get the underlying groups encoding format.
-      * @return the encoding format
+      * @return encoding format
       */
       virtual DL_Group::Format group_format() const = 0;
 
@@ -82,7 +82,7 @@ class BOTAN_DLL DL_Scheme_PrivateKey : public virtual DL_Scheme_PublicKey,
 
       /**
       * Get the secret key x.
-      * @return the secret key
+      * @return secret key
       */
       const BigInt& get_x() const { return x; }
 
diff --git a/src/pubkey/dl_group/dl_group.cpp b/src/pubkey/dl_group/dl_group.cpp
index 22c72480e..cd75e5796 100644
--- a/src/pubkey/dl_group/dl_group.cpp
+++ b/src/pubkey/dl_group/dl_group.cpp
@@ -55,31 +55,32 @@ DL_Group::DL_Group(RandomNumberGenerator& rng,
       q = (p - 1) / 2;
       g = 2;
       }
-   else if(type == Prime_Subgroup || type == DSA_Kosherizer)
+   else if(type == Prime_Subgroup)
       {
-      if(type == Prime_Subgroup)
-         {
-         if(!qbits)
-            qbits = 2 * dl_work_factor(pbits);
-
-         q = random_prime(rng, qbits);
-         BigInt X;
-         while(p.bits() != pbits || !check_prime(p, rng))
-            {
-            X.randomize(rng, pbits);
-            p = X - (X % (2*q) - 1);
-            }
-         }
-      else
+      if(!qbits)
+         qbits = 2 * dl_work_factor(pbits);
+
+      q = random_prime(rng, qbits);
+      BigInt X;
+      while(p.bits() != pbits || !check_prime(p, rng))
          {
-         qbits = qbits ? qbits : ((pbits == 1024) ? 160 : 256);
-         generate_dsa_primes(rng,
-                             global_state().algorithm_factory(),
-                             p, q, pbits, qbits);
+         X.randomize(rng, pbits);
+         p = X - (X % (2*q) - 1);
          }
 
       g = make_dsa_generator(p, q);
       }
+   else if(type == DSA_Kosherizer)
+      {
+      qbits = qbits ? qbits : ((pbits <= 1024) ? 160 : 256);
+
+      generate_dsa_primes(rng,
+                          global_state().algorithm_factory(),
+                          p, q,
+                          pbits, qbits);
+
+      g = make_dsa_generator(p, q);
+      }
 
    initialized = true;
    }
diff --git a/src/pubkey/dl_group/dl_group.h b/src/pubkey/dl_group/dl_group.h
index a84a85f87..885ccd2f9 100644
--- a/src/pubkey/dl_group/dl_group.h
+++ b/src/pubkey/dl_group/dl_group.h
@@ -22,19 +22,19 @@ class BOTAN_DLL DL_Group
    public:
       /**
       * Get the prime p.
-      * @return the prime p
+      * @return prime p
       */
       const BigInt& get_p() const;
 
       /**
       * Get the prime q.
-      * @return the prime q
+      * @return prime q
       */
       const BigInt& get_q() const;
 
       /**
       * Get the base g.
-      * @return the base g
+      * @return base g
       */
       const BigInt& get_g() const;
 
@@ -68,14 +68,14 @@ class BOTAN_DLL DL_Group
       /**
       * Encode this group into a string using PEM encoding.
       * @param format the encoding format
-      * @return the string holding the PEM encoded group
+      * @return string holding the PEM encoded group
       */
       std::string PEM_encode(Format format) const;
 
       /**
       * Encode this group into a string using DER encoding.
       * @param format the encoding format
-      * @return the string holding the DER encoded group
+      * @return string holding the DER encoded group
       */
       SecureVector<byte> DER_encode(Format format) const;
 
diff --git a/src/pubkey/dlies/dlies.h b/src/pubkey/dlies/dlies.h
index fd2cefe4a..ad8f36b40 100644
--- a/src/pubkey/dlies/dlies.h
+++ b/src/pubkey/dlies/dlies.h
@@ -14,7 +14,7 @@
 
 namespace Botan {
 
-/*
+/**
 * DLIES Encryption
 */
 class BOTAN_DLL DLIES_Encryptor : public PK_Encryptor
@@ -41,7 +41,7 @@ class BOTAN_DLL DLIES_Encryptor : public PK_Encryptor
       u32bit mac_keylen;
    };
 
-/*
+/**
 * DLIES Decryption
 */
 class BOTAN_DLL DLIES_Decryptor : public PK_Decryptor
diff --git a/src/pubkey/dsa/dsa.h b/src/pubkey/dsa/dsa.h
index 8121cfbbc..65b6edd98 100644
--- a/src/pubkey/dsa/dsa.h
+++ b/src/pubkey/dsa/dsa.h
@@ -15,7 +15,7 @@
 
 namespace Botan {
 
-/*
+/**
 * DSA Public Key
 */
 class BOTAN_DLL DSA_PublicKey : public virtual DL_Scheme_PublicKey
@@ -39,7 +39,7 @@ class BOTAN_DLL DSA_PublicKey : public virtual DL_Scheme_PublicKey
       DSA_PublicKey() {}
    };
 
-/*
+/**
 * DSA Private Key
 */
 class BOTAN_DLL DSA_PrivateKey : public DSA_PublicKey,
@@ -57,6 +57,9 @@ class BOTAN_DLL DSA_PrivateKey : public DSA_PublicKey,
       bool check_key(RandomNumberGenerator& rng, bool strong) const;
    };
 
+/**
+* Object that can create a DSA signature
+*/
 class BOTAN_DLL DSA_Signature_Operation : public PK_Ops::Signature
    {
    public:
@@ -75,6 +78,9 @@ class BOTAN_DLL DSA_Signature_Operation : public PK_Ops::Signature
       Modular_Reducer mod_q;
    };
 
+/**
+* Object that can verify a DSA signature
+*/
 class BOTAN_DLL DSA_Verification_Operation : public PK_Ops::Verification
    {
    public:
diff --git a/src/pubkey/ec_dompar/ec_dompar.h b/src/pubkey/ec_dompar/ec_dompar.h
index 15143373a..546624bf6 100644
--- a/src/pubkey/ec_dompar/ec_dompar.h
+++ b/src/pubkey/ec_dompar/ec_dompar.h
@@ -25,6 +25,9 @@ enum EC_Domain_Params_Encoding {
    EC_DOMPAR_ENC_OID = 2
 };
 
+/**
+* Class representing an elliptic curve
+*/
 class BOTAN_DLL EC_Domain_Params
    {
    public:
diff --git a/src/pubkey/ecc_key/ecc_key.cpp b/src/pubkey/ecc_key/ecc_key.cpp
index 2c66dc97f..4f90fa321 100644
--- a/src/pubkey/ecc_key/ecc_key.cpp
+++ b/src/pubkey/ecc_key/ecc_key.cpp
@@ -24,9 +24,6 @@ EC_PublicKey::EC_PublicKey(const EC_Domain_Params& dom_par,
    {
    if(domain().get_curve() != public_point().get_curve())
       throw Invalid_Argument("EC_PublicKey: curve mismatch in constructor");
-
-   if(!public_point().on_the_curve())
-      throw Invalid_State("Public key was not on the curve");
    }
 
 EC_PublicKey::EC_PublicKey(const AlgorithmIdentifier& alg_id,
@@ -38,6 +35,12 @@ EC_PublicKey::EC_PublicKey(const AlgorithmIdentifier& alg_id,
    public_key = OS2ECP(key_bits, domain().get_curve());
    }
 
+bool EC_PublicKey::check_key(RandomNumberGenerator&,
+                             bool) const
+   {
+   return public_point().on_the_curve();
+   }
+
 AlgorithmIdentifier EC_PublicKey::algorithm_identifier() const
    {
    return AlgorithmIdentifier(get_oid(), DER_domain());
diff --git a/src/pubkey/ecc_key/ecc_key.h b/src/pubkey/ecc_key/ecc_key.h
index 92f02613c..8155543da 100644
--- a/src/pubkey/ecc_key/ecc_key.h
+++ b/src/pubkey/ecc_key/ecc_key.h
@@ -49,6 +49,9 @@ class BOTAN_DLL EC_PublicKey : public virtual Public_Key
 
       MemoryVector<byte> x509_subject_public_key() const;
 
+      bool check_key(RandomNumberGenerator& rng,
+                     bool strong) const;
+
       /**
       * Get the domain parameters of this key.
       * @throw Invalid_State is thrown if the
diff --git a/src/pubkey/ecdh/ecdh.h b/src/pubkey/ecdh/ecdh.h
index 19621f2ca..f0872c5cc 100644
--- a/src/pubkey/ecdh/ecdh.h
+++ b/src/pubkey/ecdh/ecdh.h
@@ -46,12 +46,12 @@ class BOTAN_DLL ECDH_PublicKey : public virtual EC_PublicKey
       * Get the maximum number of bits allowed to be fed to this key.
       * This is the bitlength of the order of the base point.
 
-      * @return the maximum number of input bits
+      * @return maximum number of input bits
       */
       u32bit max_input_bits() const { return domain().get_order().bits(); }
 
       /**
-      * @return the public point value
+      * @return public point value
       */
       MemoryVector<byte> public_value() const
          { return EC2OSP(public_point(), PointGFp::UNCOMPRESSED); }
@@ -75,7 +75,8 @@ class BOTAN_DLL ECDH_PrivateKey : public ECDH_PublicKey,
 
       /**
       * Generate a new private key
-      * @param the domain parameters to used for this key
+      * @param rng a random number generator
+      * @param domain parameters to used for this key
       */
       ECDH_PrivateKey(RandomNumberGenerator& rng,
                       const EC_Domain_Params& domain) :
diff --git a/src/pubkey/ecdsa/ecdsa.h b/src/pubkey/ecdsa/ecdsa.h
index 62bd007f9..7e7d85ab8 100644
--- a/src/pubkey/ecdsa/ecdsa.h
+++ b/src/pubkey/ecdsa/ecdsa.h
@@ -72,7 +72,8 @@ class BOTAN_DLL ECDSA_PrivateKey : public ECDSA_PublicKey,
 
       /**
       * Generate a new private key
-      * @param the domain parameters to used for this key
+      * @param rng a random number generator
+      * @param domain parameters to used for this key
       */
       ECDSA_PrivateKey(RandomNumberGenerator& rng,
                        const EC_Domain_Params& domain) :
@@ -83,12 +84,16 @@ class BOTAN_DLL ECDSA_PrivateKey : public ECDSA_PublicKey,
       * @param domain parameters
       * @param x the private key
       */
-      ECDSA_PrivateKey(const EC_Domain_Params& domain, const BigInt& x) :
+      ECDSA_PrivateKey(const EC_Domain_Params& domain,
+                       const BigInt& x) :
          EC_PrivateKey(domain, x) {}
 
       bool check_key(RandomNumberGenerator& rng, bool) const;
    };
 
+/**
+* ECDSA signature operation
+*/
 class BOTAN_DLL ECDSA_Signature_Operation : public PK_Ops::Signature
    {
    public:
@@ -108,6 +113,9 @@ class BOTAN_DLL ECDSA_Signature_Operation : public PK_Ops::Signature
       Modular_Reducer mod_order;
    };
 
+/**
+* ECDSA verification operation
+*/
 class BOTAN_DLL ECDSA_Verification_Operation : public PK_Ops::Verification
    {
    public:
diff --git a/src/pubkey/elgamal/elgamal.h b/src/pubkey/elgamal/elgamal.h
index 143b417ec..f9b52c7b8 100644
--- a/src/pubkey/elgamal/elgamal.h
+++ b/src/pubkey/elgamal/elgamal.h
@@ -16,7 +16,7 @@
 
 namespace Botan {
 
-/*
+/**
 * ElGamal Public Key
 */
 class BOTAN_DLL ElGamal_PublicKey : public virtual DL_Scheme_PublicKey
@@ -37,7 +37,7 @@ class BOTAN_DLL ElGamal_PublicKey : public virtual DL_Scheme_PublicKey
       ElGamal_PublicKey() {}
    };
 
-/*
+/**
 * ElGamal Private Key
 */
 class BOTAN_DLL ElGamal_PrivateKey : public ElGamal_PublicKey,
@@ -55,6 +55,9 @@ class BOTAN_DLL ElGamal_PrivateKey : public ElGamal_PublicKey,
                          const BigInt& priv_key = 0);
    };
 
+/**
+* ElGamal encryption operation
+*/
 class BOTAN_DLL ElGamal_Encryption_Operation : public PK_Ops::Encryption
    {
    public:
@@ -70,6 +73,9 @@ class BOTAN_DLL ElGamal_Encryption_Operation : public PK_Ops::Encryption
       Modular_Reducer mod_p;
    };
 
+/**
+* ElGamal decryption operation
+*/
 class BOTAN_DLL ElGamal_Decryption_Operation : public PK_Ops::Decryption
    {
    public:
diff --git a/src/pubkey/gost_3410/gost_3410.h b/src/pubkey/gost_3410/gost_3410.h
index 36fa2912d..9d6a15386 100644
--- a/src/pubkey/gost_3410/gost_3410.h
+++ b/src/pubkey/gost_3410/gost_3410.h
@@ -16,7 +16,7 @@
 namespace Botan {
 
 /**
-* This class represents GOST_3410 Public Keys.
+* GOST-34.10 Public Key
 */
 class BOTAN_DLL GOST_3410_PublicKey : public virtual EC_PublicKey
    {
@@ -65,7 +65,7 @@ class BOTAN_DLL GOST_3410_PublicKey : public virtual EC_PublicKey
    };
 
 /**
-* This class represents GOST_3410 Private Keys
+* GOST-34.10 Private Key
 */
 class BOTAN_DLL GOST_3410_PrivateKey : public GOST_3410_PublicKey,
                                        public EC_PrivateKey
@@ -78,7 +78,8 @@ class BOTAN_DLL GOST_3410_PrivateKey : public GOST_3410_PublicKey,
 
       /**
       * Generate a new private key
-      * @param the domain parameters to used for this key
+      * @param rng a random number generator
+      * @param domain parameters to used for this key
       */
       GOST_3410_PrivateKey(RandomNumberGenerator& rng,
                            const EC_Domain_Params& domain) :
@@ -96,6 +97,9 @@ class BOTAN_DLL GOST_3410_PrivateKey : public GOST_3410_PublicKey,
          { return EC_PublicKey::algorithm_identifier(); }
    };
 
+/**
+* GOST-34.10 signature operation
+*/
 class BOTAN_DLL GOST_3410_Signature_Operation : public PK_Ops::Signature
    {
    public:
@@ -114,6 +118,9 @@ class BOTAN_DLL GOST_3410_Signature_Operation : public PK_Ops::Signature
       const BigInt& x;
    };
 
+/**
+* GOST-34.10 verification operation
+*/
 class BOTAN_DLL GOST_3410_Verification_Operation : public PK_Ops::Verification
    {
    public:
diff --git a/src/pubkey/if_algo/if_algo.h b/src/pubkey/if_algo/if_algo.h
index 764a99e13..d0a1ec197 100644
--- a/src/pubkey/if_algo/if_algo.h
+++ b/src/pubkey/if_algo/if_algo.h
@@ -34,12 +34,12 @@ class BOTAN_DLL IF_Scheme_PublicKey : public virtual Public_Key
       MemoryVector<byte> x509_subject_public_key() const;
 
       /**
-      * @return the public modulus
+      * @return public modulus
       */
       const BigInt& get_n() const { return n; }
 
       /**
-      * @return the public exponent
+      * @return public exponent
       */
       const BigInt& get_e() const { return e; }
 
@@ -73,13 +73,13 @@ class BOTAN_DLL IF_Scheme_PrivateKey : public virtual IF_Scheme_PublicKey,
 
       /**
       * Get the first prime p.
-      * @return the prime p
+      * @return prime p
       */
       const BigInt& get_p() const { return p; }
 
       /**
       * Get the second prime q.
-      * @return the prime q
+      * @return prime q
       */
       const BigInt& get_q() const { return q; }
 
diff --git a/src/pubkey/nr/nr.h b/src/pubkey/nr/nr.h
index bd125ab92..cd12001ad 100644
--- a/src/pubkey/nr/nr.h
+++ b/src/pubkey/nr/nr.h
@@ -15,7 +15,7 @@
 
 namespace Botan {
 
-/*
+/**
 * Nyberg-Rueppel Public Key
 */
 class BOTAN_DLL NR_PublicKey : public virtual DL_Scheme_PublicKey
@@ -37,7 +37,7 @@ class BOTAN_DLL NR_PublicKey : public virtual DL_Scheme_PublicKey
       NR_PublicKey() {}
    };
 
-/*
+/**
 * Nyberg-Rueppel Private Key
 */
 class BOTAN_DLL NR_PrivateKey : public NR_PublicKey,
@@ -55,6 +55,9 @@ class BOTAN_DLL NR_PrivateKey : public NR_PublicKey,
                     const BigInt& x = 0);
    };
 
+/**
+* Nyberg-Rueppel signature operation
+*/
 class BOTAN_DLL NR_Signature_Operation : public PK_Ops::Signature
    {
    public:
@@ -73,6 +76,9 @@ class BOTAN_DLL NR_Signature_Operation : public PK_Ops::Signature
       Modular_Reducer mod_q;
    };
 
+/**
+* Nyberg-Rueppel verification operation
+*/
 class BOTAN_DLL NR_Verification_Operation : public PK_Ops::Verification
    {
    public:
diff --git a/src/pubkey/pk_keys.cpp b/src/pubkey/pk_keys.cpp
index b93158558..c19c676ab 100644
--- a/src/pubkey/pk_keys.cpp
+++ b/src/pubkey/pk_keys.cpp
@@ -6,6 +6,7 @@
 */
 
 #include <botan/pk_keys.h>
+#include <botan/der_enc.h>
 #include <botan/oids.h>
 
 namespace Botan {
diff --git a/src/pubkey/pk_keys.h b/src/pubkey/pk_keys.h
index da73db0ee..8f086c617 100644
--- a/src/pubkey/pk_keys.h
+++ b/src/pubkey/pk_keys.h
@@ -23,13 +23,13 @@ class BOTAN_DLL Public_Key
    public:
       /**
       * Get the name of the underlying public key scheme.
-      * @return the name of the public key scheme
+      * @return name of the public key scheme
       */
       virtual std::string algo_name() const = 0;
 
       /**
       * Get the OID of the underlying public key scheme.
-      * @return the OID of the public key scheme
+      * @return OID of the public key scheme
       */
       virtual OID get_oid() const;
 
@@ -40,24 +40,24 @@ class BOTAN_DLL Public_Key
       * of the test
       * @return true if the test is passed
       */
-      virtual bool check_key(RandomNumberGenerator&, bool) const
-         { return true; }
+      virtual bool check_key(RandomNumberGenerator& rng,
+                             bool strong) const = 0;
 
       /**
       * Find out the number of message parts supported by this scheme.
-      * @return the number of message parts
+      * @return number of message parts
       */
       virtual u32bit message_parts() const { return 1; }
 
       /**
       * Find out the message part size supported by this scheme/key.
-      * @return the size of the message parts
+      * @return size of the message parts in bits
       */
       virtual u32bit message_part_size() const { return 0; }
 
       /**
       * Get the maximum message size in bits supported by this public key.
-      * @return the maximum message in bits
+      * @return maximum message size in bits
       */
       virtual u32bit max_input_bits() const = 0;
 
@@ -73,7 +73,11 @@ class BOTAN_DLL Public_Key
 
       virtual ~Public_Key() {}
    protected:
-      virtual void load_check(RandomNumberGenerator&) const;
+      /**
+      * Self-test after loading a key
+      * @param rng a random number generator
+      */
+      virtual void load_check(RandomNumberGenerator& rng) const;
    };
 
 /**
@@ -95,8 +99,17 @@ class BOTAN_DLL Private_Key : public virtual Public_Key
          { return algorithm_identifier(); }
 
    protected:
-      void load_check(RandomNumberGenerator&) const;
-      void gen_check(RandomNumberGenerator&) const;
+      /**
+      * Self-test after loading a key
+      * @param rng a random number generator
+      */
+      void load_check(RandomNumberGenerator& rng) const;
+
+      /**
+      * Self-test after generating a key
+      * @param rng a random number generator
+      */
+      void gen_check(RandomNumberGenerator& rng) const;
    };
 
 /**
@@ -105,6 +118,9 @@ class BOTAN_DLL Private_Key : public virtual Public_Key
 class BOTAN_DLL PK_Key_Agreement_Key : public virtual Private_Key
    {
    public:
+      /*
+      * @return public component of this key
+      */
       virtual MemoryVector<byte> public_value() const = 0;
 
       virtual ~PK_Key_Agreement_Key() {}
diff --git a/src/pubkey/pk_ops.h b/src/pubkey/pk_ops.h
index 97ba372c2..b15a8d8cd 100644
--- a/src/pubkey/pk_ops.h
+++ b/src/pubkey/pk_ops.h
@@ -15,6 +15,9 @@ namespace Botan {
 
 namespace PK_Ops {
 
+/**
+* Public key encryption interface
+*/
 class BOTAN_DLL Encryption
    {
    public:
@@ -26,6 +29,9 @@ class BOTAN_DLL Encryption
       virtual ~Encryption() {}
    };
 
+/**
+* Public key decryption interface
+*/
 class BOTAN_DLL Decryption
    {
    public:
@@ -37,24 +43,27 @@ class BOTAN_DLL Decryption
       virtual ~Decryption() {}
    };
 
+/**
+* Public key signature creation interface
+*/
 class BOTAN_DLL Signature
    {
    public:
       /**
       * Find out the number of message parts supported by this scheme.
-      * @return the number of message parts
+      * @return number of message parts
       */
       virtual u32bit message_parts() const { return 1; }
 
       /**
       * Find out the message part size supported by this scheme/key.
-      * @return the size of the message parts
+      * @return size of the message parts
       */
       virtual u32bit message_part_size() const { return 0; }
 
       /**
       * Get the maximum message size in bits supported by this public key.
-      * @return the maximum message in bits
+      * @return maximum message in bits
       */
       virtual u32bit max_input_bits() const = 0;
 
@@ -70,24 +79,27 @@ class BOTAN_DLL Signature
       virtual ~Signature() {}
    };
 
+/**
+* Public key signature verification interface
+*/
 class BOTAN_DLL Verification
    {
    public:
       /**
       * Get the maximum message size in bits supported by this public key.
-      * @return the maximum message in bits
+      * @return maximum message in bits
       */
       virtual u32bit max_input_bits() const = 0;
 
       /**
       * Find out the number of message parts supported by this scheme.
-      * @return the number of message parts
+      * @return number of message parts
       */
       virtual u32bit message_parts() const { return 1; }
 
       /**
       * Find out the message part size supported by this scheme/key.
-      * @return the size of the message parts
+      * @return size of the message parts
       */
       virtual u32bit message_part_size() const { return 0; }
 
@@ -127,8 +139,8 @@ class BOTAN_DLL Verification
       virtual ~Verification() {}
    };
 
-/*
-* A generic Key Agreement Operation (eg DH or ECDH)
+/**
+* A generic key agreement Operation (eg DH or ECDH)
 */
 class BOTAN_DLL Key_Agreement
    {
diff --git a/src/pubkey/pkcs8.cpp b/src/pubkey/pkcs8.cpp
index 7353be42f..7d9c0d834 100644
--- a/src/pubkey/pkcs8.cpp
+++ b/src/pubkey/pkcs8.cpp
@@ -129,43 +129,39 @@ SecureVector<byte> PKCS8_decode(DataSource& source, const User_Interface& ui,
 }
 
 /*
-* DER or PEM encode a PKCS #8 private key
+* BER encode a PKCS #8 private key, unencrypted
 */
-void encode(const Private_Key& key, Pipe& pipe, X509_Encoding encoding)
+SecureVector<byte> BER_encode(const Private_Key& key)
    {
    const u32bit PKCS8_VERSION = 0;
 
-   SecureVector<byte> contents =
-      DER_Encoder()
+   return DER_Encoder()
          .start_cons(SEQUENCE)
             .encode(PKCS8_VERSION)
             .encode(key.pkcs8_algorithm_identifier())
             .encode(key.pkcs8_private_key(), OCTET_STRING)
          .end_cons()
       .get_contents();
+   }
 
-   if(encoding == PEM)
-      pipe.write(PEM_Code::encode(contents, "PRIVATE KEY"));
-   else
-      pipe.write(contents);
+/*
+* PEM encode a PKCS #8 private key, unencrypted
+*/
+std::string PEM_encode(const Private_Key& key)
+   {
+   return PEM_Code::encode(PKCS8::BER_encode(key), "PRIVATE KEY");
    }
 
 /*
-* Encode and encrypt a PKCS #8 private key
+* BER encode a PKCS #8 private key, encrypted
 */
-void encrypt_key(const Private_Key& key,
-                 Pipe& pipe,
-                 RandomNumberGenerator& rng,
-                 const std::string& pass, const std::string& pbe_algo,
-                 X509_Encoding encoding)
+SecureVector<byte> BER_encode(const Private_Key& key,
+                              RandomNumberGenerator& rng,
+                              const std::string& pass,
+                              const std::string& pbe_algo)
    {
    const std::string DEFAULT_PBE = "PBE-PKCS5v20(SHA-1,AES-128/CBC)";
 
-   Pipe raw_key;
-   raw_key.start_msg();
-   encode(key, raw_key, RAW_BER);
-   raw_key.end_msg();
-
    std::unique_ptr<PBE> pbe(get_pbe(((pbe_algo != "") ? pbe_algo : DEFAULT_PBE)));
 
    pbe->new_params(rng);
@@ -174,36 +170,18 @@ void encrypt_key(const Private_Key& key,
    AlgorithmIdentifier pbe_algid(pbe->get_oid(), pbe->encode_params());
 
    Pipe key_encrytor(pbe.release());
-   key_encrytor.process_msg(raw_key);
+   key_encrytor.process_msg(PKCS8::BER_encode(key));
 
-   SecureVector<byte> enc_key =
-      DER_Encoder()
+   return DER_Encoder()
          .start_cons(SEQUENCE)
             .encode(pbe_algid)
             .encode(key_encrytor.read_all(), OCTET_STRING)
          .end_cons()
       .get_contents();
-
-   if(encoding == PEM)
-      pipe.write(PEM_Code::encode(enc_key, "ENCRYPTED PRIVATE KEY"));
-   else
-      pipe.write(enc_key);
    }
 
 /*
-* PEM encode a PKCS #8 private key
-*/
-std::string PEM_encode(const Private_Key& key)
-   {
-   Pipe pem;
-   pem.start_msg();
-   encode(key, pem, PEM);
-   pem.end_msg();
-   return pem.read_all_as_string();
-   }
-
-/*
-* Encrypt and PEM encode a PKCS #8 private key
+* PEM encode a PKCS #8 private key, encrypted
 */
 std::string PEM_encode(const Private_Key& key,
                        RandomNumberGenerator& rng,
@@ -213,11 +191,8 @@ std::string PEM_encode(const Private_Key& key,
    if(pass == "")
       return PEM_encode(key);
 
-   Pipe pem;
-   pem.start_msg();
-   encrypt_key(key, pem, rng, pass, pbe_algo, PEM);
-   pem.end_msg();
-   return pem.read_all_as_string();
+   return PEM_Code::encode(PKCS8::BER_encode(key, rng, pass, pbe_algo),
+                           "ENCRYPTED PRIVATE KEY");
    }
 
 /*
@@ -275,13 +250,7 @@ Private_Key* load_key(const std::string& fsname,
 Private_Key* copy_key(const Private_Key& key,
                       RandomNumberGenerator& rng)
    {
-   Pipe bits;
-
-   bits.start_msg();
-   PKCS8::encode(key, bits);
-   bits.end_msg();
-
-   DataSource_Memory source(bits.read_all());
+   DataSource_Memory source(PEM_encode(key));
    return PKCS8::load_key(source, rng);
    }
 
diff --git a/src/pubkey/pkcs8.h b/src/pubkey/pkcs8.h
index 920f8c24a..3da96d840 100644
--- a/src/pubkey/pkcs8.h
+++ b/src/pubkey/pkcs8.h
@@ -25,38 +25,33 @@ struct BOTAN_DLL PKCS8_Exception : public Decoding_Error
 namespace PKCS8 {
 
 /**
-* Encode a private key into a pipe.
+* BER encode a private key
 * @param key the private key to encode
-* @param pipe the pipe to feed the encoded key into
-* @param enc the encoding type to use
+* @return BER encoded key
 */
-BOTAN_DLL void encode(const Private_Key& key, Pipe& pipe,
-                      X509_Encoding enc = PEM);
+BOTAN_DLL SecureVector<byte> BER_encode(const Private_Key& key);
 
 /**
-* Encode and encrypt a private key into a pipe.
-* @param key the private key to encode
-* @param pipe the pipe to feed the encoded key into
-* @param pass the password to use for encryption
-* @param rng the rng to use
-* @param pbe_algo the name of the desired password-based encryption algorithm;
-         if empty ("") a reasonable (portable/secure) default will be chosen.
-* @param enc the encoding type to use
+* Get a string containing a PEM encoded private key.
+* @param key the key to encode
+* @return encoded key
 */
-BOTAN_DLL void encrypt_key(const Private_Key& key,
-                           Pipe& pipe,
-                           RandomNumberGenerator& rng,
-                           const std::string& pass,
-                           const std::string& pbe_algo = "",
-                           X509_Encoding enc = PEM);
-
+BOTAN_DLL std::string PEM_encode(const Private_Key& key);
 
 /**
-* Get a string containing a PEM encoded private key.
+* Encrypt a key using PKCS #8 encryption
 * @param key the key to encode
-* @return the encoded key
+* @param rng the rng to use
+* @param pass the password to use for encryption
+* @param pbe_algo the name of the desired password-based encryption
+         algorithm; if empty ("") a reasonable (portable/secure)
+         default will be chosen.
+* @return encrypted key in binary BER form
 */
-BOTAN_DLL std::string PEM_encode(const Private_Key& key);
+BOTAN_DLL SecureVector<byte> BER_encode(const Private_Key& key,
+                                        RandomNumberGenerator& rng,
+                                        const std::string& pass,
+                                        const std::string& pbe_algo = "");
 
 /**
 * Get a string containing a PEM encoded private key, encrypting it with a
@@ -64,20 +59,67 @@ BOTAN_DLL std::string PEM_encode(const Private_Key& key);
 * @param key the key to encode
 * @param rng the rng to use
 * @param pass the password to use for encryption
-* @param pbe_algo the name of the desired password-based encryption algorithm;
-         if empty ("") a reasonable (portable/secure) default will be chosen.
+* @param pbe_algo the name of the desired password-based encryption
+         algorithm; if empty ("") a reasonable (portable/secure)
+         default will be chosen.
+* @return encrypted key in PEM form
 */
 BOTAN_DLL std::string PEM_encode(const Private_Key& key,
                                  RandomNumberGenerator& rng,
                                  const std::string& pass,
                                  const std::string& pbe_algo = "");
 
+
+/**
+* Encode a private key into a pipe.
+* @deprecated Use PEM_encode or BER_encode instead
+*
+* @param key the private key to encode
+* @param pipe the pipe to feed the encoded key into
+* @param encoding the encoding type to use
+*/
+inline void encode(const Private_Key& key,
+                   Pipe& pipe,
+                   X509_Encoding encoding = PEM)
+   {
+   if(encoding == PEM)
+      pipe.write(PKCS8::PEM_encode(key));
+   else
+      pipe.write(PKCS8::BER_encode(key));
+   }
+
+/**
+* Encode and encrypt a private key into a pipe.
+* @deprecated Use PEM_encode or BER_encode instead
+*
+* @param key the private key to encode
+* @param pipe the pipe to feed the encoded key into
+* @param pass the password to use for encryption
+* @param rng the rng to use
+* @param pbe_algo the name of the desired password-based encryption
+         algorithm; if empty ("") a reasonable (portable/secure)
+         default will be chosen.
+* @param encoding the encoding type to use
+*/
+inline void encrypt_key(const Private_Key& key,
+                        Pipe& pipe,
+                        RandomNumberGenerator& rng,
+                        const std::string& pass,
+                        const std::string& pbe_algo = "",
+                        X509_Encoding encoding = PEM)
+   {
+   if(encoding == PEM)
+      pipe.write(PKCS8::PEM_encode(key, rng, pass, pbe_algo));
+   else
+      pipe.write(PKCS8::BER_encode(key, rng, pass, pbe_algo));
+   }
+
 /**
 * Load a key from a data source.
 * @param source the data source providing the encoded key
 * @param rng the rng to use
 * @param ui the user interface to be used for passphrase dialog
-* @return the loaded private key object
+* @return loaded private key object
 */
 BOTAN_DLL Private_Key* load_key(DataSource& source,
                                 RandomNumberGenerator& rng,
@@ -88,7 +130,7 @@ BOTAN_DLL Private_Key* load_key(DataSource& source,
 * @param rng the rng to use
 * @param pass the passphrase to decrypt the key. Provide an empty
 * string if the key is not encoded.
-* @return the loaded private key object
+* @return loaded private key object
 */
 BOTAN_DLL Private_Key* load_key(DataSource& source,
                                 RandomNumberGenerator& rng,
@@ -99,7 +141,7 @@ BOTAN_DLL Private_Key* load_key(DataSource& source,
 * @param filename the path to the file containing the encoded key
 * @param rng the rng to use
 * @param ui the user interface to be used for passphrase dialog
-* @return the loaded private key object
+* @return loaded private key object
 */
 BOTAN_DLL Private_Key* load_key(const std::string& filename,
                                 RandomNumberGenerator& rng,
@@ -110,7 +152,7 @@ BOTAN_DLL Private_Key* load_key(const std::string& filename,
 * @param rng the rng to use
 * @param pass the passphrase to decrypt the key. Provide an empty
 * string if the key is not encoded.
-* @return the loaded private key object
+* @return loaded private key object
 */
 BOTAN_DLL Private_Key* load_key(const std::string& filename,
                                 RandomNumberGenerator& rng,
@@ -120,7 +162,7 @@ BOTAN_DLL Private_Key* load_key(const std::string& filename,
 * Copy an existing encoded key object.
 * @param key the key to copy
 * @param rng the rng to use
-* @return the new copy of the key
+* @return new copy of the key
 */
 BOTAN_DLL Private_Key* copy_key(const Private_Key& key,
                                 RandomNumberGenerator& rng);
diff --git a/src/pubkey/pubkey.h b/src/pubkey/pubkey.h
index eeb4d5841..ff4355675 100644
--- a/src/pubkey/pubkey.h
+++ b/src/pubkey/pubkey.h
@@ -43,7 +43,7 @@ class BOTAN_DLL PK_Encryptor
       * @param in the message as a byte array
       * @param length the length of the above byte array
       * @param rng the random number source to use
-      * @return the encrypted message
+      * @return encrypted message
       */
       SecureVector<byte> encrypt(const byte in[], u32bit length,
                                  RandomNumberGenerator& rng) const
@@ -55,7 +55,7 @@ class BOTAN_DLL PK_Encryptor
       * Encrypt a message.
       * @param in the message
       * @param rng the random number source to use
-      * @return the encrypted message
+      * @return encrypted message
       */
       SecureVector<byte> encrypt(const MemoryRegion<byte>& in,
                                  RandomNumberGenerator& rng) const
@@ -65,7 +65,7 @@ class BOTAN_DLL PK_Encryptor
 
       /**
       * Return the maximum allowed message size in bytes.
-      * @return the maximum message size in bytes
+      * @return maximum message size in bytes
       */
       virtual u32bit maximum_input_size() const = 0;
 
@@ -89,7 +89,7 @@ class BOTAN_DLL PK_Decryptor
       * Decrypt a ciphertext.
       * @param in the ciphertext as a byte array
       * @param length the length of the above byte array
-      * @return the decrypted message
+      * @return decrypted message
       */
       SecureVector<byte> decrypt(const byte in[], u32bit length) const
          {
@@ -99,7 +99,7 @@ class BOTAN_DLL PK_Decryptor
       /**
       * Decrypt a ciphertext.
       * @param in the ciphertext
-      * @return the decrypted message
+      * @return decrypted message
       */
       SecureVector<byte> decrypt(const MemoryRegion<byte>& in) const
          {
@@ -128,7 +128,7 @@ class BOTAN_DLL PK_Signer
       * @param in the message to sign as a byte array
       * @param length the length of the above byte array
       * @param rng the rng to use
-      * @return the signature
+      * @return signature
       */
       SecureVector<byte> sign_message(const byte in[], u32bit length,
                                       RandomNumberGenerator& rng);
@@ -137,7 +137,7 @@ class BOTAN_DLL PK_Signer
       * Sign a message.
       * @param in the message to sign
       * @param rng the rng to use
-      * @return the signature
+      * @return signature
       */
       SecureVector<byte> sign_message(const MemoryRegion<byte>& in,
                                       RandomNumberGenerator& rng)
@@ -145,7 +145,7 @@ class BOTAN_DLL PK_Signer
 
       /**
       * Add a message part (single byte).
-      * @param the byte to add
+      * @param in the byte to add
       */
       void update(byte in) { update(&in, 1); }
 
@@ -166,7 +166,7 @@ class BOTAN_DLL PK_Signer
       * Get the signature of the so far processed message (provided by the
       * calls to update()).
       * @param rng the rng to use
-      * @return the signature of the total message
+      * @return signature of the total message
       */
       SecureVector<byte> signature(RandomNumberGenerator& rng);
 
@@ -305,8 +305,8 @@ class BOTAN_DLL PK_Verifier
       Signature_Format sig_format;
    };
 
-/*
-* Key Agreement
+/**
+* Key used for key agreement
 */
 class BOTAN_DLL PK_Key_Agreement
    {
@@ -438,6 +438,12 @@ class BOTAN_DLL PK_Decryptor_EME : public PK_Decryptor
       const EME* eme;
    };
 
+/*
+* Typedefs for compatability with 1.8
+*/
+typedef PK_Encryptor_EME PK_Encryptor_MR_with_EME;
+typedef PK_Decryptor_EME PK_Decryptor_MR_with_EME;
+
 }
 
 #endif
diff --git a/src/pubkey/rsa/rsa.h b/src/pubkey/rsa/rsa.h
index e2da173f9..f7700e08c 100644
--- a/src/pubkey/rsa/rsa.h
+++ b/src/pubkey/rsa/rsa.h
@@ -42,7 +42,7 @@ class BOTAN_DLL RSA_PublicKey : public virtual IF_Scheme_PublicKey
    };
 
 /**
-* RSA Private Key class.
+* RSA Private Key
 */
 class BOTAN_DLL RSA_PrivateKey : public RSA_PublicKey,
                                  public IF_Scheme_PrivateKey
@@ -83,6 +83,9 @@ class BOTAN_DLL RSA_PrivateKey : public RSA_PublicKey,
                      u32bit bits, u32bit exp = 65537);
    };
 
+/**
+* RSA private (decrypt/sign) operation
+*/
 class BOTAN_DLL RSA_Private_Operation : public PK_Ops::Signature,
                                         public PK_Ops::Decryption
    {
@@ -107,6 +110,9 @@ class BOTAN_DLL RSA_Private_Operation : public PK_Ops::Signature,
       Blinder blinder;
    };
 
+/**
+* RSA public (encrypt/verify) operation
+*/
 class BOTAN_DLL RSA_Public_Operation : public PK_Ops::Verification,
                                        public PK_Ops::Encryption
    {
diff --git a/src/pubkey/rw/rw.h b/src/pubkey/rw/rw.h
index 831c7a960..24f4ffab6 100644
--- a/src/pubkey/rw/rw.h
+++ b/src/pubkey/rw/rw.h
@@ -15,7 +15,7 @@
 
 namespace Botan {
 
-/*
+/**
 * Rabin-Williams Public Key
 */
 class BOTAN_DLL RW_PublicKey : public virtual IF_Scheme_PublicKey
@@ -36,7 +36,7 @@ class BOTAN_DLL RW_PublicKey : public virtual IF_Scheme_PublicKey
       RW_PublicKey() {}
    };
 
-/*
+/**
 * Rabin-Williams Private Key
 */
 class BOTAN_DLL RW_PrivateKey : public RW_PublicKey,
@@ -59,6 +59,9 @@ class BOTAN_DLL RW_PrivateKey : public RW_PublicKey,
       bool check_key(RandomNumberGenerator& rng, bool) const;
    };
 
+/**
+* Rabin-Williams Signature Operation
+*/
 class BOTAN_DLL RW_Signature_Operation : public PK_Ops::Signature
    {
    public:
@@ -79,6 +82,9 @@ class BOTAN_DLL RW_Signature_Operation : public PK_Ops::Signature
       Blinder blinder;
    };
 
+/**
+* Rabin-Williams Verification Operation
+*/
 class BOTAN_DLL RW_Verification_Operation : public PK_Ops::Verification
    {
    public:
diff --git a/src/pubkey/x509_key.cpp b/src/pubkey/x509_key.cpp
index babeb517f..d321ce338 100644
--- a/src/pubkey/x509_key.cpp
+++ b/src/pubkey/x509_key.cpp
@@ -1,6 +1,6 @@
 /*
 * X.509 Public Key
-* (C) 1999-2007 Jack Lloyd
+* (C) 1999-2010 Jack Lloyd
 *
 * Distributed under the terms of the Botan license
 */
@@ -18,23 +18,14 @@ namespace Botan {
 
 namespace X509 {
 
-/*
-* DER or PEM encode a X.509 public key
-*/
-void encode(const Public_Key& key, Pipe& pipe, X509_Encoding encoding)
+MemoryVector<byte> BER_encode(const Public_Key& key)
    {
-   MemoryVector<byte> der =
-      DER_Encoder()
+   return DER_Encoder()
          .start_cons(SEQUENCE)
             .encode(key.algorithm_identifier())
             .encode(key.x509_subject_public_key(), BIT_STRING)
          .end_cons()
       .get_contents();
-
-   if(encoding == PEM)
-      pipe.write(PEM_Code::encode(der, "PUBLIC KEY"));
-   else
-      pipe.write(der);
    }
 
 /*
@@ -42,11 +33,8 @@ void encode(const Public_Key& key, Pipe& pipe, X509_Encoding encoding)
 */
 std::string PEM_encode(const Public_Key& key)
    {
-   Pipe pem;
-   pem.start_msg();
-   encode(key, pem, PEM);
-   pem.end_msg();
-   return pem.read_all_as_string();
+   return PEM_Code::encode(X509::BER_encode(key),
+                           "PUBLIC KEY");
    }
 
 /*
@@ -115,11 +103,7 @@ Public_Key* load_key(const MemoryRegion<byte>& mem)
 */
 Public_Key* copy_key(const Public_Key& key)
    {
-   Pipe bits;
-   bits.start_msg();
-   X509::encode(key, bits, RAW_BER);
-   bits.end_msg();
-   DataSource_Memory source(bits.read_all());
+   DataSource_Memory source(PEM_encode(key));
    return X509::load_key(source);
    }
 
diff --git a/src/pubkey/x509_key.h b/src/pubkey/x509_key.h
index 13f11646e..4b17f9974 100644
--- a/src/pubkey/x509_key.h
+++ b/src/pubkey/x509_key.h
@@ -1,6 +1,6 @@
 /*
 * X.509 Public Key
-* (C) 1999-2007 Jack Lloyd
+* (C) 1999-2010 Jack Lloyd
 *
 * Distributed under the terms of the Botan license
 */
@@ -16,51 +16,49 @@
 namespace Botan {
 
 /**
-* This namespace contains functions for handling X509 objects.
+* This namespace contains functions for handling X.509 public keys
 */
 namespace X509 {
 
 /**
-* Encode a key into a pipe.
+* BER encode a key
 * @param key the public key to encode
-* @param pipe the pipe to feed the encoded key into
-* @param enc the encoding type to use
+* @return BER encoding of this key
 */
-BOTAN_DLL void encode(const Public_Key& key, Pipe& pipe,
-                      X509_Encoding enc = PEM);
+BOTAN_DLL MemoryVector<byte> BER_encode(const Public_Key& key);
 
 /**
 * PEM encode a public key into a string.
 * @param key the key to encode
-* @return the PEM encoded key
+* @return PEM encoded key
 */
 BOTAN_DLL std::string PEM_encode(const Public_Key& key);
 
 /**
 * Create a public key from a data source.
 * @param source the source providing the DER or PEM encoded key
-* @return the new public key object
+* @return new public key object
 */
 BOTAN_DLL Public_Key* load_key(DataSource& source);
 
 /**
-* Create a public key from a string.
-* @param enc the string containing the PEM encoded key
-* @return the new public key object
+* Create a public key from a file
+* @param filename pathname to the file to load
+* @return new public key object
 */
-BOTAN_DLL Public_Key* load_key(const std::string& enc);
+BOTAN_DLL Public_Key* load_key(const std::string& filename);
 
 /**
 * Create a public key from a memory region.
 * @param enc the memory region containing the DER or PEM encoded key
-* @return the new public key object
+* @return new public key object
 */
 BOTAN_DLL Public_Key* load_key(const MemoryRegion<byte>& enc);
 
 /**
 * Copy a key.
 * @param key the public key to copy
-* @return the new public key object
+* @return new public key object
 */
 BOTAN_DLL Public_Key* copy_key(const Public_Key& key);
 
@@ -70,13 +68,30 @@ BOTAN_DLL Public_Key* copy_key(const Public_Key& key);
 * constraints to be placed in the return value is derived
 * @param limits additional limits that will be incorporated into the
 * return value
-* @return the combination of key type specific constraints and
+* @return combination of key type specific constraints and
 * additional limits
 */
-
 BOTAN_DLL Key_Constraints find_constraints(const Public_Key& pub_key,
                                            Key_Constraints limits);
 
+/**
+* Encode a key into a pipe.
+* @deprecated Use PEM_encode or BER_encode instead
+*
+* @param key the public key to encode
+* @param pipe the pipe to feed the encoded key into
+* @param encoding the encoding type to use
+*/
+inline void encode(const Public_Key& key,
+                      Pipe& pipe,
+                      X509_Encoding encoding = PEM)
+   {
+   if(encoding == PEM)
+      pipe.write(X509::PEM_encode(key));
+   else
+      pipe.write(X509::BER_encode(key));
+   }
+
 }
 
 }