Improve pubkey doxygen [ci skip]

15 files changed, 251 insertions, 17 deletions

diff --git a/src/lib/pubkey/blinding.h b/src/lib/pubkey/blinding.h
index a6b266807..bc05d97e7 100644
--- a/src/lib/pubkey/blinding.h
+++ b/src/lib/pubkey/blinding.h
@@ -17,15 +17,38 @@ namespace Botan {
 class RandomNumberGenerator;
 
 /**
-* Blinding Function Object
+* Blinding Function Object.
 */
 class BOTAN_DLL Blinder
    {
    public:
+      /**
+      * Blind a value.
+      * The blinding nonce k is freshly generated after
+      * BOTAN_BLINDING_REINIT_INTERVAL calls to blind().
+      * BOTAN_BLINDING_REINIT_INTERVAL = 0 means a fresh
+      * nonce is only generated once. On every other call,
+      * an updated nonce is used for blinding: k' = k*k mod n.
+      * @param x value to blind
+      * @return blinded value
+      */
       BigInt blind(const BigInt& x) const;
 
+      /**
+      * Unblind a value.
+      * @param x value to unblind
+      * @return unblinded value
+      */
       BigInt unblind(const BigInt& x) const;
 
+      /**
+      * @param modulus the modulus
+      * @param rng the RNG to use for generating the nonce
+      * @param fwd_func a function that calculates the modular
+      * exponentiation of the public exponent and the given value (the nonce)
+      * @param inv_func a function that calculates the modular inverse
+      * of the given value (the nonce)
+      */
       Blinder(const BigInt& modulus,
               RandomNumberGenerator& rng,
               std::function<BigInt (const BigInt&)> fwd_func,
diff --git a/src/lib/pubkey/curve25519/curve25519.h b/src/lib/pubkey/curve25519/curve25519.h
index fe39d9dd6..476db80d1 100644
--- a/src/lib/pubkey/curve25519/curve25519.h
+++ b/src/lib/pubkey/curve25519/curve25519.h
@@ -29,9 +29,18 @@ class BOTAN_DLL Curve25519_PublicKey : public virtual Public_Key
 
       std::vector<byte> public_value() const { return unlock(m_public); }
 
+      /**
+      * Create a Curve25519 Public Key.
+      * @param alg_id the X.509 algorithm identifier
+      * @param key_bits X.509 subject public key info structure
+      */
       Curve25519_PublicKey(const AlgorithmIdentifier& alg_id,
                            const secure_vector<byte>& key_bits);
 
+      /**
+      * Create a Curve25519 Public Key.
+      * @param pub DER encoded public key bits
+      */
       explicit Curve25519_PublicKey(const secure_vector<byte>& pub) : m_public(pub) {}
 
    protected:
@@ -44,12 +53,26 @@ class BOTAN_DLL Curve25519_PrivateKey : public Curve25519_PublicKey,
                                         public virtual PK_Key_Agreement_Key
    {
    public:
+      /**
+      * Construct a private key from the specified parameters.
+      * @param alg_id the X.509 algorithm identifier
+      * @param key_bits PKCS #8 structure
+      * @param rng the RNG to use
+      */
       Curve25519_PrivateKey(const AlgorithmIdentifier& alg_id,
                             const secure_vector<byte>& key_bits,
                             RandomNumberGenerator& rng);
 
+      /**
+      * Generate a private key.
+      * @param rng the RNG to use
+      */
       explicit Curve25519_PrivateKey(RandomNumberGenerator& rng);
 
+      /**
+      * Construct a private key from the specified parameters.
+      * @param secret_key DER encoded private key bits
+      */
       explicit Curve25519_PrivateKey(const secure_vector<byte>& secret_key);
 
       std::vector<byte> public_value() const override { return Curve25519_PublicKey::public_value(); }
diff --git a/src/lib/pubkey/dh/dh.h b/src/lib/pubkey/dh/dh.h
index d15bc5eb3..e46a35dff 100644
--- a/src/lib/pubkey/dh/dh.h
+++ b/src/lib/pubkey/dh/dh.h
@@ -25,6 +25,11 @@ class BOTAN_DLL DH_PublicKey : public virtual DL_Scheme_PublicKey
 
       DL_Group::Format group_format() const override { return DL_Group::ANSI_X9_42; }
 
+      /**
+      * Create a public key.
+      * @param alg_id the X.509 algorithm identifier
+      * @param key_bits X.509 subject public key info structure
+      */
       DH_PublicKey(const AlgorithmIdentifier& alg_id,
                    const secure_vector<byte>& key_bits) :
          DL_Scheme_PublicKey(alg_id, key_bits, DL_Group::ANSI_X9_42) {}
@@ -50,9 +55,9 @@ class BOTAN_DLL DH_PrivateKey : public DH_PublicKey,
       std::vector<byte> public_value() const override;
 
       /**
-      * Load a DH private key
-      * @param alg_id the algorithm id
-      * @param key_bits the subject public key
+      * Load a private key.
+      * @param alg_id the X.509 algorithm identifier
+      * @param key_bits PKCS #8 structure
       * @param rng a random number generator
       */
       DH_PrivateKey(const AlgorithmIdentifier& alg_id,
@@ -60,7 +65,7 @@ class BOTAN_DLL DH_PrivateKey : public DH_PublicKey,
                     RandomNumberGenerator& rng);
 
       /**
-      * Construct a private key with predetermined value.
+      * Create a private key.
       * @param rng random number generator to use
       * @param grp the group to be used in the key
       * @param x the key's secret value (or if zero, generate a new key)
diff --git a/src/lib/pubkey/dl_algo/dl_algo.h b/src/lib/pubkey/dl_algo/dl_algo.h
index 705cce8b3..78816935e 100644
--- a/src/lib/pubkey/dl_algo/dl_algo.h
+++ b/src/lib/pubkey/dl_algo/dl_algo.h
@@ -62,6 +62,12 @@ class BOTAN_DLL DL_Scheme_PublicKey : public virtual Public_Key
 
       size_t estimated_strength() const override;
 
+      /**
+      * Create a public key.
+      * @param alg_id the X.509 algorithm identifier
+      * @param key_bits X.509 subject public key info structure
+      * @param group_format the underlying groups encoding format
+      */
       DL_Scheme_PublicKey(const AlgorithmIdentifier& alg_id,
                           const secure_vector<byte>& key_bits,
                           DL_Group::Format group_format);
@@ -97,6 +103,12 @@ class BOTAN_DLL DL_Scheme_PrivateKey : public virtual DL_Scheme_PublicKey,
 
       secure_vector<byte> pkcs8_private_key() const override;
 
+      /**
+      * Create a private key.
+      * @param alg_id the X.509 algorithm identifier
+      * @param key_bits DER encoded private key bits
+      * @param group_format the underlying groups encoding format
+      */
       DL_Scheme_PrivateKey(const AlgorithmIdentifier& alg_id,
                            const secure_vector<byte>& key_bits,
                            DL_Group::Format group_format);
diff --git a/src/lib/pubkey/dsa/dsa.h b/src/lib/pubkey/dsa/dsa.h
index 57c7b7c5c..5ca7b8698 100644
--- a/src/lib/pubkey/dsa/dsa.h
+++ b/src/lib/pubkey/dsa/dsa.h
@@ -25,12 +25,22 @@ class BOTAN_DLL DSA_PublicKey : public virtual DL_Scheme_PublicKey
       size_t message_part_size() const override { return group_q().bytes(); }
       size_t max_input_bits() const override { return group_q().bits(); }
 
+      /**
+      * Load a public key.
+      * @param alg_id the X.509 algorithm identifier
+      * @param key_bits DER encoded public key bits
+      */
       DSA_PublicKey(const AlgorithmIdentifier& alg_id,
                     const secure_vector<byte>& key_bits) :
          DL_Scheme_PublicKey(alg_id, key_bits, DL_Group::ANSI_X9_57)
          {
          }
 
+      /**
+      * Create a public key.
+      * @param group the underlying DL group
+      * @param y the public value y = g^x mod p
+      */
       DSA_PublicKey(const DL_Group& group, const BigInt& y);
 
       std::unique_ptr<PK_Ops::Verification>
@@ -47,10 +57,22 @@ class BOTAN_DLL DSA_PrivateKey : public DSA_PublicKey,
                                  public virtual DL_Scheme_PrivateKey
    {
    public:
+      /**
+      * Load a private key.
+      * @param alg_id the X.509 algorithm identifier
+      * @param key_bits PKCS#8 structure
+      * @param rng the RNG to use
+      */
       DSA_PrivateKey(const AlgorithmIdentifier& alg_id,
                      const secure_vector<byte>& key_bits,
                      RandomNumberGenerator& rng);
 
+      /**
+      * Create a private key.
+      * @param rng the RNG to use
+      * @param group the underlying DL group
+      * @param private_key the private key (if zero, a new random key is generated)
+      */
       DSA_PrivateKey(RandomNumberGenerator& rng,
                      const DL_Group& group,
                      const BigInt& private_key = 0);
diff --git a/src/lib/pubkey/ecc_key/ecc_key.h b/src/lib/pubkey/ecc_key/ecc_key.h
index a8e77b895..ec6806931 100644
--- a/src/lib/pubkey/ecc_key/ecc_key.h
+++ b/src/lib/pubkey/ecc_key/ecc_key.h
@@ -29,9 +29,19 @@ namespace Botan {
 class BOTAN_DLL EC_PublicKey : public virtual Public_Key
    {
    public:
+      /**
+      * Create a public key.
+      * @param dom_par EC domain parameters
+      * @param pub_point public point on the curve
+      */
       EC_PublicKey(const EC_Group& dom_par,
                    const PointGFp& pub_point);
 
+      /**
+      * Load a public key.
+      * @param alg_id the X.509 algorithm identifier
+      * @param key_bits PKCS #8 structure
+      */
       EC_PublicKey(const AlgorithmIdentifier& alg_id,
                    const secure_vector<byte>& key_bits);
 
diff --git a/src/lib/pubkey/ecdh/ecdh.h b/src/lib/pubkey/ecdh/ecdh.h
index 5b6ec7261..132a3d47d 100644
--- a/src/lib/pubkey/ecdh/ecdh.h
+++ b/src/lib/pubkey/ecdh/ecdh.h
@@ -20,7 +20,11 @@ namespace Botan {
 class BOTAN_DLL ECDH_PublicKey : public virtual EC_PublicKey
    {
    public:
-
+      /**
+      * Create an ECDH public key.
+      * @param alg_id algorithm identifier
+      * @param key_bits DER encoded public key bits
+      */
       ECDH_PublicKey(const AlgorithmIdentifier& alg_id,
                      const secure_vector<byte>& key_bits) :
          EC_PublicKey(alg_id, key_bits) {}
@@ -74,6 +78,11 @@ class BOTAN_DLL ECDH_PrivateKey : public ECDH_PublicKey,
    {
    public:
 
+      /**
+      * Create an ECDH public key.
+      * @param alg_id the X.509 algorithm identifier
+      * @param key_bits X.509 subject public key info structure
+      */
       ECDH_PrivateKey(const AlgorithmIdentifier& alg_id,
                       const secure_vector<byte>& key_bits) :
          EC_PrivateKey(alg_id, key_bits) {}
diff --git a/src/lib/pubkey/ecdsa/ecdsa.h b/src/lib/pubkey/ecdsa/ecdsa.h
index d9dcacd06..9fad4e921 100644
--- a/src/lib/pubkey/ecdsa/ecdsa.h
+++ b/src/lib/pubkey/ecdsa/ecdsa.h
@@ -22,7 +22,7 @@ class BOTAN_DLL ECDSA_PublicKey : public virtual EC_PublicKey
    public:
 
       /**
-      * Construct a public key from a given public point.
+      * Create a public key from a given public point.
       * @param dom_par the domain parameters associated with this key
       * @param public_point the public point defining this key
       */
@@ -30,6 +30,11 @@ class BOTAN_DLL ECDSA_PublicKey : public virtual EC_PublicKey
                       const PointGFp& public_point) :
          EC_PublicKey(dom_par, public_point) {}
 
+      /**
+      * Load a public key.
+      * @param alg_id the X.509 algorithm identifier
+      * @param key_bits X.509 subject public key info structure
+      */
       ECDSA_PublicKey(const AlgorithmIdentifier& alg_id,
                       const secure_vector<byte>& key_bits) :
          EC_PublicKey(alg_id, key_bits) {}
@@ -78,7 +83,7 @@ class BOTAN_DLL ECDSA_PrivateKey : public ECDSA_PublicKey,
          EC_PrivateKey(alg_id, key_bits) {}
 
       /**
-      * Generate a new private key
+      * Create a private key.
       * @param rng a random number generator
       * @param domain parameters to used for this key
       * @param x the private key (if zero, generate a new random key)
diff --git a/src/lib/pubkey/ecgdsa/ecgdsa.h b/src/lib/pubkey/ecgdsa/ecgdsa.h
index 203e8d0a8..f90f7bfd4 100644
--- a/src/lib/pubkey/ecgdsa/ecgdsa.h
+++ b/src/lib/pubkey/ecgdsa/ecgdsa.h
@@ -28,6 +28,11 @@ class BOTAN_DLL ECGDSA_PublicKey : public virtual EC_PublicKey
                       const PointGFp& public_point) :
          EC_PublicKey(dom_par, public_point) {}
 
+      /**
+      * Load a public key.
+      * @param alg_id the X.509 algorithm identifier
+      * @param key_bits X.509 subject public key info structure
+      */
       ECGDSA_PublicKey(const AlgorithmIdentifier& alg_id,
                       const secure_vector<byte>& key_bits) :
          EC_PublicKey(alg_id, key_bits) {}
@@ -67,7 +72,7 @@ class BOTAN_DLL ECGDSA_PrivateKey : public ECGDSA_PublicKey,
    public:
 
       /**
-      * Load a private key
+      * Load a private key.
       * @param alg_id the X.509 algorithm identifier
       * @param key_bits PKCS #8 structure
       */
@@ -76,7 +81,7 @@ class BOTAN_DLL ECGDSA_PrivateKey : public ECGDSA_PublicKey,
          EC_PrivateKey(alg_id, key_bits, true) {}
 
       /**
-      * Generate a new private key
+      * Generate a new private key.
       * @param rng a random number generator
       * @param domain parameters to used for this key
       * @param x the private key (if zero, generate a new random key)
diff --git a/src/lib/pubkey/ecies/ecies.h b/src/lib/pubkey/ecies/ecies.h
index 6b9eba31d..35dc07559 100644
--- a/src/lib/pubkey/ecies/ecies.h
+++ b/src/lib/pubkey/ecies/ecies.h
@@ -53,7 +53,7 @@ inline ECIES_Flags operator &(ECIES_Flags a, ECIES_Flags b)
    }
 
 /**
-* Parameters for ecies secret derivation
+* Parameters for ECIES secret derivation
 */
 class BOTAN_DLL ECIES_KA_Params
    {
diff --git a/src/lib/pubkey/eckcdsa/eckcdsa.h b/src/lib/pubkey/eckcdsa/eckcdsa.h
index 09ee34ed5..be5daf2da 100644
--- a/src/lib/pubkey/eckcdsa/eckcdsa.h
+++ b/src/lib/pubkey/eckcdsa/eckcdsa.h
@@ -28,6 +28,11 @@ class BOTAN_DLL ECKCDSA_PublicKey : public virtual EC_PublicKey
                       const PointGFp& public_point) :
          EC_PublicKey(dom_par, public_point) {}
 
+      /**
+      * Load a public key.
+      * @param alg_id the X.509 algorithm identifier
+      * @param key_bits X.509 subject public key info structure
+      */
       ECKCDSA_PublicKey(const AlgorithmIdentifier& alg_id,
                       const secure_vector<byte>& key_bits) :
          EC_PublicKey(alg_id, key_bits) {}
@@ -67,7 +72,7 @@ class BOTAN_DLL ECKCDSA_PrivateKey : public ECKCDSA_PublicKey,
    public:
 
       /**
-      * Load a private key
+      * Load a private key.
       * @param alg_id the X.509 algorithm identifier
       * @param key_bits PKCS #8 structure
       */
@@ -76,7 +81,7 @@ class BOTAN_DLL ECKCDSA_PrivateKey : public ECKCDSA_PublicKey,
          EC_PrivateKey(alg_id, key_bits, true) {}
 
       /**
-      * Generate a new private key
+      * Create a private key.
       * @param rng a random number generator
       * @param domain parameters to used for this key
       * @param x the private key (if zero, generate a new random key)
diff --git a/src/lib/pubkey/elgamal/elgamal.h b/src/lib/pubkey/elgamal/elgamal.h
index 8ca4facc2..fbf38f4ee 100644
--- a/src/lib/pubkey/elgamal/elgamal.h
+++ b/src/lib/pubkey/elgamal/elgamal.h
@@ -23,11 +23,21 @@ class BOTAN_DLL ElGamal_PublicKey : public virtual DL_Scheme_PublicKey
 
       size_t max_input_bits() const override { return (group_p().bits() - 1); }
 
+      /**
+      * Load a public key.
+      * @param alg_id the X.509 algorithm identifier
+      * @param key_bits X.509 subject public key info structure
+      */
       ElGamal_PublicKey(const AlgorithmIdentifier& alg_id,
                         const secure_vector<byte>& key_bits) :
          DL_Scheme_PublicKey(alg_id, key_bits, DL_Group::ANSI_X9_42)
          {}
 
+      /**
+      * Create a public key.
+      * @param group the underlying DL group
+      * @param y the public value y = g^x mod p
+      */
       ElGamal_PublicKey(const DL_Group& group, const BigInt& y);
 
       std::unique_ptr<PK_Ops::Encryption>
@@ -48,10 +58,22 @@ class BOTAN_DLL ElGamal_PrivateKey : public ElGamal_PublicKey,
    public:
       bool check_key(RandomNumberGenerator& rng, bool) const override;
 
+      /**
+      * Load a private key.
+      * @param alg_id the X.509 algorithm identifier
+      * @param key_bits PKCS #8 structure
+      * @paran rng the RNG to use
+      */
       ElGamal_PrivateKey(const AlgorithmIdentifier& alg_id,
                          const secure_vector<byte>& key_bits,
                          RandomNumberGenerator& rng);
 
+      /**
+      * Create a private key.
+      * @param rng random number generator to use
+      * @param grp the group to be used in the key
+      * @param priv_key the key's secret value (or if zero, generate a new key)
+      */
       ElGamal_PrivateKey(RandomNumberGenerator& rng,
                          const DL_Group& group,
                          const BigInt& priv_key = 0);
diff --git a/src/lib/pubkey/gost_3410/gost_3410.h b/src/lib/pubkey/gost_3410/gost_3410.h
index cca811896..dd7cf1af0 100644
--- a/src/lib/pubkey/gost_3410/gost_3410.h
+++ b/src/lib/pubkey/gost_3410/gost_3410.h
@@ -31,7 +31,9 @@ class BOTAN_DLL GOST_3410_PublicKey : public virtual EC_PublicKey
          EC_PublicKey(dom_par, public_point) {}
 
       /**
-      * Construct from X.509 algorithm id and subject public key bits
+      * Load a public key.
+      * @param alg_id the X.509 algorithm identifier
+      * @param key_bits X.509 subject public key info structure
       */
       GOST_3410_PublicKey(const AlgorithmIdentifier& alg_id,
                           const secure_vector<byte>& key_bits);
@@ -74,7 +76,12 @@ class BOTAN_DLL GOST_3410_PrivateKey : public GOST_3410_PublicKey,
                                        public EC_PrivateKey
    {
    public:
-
+      /**
+      * Load a private key.
+      * @param alg_id the X.509 algorithm identifier
+      * @param key_bits PKCS #8 structure
+      * @paran rng the RNG to use
+      */
       GOST_3410_PrivateKey(const AlgorithmIdentifier& alg_id,
                            const secure_vector<byte>& key_bits) :
          EC_PrivateKey(alg_id, key_bits) {}
diff --git a/src/lib/pubkey/pubkey.h b/src/lib/pubkey/pubkey.h
index 94332c8f0..b462253ef 100644
--- a/src/lib/pubkey/pubkey.h
+++ b/src/lib/pubkey/pubkey.h
@@ -220,6 +220,12 @@ class BOTAN_DLL PK_Signer final
                                      RandomNumberGenerator& rng)
          { return sign_message(in.data(), in.size(), rng); }
 
+      /**
+      * Sign a message.
+      * @param in the message to sign
+      * @param rng the rng to use
+      * @return signature
+      */
       std::vector<byte> sign_message(const secure_vector<byte>& in,
                                      RandomNumberGenerator& rng)
          { return sign_message(in.data(), in.size(), rng); }
@@ -502,6 +508,7 @@ class BOTAN_DLL PK_Encryptor_EME final : public PK_Encryptor
       /**
       * Construct an instance.
       * @param key the key to use inside the encryptor
+      * @param rng the RNG to use
       * @param padding the message encoding scheme to use (eg "OAEP(SHA-256)")
       */
       PK_Encryptor_EME(const Public_Key& key,
@@ -543,7 +550,7 @@ class BOTAN_DLL PK_Decryptor_EME final : public PK_Decryptor
       * Construct an instance.
       * @param key the key to use inside the decryptor
       * @param eme the EME to use
-      * @param provider
+      * @param provider the provider to use
       */
       PK_Decryptor_EME(const Private_Key& key,
                        RandomNumberGenerator& rng,
@@ -575,9 +582,19 @@ class BOTAN_DLL PK_Decryptor_EME final : public PK_Decryptor
       std::unique_ptr<PK_Ops::Decryption> m_op;
    };
 
+/**
+* Public Key Key Encapsulation Mechanism Encryption.
+*/
 class BOTAN_DLL PK_KEM_Encryptor final
    {
    public:
+      /**
+      * Construct an instance.
+      * @param key the key to use inside the encryptor
+      * @param rng the RNG to use
+      * @param kem_param additional KEM parameters
+      * @param provider the provider to use
+      */
       PK_KEM_Encryptor(const Public_Key& key,
                        RandomNumberGenerator& rng,
                        const std::string& kem_param = "",
@@ -596,6 +613,15 @@ class BOTAN_DLL PK_KEM_Encryptor final
       PK_KEM_Encryptor& operator=(const PK_KEM_Encryptor&) = delete;
       PK_KEM_Encryptor(const PK_KEM_Encryptor&) = delete;
 
+      /**
+      * Generate a shared key for data encryption.
+      * @param out_encapsulated_key the generated encapsulated key
+      * @param out_shared_key the generated shared key
+      * @param desired_shared_key_len desired size of the shared key in bytes
+      * @param rng the RNG to use
+      * @param salt a salt value used in the KDF
+      * @param salt_len size of the salt value in bytes
+      */
       void encrypt(secure_vector<byte>& out_encapsulated_key,
                    secure_vector<byte>& out_shared_key,
                    size_t desired_shared_key_len,
@@ -603,6 +629,14 @@ class BOTAN_DLL PK_KEM_Encryptor final
                    const uint8_t salt[],
                    size_t salt_len);
 
+      /**
+      * Generate a shared key for data encryption.
+      * @param out_encapsulated_key the generated encapsulated key
+      * @param out_shared_key the generated shared key
+      * @param desired_shared_key_len desired size of the shared key in bytes
+      * @param rng the RNG to use
+      * @param salt a salt value used in the KDF
+      */
       template<typename Alloc>
          void encrypt(secure_vector<byte>& out_encapsulated_key,
                       secure_vector<byte>& out_shared_key,
@@ -617,6 +651,14 @@ class BOTAN_DLL PK_KEM_Encryptor final
                        salt.data(), salt.size());
          }
 
+
+      /**
+      * Generate a shared key for data encryption.
+      * @param out_encapsulated_key the generated encapsulated key
+      * @param out_shared_key the generated shared key
+      * @param desired_shared_key_len desired size of the shared key in bytes
+      * @param rng the RNG to use
+      */
       void encrypt(secure_vector<byte>& out_encapsulated_key,
                    secure_vector<byte>& out_shared_key,
                    size_t desired_shared_key_len,
@@ -634,9 +676,19 @@ class BOTAN_DLL PK_KEM_Encryptor final
       std::unique_ptr<PK_Ops::KEM_Encryption> m_op;
    };
 
+/**
+* Public Key Key Encapsulation Mechanism Decryption.
+*/
 class BOTAN_DLL PK_KEM_Decryptor final
    {
    public:
+      /**
+      * Construct an instance.
+      * @param key the key to use inside the decryptor
+      * @param rng the RNG to use
+      * @param kem_param additional KEM parameters
+      * @param provider the provider to use
+      */
       PK_KEM_Decryptor(const Private_Key& key,
                        RandomNumberGenerator& rng,
                        const std::string& kem_param = "",
@@ -655,12 +707,28 @@ class BOTAN_DLL PK_KEM_Decryptor final
       PK_KEM_Decryptor& operator=(const PK_KEM_Decryptor&) = delete;
       PK_KEM_Decryptor(const PK_KEM_Decryptor&) = delete;
 
+      /**
+      * Decrypts the shared key for data encryption.
+      * @param encap_key the encapsulated key
+      * @param encap_key_len size of the encapsulated key in bytes
+      * @param desired_shared_key_len desired size of the shared key in bytes
+      * @param salt a salt value used in the KDF
+      * @param salt_len size of the salt value in bytes
+      * @return the shared data encryption key
+      */
       secure_vector<byte> decrypt(const byte encap_key[],
                                   size_t encap_key_len,
                                   size_t desired_shared_key_len,
                                   const uint8_t salt[],
                                   size_t salt_len);
 
+      /**
+      * Decrypts the shared key for data encryption.
+      * @param encap_key the encapsulated key
+      * @param encap_key_len size of the encapsulated key in bytes
+      * @param desired_shared_key_len desired size of the shared key in bytes
+      * @return the shared data encryption key
+      */
       secure_vector<byte> decrypt(const byte encap_key[],
                                   size_t encap_key_len,
                                   size_t desired_shared_key_len)
@@ -670,6 +738,13 @@ class BOTAN_DLL PK_KEM_Decryptor final
                               nullptr, 0);
          }
 
+      /**
+      * Decrypts the shared key for data encryption.
+      * @param encap_key the encapsulated key
+      * @param desired_shared_key_len desired size of the shared key in bytes
+      * @param salt a salt value used in the KDF
+      * @return the shared data encryption key
+      */
       template<typename Alloc1, typename Alloc2>
          secure_vector<byte> decrypt(const std::vector<byte, Alloc1>& encap_key,
                                      size_t desired_shared_key_len,
diff --git a/src/lib/pubkey/rsa/rsa.h b/src/lib/pubkey/rsa/rsa.h
index ddfd23b05..aae78e574 100644
--- a/src/lib/pubkey/rsa/rsa.h
+++ b/src/lib/pubkey/rsa/rsa.h
@@ -19,11 +19,16 @@ namespace Botan {
 class BOTAN_DLL RSA_PublicKey : public virtual Public_Key
    {
    public:
+      /**
+      * Load a public key.
+      * @param alg_id the X.509 algorithm identifier
+      * @param key_bits X.509 subject public key info structure
+      */
       RSA_PublicKey(const AlgorithmIdentifier& alg_id,
                     const secure_vector<byte>& key_bits);
 
       /**
-      * Create a RSA_PublicKey
+      * Create a public key.
       * @arg n the modulus
       * @arg e the exponent
       */
@@ -78,6 +83,12 @@ class BOTAN_DLL RSA_PublicKey : public virtual Public_Key
 class BOTAN_DLL RSA_PrivateKey : public Private_Key, public RSA_PublicKey
    {
    public:
+      /**
+      * Load a private key.
+      * @param alg_id the X.509 algorithm identifier
+      * @param key_bits PKCS #8 structure
+      * @paran rng the RNG to use
+      */
       RSA_PrivateKey(const AlgorithmIdentifier& alg_id,
                      const secure_vector<byte>& key_bits,
                      RandomNumberGenerator& rng);