From 76b57a7c4656f0f5759c34efe8bab664b49cd21d Mon Sep 17 00:00:00 2001 From: lloyd Date: Tue, 15 Jun 2010 23:23:49 +0000 Subject: More Doxygen updates/fixes --- src/hash/sha1/sha160.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'src/hash/sha1/sha160.h') diff --git a/src/hash/sha1/sha160.h b/src/hash/sha1/sha160.h index cb7e63821..3d46e0c79 100644 --- a/src/hash/sha1/sha160.h +++ b/src/hash/sha1/sha160.h @@ -12,8 +12,8 @@ namespace Botan { -/* -* SHA-160 +/** +* NIST's SHA-160 */ class BOTAN_DLL SHA_160 : public MDx_HashFunction { -- cgit v1.2.3 From ecb574d32f4382326e94ad19e9d5baecc84a3c29 Mon Sep 17 00:00:00 2001 From: lloyd Date: Wed, 16 Jun 2010 00:52:24 +0000 Subject: More Doxygen comments --- src/algo_factory/algo_factory.h | 7 +++ src/constructs/tss/tss.h | 34 ++++++++++--- src/hash/comb4p/comb4p.h | 6 ++- src/hash/hash.h | 5 ++ src/hash/par_hash/par_hash.h | 5 +- src/hash/sha1/sha160.h | 6 +++ src/hash/sha2/sha2_32.h | 4 ++ src/hash/sha2/sha2_64.h | 3 ++ src/hash/skein/skein_512.h | 5 ++ src/libstate/init.h | 7 +++ src/libstate/libstate.h | 3 ++ src/mac/cbc_mac/cbc_mac.h | 5 +- src/mac/cmac/cmac.h | 10 +++- src/mac/mac.h | 6 +++ src/mac/ssl3mac/ssl3_mac.h | 5 +- src/mac/x919_mac/x919_mac.h | 5 +- src/pbe/pbes1/pbes1.h | 7 ++- src/s2k/pbkdf1/pbkdf1.h | 4 ++ src/s2k/pgps2k/pgp_s2k.h | 3 ++ src/ssl/tls_alerts.h | 8 +++ src/stream/arc4/arc4.h | 6 ++- src/stream/ctr/ctr.h | 5 +- src/stream/ofb/ofb.h | 5 +- src/sym_algo/symkey.h | 109 ++++++++++++++++++++++++++++++++++++---- 24 files changed, 235 insertions(+), 28 deletions(-) (limited to 'src/hash/sha1/sha160.h') diff --git a/src/algo_factory/algo_factory.h b/src/algo_factory/algo_factory.h index 3284942ad..5e0e49f13 100644 --- a/src/algo_factory/algo_factory.h +++ b/src/algo_factory/algo_factory.h @@ -162,7 +162,14 @@ class BOTAN_DLL Algorithm_Factory class BOTAN_DLL Engine_Iterator { public: + /** + * @return next engine in the sequence + */ class Engine* next() { return af.get_engine_n(n++); } + + /** + * @param a an algorithm factory + */ Engine_Iterator(const Algorithm_Factory& a) : af(a) { n = 0; } private: const Algorithm_Factory& af; diff --git a/src/constructs/tss/tss.h b/src/constructs/tss/tss.h index 440132eb9..485e42c53 100644 --- a/src/constructs/tss/tss.h +++ b/src/constructs/tss/tss.h @@ -22,12 +22,12 @@ class BOTAN_DLL RTSS_Share { public: /** - * @arg M the number of shares needed to reconstruct - * @arg N the number of shares generated - * @arg secret the secret to split - * @arg secret_len the length of the secret - * @arg identifier the 16 byte share identifier - * @arg rng the random number generator to use + * @param M the number of shares needed to reconstruct + * @param N the number of shares generated + * @param secret the secret to split + * @param secret_len the length of the secret + * @param identifier the 16 byte share identifier + * @param rng the random number generator to use */ static std::vector split(byte M, byte N, @@ -36,18 +36,36 @@ class BOTAN_DLL RTSS_Share RandomNumberGenerator& rng); /** - * @arg shares the list of shares + * @param shares the list of shares */ static SecureVector reconstruct(const std::vector& shares); RTSS_Share() {} - RTSS_Share(const std::string&); + /** + * @param hex_input the share encoded in hexadecimal + */ + RTSS_Share(const std::string& hex_input); + + /** + * @return hex representation + */ std::string to_string() const; + + /** + * @return share identifier + */ byte share_id() const; + /** + * @return size of this share in bytes + */ u32bit size() const { return contents.size(); } + + /** + * @return if this TSS share was initialized or not + */ bool initialized() const { return (contents.size() > 0); } private: SecureVector contents; diff --git a/src/hash/comb4p/comb4p.h b/src/hash/comb4p/comb4p.h index 424512092..550b70b14 100644 --- a/src/hash/comb4p/comb4p.h +++ b/src/hash/comb4p/comb4p.h @@ -16,9 +16,13 @@ namespace Botan { * Combines two hash functions using a Feistel scheme. Described in * "On the Security of Hash Function Combiners", Anja Lehmann */ -class Comb4P : public HashFunction +class BOTAN_DLL Comb4P : public HashFunction { public: + /** + * @param h1 the first hash + * @param h2 the second hash + */ Comb4P(HashFunction* h1, HashFunction* h2); ~Comb4P() { delete hash1; delete hash2; } diff --git a/src/hash/hash.h b/src/hash/hash.h index 7cdfc6712..4f753f765 100644 --- a/src/hash/hash.h +++ b/src/hash/hash.h @@ -40,8 +40,13 @@ class BOTAN_DLL HashFunction : public BufferedComputation */ virtual void clear() = 0; + /** + * @param hash_len the output length + * @param block_len the internal block size (if applicable) + */ HashFunction(u32bit hash_len, u32bit block_len = 0) : BufferedComputation(hash_len), HASH_BLOCK_SIZE(block_len) {} + virtual ~HashFunction() {} private: HashFunction& operator=(const HashFunction&); diff --git a/src/hash/par_hash/par_hash.h b/src/hash/par_hash/par_hash.h index 34d69e39a..d82a74a19 100644 --- a/src/hash/par_hash/par_hash.h +++ b/src/hash/par_hash/par_hash.h @@ -23,7 +23,10 @@ class BOTAN_DLL Parallel : public HashFunction std::string name() const; HashFunction* clone() const; - Parallel(const std::vector&); + /** + * @param hashes a set of hashes to compute in parallel + */ + Parallel(const std::vector& hashes); ~Parallel(); private: void add_data(const byte[], u32bit); diff --git a/src/hash/sha1/sha160.h b/src/hash/sha1/sha160.h index 3d46e0c79..c66831a1e 100644 --- a/src/hash/sha1/sha160.h +++ b/src/hash/sha1/sha160.h @@ -24,6 +24,12 @@ class BOTAN_DLL SHA_160 : public MDx_HashFunction SHA_160(); protected: + /** + * Set a custom size for the W array. Normally 80, but some + * subclasses need slightly more for best performance/internal + * constraints + * @param W_size how big to make W + */ SHA_160(u32bit W_size); void compress_n(const byte[], u32bit blocks); diff --git a/src/hash/sha2/sha2_32.h b/src/hash/sha2/sha2_32.h index 319432122..e8e60d07c 100644 --- a/src/hash/sha2/sha2_32.h +++ b/src/hash/sha2/sha2_32.h @@ -20,6 +20,10 @@ class BOTAN_DLL SHA_224_256_BASE : public MDx_HashFunction { protected: void clear(); + + /** + * @param out output size in bytes + */ SHA_224_256_BASE(u32bit out) : MDx_HashFunction(out, 64, true, true) { clear(); } diff --git a/src/hash/sha2/sha2_64.h b/src/hash/sha2/sha2_64.h index 5094fc0d2..bf87eb62d 100644 --- a/src/hash/sha2/sha2_64.h +++ b/src/hash/sha2/sha2_64.h @@ -20,6 +20,9 @@ class BOTAN_DLL SHA_384_512_BASE : public MDx_HashFunction protected: void clear(); + /** + * @param out output size in bytes + */ SHA_384_512_BASE(u32bit out) : MDx_HashFunction(out, 128, true, true, 16) {} diff --git a/src/hash/skein/skein_512.h b/src/hash/skein/skein_512.h index b2ec57962..5d17fa564 100644 --- a/src/hash/skein/skein_512.h +++ b/src/hash/skein/skein_512.h @@ -20,6 +20,11 @@ namespace Botan { class BOTAN_DLL Skein_512 : public HashFunction { public: + /** + * @param output_bits the output size of Skein in bits + * @param personalization is a string that will paramaterize the + * hash output + */ Skein_512(u32bit output_bits = 512, const std::string& personalization = ""); diff --git a/src/libstate/init.h b/src/libstate/init.h index 4c4a09d1f..2d70e4370 100644 --- a/src/libstate/init.h +++ b/src/libstate/init.h @@ -22,8 +22,15 @@ namespace Botan { class BOTAN_DLL LibraryInitializer { public: + /** + * Initialize the library + * @param options a string listing initialization options + */ static void initialize(const std::string& options = ""); + /** + * Shutdown the library + */ static void deinitialize(); /** diff --git a/src/libstate/libstate.h b/src/libstate/libstate.h index 058b70e74..d7fb6e02c 100644 --- a/src/libstate/libstate.h +++ b/src/libstate/libstate.h @@ -29,6 +29,9 @@ class BOTAN_DLL Library_State Library_State(); ~Library_State(); + /** + * @param thread_safe should a mutex be used for serialization + */ void initialize(bool thread_safe); /** diff --git a/src/mac/cbc_mac/cbc_mac.h b/src/mac/cbc_mac/cbc_mac.h index 3818cce84..772abd38f 100644 --- a/src/mac/cbc_mac/cbc_mac.h +++ b/src/mac/cbc_mac/cbc_mac.h @@ -23,7 +23,10 @@ class BOTAN_DLL CBC_MAC : public MessageAuthenticationCode std::string name() const; MessageAuthenticationCode* clone() const; - CBC_MAC(BlockCipher* e); + /** + * @param cipher the underlying block cipher to use + */ + CBC_MAC(BlockCipher* cipher); ~CBC_MAC(); private: void add_data(const byte[], u32bit); diff --git a/src/mac/cmac/cmac.h b/src/mac/cmac/cmac.h index bf7ccdc91..b5f3eec1a 100644 --- a/src/mac/cmac/cmac.h +++ b/src/mac/cmac/cmac.h @@ -23,10 +23,18 @@ class BOTAN_DLL CMAC : public MessageAuthenticationCode std::string name() const; MessageAuthenticationCode* clone() const; + /** + * CMAC's polynomial doubling operation + * @param in the input + * @param polynomial the byte value of the polynomial + */ static SecureVector poly_double(const MemoryRegion& in, byte polynomial); - CMAC(BlockCipher* e); + /** + * @param cipher the underlying block cipher to use + */ + CMAC(BlockCipher* cipher); ~CMAC(); private: void add_data(const byte[], u32bit); diff --git a/src/mac/mac.h b/src/mac/mac.h index b93ae473d..52ff9c94c 100644 --- a/src/mac/mac.h +++ b/src/mac/mac.h @@ -45,6 +45,12 @@ class BOTAN_DLL MessageAuthenticationCode : public BufferedComputation, */ virtual void clear() = 0; + /** + * @param mac_len the output length of this MAC + * @param key_min the minimum key size + * @param key_max the maximum key size + * @param key_mod the modulo restriction on the key size + */ MessageAuthenticationCode(u32bit mac_len, u32bit key_min, u32bit key_max = 0, diff --git a/src/mac/ssl3mac/ssl3_mac.h b/src/mac/ssl3mac/ssl3_mac.h index 631b67c44..019163ec8 100644 --- a/src/mac/ssl3mac/ssl3_mac.h +++ b/src/mac/ssl3mac/ssl3_mac.h @@ -23,7 +23,10 @@ class BOTAN_DLL SSL3_MAC : public MessageAuthenticationCode std::string name() const; MessageAuthenticationCode* clone() const; - SSL3_MAC(HashFunction*); + /** + * @param hash the underlying hash to use + */ + SSL3_MAC(HashFunction* hash); ~SSL3_MAC() { delete hash; } private: void add_data(const byte[], u32bit); diff --git a/src/mac/x919_mac/x919_mac.h b/src/mac/x919_mac/x919_mac.h index abd149ecd..8432db7d1 100644 --- a/src/mac/x919_mac/x919_mac.h +++ b/src/mac/x919_mac/x919_mac.h @@ -23,7 +23,10 @@ class BOTAN_DLL ANSI_X919_MAC : public MessageAuthenticationCode std::string name() const; MessageAuthenticationCode* clone() const; - ANSI_X919_MAC(BlockCipher*); + /** + * @param cipher the underlying block cipher to use + */ + ANSI_X919_MAC(BlockCipher* cipher); ~ANSI_X919_MAC(); private: void add_data(const byte[], u32bit); diff --git a/src/pbe/pbes1/pbes1.h b/src/pbe/pbes1/pbes1.h index e0af8631b..d50c01f53 100644 --- a/src/pbe/pbes1/pbes1.h +++ b/src/pbe/pbes1/pbes1.h @@ -25,9 +25,14 @@ class BOTAN_DLL PBE_PKCS5v15 : public PBE void start_msg(); void end_msg(); + /** + * @param cipher the block cipher to use (DES or RC2) + * @param hash the hash function to use + * @param direction are we encrypting or decrypting + */ PBE_PKCS5v15(BlockCipher* cipher, HashFunction* hash, - Cipher_Dir); + Cipher_Dir direction); ~PBE_PKCS5v15(); private: diff --git a/src/s2k/pbkdf1/pbkdf1.h b/src/s2k/pbkdf1/pbkdf1.h index cf439efd8..c0508d127 100644 --- a/src/s2k/pbkdf1/pbkdf1.h +++ b/src/s2k/pbkdf1/pbkdf1.h @@ -33,6 +33,10 @@ class BOTAN_DLL PKCS5_PBKDF1 : public S2K */ PKCS5_PBKDF1(HashFunction* hash_in) : hash(hash_in) {} + /** + * Copy constructor + * @param other the object to copy + */ PKCS5_PBKDF1(const PKCS5_PBKDF1& other) : S2K(), hash(other.hash->clone()) {} diff --git a/src/s2k/pgps2k/pgp_s2k.h b/src/s2k/pgps2k/pgp_s2k.h index d4c6a02bb..cfe9bf5d5 100644 --- a/src/s2k/pgps2k/pgp_s2k.h +++ b/src/s2k/pgps2k/pgp_s2k.h @@ -27,6 +27,9 @@ class BOTAN_DLL OpenPGP_S2K : public S2K const byte salt[], u32bit salt_len, u32bit iterations) const; + /** + * @param hash_in the hash function to use + */ OpenPGP_S2K(HashFunction* hash_in) : hash(hash_in) {} ~OpenPGP_S2K() { delete hash; } private: diff --git a/src/ssl/tls_alerts.h b/src/ssl/tls_alerts.h index cb7529021..f189cf507 100644 --- a/src/ssl/tls_alerts.h +++ b/src/ssl/tls_alerts.h @@ -18,11 +18,19 @@ namespace Botan { class BOTAN_DLL Alert { public: + /** + * @return if this alert is a fatal one or not + */ bool is_fatal() const { return fatal; } + + /** + * @return type of alert + */ Alert_Type type() const { return type_code; } /** * Deserialize an Alert message + * @param buf the serialized alert */ Alert(const MemoryRegion& buf) { diff --git a/src/stream/arc4/arc4.h b/src/stream/arc4/arc4.h index 78c665985..0488783ef 100644 --- a/src/stream/arc4/arc4.h +++ b/src/stream/arc4/arc4.h @@ -26,7 +26,11 @@ class BOTAN_DLL ARC4 : public StreamCipher StreamCipher* clone() const { return new ARC4(SKIP); } - ARC4(u32bit = 0); + /** + * @param skip skip this many initial bytes in the keystream + */ + ARC4(u32bit skip = 0); + ~ARC4() { clear(); } private: void key_schedule(const byte[], u32bit); diff --git a/src/stream/ctr/ctr.h b/src/stream/ctr/ctr.h index 4e8d4de7f..fc7ba522f 100644 --- a/src/stream/ctr/ctr.h +++ b/src/stream/ctr/ctr.h @@ -33,7 +33,10 @@ class BOTAN_DLL CTR_BE : public StreamCipher void clear(); - CTR_BE(BlockCipher*); + /** + * @param cipher the underlying block cipher to use + */ + CTR_BE(BlockCipher* cipher); ~CTR_BE(); private: void key_schedule(const byte key[], u32bit key_len); diff --git a/src/stream/ofb/ofb.h b/src/stream/ofb/ofb.h index de212ec2c..2871dd8ee 100644 --- a/src/stream/ofb/ofb.h +++ b/src/stream/ofb/ofb.h @@ -33,7 +33,10 @@ class BOTAN_DLL OFB : public StreamCipher void clear(); - OFB(BlockCipher*); + /** + * @param cipher the underlying block cipher to use + */ + OFB(BlockCipher* cipher); ~OFB(); private: void key_schedule(const byte key[], u32bit key_len); diff --git a/src/sym_algo/symkey.h b/src/sym_algo/symkey.h index 0d12377bd..450dab306 100644 --- a/src/sym_algo/symkey.h +++ b/src/sym_algo/symkey.h @@ -19,37 +19,126 @@ namespace Botan { class BOTAN_DLL OctetString { public: + /** + * @return size of this octet string in bytes + */ u32bit length() const { return bits.size(); } + + /** + * @return this object as a SecureVector + */ SecureVector bits_of() const { return bits; } + /** + * @return start of this string + */ const byte* begin() const { return bits.begin(); } + + /** + * @return end of this string + */ const byte* end() const { return bits.end(); } + /** + * @return this encoded as hex + */ std::string as_string() const; - OctetString& operator^=(const OctetString&); + /** + * XOR the contents of another octet string into this one + * @param other octet string + * @return reference to this + */ + OctetString& operator^=(const OctetString& other); + /** + * Force to have odd parity + */ void set_odd_parity(); - void change(const std::string&); - void change(const byte[], u32bit); + /** + * Change the contents of this octet string + * @param hex_string a hex encoded bytestring + */ + void change(const std::string& hex_string); + + /** + * Change the contents of this octet string + * @param in the input + * @param length of in in bytes + */ + void change(const byte in[], u32bit length); + + /** + * Change the contents of this octet string + * @param in the input + */ void change(const MemoryRegion& in) { bits = in; } - OctetString(class RandomNumberGenerator&, u32bit len); + /** + * Create a new random OctetString + * @param rng is a random number generator + * @param len is the desired length in bytes + */ + OctetString(class RandomNumberGenerator& rng, u32bit len); + + /** + * Create a new OctetString + * @param str is a hex encoded string + */ OctetString(const std::string& str = "") { change(str); } + + /** + * Create a new OctetString + * @param in is an array + * @param len is the length of in in bytes + */ OctetString(const byte in[], u32bit len) { change(in, len); } + + /** + * Create a new OctetString + * @param in a bytestring + */ OctetString(const MemoryRegion& in) { change(in); } private: SecureVector bits; }; -/* -* Operations on Octet Strings +/** +* Compare two strings +* @param x an octet string +* @param y an octet string +* @return if x is equal to y +*/ +BOTAN_DLL bool operator==(const OctetString& x, + const OctetString& y); + +/** +* Compare two strings +* @param x an octet string +* @param y an octet string +* @return if x is not equal to y +*/ +BOTAN_DLL bool operator!=(const OctetString& x, + const OctetString& y); + +/** +* Concatenate two strings +* @param x an octet string +* @param y an octet string +* @return x concatenated with y +*/ +BOTAN_DLL OctetString operator+(const OctetString& x, + const OctetString& y); + +/** +* XOR two strings +* @param x an octet string +* @param y an octet string +* @return x XORed with y */ -BOTAN_DLL bool operator==(const OctetString&, const OctetString&); -BOTAN_DLL bool operator!=(const OctetString&, const OctetString&); -BOTAN_DLL OctetString operator+(const OctetString&, const OctetString&); -BOTAN_DLL OctetString operator^(const OctetString&, const OctetString&); +BOTAN_DLL OctetString operator^(const OctetString& x, + const OctetString& y); /* * Alternate Names -- cgit v1.2.3