diff options
Diffstat (limited to 'src')
50 files changed, 923 insertions, 183 deletions
diff --git a/src/alloc/allocate.h b/src/alloc/allocate.h index 819e2542c..5bce1f205 100644 --- a/src/alloc/allocate.h +++ b/src/alloc/allocate.h @@ -19,14 +19,42 @@ namespace Botan { class BOTAN_DLL Allocator { public: - static Allocator* get(bool); + /** + * Acquire a pointer to an allocator + * @param locking is true if the allocator should attempt to + * secure the memory (eg for using to store keys) + * @return pointer to an allocator; ownership remains with library, + * so do not delete + */ + static Allocator* get(bool locking); - virtual void* allocate(u32bit) = 0; - virtual void deallocate(void*, u32bit) = 0; + /** + * Allocate a block of memory + * @param n how many bytes to allocate + * @return pointer to n bytes of memory + */ + virtual void* allocate(u32bit n) = 0; + /** + * Deallocate memory allocated with allocate() + * @param ptr the pointer returned by allocate() + * @param n the size of the block pointed to by ptr + */ + virtual void deallocate(void* ptr, u32bit n) = 0; + + /** + * @return name of this allocator type + */ virtual std::string type() const = 0; + /** + * Initialize the allocator + */ virtual void init() {} + + /** + * Shutdown the allocator + */ virtual void destroy() {} virtual ~Allocator() {} diff --git a/src/alloc/secmem.h b/src/alloc/secmem.h index 39b5549a9..bc5a2499d 100644 --- a/src/alloc/secmem.h +++ b/src/alloc/secmem.h @@ -195,6 +195,11 @@ class MemoryRegion ~MemoryRegion() { deallocate(buf, allocated); } protected: MemoryRegion() { buf = 0; alloc = 0; used = allocated = 0; } + + /** + * Copy constructor + * @param other the other region to copy + */ MemoryRegion(const MemoryRegion<T>& other) { buf = 0; @@ -203,6 +208,10 @@ class MemoryRegion set(other.buf, other.used); } + /** + * @param locking should we use a locking allocator + * @param length the initial length to use + */ void init(bool locking, u32bit length = 0) { alloc = Allocator::get(locking); resize(length); } private: diff --git a/src/asn1/asn1_int.h b/src/asn1/asn1_int.h index 3562f692b..cac46190f 100644 --- a/src/asn1/asn1_int.h +++ b/src/asn1/asn1_int.h @@ -56,8 +56,18 @@ enum ASN1_Tag { class BOTAN_DLL ASN1_Object { public: - virtual void encode_into(class DER_Encoder&) const = 0; - virtual void decode_from(class BER_Decoder&) = 0; + /** + * Encode whatever this object is into to + * @param to the DER_Encoder that will be written to + */ + virtual void encode_into(class DER_Encoder& to) const = 0; + + /** + * Decode whatever this object is from from + * @param from the BER_Decoder that will be read from + */ + virtual void decode_from(class BER_Decoder& from) = 0; + virtual ~ASN1_Object() {} }; @@ -80,9 +90,14 @@ class DataSource; namespace ASN1 { -SecureVector<byte> put_in_sequence(const MemoryRegion<byte>&); -std::string to_string(const BER_Object&); -bool maybe_BER(DataSource&); +SecureVector<byte> put_in_sequence(const MemoryRegion<byte>& val); +std::string to_string(const BER_Object& obj); + +/** +* Heuristics tests; is this object possibly BER? +* @param src a data source that will be peeked at but not modified +*/ +bool maybe_BER(DataSource& src); } diff --git a/src/asn1/asn1_obj.h b/src/asn1/asn1_obj.h index c0b74ea0e..3da376e2c 100644 --- a/src/asn1/asn1_obj.h +++ b/src/asn1/asn1_obj.h @@ -24,8 +24,8 @@ namespace Botan { class BOTAN_DLL Attribute : public ASN1_Object { public: - void encode_into(class DER_Encoder&) const; - void decode_from(class BER_Decoder&); + void encode_into(class DER_Encoder& to) const; + void decode_from(class BER_Decoder& from); OID oid; MemoryVector<byte> parameters; diff --git a/src/block/idea/idea.h b/src/block/idea/idea.h index e9ccf366d..aed3be3ea 100644 --- a/src/block/idea/idea.h +++ b/src/block/idea/idea.h @@ -26,10 +26,19 @@ class BOTAN_DLL IDEA : public BlockCipher BlockCipher* clone() const { return new IDEA; } IDEA() : BlockCipher(8, 16) {} + protected: + /** + * @return const reference to encryption subkeys + */ + const SecureVector<u16bit, 52>& get_EK() const { return EK; } + + /** + * @return const reference to decryption subkeys + */ + const SecureVector<u16bit, 52>& get_DK() const { return DK; } + private: void key_schedule(const byte[], u32bit); - - protected: // for IDEA_SSE2 SecureVector<u16bit, 52> EK, DK; }; diff --git a/src/block/idea_sse2/idea_sse2.cpp b/src/block/idea_sse2/idea_sse2.cpp index 0fe35112d..0948bf46a 100644 --- a/src/block/idea_sse2/idea_sse2.cpp +++ b/src/block/idea_sse2/idea_sse2.cpp @@ -198,7 +198,7 @@ void IDEA_SSE2::encrypt_n(const byte in[], byte out[], u32bit blocks) const { while(blocks >= 8) { - idea_op_8(in, out, this->EK); + idea_op_8(in, out, this->get_EK()); in += 8 * BLOCK_SIZE; out += 8 * BLOCK_SIZE; blocks -= 8; @@ -214,7 +214,7 @@ void IDEA_SSE2::decrypt_n(const byte in[], byte out[], u32bit blocks) const { while(blocks >= 8) { - idea_op_8(in, out, this->DK); + idea_op_8(in, out, this->get_DK()); in += 8 * BLOCK_SIZE; out += 8 * BLOCK_SIZE; blocks -= 8; diff --git a/src/block/noekeon/noekeon.h b/src/block/noekeon/noekeon.h index 018c1d1fd..2e524f8b8 100644 --- a/src/block/noekeon/noekeon.h +++ b/src/block/noekeon/noekeon.h @@ -26,15 +26,24 @@ class BOTAN_DLL Noekeon : public BlockCipher BlockCipher* clone() const { return new Noekeon; } Noekeon() : BlockCipher(16, 16) {} - private: - void key_schedule(const byte[], u32bit); - protected: // for access by SIMD subclass - + protected: /** * The Noekeon round constants */ static const byte RC[17]; + /** + * @return const reference to encryption subkeys + */ + const SecureVector<u32bit, 4>& get_EK() const { return EK; } + + /** + * @return const reference to decryption subkeys + */ + const SecureVector<u32bit, 4>& get_DK() const { return DK; } + + private: + void key_schedule(const byte[], u32bit); SecureVector<u32bit, 4> EK, DK; }; diff --git a/src/block/noekeon_simd/noekeon_simd.cpp b/src/block/noekeon_simd/noekeon_simd.cpp index f44104901..c36f269a4 100644 --- a/src/block/noekeon_simd/noekeon_simd.cpp +++ b/src/block/noekeon_simd/noekeon_simd.cpp @@ -55,6 +55,8 @@ namespace Botan { */ void Noekeon_SIMD::encrypt_n(const byte in[], byte out[], u32bit blocks) const { + const SecureVector<u32bit, 4>& EK = this->get_EK(); + SIMD_32 K0 = SIMD_32(EK[0]); SIMD_32 K1 = SIMD_32(EK[1]); SIMD_32 K2 = SIMD_32(EK[2]); @@ -109,6 +111,8 @@ void Noekeon_SIMD::encrypt_n(const byte in[], byte out[], u32bit blocks) const */ void Noekeon_SIMD::decrypt_n(const byte in[], byte out[], u32bit blocks) const { + const SecureVector<u32bit, 4>& DK = this->get_DK(); + SIMD_32 K0 = SIMD_32(DK[0]); SIMD_32 K1 = SIMD_32(DK[1]); SIMD_32 K2 = SIMD_32(DK[2]); diff --git a/src/block/serpent/serpent.h b/src/block/serpent/serpent.h index 1c13d00f9..dc81d4178 100644 --- a/src/block/serpent/serpent.h +++ b/src/block/serpent/serpent.h @@ -26,8 +26,22 @@ class BOTAN_DLL Serpent : public BlockCipher BlockCipher* clone() const { return new Serpent; } Serpent() : BlockCipher(16, 16, 32, 8) {} protected: + /** + * For use by subclasses using SIMD, asm, etc + * @return const reference to the key schedule + */ + const SecureVector<u32bit, 132>& get_round_keys() const + { return round_key; } + + /** + * For use by subclasses that implement the key schedule + * @param ks is the new key schedule value to set + */ + void set_round_keys(const u32bit ks[132]) + { round_key.set(ks, 132); } + + private: void key_schedule(const byte key[], u32bit length); - SecureVector<u32bit, 132> round_key; }; diff --git a/src/block/serpent_ia32/serp_ia32.cpp b/src/block/serpent_ia32/serp_ia32.cpp index ff454ab4c..ecdfec9b1 100644 --- a/src/block/serpent_ia32/serp_ia32.cpp +++ b/src/block/serpent_ia32/serp_ia32.cpp @@ -12,9 +12,32 @@ namespace Botan { extern "C" { -void botan_serpent_ia32_encrypt(const byte[16], byte[16], const u32bit[132]); -void botan_serpent_ia32_decrypt(const byte[16], byte[16], const u32bit[132]); -void botan_serpent_ia32_key_schedule(u32bit[140]); +/** +* Entry point for Serpent encryption in x86 asm +* @param in the input block +* @param out the output block +* @param ks the key schedule +*/ +void botan_serpent_ia32_encrypt(const byte in[16], + byte out[16], + const u32bit ks[132]); + +/** +* Entry point for Serpent decryption in x86 asm +* @param in the input block +* @param out the output block +* @param ks the key schedule +*/ +void botan_serpent_ia32_decrypt(const byte in[16], + byte out[16], + const u32bit ks[132]); + +/** +* Entry point for Serpent key schedule in x86 asm +* @param ks holds the initial working key (padded), and is set to the + final key schedule +*/ +void botan_serpent_ia32_key_schedule(u32bit ks[140]); } @@ -25,7 +48,7 @@ void Serpent_IA32::encrypt_n(const byte in[], byte out[], u32bit blocks) const { for(u32bit i = 0; i != blocks; ++i) { - botan_serpent_ia32_encrypt(in, out, round_key); + botan_serpent_ia32_encrypt(in, out, this->get_round_keys()); in += BLOCK_SIZE; out += BLOCK_SIZE; } @@ -38,7 +61,7 @@ void Serpent_IA32::decrypt_n(const byte in[], byte out[], u32bit blocks) const { for(u32bit i = 0; i != blocks; ++i) { - botan_serpent_ia32_decrypt(in, out, round_key); + botan_serpent_ia32_decrypt(in, out, this->get_round_keys()); in += BLOCK_SIZE; out += BLOCK_SIZE; } @@ -55,7 +78,7 @@ void Serpent_IA32::key_schedule(const byte key[], u32bit length) W[length / 4] |= u32bit(1) << ((length%4)*8); botan_serpent_ia32_key_schedule(W); - round_key.copy(W + 8, 132); + this->set_round_keys(W + 8); } } diff --git a/src/block/serpent_simd/serp_simd.cpp b/src/block/serpent_simd/serp_simd.cpp index 0a535c9a0..ba587e93d 100644 --- a/src/block/serpent_simd/serp_simd.cpp +++ b/src/block/serpent_simd/serp_simd.cpp @@ -182,7 +182,7 @@ void Serpent_SIMD::encrypt_n(const byte in[], byte out[], u32bit blocks) const { while(blocks >= 4) { - serpent_encrypt_4(in, out, this->round_key); + serpent_encrypt_4(in, out, this->get_round_keys()); in += 4 * BLOCK_SIZE; out += 4 * BLOCK_SIZE; blocks -= 4; @@ -198,7 +198,7 @@ void Serpent_SIMD::decrypt_n(const byte in[], byte out[], u32bit blocks) const { while(blocks >= 4) { - serpent_decrypt_4(in, out, this->round_key); + serpent_decrypt_4(in, out, this->get_round_keys()); in += 4 * BLOCK_SIZE; out += 4 * BLOCK_SIZE; blocks -= 4; diff --git a/src/block/xtea/xtea.h b/src/block/xtea/xtea.h index b16cdf555..d15108939 100644 --- a/src/block/xtea/xtea.h +++ b/src/block/xtea/xtea.h @@ -27,6 +27,12 @@ class BOTAN_DLL XTEA : public BlockCipher XTEA() : BlockCipher(8, 16) {} protected: + /** + * @return const reference to the key schedule + */ + const SecureVector<u32bit, 64>& get_EK() const { return EK; } + + private: void key_schedule(const byte[], u32bit); SecureVector<u32bit, 64> EK; }; diff --git a/src/block/xtea_simd/xtea_simd.cpp b/src/block/xtea_simd/xtea_simd.cpp index 264d4f949..44a4e81b6 100644 --- a/src/block/xtea_simd/xtea_simd.cpp +++ b/src/block/xtea_simd/xtea_simd.cpp @@ -96,7 +96,7 @@ void XTEA_SIMD::encrypt_n(const byte in[], byte out[], u32bit blocks) const { while(blocks >= 8) { - xtea_encrypt_8(in, out, this->EK); + xtea_encrypt_8(in, out, this->get_EK()); in += 8 * BLOCK_SIZE; out += 8 * BLOCK_SIZE; blocks -= 8; @@ -112,7 +112,7 @@ void XTEA_SIMD::decrypt_n(const byte in[], byte out[], u32bit blocks) const { while(blocks >= 8) { - xtea_decrypt_8(in, out, this->EK); + xtea_decrypt_8(in, out, this->get_EK()); in += 8 * BLOCK_SIZE; out += 8 * BLOCK_SIZE; blocks -= 8; diff --git a/src/cert/x509/x509_obj.cpp b/src/cert/x509/x509_obj.cpp index 1c8066c56..ffee74f12 100644 --- a/src/cert/x509/x509_obj.cpp +++ b/src/cert/x509/x509_obj.cpp @@ -88,20 +88,10 @@ void X509_Object::decode_info(DataSource& source) */ void X509_Object::encode(Pipe& out, X509_Encoding encoding) const { - SecureVector<byte> der = DER_Encoder() - .start_cons(SEQUENCE) - .start_cons(SEQUENCE) - .raw_bytes(tbs_bits) - .end_cons() - .encode(sig_algo) - .encode(sig, BIT_STRING) - .end_cons() - .get_contents(); - if(encoding == PEM) - out.write(PEM_Code::encode(der, PEM_label_pref)); + out.write(this->PEM_encode()); else - out.write(der); + out.write(this->BER_encode()); } /* @@ -109,11 +99,15 @@ void X509_Object::encode(Pipe& out, X509_Encoding encoding) const */ SecureVector<byte> X509_Object::BER_encode() const { - Pipe ber; - ber.start_msg(); - encode(ber, RAW_BER); - ber.end_msg(); - return ber.read_all(); + return DER_Encoder() + .start_cons(SEQUENCE) + .start_cons(SEQUENCE) + .raw_bytes(tbs_bits) + .end_cons() + .encode(sig_algo) + .encode(sig, BIT_STRING) + .end_cons() + .get_contents(); } /* @@ -121,11 +115,7 @@ SecureVector<byte> X509_Object::BER_encode() const */ std::string X509_Object::PEM_encode() const { - Pipe pem; - pem.start_msg(); - encode(pem, PEM); - pem.end_msg(); - return pem.read_all_as_string(); + return PEM_Code::encode(BER_encode(), PEM_label_pref); } /* diff --git a/src/cert/x509/x509_obj.h b/src/cert/x509/x509_obj.h index 52b76d218..28ee95073 100644 --- a/src/cert/x509/x509_obj.h +++ b/src/cert/x509/x509_obj.h @@ -23,8 +23,21 @@ namespace Botan { class BOTAN_DLL X509_Object { public: + + /** + * The underlying data that is to be or was signed + * @return data that is or was signed + */ SecureVector<byte> tbs_data() const; + + /** + * @return signature on tbs_data() + */ SecureVector<byte> signature() const; + + /** + * @return signature algorithm that was used to generate signature + */ AlgorithmIdentifier signature_algorithm() const; /** @@ -40,10 +53,29 @@ class BOTAN_DLL X509_Object const AlgorithmIdentifier& alg_id, const MemoryRegion<byte>& tbs); - bool check_signature(class Public_Key&) const; + /** + * Check the signature on this data + * @param key the public key purportedly used to sign this data + * @return true if the signature is valid, otherwise false + */ + bool check_signature(class Public_Key& key) const; - void encode(Pipe&, X509_Encoding = PEM) const; + /** + * Encode this to a pipe + * @deprecated use BER_encode or PEM_encode instead + * @param out the pipe to write to + * @param encoding the encoding to use + */ + void encode(Pipe& out, X509_Encoding encoding = PEM) const; + + /** + * @return BER encoding of this + */ SecureVector<byte> BER_encode() const; + + /** + * @return PEM encoding of this + */ std::string PEM_encode() const; X509_Object(DataSource&, const std::string&); diff --git a/src/constructs/aont/package.h b/src/constructs/aont/package.h index 211623347..34e0f35d5 100644 --- a/src/constructs/aont/package.h +++ b/src/constructs/aont/package.h @@ -1,6 +1,5 @@ /* * Rivest's Package Tranform -* * (C) 2009 Jack Lloyd * * Distributed under the terms of the Botan license @@ -16,12 +15,12 @@ namespace Botan { /** * Rivest's Package Tranform -* @arg rng the random number generator to use -* @arg cipher the block cipher to use -* @arg input the input data buffer -* @arg input_len the length of the input data in bytes -* @arg output the output data buffer (must be at least -* input_len + cipher->BLOCK_SIZE bytes long) +* @param rng the random number generator to use +* @param cipher the block cipher to use +* @param input the input data buffer +* @param input_len the length of the input data in bytes +* @param output the output data buffer (must be at least +* input_len + cipher->BLOCK_SIZE bytes long) */ void BOTAN_DLL aont_package(RandomNumberGenerator& rng, BlockCipher* cipher, @@ -30,12 +29,11 @@ void BOTAN_DLL aont_package(RandomNumberGenerator& rng, /** * Rivest's Package Tranform (Inversion) -* @arg rng the random number generator to use -* @arg cipher the block cipher to use -* @arg input the input data buffer -* @arg input_len the length of the input data in bytes -* @arg output the output data buffer (must be at least -* input_len - cipher->BLOCK_SIZE bytes long) +* @param cipher the block cipher to use +* @param input the input data buffer +* @param input_len the length of the input data in bytes +* @param output the output data buffer (must be at least +* input_len - cipher->BLOCK_SIZE bytes long) */ void BOTAN_DLL aont_unpackage(BlockCipher* cipher, const byte input[], u32bit input_len, diff --git a/src/constructs/fpe/fpe.cpp b/src/constructs/fpe/fpe.cpp index a0b3274b5..4eaff0eb6 100644 --- a/src/constructs/fpe/fpe.cpp +++ b/src/constructs/fpe/fpe.cpp @@ -136,7 +136,7 @@ BigInt FPE_Encryptor::operator()(u32bit round_no, const BigInt& R) } -/** +/* * Generic Z_n FPE encryption, FE1 scheme */ BigInt fpe_encrypt(const BigInt& n, const BigInt& X0, @@ -164,7 +164,7 @@ BigInt fpe_encrypt(const BigInt& n, const BigInt& X0, return X; } -/** +/* * Generic Z_n FPE decryption, FD1 scheme */ BigInt fpe_decrypt(const BigInt& n, const BigInt& X0, diff --git a/src/constructs/fpe/fpe.h b/src/constructs/fpe/fpe.h index 75f90247f..7a4a7861a 100644 --- a/src/constructs/fpe/fpe.h +++ b/src/constructs/fpe/fpe.h @@ -13,15 +13,23 @@ namespace Botan { -/* +/** * Encrypt X from and onto the group Z_n using key and tweak +* @param n the modulus +* @param X the plaintext as a BigInt +* @param key a random key +* @param tweak will modify the ciphertext (think of as an IV) */ BigInt BOTAN_DLL fpe_encrypt(const BigInt& n, const BigInt& X, const SymmetricKey& key, const MemoryRegion<byte>& tweak); -/* +/** * Decrypt X from and onto the group Z_n using key and tweak +* @param n the modulus +* @param X the ciphertext as a BigInt +* @param key is the key used for encryption +* @param tweak the same tweak used for encryption */ BigInt BOTAN_DLL fpe_decrypt(const BigInt& n, const BigInt& X, const SymmetricKey& key, diff --git a/src/engine/def_engine/default_engine.h b/src/engine/def_engine/default_engine.h index f7e6d9746..0d864e514 100644 --- a/src/engine/def_engine/default_engine.h +++ b/src/engine/def_engine/default_engine.h @@ -51,6 +51,13 @@ class Default_Engine : public Engine Algorithm_Factory&) const; }; +/** +* Create a cipher mode filter object +* @param block_cipher a block cipher object +* @param direction are we encrypting or decrypting? +* @param mode the name of the cipher mode to use +* @param padding the mode padding to use (only used for ECB, CBC) +*/ Keyed_Filter* get_cipher_mode(const BlockCipher* block_cipher, Cipher_Dir direction, const std::string& mode, diff --git a/src/entropy/proc_walk/info.txt b/src/entropy/proc_walk/info.txt index fd65d8ffe..9039f0ad9 100644 --- a/src/entropy/proc_walk/info.txt +++ b/src/entropy/proc_walk/info.txt @@ -12,20 +12,17 @@ es_ftw.h aix cygwin darwin -freebsd dragonfly +freebsd hpux hurd irix linux +netbsd openbsd qnx solaris tru64 - -# Doesn't build on 2.0.2/x86 due to libc/libstdc++ header issues; no -# big deal since it has /dev/*random -#netbsd </os> <requires> diff --git a/src/entropy/unix_procs/unix_cmd.h b/src/entropy/unix_procs/unix_cmd.h index 3abca8f37..2dc55f6d7 100644 --- a/src/entropy/unix_procs/unix_cmd.h +++ b/src/entropy/unix_procs/unix_cmd.h @@ -27,8 +27,19 @@ struct Unix_Program Unix_Program(const char* n, u32bit p) { name_and_args = n; priority = p; working = true; } + /** + * The name and arguments for this command + */ std::string name_and_args; + + /** + * Priority: we scan from low to high + */ u32bit priority; + + /** + * Does this source seem to be working? + */ bool working; }; diff --git a/src/filters/buf_filt.h b/src/filters/buf_filt.h index 1ab402df7..3acf1f809 100644 --- a/src/filters/buf_filt.h +++ b/src/filters/buf_filt.h @@ -26,14 +26,27 @@ class BOTAN_DLL Buffered_Filter virtual ~Buffered_Filter() {} protected: + /** + * @return name of this filter object + */ virtual std::string name() const = 0; virtual void buffered_block(const byte input[], u32bit length) = 0; virtual void buffered_final(const byte input[], u32bit length) = 0; + /** + * @return block size of inputs + */ u32bit buffered_block_size() const { return main_block_mod; } + /** + * @return current position in the buffer + */ u32bit current_position() const { return buffer_pos; } + + /** + * Reset the buffer position + */ void buffer_reset() { buffer_pos = 0; } private: u32bit main_block_mod, final_minimum; diff --git a/src/filters/hex/hex.cpp b/src/filters/hex/hex.cpp index 56576a8a0..430958ebd 100644 --- a/src/filters/hex/hex.cpp +++ b/src/filters/hex/hex.cpp @@ -13,6 +13,9 @@ namespace Botan { +/** +* Size used for internal buffer in hex encoder/decoder +*/ const u32bit HEX_CODEC_BUFFER_SIZE = 256; /* diff --git a/src/filters/hex/hex.h b/src/filters/hex/hex.h index 035bf4ef9..b03b933bc 100644 --- a/src/filters/hex/hex.h +++ b/src/filters/hex/hex.h @@ -24,7 +24,7 @@ class BOTAN_DLL Hex_Encoder : public Filter enum Case { Uppercase, Lowercase }; /** - Encode a single byte into two hex characters + * Encode a single byte into two hex characters */ static void encode(byte in, byte out[2], Case the_case = Uppercase); @@ -63,8 +63,19 @@ class BOTAN_DLL Hex_Encoder : public Filter class BOTAN_DLL Hex_Decoder : public Filter { public: - static byte decode(const byte[2]); - static bool is_valid(byte); + /** + * Decode a pair of hex chars to a byte + * @param in an array of two hex chars + * @return byte formed by decoding in + */ + static byte decode(const byte in[2]); + + /** + * Check if this character is a valid hex input + * @param c a single character + * @return true iff c is a valid hex char + */ + static bool is_valid(byte c); void write(const byte[], u32bit); void end_msg(); diff --git a/src/libstate/lookup.h b/src/libstate/lookup.h index 76e06b2de..debcee52b 100644 --- a/src/libstate/lookup.h +++ b/src/libstate/lookup.h @@ -19,12 +19,12 @@ namespace Botan { -/* -* Retrieve an object from the lookup table +/** +* Retrieve an object prototype from the global factory +* @param algo_spec an algorithm name +* @return constant prototype object (use clone to create usable object), + library retains ownership */ -// NOTE: these functions return internally stored objects, library -// retains ownership - inline const BlockCipher* retrieve_block_cipher(const std::string& algo_spec) { @@ -32,6 +32,12 @@ retrieve_block_cipher(const std::string& algo_spec) return af.prototype_block_cipher(algo_spec); } +/** +* Retrieve an object prototype from the global factory +* @param algo_spec an algorithm name +* @return constant prototype object (use clone to create usable object), + library retains ownership +*/ inline const StreamCipher* retrieve_stream_cipher(const std::string& algo_spec) { @@ -39,6 +45,12 @@ retrieve_stream_cipher(const std::string& algo_spec) return af.prototype_stream_cipher(algo_spec); } +/** +* Retrieve an object prototype from the global factory +* @param algo_spec an algorithm name +* @return constant prototype object (use clone to create usable object), + library retains ownership +*/ inline const HashFunction* retrieve_hash(const std::string& algo_spec) { @@ -46,6 +58,12 @@ retrieve_hash(const std::string& algo_spec) return af.prototype_hash_function(algo_spec); } +/** +* Retrieve an object prototype from the global factory +* @param algo_spec an algorithm name +* @return constant prototype object (use clone to create usable object), + library retains ownership +*/ inline const MessageAuthenticationCode* retrieve_mac(const std::string& algo_spec) { diff --git a/src/math/numbertheory/curve_gfp.h b/src/math/numbertheory/curve_gfp.h index 0a91fc52d..8a46a9735 100644 --- a/src/math/numbertheory/curve_gfp.h +++ b/src/math/numbertheory/curve_gfp.h @@ -52,14 +52,12 @@ class BOTAN_DLL CurveGFp // CurveGFp& operator=(const CurveGFp& other) = default; /** - * Get coefficient a - * @return coefficient a + * @return curve coefficient a */ const BigInt& get_a() const { return a; } /** - * Get coefficient b - * @return coefficient b + * @return curve coefficient b */ const BigInt& get_b() const { return b; } @@ -94,11 +92,14 @@ class BOTAN_DLL CurveGFp */ u32bit get_p_words() const { return p_words; } + /** + * @return modular reducer for p + */ const Modular_Reducer& mod_p() const { return reducer_p; } /** * swaps the states of *this and other, does not throw - * @param other The curve to swap values with + * @param other curve to swap values with */ void swap(CurveGFp& other) { @@ -112,6 +113,11 @@ class BOTAN_DLL CurveGFp std::swap(p_dash, other.p_dash); } + /** + * Equality operator + * @param other curve to compare with + * @return true iff this is the same curve as other + */ bool operator==(const CurveGFp& other) const { return (p == other.p && a == other.a && b == other.b); @@ -130,6 +136,12 @@ class BOTAN_DLL CurveGFp Modular_Reducer reducer_p; }; +/** +* Equality operator +* @param lhs a curve +* @param rhs a curve +* @return true iff lhs is not the same as rhs +*/ inline bool operator!=(const CurveGFp& lhs, const CurveGFp& rhs) { return !(lhs == rhs); diff --git a/src/math/numbertheory/numthry.h b/src/math/numbertheory/numthry.h index 9a1005413..1ab64b038 100644 --- a/src/math/numbertheory/numthry.h +++ b/src/math/numbertheory/numthry.h @@ -15,13 +15,31 @@ namespace Botan { /** -* Fused Arithmetic Operation +* Fused multiply-add +* @param a an integer +* @param b an integer +* @param c an integer +* @return (a*b)+c */ -BigInt BOTAN_DLL mul_add(const BigInt&, const BigInt&, const BigInt&); -BigInt BOTAN_DLL sub_mul(const BigInt&, const BigInt&, const BigInt&); +BigInt BOTAN_DLL mul_add(const BigInt& a, + const BigInt& b, + const BigInt& c); -/* -* Number Theory Functions +/** +* Fused subtract-multiply +* @param a an integer +* @param b an integer +* @param c an integer +* @return (a-b)*c +*/ +BigInt BOTAN_DLL sub_mul(const BigInt& a, + const BigInt& b, + const BigInt& c); + +/** +* Return the absolute value +* @param n an integer +* @return absolute value of n */ inline BigInt abs(const BigInt& n) { return n.abs(); } @@ -70,8 +88,14 @@ s32bit BOTAN_DLL jacobi(const BigInt& a, /** * Modular exponentation +* @param b an integer base +* @param x a positive exponent +* @param m a positive modulus +* @return (b^x) % m */ -BigInt BOTAN_DLL power_mod(const BigInt&, const BigInt&, const BigInt&); +BigInt BOTAN_DLL power_mod(const BigInt& b, + const BigInt& x, + const BigInt& m); /** * Compute the square root of x modulo a prime using the @@ -90,55 +114,114 @@ BigInt BOTAN_DLL ressol(const BigInt& x, const BigInt& p); */ u32bit BOTAN_DLL low_zero_bits(const BigInt& x); -/* +/** * Primality Testing +* @param n a positive integer to test for primality +* @param rng a random number generator +* @param level how hard to test +* @return true if all primality tests passed, otherwise false */ bool BOTAN_DLL primality_test(const BigInt& n, RandomNumberGenerator& rng, u32bit level = 1); +/** +* Quickly check for primality +* @param n a positive integer to test for primality +* @param rng a random number generator +* @return true if all primality tests passed, otherwise false +*/ inline bool quick_check_prime(const BigInt& n, RandomNumberGenerator& rng) { return primality_test(n, rng, 0); } +/** +* Check for primality +* @param n a positive integer to test for primality +* @param rng a random number generator +* @return true if all primality tests passed, otherwise false +*/ inline bool check_prime(const BigInt& n, RandomNumberGenerator& rng) { return primality_test(n, rng, 1); } +/** +* Verify primality - this function is slow but useful if you want to +* ensure that a possibly malicious entity did not provide you with +* something that 'looks like' a prime +* @param n a positive integer to test for primality +* @param rng a random number generator +* @return true if all primality tests passed, otherwise false +*/ inline bool verify_prime(const BigInt& n, RandomNumberGenerator& rng) { return primality_test(n, rng, 2); } -/* -* Random Number Generation +/** +* Randomly generate a prime +* @param rng a random number generator +* @param bits how large the resulting prime should be in bits +* @param coprime a positive integer the result should be coprime to +* @param equiv a non-negative number that the result should be + equivalent to modulo equiv_mod +* @param equiv_mod the modulus equiv should be checked against +* @return random prime with the specified criteria */ BigInt BOTAN_DLL random_prime(RandomNumberGenerator& rng, u32bit bits, const BigInt& coprime = 1, u32bit equiv = 1, u32bit equiv_mod = 2); +/** +* Return a 'safe' prime, of the form p=2*q+1 with q prime +* @param rng a random number generator +* @param bits is how long the resulting prime should be +* @return prime randomly chosen from safe primes of length bits +*/ BigInt BOTAN_DLL random_safe_prime(RandomNumberGenerator& rng, u32bit bits); -/* -* DSA Parameter Generation -*/ class Algorithm_Factory; +/** +* Generate DSA parameters using the FIPS 186 kosherizer +* @param rng a random number generator +* @param af an algorithm factory +* @param p_out where the prime p will be stored +* @param q_out where the prime q will be stored +* @param pbits how long p will be in bits +* @param qbits how long q will be in bits +* @return random seed used to generate this parameter set +*/ SecureVector<byte> BOTAN_DLL generate_dsa_primes(RandomNumberGenerator& rng, Algorithm_Factory& af, - BigInt& p, BigInt& q, + BigInt& p_out, BigInt& q_out, u32bit pbits, u32bit qbits); +/** +* Generate DSA parameters using the FIPS 186 kosherizer +* @param rng a random number generator +* @param af an algorithm factory +* @param p_out where the prime p will be stored +* @param q_out where the prime q will be stored +* @param pbits how long p will be in bits +* @param qbits how long q will be in bits +* @param seed the seed used to generate the parameters +* @return true if seed generated a valid DSA parameter set, otherwise + false. p_out and q_out are only valid if true was returned. +*/ bool BOTAN_DLL generate_dsa_primes(RandomNumberGenerator& rng, Algorithm_Factory& af, BigInt& p_out, BigInt& q_out, - u32bit p_bits, u32bit q_bits, + u32bit pbits, u32bit qbits, const MemoryRegion<byte>& seed); -/* -* Prime Numbers +/** +* The size of the PRIMES[] array */ const u32bit PRIME_TABLE_SIZE = 6541; +/** +* A const array of all primes less than 65535 +*/ extern const u16bit BOTAN_DLL PRIMES[]; } diff --git a/src/pk_pad/eme.h b/src/pk_pad/eme.h index 02b8208ef..1bc3ba3c9 100644 --- a/src/pk_pad/eme.h +++ b/src/pk_pad/eme.h @@ -19,22 +19,82 @@ namespace Botan { class BOTAN_DLL EME { public: - virtual u32bit maximum_input_size(u32bit) const = 0; + /** + * Return the maximum input size in bytes we can support + * @param keybits the size of the key in bits + * @return upper bound of input in bytes + */ + virtual u32bit maximum_input_size(u32bit keybits) const = 0; - SecureVector<byte> encode(const byte[], u32bit, u32bit, - RandomNumberGenerator&) const; - SecureVector<byte> encode(const MemoryRegion<byte>&, u32bit, - RandomNumberGenerator&) const; + /** + * Encode an input + * @param in the plaintext + * @param in_length length of plaintext in bytes + * @param key_length length of the key in bits + * @param rng a random number generator + * @return encoded plaintext + */ + SecureVector<byte> encode(const byte in[], + u32bit in_length, + u32bit key_length, + RandomNumberGenerator& rng) const; - SecureVector<byte> decode(const byte[], u32bit, u32bit) const; - SecureVector<byte> decode(const MemoryRegion<byte>&, u32bit) const; + /** + * Encode an input + * @param in the plaintext + * @param key_length length of the key in bits + * @param rng a random number generator + * @return encoded plaintext + */ + SecureVector<byte> encode(const MemoryRegion<byte>& in, + u32bit key_length, + RandomNumberGenerator& rng) const; + + /** + * Decode an input + * @param in the encoded plaintext + * @param in_length length of encoded plaintext in bytes + * @param key_length length of the key in bits + * @return plaintext + */ + SecureVector<byte> decode(const byte in[], + u32bit in_length, + u32bit key_length) const; + + /** + * Decode an input + * @param in the encoded plaintext + * @param key_length length of the key in bits + * @return plaintext + */ + SecureVector<byte> decode(const MemoryRegion<byte>& in, + u32bit key_length) const; virtual ~EME() {} private: - virtual SecureVector<byte> pad(const byte[], u32bit, u32bit, - RandomNumberGenerator&) const = 0; + /** + * Encode an input + * @param in the plaintext + * @param in_length length of plaintext in bytes + * @param key_length length of the key in bits + * @param rng a random number generator + * @return encoded plaintext + */ + virtual SecureVector<byte> pad(const byte in[], + u32bit in_length, + u32bit key_length, + RandomNumberGenerator& rng) const = 0; - virtual SecureVector<byte> unpad(const byte[], u32bit, u32bit) const = 0; + /** + * Decode an input + * @param in the encoded plaintext + * @param in_length length of encoded plaintext in bytes + * @param key_length length of the key in bits + * @return plaintext + */ + virtual SecureVector<byte> unpad(const byte in[], + u32bit in_length, + u32bit key_length) const = 0; }; } diff --git a/src/pk_pad/eme1/eme1.h b/src/pk_pad/eme1/eme1.h index d00eeeeb9..0ecdb279e 100644 --- a/src/pk_pad/eme1/eme1.h +++ b/src/pk_pad/eme1/eme1.h @@ -23,9 +23,8 @@ class BOTAN_DLL EME1 : public EME u32bit maximum_input_size(u32bit) const; /** - EME1 constructor. Hash will be deleted by ~EME1 (when mgf is deleted) - - P is an optional label. Normally empty. + * @param hash object to use for hashing (takes ownership) + * @param P an optional label. Normally empty. */ EME1(HashFunction* hash, const std::string& P = ""); diff --git a/src/pk_pad/emsa.h b/src/pk_pad/emsa.h index 6d01beb7f..372eb836d 100644 --- a/src/pk_pad/emsa.h +++ b/src/pk_pad/emsa.h @@ -19,15 +19,39 @@ namespace Botan { class BOTAN_DLL EMSA { public: - virtual void update(const byte[], u32bit) = 0; + /** + * Add more data to the signature computation + * @param input some data + * @param length length of input in bytes + */ + virtual void update(const byte input[], u32bit length) = 0; + + /** + * @return raw hash + */ virtual SecureVector<byte> raw_data() = 0; - virtual SecureVector<byte> encoding_of(const MemoryRegion<byte>&, - u32bit, + /** + * Return the encoding of a message + * @param msg the result of raw_data() + * @param output_bits the desired output bit size + * @param rng a random number generator + * @return encoded signature + */ + virtual SecureVector<byte> encoding_of(const MemoryRegion<byte>& msg, + u32bit output_bits, RandomNumberGenerator& rng) = 0; - virtual bool verify(const MemoryRegion<byte>&, const MemoryRegion<byte>&, - u32bit) = 0; + /** + * Verify the encoding + * @param coded the received (coded) message representative + * @param raw the computed (local, uncoded) message representative + * @param key_bits the size of the key in bits + * @return true if coded is a valid encoding of raw, otherwise false + */ + virtual bool verify(const MemoryRegion<byte>& coded, + const MemoryRegion<byte>& raw, + u32bit key_bits) = 0; virtual ~EMSA() {} }; diff --git a/src/pk_pad/emsa1/emsa1.h b/src/pk_pad/emsa1/emsa1.h index 28d856525..50fda5273 100644 --- a/src/pk_pad/emsa1/emsa1.h +++ b/src/pk_pad/emsa1/emsa1.h @@ -20,9 +20,15 @@ namespace Botan { class BOTAN_DLL EMSA1 : public EMSA { public: + /** + * @param h the hash object to use + */ EMSA1(HashFunction* h) : hash(h) {} ~EMSA1() { delete hash; } protected: + /** + * @return const pointer to the underlying hash + */ const HashFunction* hash_ptr() const { return hash; } private: void update(const byte[], u32bit); diff --git a/src/pk_pad/emsa1_bsi/emsa1_bsi.h b/src/pk_pad/emsa1_bsi/emsa1_bsi.h index ec86d40e2..a0a3515fb 100644 --- a/src/pk_pad/emsa1_bsi/emsa1_bsi.h +++ b/src/pk_pad/emsa1_bsi/emsa1_bsi.h @@ -21,6 +21,9 @@ implementation comes from InSiTo class BOTAN_DLL EMSA1_BSI : public EMSA1 { public: + /** + * @param hash the hash object to use + */ EMSA1_BSI(HashFunction* hash) : EMSA1(hash) {} private: SecureVector<byte> encoding_of(const MemoryRegion<byte>&, u32bit, diff --git a/src/pk_pad/emsa2/emsa2.h b/src/pk_pad/emsa2/emsa2.h index bda34fbd1..cfb3f9e12 100644 --- a/src/pk_pad/emsa2/emsa2.h +++ b/src/pk_pad/emsa2/emsa2.h @@ -20,6 +20,9 @@ namespace Botan { class BOTAN_DLL EMSA2 : public EMSA { public: + /** + * @param hash the hash object to use + */ EMSA2(HashFunction* hash); ~EMSA2() { delete hash; } private: diff --git a/src/pk_pad/emsa3/emsa3.cpp b/src/pk_pad/emsa3/emsa3.cpp index dc905a464..82981d38c 100644 --- a/src/pk_pad/emsa3/emsa3.cpp +++ b/src/pk_pad/emsa3/emsa3.cpp @@ -12,7 +12,7 @@ namespace Botan { namespace { -/** +/* * EMSA3 Encode Operation */ SecureVector<byte> emsa3_encoding(const MemoryRegion<byte>& msg, @@ -37,7 +37,7 @@ SecureVector<byte> emsa3_encoding(const MemoryRegion<byte>& msg, } -/** +/* * EMSA3 Update Operation */ void EMSA3::update(const byte input[], u32bit length) @@ -45,7 +45,7 @@ void EMSA3::update(const byte input[], u32bit length) hash->update(input, length); } -/** +/* * Return the raw (unencoded) data */ SecureVector<byte> EMSA3::raw_data() @@ -53,7 +53,7 @@ SecureVector<byte> EMSA3::raw_data() return hash->final(); } -/** +/* * EMSA3 Encode Operation */ SecureVector<byte> EMSA3::encoding_of(const MemoryRegion<byte>& msg, @@ -67,7 +67,7 @@ SecureVector<byte> EMSA3::encoding_of(const MemoryRegion<byte>& msg, hash_id, hash_id.size()); } -/** +/* * Default signature decoding */ bool EMSA3::verify(const MemoryRegion<byte>& coded, @@ -88,7 +88,7 @@ bool EMSA3::verify(const MemoryRegion<byte>& coded, } } -/** +/* * EMSA3 Constructor */ EMSA3::EMSA3(HashFunction* hash_in) : hash(hash_in) @@ -96,7 +96,7 @@ EMSA3::EMSA3(HashFunction* hash_in) : hash(hash_in) hash_id = pkcs_hash_id(hash->name()); } -/** +/* * EMSA3 Destructor */ EMSA3::~EMSA3() @@ -104,7 +104,7 @@ EMSA3::~EMSA3() delete hash; } -/** +/* * EMSA3_Raw Update Operation */ void EMSA3_Raw::update(const byte input[], u32bit length) @@ -112,7 +112,7 @@ void EMSA3_Raw::update(const byte input[], u32bit length) message.append(input, length); } -/** +/* * Return the raw (unencoded) data */ SecureVector<byte> EMSA3_Raw::raw_data() @@ -122,7 +122,7 @@ SecureVector<byte> EMSA3_Raw::raw_data() return ret; } -/** +/* * EMSA3_Raw Encode Operation */ SecureVector<byte> EMSA3_Raw::encoding_of(const MemoryRegion<byte>& msg, @@ -132,7 +132,7 @@ SecureVector<byte> EMSA3_Raw::encoding_of(const MemoryRegion<byte>& msg, return emsa3_encoding(msg, output_bits, 0, 0); } -/** +/* * Default signature decoding */ bool EMSA3_Raw::verify(const MemoryRegion<byte>& coded, diff --git a/src/pk_pad/emsa3/emsa3.h b/src/pk_pad/emsa3/emsa3.h index 1e080aab6..09c1e40cc 100644 --- a/src/pk_pad/emsa3/emsa3.h +++ b/src/pk_pad/emsa3/emsa3.h @@ -21,7 +21,10 @@ namespace Botan { class BOTAN_DLL EMSA3 : public EMSA { public: - EMSA3(HashFunction*); + /** + * @param hash the hash object to use + */ + EMSA3(HashFunction* hash); ~EMSA3(); void update(const byte[], u32bit); diff --git a/src/pk_pad/emsa4/emsa4.h b/src/pk_pad/emsa4/emsa4.h index 6315c424e..7dfc3892a 100644 --- a/src/pk_pad/emsa4/emsa4.h +++ b/src/pk_pad/emsa4/emsa4.h @@ -20,8 +20,16 @@ namespace Botan { class BOTAN_DLL EMSA4 : public EMSA { public: - EMSA4(HashFunction*); - EMSA4(HashFunction*, u32bit); + /** + * @param hash the hash object to use + */ + EMSA4(HashFunction* hash); + + /** + * @param hash the hash object to use + * @param salt_size the size of the salt to use in bytes + */ + EMSA4(HashFunction* hash, u32bit salt_size); ~EMSA4() { delete hash; delete mgf; } private: diff --git a/src/pk_pad/hash_id/hash_id.cpp b/src/pk_pad/hash_id/hash_id.cpp index 203c27f14..173f02a6d 100644 --- a/src/pk_pad/hash_id/hash_id.cpp +++ b/src/pk_pad/hash_id/hash_id.cpp @@ -54,10 +54,8 @@ const byte TIGER_PKCS_ID[] = { } -/** -* @return HashID as specified by PKCS -* For details see RFC 3447 section 9.2 -* http://tools.ietf.org/html/rfc3447#section-9.2 +/* +* HashID as specified by PKCS */ MemoryVector<byte> pkcs_hash_id(const std::string& name) { @@ -94,8 +92,8 @@ MemoryVector<byte> pkcs_hash_id(const std::string& name) throw Invalid_Argument("No PKCS #1 identifier for " + name); } -/** -* @return HashID as specified by IEEE 1363/X9.31 +/* +* HashID as specified by IEEE 1363/X9.31 */ byte ieee1363_hash_id(const std::string& name) { diff --git a/src/pk_pad/hash_id/hash_id.h b/src/pk_pad/hash_id/hash_id.h index 847d9106c..909cc6b19 100644 --- a/src/pk_pad/hash_id/hash_id.h +++ b/src/pk_pad/hash_id/hash_id.h @@ -13,11 +13,21 @@ namespace Botan { -/* -* Return the values of various defined HashIDs +/** +* Return the PKCS #1 hash identifier +* @see RFC 3447 section 9.2 +* @param hash_name the name of the hash function +* @return byte sequence identifying the hash +* @throw Invalid_Argument if the hash has no known PKCS #1 hash id +*/ +BOTAN_DLL MemoryVector<byte> pkcs_hash_id(const std::string& hash_name); + +/** +* Return the IEEE 1363 hash identifier +* @param hash_name the name of the hash function +* @return byte code identifying the hash, or 0 if not known */ -BOTAN_DLL MemoryVector<byte> pkcs_hash_id(const std::string&); -BOTAN_DLL byte ieee1363_hash_id(const std::string&); +BOTAN_DLL byte ieee1363_hash_id(const std::string& hash_name); } diff --git a/src/pubkey/dl_algo/dl_algo.h b/src/pubkey/dl_algo/dl_algo.h index 429bfb554..2cc632caa 100644 --- a/src/pubkey/dl_algo/dl_algo.h +++ b/src/pubkey/dl_algo/dl_algo.h @@ -67,7 +67,15 @@ class BOTAN_DLL DL_Scheme_PublicKey : public virtual Public_Key protected: DL_Scheme_PublicKey() {} + + /** + * The DL public key + */ BigInt y; + + /** + * The DL group + */ DL_Group group; }; @@ -94,6 +102,10 @@ class BOTAN_DLL DL_Scheme_PrivateKey : public virtual DL_Scheme_PublicKey, protected: DL_Scheme_PrivateKey() {} + + /** + * The DL private key + */ BigInt x; }; diff --git a/src/pubkey/pkcs8.h b/src/pubkey/pkcs8.h index 3da96d840..376429d5b 100644 --- a/src/pubkey/pkcs8.h +++ b/src/pubkey/pkcs8.h @@ -22,6 +22,9 @@ struct BOTAN_DLL PKCS8_Exception : public Decoding_Error Decoding_Error("PKCS #8: " + error) {} }; +/** +* This namespace contains functions for handling PKCS #8 private keys +*/ namespace PKCS8 { /** diff --git a/src/selftest/selftest.h b/src/selftest/selftest.h index df71e6f8e..091206579 100644 --- a/src/selftest/selftest.h +++ b/src/selftest/selftest.h @@ -15,13 +15,28 @@ namespace Botan { -/* -* Self Tests +/** +* Run a set of self tests on some basic algorithms like AES and SHA-1 +* @param af an algorithm factory +* @throws Self_Test_Error if a failure occured */ BOTAN_DLL void confirm_startup_self_tests(Algorithm_Factory& af); +/** +* Run a set of self tests on some basic algorithms like AES and SHA-1 +* @param af an algorithm factory +* @returns false if a failure occured, otherwise true +*/ BOTAN_DLL bool passes_self_tests(Algorithm_Factory& af); +/** +* Run a set of algorithm KATs (known answer tests) +* @param algo_name the algorithm we are testing +* @param vars a set of input variables for this test, all + hex encoded. Keys used: "input", "output", "key", and "iv" +* @param af an algorithm factory +* @returns map from provider name to test result for that provider +*/ BOTAN_DLL std::map<std::string, bool> algorithm_kat(const SCAN_Name& algo_name, const std::map<std::string, std::string>& vars, diff --git a/src/sym_algo/symkey.h b/src/sym_algo/symkey.h index 450dab306..07b588329 100644 --- a/src/sym_algo/symkey.h +++ b/src/sym_algo/symkey.h @@ -140,10 +140,15 @@ BOTAN_DLL OctetString operator+(const OctetString& x, BOTAN_DLL OctetString operator^(const OctetString& x, const OctetString& y); -/* -* Alternate Names + +/** +* Alternate name for octet string showing intent to use as a key */ typedef OctetString SymmetricKey; + +/** +* Alternate name for octet string showing intent to use as an IV +*/ typedef OctetString InitializationVector; } diff --git a/src/utils/bit_ops.h b/src/utils/bit_ops.h index c02ec536f..36bac9f73 100644 --- a/src/utils/bit_ops.h +++ b/src/utils/bit_ops.h @@ -12,9 +12,10 @@ namespace Botan { -/* -* Return true iff arg is 2**n for some n > 0 -* T should be an unsigned integer type +/** +* Power of 2 test. T should be an unsigned integer type +* @param arg an integer value +* @return true iff arg is 2^n for some n > 0 */ template<typename T> inline bool power_of_2(T arg) @@ -22,9 +23,11 @@ inline bool power_of_2(T arg) return ((arg != 0 && arg != 1) && ((arg & (arg-1)) == 0)); } -/* +/** * Return the index of the highest set bit * T is an unsigned integer type +* @param n an integer value +* @return index of the highest set bit in n */ template<typename T> inline u32bit high_bit(T n) @@ -35,8 +38,11 @@ inline u32bit high_bit(T n) return 0; } -/* +/** * Return the index of the lowest set bit +* T is an unsigned integer type +* @param n an integer value +* @return index of the lowest set bit in n */ template<typename T> inline u32bit low_bit(T n) @@ -47,8 +53,10 @@ inline u32bit low_bit(T n) return 0; } -/* +/** * Return the number of significant bytes in n +* @param n an integer value +* @return number of significant bytes in n */ template<typename T> inline u32bit significant_bytes(T n) @@ -59,8 +67,10 @@ inline u32bit significant_bytes(T n) return 0; } -/* -* Return the Hamming weight of n +/** +* Compute Hamming weights +* @param n an integer value +* @return number of bits in n set to 1 */ template<typename T> inline u32bit hamming_weight(T n) @@ -74,8 +84,10 @@ inline u32bit hamming_weight(T n) return weight; } -/* +/** * Count the trailing zero bits in n +* @param n an integer value +* @return maximum x st 2^x divides n */ template<typename T> inline u32bit ctz(T n) diff --git a/src/utils/cpuid.h b/src/utils/cpuid.h index a41e932fb..dbac89455 100644 --- a/src/utils/cpuid.h +++ b/src/utils/cpuid.h @@ -18,15 +18,6 @@ namespace Botan { class BOTAN_DLL CPUID { public: - enum CPUID_bits { - CPUID_RDTSC_BIT = 4, - CPUID_SSE2_BIT = 26, - CPUID_SSSE3_BIT = 41, - CPUID_SSE41_BIT = 51, - CPUID_SSE42_BIT = 52, - CPUID_INTEL_AES_BIT = 57 - }; - /** * Return a best guess of the cache line size */ @@ -73,6 +64,15 @@ class BOTAN_DLL CPUID */ static bool has_altivec(); private: + enum CPUID_bits { + CPUID_RDTSC_BIT = 4, + CPUID_SSE2_BIT = 26, + CPUID_SSSE3_BIT = 41, + CPUID_SSE41_BIT = 51, + CPUID_SSE42_BIT = 52, + CPUID_INTEL_AES_BIT = 57 + }; + static u64bit x86_processor_flags(); }; diff --git a/src/utils/get_byte.h b/src/utils/get_byte.h index fce87af83..7eedbd783 100644 --- a/src/utils/get_byte.h +++ b/src/utils/get_byte.h @@ -12,8 +12,11 @@ namespace Botan { -/* -* Byte Extraction Function +/** +* Byte extraction +* @param byte_num which byte to extract, 0 == highest byte +* @param input the value to extract from +* @return byte byte_num of input */ template<typename T> inline byte get_byte(u32bit byte_num, T input) { diff --git a/src/utils/loadstor.h b/src/utils/loadstor.h index ffd27540d..e812fca4e 100644 --- a/src/utils/loadstor.h +++ b/src/utils/loadstor.h @@ -38,14 +38,25 @@ namespace Botan { -/* -* Byte to Word Conversions +/** +* Make a u16bit from two bytes +* @param i0 the first byte +* @param i1 the second byte +* @return i0 || i1 */ inline u16bit make_u16bit(byte i0, byte i1) { return ((static_cast<u16bit>(i0) << 8) | i1); } +/** +* Make a u32bit from four bytes +* @param i0 the first byte +* @param i1 the second byte +* @param i2 the third byte +* @param i3 the fourth byte +* @return i0 || i1 || i2 || i3 +*/ inline u32bit make_u32bit(byte i0, byte i1, byte i2, byte i3) { return ((static_cast<u32bit>(i0) << 24) | @@ -54,6 +65,18 @@ inline u32bit make_u32bit(byte i0, byte i1, byte i2, byte i3) (static_cast<u32bit>(i3))); } +/** +* Make a u32bit from eight bytes +* @param i0 the first byte +* @param i1 the second byte +* @param i2 the third byte +* @param i3 the fourth byte +* @param i4 the fifth byte +* @param i5 the sixth byte +* @param i6 the seventh byte +* @param i7 the eighth byte +* @return i0 || i1 || i2 || i3 || i4 || i5 || i6 || i7 +*/ inline u64bit make_u64bit(byte i0, byte i1, byte i2, byte i3, byte i4, byte i5, byte i6, byte i7) { @@ -67,8 +90,11 @@ inline u64bit make_u64bit(byte i0, byte i1, byte i2, byte i3, (static_cast<u64bit>(i7))); } -/* -* Endian-Specific Word Loading Operations +/** +* Load a big-endian word +* @param in a pointer to some bytes +* @param off an offset into the array +* @return off'th T of in, as a big-endian value */ template<typename T> inline T load_be(const byte in[], u32bit off) @@ -80,6 +106,12 @@ inline T load_be(const byte in[], u32bit off) return out; } +/** +* Load a little-endian word +* @param in a pointer to some bytes +* @param off an offset into the array +* @return off'th T of in, as a litte-endian value +*/ template<typename T> inline T load_le(const byte in[], u32bit off) { @@ -90,6 +122,12 @@ inline T load_le(const byte in[], u32bit off) return out; } +/** +* Load a big-endian u16bit +* @param in a pointer to some bytes +* @param off an offset into the array +* @return off'th u16bit of in, as a big-endian value +*/ template<> inline u16bit load_be<u16bit>(const byte in[], u32bit off) { @@ -101,6 +139,12 @@ inline u16bit load_be<u16bit>(const byte in[], u32bit off) #endif } +/** +* Load a little-endian u16bit +* @param in a pointer to some bytes +* @param off an offset into the array +* @return off'th u16bit of in, as a little-endian value +*/ template<> inline u16bit load_le<u16bit>(const byte in[], u32bit off) { @@ -112,6 +156,12 @@ inline u16bit load_le<u16bit>(const byte in[], u32bit off) #endif } +/** +* Load a big-endian u32bit +* @param in a pointer to some bytes +* @param off an offset into the array +* @return off'th u32bit of in, as a big-endian value +*/ template<> inline u32bit load_be<u32bit>(const byte in[], u32bit off) { @@ -123,6 +173,12 @@ inline u32bit load_be<u32bit>(const byte in[], u32bit off) #endif } +/** +* Load a little-endian u32bit +* @param in a pointer to some bytes +* @param off an offset into the array +* @return off'th u32bit of in, as a little-endian value +*/ template<> inline u32bit load_le<u32bit>(const byte in[], u32bit off) { @@ -134,6 +190,12 @@ inline u32bit load_le<u32bit>(const byte in[], u32bit off) #endif } +/** +* Load a big-endian u64bit +* @param in a pointer to some bytes +* @param off an offset into the array +* @return off'th u64bit of in, as a big-endian value +*/ template<> inline u64bit load_be<u64bit>(const byte in[], u32bit off) { @@ -146,6 +208,12 @@ inline u64bit load_be<u64bit>(const byte in[], u32bit off) #endif } +/** +* Load a little-endian u64bit +* @param in a pointer to some bytes +* @param off an offset into the array +* @return off'th u64bit of in, as a little-endian value +*/ template<> inline u64bit load_le<u64bit>(const byte in[], u32bit off) { @@ -158,6 +226,12 @@ inline u64bit load_le<u64bit>(const byte in[], u32bit off) #endif } +/** +* Load two little-endian words +* @param in a pointer to some bytes +* @param x0 where the first word will be written +* @param x1 where the second word will be written +*/ template<typename T> inline void load_le(const byte in[], T& x0, T& x1) { @@ -165,6 +239,14 @@ inline void load_le(const byte in[], T& x0, T& x1) x1 = load_le<T>(in, 1); } +/** +* Load four little-endian words +* @param in a pointer to some bytes +* @param x0 where the first word will be written +* @param x1 where the second word will be written +* @param x2 where the third word will be written +* @param x3 where the fourth word will be written +*/ template<typename T> inline void load_le(const byte in[], T& x0, T& x1, T& x2, T& x3) @@ -175,6 +257,18 @@ inline void load_le(const byte in[], x3 = load_le<T>(in, 3); } +/** +* Load eight little-endian words +* @param in a pointer to some bytes +* @param x0 where the first word will be written +* @param x1 where the second word will be written +* @param x2 where the third word will be written +* @param x3 where the fourth word will be written +* @param x4 where the fifth word will be written +* @param x5 where the sixth word will be written +* @param x6 where the seventh word will be written +* @param x7 where the eighth word will be written +*/ template<typename T> inline void load_le(const byte in[], T& x0, T& x1, T& x2, T& x3, @@ -190,6 +284,12 @@ inline void load_le(const byte in[], x7 = load_le<T>(in, 7); } +/** +* Load a variable number of little-endian words +* @param out the output array of words +* @param in the input array of bytes +* @param count how many words are in in +*/ template<typename T> inline void load_le(T out[], const byte in[], @@ -215,6 +315,12 @@ inline void load_le(T out[], #endif } +/** +* Load two big-endian words +* @param in a pointer to some bytes +* @param x0 where the first word will be written +* @param x1 where the second word will be written +*/ template<typename T> inline void load_be(const byte in[], T& x0, T& x1) { @@ -222,6 +328,14 @@ inline void load_be(const byte in[], T& x0, T& x1) x1 = load_be<T>(in, 1); } +/** +* Load four big-endian words +* @param in a pointer to some bytes +* @param x0 where the first word will be written +* @param x1 where the second word will be written +* @param x2 where the third word will be written +* @param x3 where the fourth word will be written +*/ template<typename T> inline void load_be(const byte in[], T& x0, T& x1, T& x2, T& x3) @@ -232,6 +346,18 @@ inline void load_be(const byte in[], x3 = load_be<T>(in, 3); } +/** +* Load eight big-endian words +* @param in a pointer to some bytes +* @param x0 where the first word will be written +* @param x1 where the second word will be written +* @param x2 where the third word will be written +* @param x3 where the fourth word will be written +* @param x4 where the fifth word will be written +* @param x5 where the sixth word will be written +* @param x6 where the seventh word will be written +* @param x7 where the eighth word will be written +*/ template<typename T> inline void load_be(const byte in[], T& x0, T& x1, T& x2, T& x3, @@ -247,6 +373,12 @@ inline void load_be(const byte in[], x7 = load_be<T>(in, 7); } +/** +* Load a variable number of big-endian words +* @param out the output array of words +* @param in the input array of bytes +* @param count how many words are in in +*/ template<typename T> inline void load_be(T out[], const byte in[], @@ -272,8 +404,10 @@ inline void load_be(T out[], #endif } -/* -* Endian-Specific Word Storing Operations +/** +* Store a big-endian u16bit +* @param in the input u16bit +* @param out the byte array to write to */ inline void store_be(u16bit in, byte out[2]) { @@ -285,6 +419,11 @@ inline void store_be(u16bit in, byte out[2]) #endif } +/** +* Store a little-endian u16bit +* @param in the input u16bit +* @param out the byte array to write to +*/ inline void store_le(u16bit in, byte out[2]) { #if BOTAN_TARGET_UNALIGNED_MEMORY_ACCESS_OK @@ -295,6 +434,11 @@ inline void store_le(u16bit in, byte out[2]) #endif } +/** +* Store a big-endian u32bit +* @param in the input u32bit +* @param out the byte array to write to +*/ inline void store_be(u32bit in, byte out[4]) { #if BOTAN_TARGET_UNALIGNED_MEMORY_ACCESS_OK @@ -307,6 +451,11 @@ inline void store_be(u32bit in, byte out[4]) #endif } +/** +* Store a little-endian u32bit +* @param in the input u32bit +* @param out the byte array to write to +*/ inline void store_le(u32bit in, byte out[4]) { #if BOTAN_TARGET_UNALIGNED_MEMORY_ACCESS_OK @@ -319,6 +468,11 @@ inline void store_le(u32bit in, byte out[4]) #endif } +/** +* Store a big-endian u64bit +* @param in the input u64bit +* @param out the byte array to write to +*/ inline void store_be(u64bit in, byte out[8]) { #if BOTAN_TARGET_UNALIGNED_MEMORY_ACCESS_OK @@ -335,6 +489,11 @@ inline void store_be(u64bit in, byte out[8]) #endif } +/** +* Store a little-endian u64bit +* @param in the input u64bit +* @param out the byte array to write to +*/ inline void store_le(u64bit in, byte out[8]) { #if BOTAN_TARGET_UNALIGNED_MEMORY_ACCESS_OK @@ -351,6 +510,12 @@ inline void store_le(u64bit in, byte out[8]) #endif } +/** +* Store two little-endian words +* @param out the output byte array +* @param x0 the first word +* @param x1 the second word +*/ template<typename T> inline void store_le(byte out[], T x0, T x1) { @@ -358,6 +523,12 @@ inline void store_le(byte out[], T x0, T x1) store_le(x1, out + (1 * sizeof(T))); } +/** +* Store two big-endian words +* @param out the output byte array +* @param x0 the first word +* @param x1 the second word +*/ template<typename T> inline void store_be(byte out[], T x0, T x1) { @@ -365,6 +536,14 @@ inline void store_be(byte out[], T x0, T x1) store_be(x1, out + (1 * sizeof(T))); } +/** +* Store four little-endian words +* @param out the output byte array +* @param x0 the first word +* @param x1 the second word +* @param x2 the third word +* @param x3 the fourth word +*/ template<typename T> inline void store_le(byte out[], T x0, T x1, T x2, T x3) { @@ -374,6 +553,14 @@ inline void store_le(byte out[], T x0, T x1, T x2, T x3) store_le(x3, out + (3 * sizeof(T))); } +/** +* Store four big-endian words +* @param out the output byte array +* @param x0 the first word +* @param x1 the second word +* @param x2 the third word +* @param x3 the fourth word +*/ template<typename T> inline void store_be(byte out[], T x0, T x1, T x2, T x3) { @@ -383,6 +570,18 @@ inline void store_be(byte out[], T x0, T x1, T x2, T x3) store_be(x3, out + (3 * sizeof(T))); } +/** +* Store eight little-endian words +* @param out the output byte array +* @param x0 the first word +* @param x1 the second word +* @param x2 the third word +* @param x3 the fourth word +* @param x4 the fifth word +* @param x5 the sixth word +* @param x6 the seventh word +* @param x7 the eighth word +*/ template<typename T> inline void store_le(byte out[], T x0, T x1, T x2, T x3, T x4, T x5, T x6, T x7) @@ -397,6 +596,18 @@ inline void store_le(byte out[], T x0, T x1, T x2, T x3, store_le(x7, out + (7 * sizeof(T))); } +/** +* Store eight big-endian words +* @param out the output byte array +* @param x0 the first word +* @param x1 the second word +* @param x2 the third word +* @param x3 the fourth word +* @param x4 the fifth word +* @param x5 the sixth word +* @param x6 the seventh word +* @param x7 the eighth word +*/ template<typename T> inline void store_be(byte out[], T x0, T x1, T x2, T x3, T x4, T x5, T x6, T x7) diff --git a/src/utils/mem_ops.h b/src/utils/mem_ops.h index 0fcf34ba8..503be90b3 100644 --- a/src/utils/mem_ops.h +++ b/src/utils/mem_ops.h @@ -13,18 +13,47 @@ namespace Botan { -/* -* Memory Manipulation Functions +/** +* Copy memory +* @param out the destination array +* @param in the source array +* @param n the number of elements of in/out */ template<typename T> inline void copy_mem(T* out, const T* in, u32bit n) - { std::memmove(out, in, sizeof(T)*n); } + { + std::memmove(out, in, sizeof(T)*n); + } +/** +* Zeroize memory +* @param ptr a pointer to an array +* @param n the number of Ts pointed to by ptr +*/ template<typename T> inline void clear_mem(T* ptr, u32bit n) - { if(n) std::memset(ptr, 0, sizeof(T)*n); } + { + if(n) // avoid glibc warning if n == 0 + std::memset(ptr, 0, sizeof(T)*n); + } -template<typename T> inline void set_mem(T* ptr, u32bit n, byte val) - { std::memset(ptr, val, sizeof(T)*n); } +/** +* Set memory to a fixed value +* @param ptr a pointer to an array +* @param n the number of Ts pointed to by ptr +* @param val the value to set each byte to +*/ +template<typename T> +inline void set_mem(T* ptr, u32bit n, byte val) + { + std::memset(ptr, val, sizeof(T)*n); + } +/** +* Memory comparison, input insensitive +* @param p1 a pointer to an array +* @param p2 a pointer to another array +* @param n the number of Ts in p1 and p2 +* @return true iff p1[i] == p2[i] forall i in [0...n) +*/ template<typename T> inline bool same_mem(const T* p1, const T* p2, u32bit n) { bool is_same = true; diff --git a/src/utils/time.cpp b/src/utils/time.cpp index 4fea41c52..d5b74828b 100644 --- a/src/utils/time.cpp +++ b/src/utils/time.cpp @@ -35,7 +35,7 @@ namespace Botan { namespace { -/** +/* * Combine a two time values into a single one */ u64bit combine_timers(u32bit seconds, u32bit parts, u32bit parts_hz) diff --git a/src/utils/time.h b/src/utils/time.h index c7a7e0e1a..516efba3e 100644 --- a/src/utils/time.h +++ b/src/utils/time.h @@ -18,11 +18,24 @@ namespace Botan { */ struct BOTAN_DLL calendar_point { + /** The year */ u32bit year; + + /** The month, 1 through 12 for Jan to Dec */ byte month; + + /** The day of the month, 1 through 31 (or 28 or 30 based on month */ byte day; + + /** Hour in 24-hour form, 0 to 23 */ byte hour; + + /** Minutes in the hour, 0 to 60 */ byte minutes; + + /** Seconds in the minute, 0 to 60, but might be slightly + larger to deal with leap seconds on some systems + */ byte seconds; /** diff --git a/src/utils/types.h b/src/utils/types.h index 304628d02..58fdb5ff8 100644 --- a/src/utils/types.h +++ b/src/utils/types.h @@ -10,14 +10,34 @@ #include <botan/build.h> +/** +* The primary namespace for the botan library +*/ namespace Botan { +/** +* Typedef representing an unsigned 8-bit quantity +*/ typedef unsigned char byte; + +/** +* Typedef representing an unsigned 16-bit quantity +*/ typedef unsigned short u16bit; + +/** +* Typedef representing an unsigned 32-bit quantity +*/ typedef unsigned int u32bit; +/** +* Typedef representing a signed 32-bit quantity +*/ typedef signed int s32bit; +/** +* Typedef representing an unsigned 64-bit quantity +*/ #if defined(_MSC_VER) || defined(__BORLANDC__) typedef unsigned __int64 u64bit; #elif defined(__KCC) @@ -28,6 +48,9 @@ typedef signed int s32bit; typedef unsigned long long u64bit; #endif +/** +* A default buffer size; typically a memory page +*/ static const u32bit DEFAULT_BUFFERSIZE = BOTAN_DEFAULT_BUFFER_SIZE; } |