Improve modes doxygen [ci skip]

9 files changed, 104 insertions, 8 deletions

diff --git a/src/lib/modes/aead/aead.h b/src/lib/modes/aead/aead.h
index 3214187db..0769a1829 100644
--- a/src/lib/modes/aead/aead.h
+++ b/src/lib/modes/aead/aead.h
@@ -38,12 +38,30 @@ class BOTAN_DLL AEAD_Mode : public Cipher_Mode
       */
       virtual void set_associated_data(const byte ad[], size_t ad_len) = 0;
 
+      /**
+      * Set associated data that is not included in the ciphertext but
+      * that should be authenticated. Must be called after set_key and
+      * before start.
+      *
+      * See @ref set_associated_data().
+      *
+      * @param ad the associated data
+      */
       template<typename Alloc>
       void set_associated_data_vec(const std::vector<byte, Alloc>& ad)
          {
          set_associated_data(ad.data(), ad.size());
          }
 
+      /**
+      * Set associated data that is not included in the ciphertext but
+      * that should be authenticated. Must be called after set_key and
+      * before start.
+      *
+      * See @ref set_associated_data().
+      *
+      * @param ad the associated data
+      */
       template<typename Alloc>
       void set_ad(const std::vector<byte, Alloc>& ad)
          {
@@ -51,8 +69,8 @@ class BOTAN_DLL AEAD_Mode : public Cipher_Mode
          }
 
       /**
-      * Default AEAD nonce size (a commonly supported value among AEAD
-      * modes, and large enough that random collisions are unlikely).
+      * @return default AEAD nonce size (a commonly supported value among AEAD
+      * modes, and large enough that random collisions are unlikely)
       */
       size_t default_nonce_length() const override { return 12; }
 
@@ -61,6 +79,8 @@ class BOTAN_DLL AEAD_Mode : public Cipher_Mode
 
 /**
 * Get an AEAD mode by name (eg "AES-128/GCM" or "Serpent/EAX")
+* @param name AEAD name
+* @param direction ENCRYPTION or DECRYPTION
 */
 BOTAN_DLL AEAD_Mode* get_aead(const std::string& name, Cipher_Dir direction);
 
diff --git a/src/lib/modes/aead/siv/siv.h b/src/lib/modes/aead/siv/siv.h
index 6acfe515a..ca3e7df37 100644
--- a/src/lib/modes/aead/siv/siv.h
+++ b/src/lib/modes/aead/siv/siv.h
@@ -23,6 +23,12 @@ class BOTAN_DLL SIV_Mode : public AEAD_Mode
    public:
       size_t process(uint8_t buf[], size_t size) override;
 
+      /**
+      * Sets the nth element of the vector of associated data
+      * @param n index into the AD vector
+      * @param ad associated data
+      * @param ad_len length of associated data in bytes
+      */
       void set_associated_data_n(size_t n, const byte ad[], size_t ad_len);
 
       void set_associated_data(const byte ad[], size_t ad_len) override
diff --git a/src/lib/modes/cbc/cbc.h b/src/lib/modes/cbc/cbc.h
index caad102d4..c6b6e4e4b 100644
--- a/src/lib/modes/cbc/cbc.h
+++ b/src/lib/modes/cbc/cbc.h
@@ -62,6 +62,10 @@ class BOTAN_DLL CBC_Mode : public Cipher_Mode
 class BOTAN_DLL CBC_Encryption : public CBC_Mode
    {
    public:
+      /**
+      * @param cipher block cipher to use
+      * @param padding padding method to use
+      */
       CBC_Encryption(BlockCipher* cipher, BlockCipherModePaddingMethod* padding) :
          CBC_Mode(cipher, padding) {}
 
@@ -80,6 +84,9 @@ class BOTAN_DLL CBC_Encryption : public CBC_Mode
 class BOTAN_DLL CTS_Encryption final : public CBC_Encryption
    {
    public:
+      /**
+      * @param cipher block cipher to use
+      */
       explicit CTS_Encryption(BlockCipher* cipher) : CBC_Encryption(cipher, nullptr) {}
 
       size_t output_length(size_t input_length) const override;
@@ -97,6 +104,10 @@ class BOTAN_DLL CTS_Encryption final : public CBC_Encryption
 class BOTAN_DLL CBC_Decryption : public CBC_Mode
    {
    public:
+      /**
+      * @param cipher block cipher to use
+      * @param padding padding method to use
+      */
       CBC_Decryption(BlockCipher* cipher, BlockCipherModePaddingMethod* padding) :
          CBC_Mode(cipher, padding), m_tempbuf(update_granularity()) {}
 
@@ -117,6 +128,9 @@ class BOTAN_DLL CBC_Decryption : public CBC_Mode
 class BOTAN_DLL CTS_Decryption final : public CBC_Decryption
    {
    public:
+      /**
+      * @param cipher block cipher to use
+      */
       explicit CTS_Decryption(BlockCipher* cipher) : CBC_Decryption(cipher, nullptr) {}
 
       void finish(secure_vector<byte>& final_block, size_t offset = 0) override;
diff --git a/src/lib/modes/cfb/cfb.h b/src/lib/modes/cfb/cfb.h
index 2ec87244e..318bdab64 100644
--- a/src/lib/modes/cfb/cfb.h
+++ b/src/lib/modes/cfb/cfb.h
@@ -61,6 +61,12 @@ class BOTAN_DLL CFB_Mode : public Cipher_Mode
 class BOTAN_DLL CFB_Encryption final : public CFB_Mode
    {
    public:
+      /**
+      * If feedback_bits is zero, cipher->block_size() bytes will be used.
+      * @param cipher block cipher to use
+      * @param feedback_bits number of bits fed back into the shift register,
+      * must be a multiple of 8
+      */
       CFB_Encryption(BlockCipher* cipher, size_t feedback_bits) :
          CFB_Mode(cipher, feedback_bits) {}
 
@@ -75,6 +81,12 @@ class BOTAN_DLL CFB_Encryption final : public CFB_Mode
 class BOTAN_DLL CFB_Decryption final : public CFB_Mode
    {
    public:
+      /**
+      * If feedback_bits is zero, cipher->block_size() bytes will be used.
+      * @param cipher block cipher to use
+      * @param feedback_bits number of bits fed back into the shift register,
+      * must be a multiple of 8
+      */
       CFB_Decryption(BlockCipher* cipher, size_t feedback_bits) :
          CFB_Mode(cipher, feedback_bits) {}
 
diff --git a/src/lib/modes/cipher_mode.h b/src/lib/modes/cipher_mode.h
index d890870c1..2abaa7ac8 100644
--- a/src/lib/modes/cipher_mode.h
+++ b/src/lib/modes/cipher_mode.h
@@ -69,7 +69,10 @@ class BOTAN_DLL Cipher_Mode
       * Processes msg in place and returns bytes written. Normally
       * this will be either msg_len (indicating the entire message was
       * processes) or for certain AEAD modes zero (indicating that the
-      * mode requires the entire message be processed in one pass.
+      * mode requires the entire message be processed in one pass).
+      *
+      * @param msg the message to be processed
+      * @param msg_len length of the message in bytes
       */
       virtual size_t process(uint8_t msg[], size_t msg_len) = 0;
 
@@ -116,12 +119,12 @@ class BOTAN_DLL Cipher_Mode
       virtual size_t minimum_final_size() const = 0;
 
       /**
-      * Return the default size for a nonce
+      * @return the default size for a nonce
       */
       virtual size_t default_nonce_length() const = 0;
 
       /**
-      * Return true iff nonce_len is a valid length for the nonce
+      * @return true iff nonce_len is a valid length for the nonce
       */
       virtual bool valid_nonce_length(size_t nonce_len) const = 0;
 
@@ -130,13 +133,13 @@ class BOTAN_DLL Cipher_Mode
       virtual void clear() = 0;
 
       /**
-      * Returns true iff this mode provides authentication as well as
+      * @return true iff this mode provides authentication as well as
       * confidentiality.
       */
       virtual bool authenticated() const { return false; }
 
       /**
-      * Return the size of the authentication tag used (in bytes)
+      * @return the size of the authentication tag used (in bytes)
       */
       virtual size_t tag_size() const { return 0; }
 
@@ -155,12 +158,20 @@ class BOTAN_DLL Cipher_Mode
          return key_spec().valid_keylength(length);
          }
 
+      /**
+      * Set the symmetric key of this transform
+      * @param key contains the key material
+      */
       template<typename Alloc>
       void set_key(const std::vector<byte, Alloc>& key)
          {
          set_key(key.data(), key.size());
          }
 
+      /**
+      * Set the symmetric key of this transform
+      * @param key contains the key material
+      */
       void set_key(const SymmetricKey& key)
          {
          set_key(key.begin(), key.length());
@@ -194,6 +205,11 @@ class BOTAN_DLL Cipher_Mode
 */
 enum Cipher_Dir { ENCRYPTION, DECRYPTION };
 
+/**
+* Get a cipher mode by name (eg "AES-128/CBC" or "Serpent/XTS")
+* @param algo_spec cipher name
+* @param direction ENCRYPTION or DECRYPTION
+*/
 BOTAN_DLL Cipher_Mode* get_cipher_mode(const std::string& algo_spec, Cipher_Dir direction);
 
 }
diff --git a/src/lib/modes/ecb/ecb.h b/src/lib/modes/ecb/ecb.h
index 9ebbf76a4..4d2a11d05 100644
--- a/src/lib/modes/ecb/ecb.h
+++ b/src/lib/modes/ecb/ecb.h
@@ -52,6 +52,10 @@ class BOTAN_DLL ECB_Mode : public Cipher_Mode
 class BOTAN_DLL ECB_Encryption final : public ECB_Mode
    {
    public:
+      /**
+      * @param cipher block cipher to use
+      * @param padding padding method to use
+      */
       ECB_Encryption(BlockCipher* cipher, BlockCipherModePaddingMethod* padding) :
          ECB_Mode(cipher, padding) {}
 
@@ -70,6 +74,10 @@ class BOTAN_DLL ECB_Encryption final : public ECB_Mode
 class BOTAN_DLL ECB_Decryption final : public ECB_Mode
    {
    public:
+      /**
+      * @param cipher block cipher to use
+      * @param padding padding method to use
+      */
       ECB_Decryption(BlockCipher* cipher, BlockCipherModePaddingMethod* padding) :
          ECB_Mode(cipher, padding) {}
 
diff --git a/src/lib/modes/mode_pad/mode_pad.h b/src/lib/modes/mode_pad/mode_pad.h
index bc2b7c132..ab0941f54 100644
--- a/src/lib/modes/mode_pad/mode_pad.h
+++ b/src/lib/modes/mode_pad/mode_pad.h
@@ -25,13 +25,20 @@ namespace Botan {
 class BOTAN_DLL BlockCipherModePaddingMethod
    {
    public:
+      /**
+      * Add padding bytes to buffer.
+      * @param buffer data to pad
+      * @param size of the final block in bytes
+      * @param size of each block in bytes
+      */
       virtual void add_padding(secure_vector<byte>& buffer,
                                size_t final_block_bytes,
                                size_t block_size) const = 0;
 
       /**
+      * Remove padding bytes from block
       * @param block the last block
-      * @param size the of the block
+      * @param size the size of the block in bytes
       * @return number of padding bytes
       */
       virtual size_t unpad(const byte block[],
@@ -120,6 +127,10 @@ class BOTAN_DLL Null_Padding final : public BlockCipherModePaddingMethod
       std::string name() const override { return "NoPadding"; }
    };
 
+/**
+* Get a block cipher padding mode by name (eg "NoPadding" or "PKCS7")
+* @param algo_spec block cipher padding mode name
+*/
 BOTAN_DLL BlockCipherModePaddingMethod* get_bc_pad(const std::string& algo_spec);
 
 }
diff --git a/src/lib/modes/stream_mode.h b/src/lib/modes/stream_mode.h
index f59f6d9ba..3a0c8574c 100644
--- a/src/lib/modes/stream_mode.h
+++ b/src/lib/modes/stream_mode.h
@@ -15,6 +15,9 @@ namespace Botan {
 class BOTAN_DLL Stream_Cipher_Mode : public Cipher_Mode
    {
    public:
+      /**
+      * @param cipher underyling stream cipher
+      */
       explicit Stream_Cipher_Mode(StreamCipher* cipher) : m_cipher(cipher) {}
 
       size_t process(uint8_t buf[], size_t sz) override
diff --git a/src/lib/modes/xts/xts.h b/src/lib/modes/xts/xts.h
index 6c4ba8d99..1216251c2 100644
--- a/src/lib/modes/xts/xts.h
+++ b/src/lib/modes/xts/xts.h
@@ -55,6 +55,9 @@ class BOTAN_DLL XTS_Mode : public Cipher_Mode
 class BOTAN_DLL XTS_Encryption final : public XTS_Mode
    {
    public:
+      /**
+      * @param cipher underlying block cipher
+      */
       explicit XTS_Encryption(BlockCipher* cipher) : XTS_Mode(cipher) {}
 
       size_t process(uint8_t buf[], size_t size) override;
@@ -70,6 +73,9 @@ class BOTAN_DLL XTS_Encryption final : public XTS_Mode
 class BOTAN_DLL XTS_Decryption final : public XTS_Mode
    {
    public:
+      /**
+      * @param cipher underlying block cipher
+      */
       explicit XTS_Decryption(BlockCipher* cipher) : XTS_Mode(cipher) {}
 
       size_t process(uint8_t buf[], size_t size) override;