diff options
| -rw-r--r-- | src/core/data_src.h | 105 | ||||
| -rw-r--r-- | src/filters/basefilt.h | 67 | ||||
| -rw-r--r-- | src/filters/filter.h | 47 | ||||
| -rw-r--r-- | src/filters/filters.h | 83 | ||||
| -rw-r--r-- | src/pubkey/pubkey/pk_keys.h | 100 |
5 files changed, 323 insertions, 79 deletions
diff --git a/src/core/data_src.h b/src/core/data_src.h index f7285e8fb..d250addfc 100644 --- a/src/core/data_src.h +++ b/src/core/data_src.h @@ -11,20 +11,67 @@ namespace Botan { -/************************************************* -* Generic DataSource Interface * -*************************************************/ +/** +* This class represents an abstract data source object. +*/ class BOTAN_DLL DataSource { public: - virtual u32bit read(byte[], u32bit) = 0; - virtual u32bit peek(byte[], u32bit, u32bit) const = 0; + /** + * Read from the source. Moves the internal offset so that + * every call to read will return a new portion of the source. + * @param out the byte array to write the result to + * @param length the length of the byte array out + * @return the length in bytes that was actually read and put + * into out + */ + virtual u32bit read(byte out[], u32bit length) = 0; + + /** + * Read from the source but do not modify the internal offset. Consecutive + * calls to peek() will return portions of the source starting at the same + * position. + * @param out the byte array to write the output to + * @param length the length of the byte array out + * @return the length in bytes that was actually read and put + * into out + */ + virtual u32bit peek(byte out[], u32bit length, + u32bit peek_offset) const = 0; + + /** + * Test whether the source still has data that can be read. + * @return true if there is still data to read, false otherwise + */ virtual bool end_of_data() const = 0; + /** + * return the id of this data source + * @return the std::string representing the id of this data source + */ virtual std::string id() const { return ""; } - u32bit read_byte(byte&); - u32bit peek_byte(byte&) const; - u32bit discard_next(u32bit); + /** + * Read one byte. + * @param the byte to read to + * @return the length in bytes that was actually read and put + * into out + */ + u32bit read_byte(byte& out); + + /** + * Peek at one byte. + * @param the byte to read to + * @return the length in bytes that was actually read and put + * into out + */ + u32bit peek_byte(byte& out) const; + + /** + * Discard the next N bytes of the data + * @param N the number of bytes to discard + * @return the number of bytes actually discarded + */ + u32bit discard_next(u32bit N); DataSource() {} virtual ~DataSource() {} @@ -33,9 +80,9 @@ class BOTAN_DLL DataSource DataSource(const DataSource&); }; -/************************************************* -* Memory-Based DataSource * -*************************************************/ +/** +* This class represents a Memory-Based DataSource +*/ class BOTAN_DLL DataSource_Memory : public DataSource { public: @@ -43,17 +90,32 @@ class BOTAN_DLL DataSource_Memory : public DataSource u32bit peek(byte[], u32bit, u32bit) const; bool end_of_data() const; - DataSource_Memory(const std::string&); - DataSource_Memory(const byte[], u32bit); - DataSource_Memory(const MemoryRegion<byte>&); + /** + * Construct a memory source that reads from a string + * @param in the string to read from + */ + DataSource_Memory(const std::string& in); + + /** + * Construct a memory source that reads from a byte array + * @param in the byte array to read from + * @param length the length of the byte array + */ + DataSource_Memory(const byte in[], u32bit length); + + /** + * Construct a memory source that reads from a MemoryRegion + * @param in the MemoryRegion to read from + */ + DataSource_Memory(const MemoryRegion<byte>& in); private: SecureVector<byte> source; u32bit offset; }; -/************************************************* -* Stream-Based DataSource * -*************************************************/ +/** +* This class represents a Stream-Based DataSource. +*/ class BOTAN_DLL DataSource_Stream : public DataSource { public: @@ -63,7 +125,14 @@ class BOTAN_DLL DataSource_Stream : public DataSource std::string id() const; DataSource_Stream(std::istream&, const std::string& id = ""); - DataSource_Stream(const std::string&, bool = false); + + /** + * Construct a Stream-Based DataSource from file + * @param file the name of the file + * @param use_binary whether to treat the file as binary or not + */ + DataSource_Stream(const std::string& file, bool use_binary = false); + ~DataSource_Stream(); private: const std::string identifier; diff --git a/src/filters/basefilt.h b/src/filters/basefilt.h index d6c5b1e0b..975ed5ca0 100644 --- a/src/filters/basefilt.h +++ b/src/filters/basefilt.h @@ -10,40 +10,81 @@ namespace Botan { -/************************************************* -* Chain * -*************************************************/ +/** +* This class represents Filter chains. A Filter chain is an ordered +* concatenation of Filters, the input to a Chain sequentially passes +* through all the Filters contained in the Chain. +*/ + class BOTAN_DLL Chain : public Fanout_Filter { public: void write(const byte input[], u32bit length) { send(input, length); } + /** + * Construct a chain of up to four filters. The filters are set up in the same order + * as the arguments. + */ Chain(Filter* = 0, Filter* = 0, Filter* = 0, Filter* = 0); - Chain(Filter*[], u32bit); + + /** + * Construct a chain from range of filters + * @param filter_arr the list of filters + * @param length how many filters + */ + Chain(Filter* filter_arr[], u32bit length); }; -/************************************************* -* Fork * -*************************************************/ +/** +* This class represents a fork filter, whose purpose is to fork the +* flow of data. It causes an input message to result in n messages at +* the end of the filter, where n is the number of forks. +*/ class BOTAN_DLL Fork : public Fanout_Filter { public: void write(const byte input[], u32bit length) { send(input, length); } void set_port(u32bit n) { Fanout_Filter::set_port(n); } + /** + * Construct a Fork filter with up to four forks. + */ Fork(Filter*, Filter*, Filter* = 0, Filter* = 0); - Fork(Filter*[], u32bit); + + /** + * Construct a Fork from range of filters + * @param filter_arr the list of filters + * @param length how many filters + */ + Fork(Filter* filter_arr[], u32bit length); }; -/************************************************* -* Keyed Filter * -*************************************************/ +/** +* This class represents keyed filters, i.e. filters that have to be +* fed with a key in order to function. +*/ class BOTAN_DLL Keyed_Filter : public Filter { public: - virtual void set_key(const SymmetricKey&); + + /** + * Set the key of this filter. + * @param key the key to set + */ + virtual void set_key(const SymmetricKey& key); + + /** + * Set the initialization vector of this filter. + * @param iv the initialization vector to set + */ virtual void set_iv(const InitializationVector&) {} - virtual bool valid_keylength(u32bit) const; + + /** + * Check whether a key length is valid for this filter. + * @param length the key length to be checked for validity + * @return true if the key length is valid, false otherwise + */ + virtual bool valid_keylength(u32bit length) const; Keyed_Filter() { base_ptr = 0; } protected: diff --git a/src/filters/filter.h b/src/filters/filter.h index c73bda1be..51db50a57 100644 --- a/src/filters/filter.h +++ b/src/filters/filter.h @@ -11,18 +11,49 @@ namespace Botan { -/************************************************* -* Filter Base Class * -*************************************************/ +/** +* This class represents general abstract filter objects. +*/ class BOTAN_DLL Filter { public: - virtual void write(const byte[], u32bit) = 0; + + /** + * Write a portion of a message to this filter. + * @param input the input as a byte array + * @param length the length of the byte array input + */ + virtual void write(const byte input[], u32bit length) = 0; + + /** + * Start a new message. Must be closed by end_msg() before another + * message can be startet. + */ virtual void start_msg() {} + + /** + * Tell the Filter that the current message shall be ended. + */ virtual void end_msg() {} + + /** + * Check whether this filter is an attachable filter. + * @return true if this filter is attachable, false otherwise + */ virtual bool attachable() { return true; } + + /** + * Start a new message in *this and all following filters. Only for + * internal use, not intended for use in client applications. + */ void new_msg(); + + /** + * End a new message in *this and all following filters. Only for + * internal use, not intended for use in client applications. + */ void finish_msg(); + virtual ~Filter() {} protected: void send(const byte[], u32bit); @@ -49,12 +80,12 @@ class BOTAN_DLL Filter SecureVector<byte> write_queue; std::vector<Filter*> next; u32bit port_num, filter_owns; - bool owned; + bool owned; // true if filter belongs to a pipe --> prohibit filter sharing! }; -/************************************************* -* Fanout Filter Base Class * -*************************************************/ +/** +* This is the abstract Fanout_Filter base class. +**/ class BOTAN_DLL Fanout_Filter : public Filter { protected: diff --git a/src/filters/filters.h b/src/filters/filters.h index 926217a5d..43c38ef2d 100644 --- a/src/filters/filters.h +++ b/src/filters/filters.h @@ -20,53 +20,106 @@ namespace Botan { -/************************************************* -* Stream Cipher Filter * -*************************************************/ +/** +* Stream Cipher Filter. +*/ class BOTAN_DLL StreamCipher_Filter : public Keyed_Filter { public: + + /** + * Seek in the stream. + * @param position the position to seek ahead + */ void seek(u32bit position) { cipher->seek(position); } + + /** + * Find out whether the cipher underlying this filter supports + * resyncing. + * @return true if the cipher supports resyncing + */ bool supports_resync() const { return (cipher->IV_LENGTH != 0); } - void set_iv(const InitializationVector&); + /** + * Set the initialization vector for this filter. + * @param iv the initialization vector to set + */ + void set_iv(const InitializationVector& iv); void write(const byte[], u32bit); - StreamCipher_Filter(const std::string&); - StreamCipher_Filter(const std::string&, const SymmetricKey&); + /** + * Construct a stream cipher filter. + * @param cipher the name of the desired cipher + */ + StreamCipher_Filter(const std::string& cipher); + + /** + * Construct a stream cipher filter. + * @param cipher the name of the desired cipher + * @param key the key to use inside this filter + */ + StreamCipher_Filter(const std::string& cipher, const SymmetricKey& key); + ~StreamCipher_Filter() { delete cipher; } private: SecureVector<byte> buffer; StreamCipher* cipher; }; -/************************************************* -* Hash Filter * -*************************************************/ +/** +* Hash Filter. +*/ class BOTAN_DLL Hash_Filter : public Filter { public: void write(const byte input[], u32bit len) { hash->update(input, len); } void end_msg(); - Hash_Filter(const std::string&, u32bit = 0); + /** + * Construct a hash filter. + * @param hash the name of the hash algorithm to use + * @param len the output length of this filter. Leave the default + * value 0 if you want to use the full output of the hashfunction + * hash. Otherwise, specify a smaller value here so that the + * output of the hash algorithm will be cut off. + */ + Hash_Filter(const std::string& hash, u32bit len = 0); ~Hash_Filter() { delete hash; } private: const u32bit OUTPUT_LENGTH; HashFunction* hash; }; -/************************************************* -* MessageAuthenticationCode Filter * -*************************************************/ +/** +* MessageAuthenticationCode Filter. +*/ class BOTAN_DLL MAC_Filter : public Keyed_Filter { public: void write(const byte input[], u32bit len) { mac->update(input, len); } void end_msg(); - MAC_Filter(const std::string&, u32bit = 0); - MAC_Filter(const std::string&, const SymmetricKey&, u32bit = 0); + /** + * Construct a MAC filter. The MAC key will be left empty. + * @param mac the name of the MAC to use + * @param len the output length of this filter. Leave the default + * value 0 if you want to use the full output of the + * MAC. Otherwise, specify a smaller value here so that the + * output of the MAC will be cut off. + */ + MAC_Filter(const std::string& mac, u32bit len = 0); + + /** + * Construct a MAC filter. + * @param mac the name of the MAC to use + * @param key the MAC key to use + * @param len the output length of this filter. Leave the default + * value 0 if you want to use the full output of the + * MAC. Otherwise, specify a smaller value here so that the + * output of the MAC will be cut off. + */ + MAC_Filter(const std::string& mac, const SymmetricKey& key, u32bit len = 0); + ~MAC_Filter() { delete mac; } private: const u32bit OUTPUT_LENGTH; diff --git a/src/pubkey/pubkey/pk_keys.h b/src/pubkey/pubkey/pk_keys.h index 16109c634..1aa5e3fa1 100644 --- a/src/pubkey/pubkey/pk_keys.h +++ b/src/pubkey/pubkey/pk_keys.h @@ -1,7 +1,7 @@ /************************************************* * PK Key Types Header File * * (C) 1999-2007 Jack Lloyd * -*************************************************/ +n*************************************************/ #ifndef BOTAN_PK_KEYS_H__ #define BOTAN_PK_KEYS_H__ @@ -12,23 +12,63 @@ namespace Botan { -/************************************************* -* Public Key Base Class * -*************************************************/ +/** +* Public Key Base Class. +*/ class BOTAN_DLL Public_Key { public: + /** + * Get the name of the underlying public key scheme. + * @return the name of the public key scheme + */ virtual std::string algo_name() const = 0; + + /** + * Get the OID of the underlying public key scheme. + * @return the OID of the public key scheme + */ virtual OID get_oid() const; + /** + * Test the key values for consistency. + * @param rng rng to use + * @param strong whether to perform strong and lengthy version + * of the test + * @return true if the test is passed + */ virtual bool check_key(RandomNumberGenerator&, bool) const { return true; } + /** + * Find out the number of message parts supported by this scheme. + * @return the number of message parts + */ virtual u32bit message_parts() const { return 1; } + + /** + * Find out the message part size supported by this scheme/key. + * @return the size of the message parts + */ virtual u32bit message_part_size() const { return 0; } + + /** + * Get the maximum message size in bits supported by this public key. + * @return the maximum message in bits + */ virtual u32bit max_input_bits() const = 0; + /** + * Get an X509 encoder that can be used to encode this key in X509 format. + * @return an X509 encoder for this key + */ virtual class X509_Encoder* x509_encoder() const = 0; + + /** + * Get an X509 decoder that can be used to set the values of this + * key based on an X509 encoded key object. + * @return an X509 decoder for this key + */ virtual class X509_Decoder* x509_decoder() = 0; virtual ~Public_Key() {} @@ -36,14 +76,24 @@ class BOTAN_DLL Public_Key virtual void load_check(RandomNumberGenerator&) const; }; -/************************************************* -* Private Key Base Class * -*************************************************/ +/** +* Private Key Base Class +*/ class BOTAN_DLL Private_Key : public virtual Public_Key { public: + /** + * Get a PKCS#8 encoder that can be used to encode this key in PKCS#8 format. + * @return an PKCS#8 encoder for this key + */ virtual class PKCS8_Encoder* pkcs8_encoder() const { return 0; } + + /** + * Get an PKCS#8 decoder that can be used to set the values of this key + * based on an PKCS#8 encoded key object. + * @return an PKCS#8 decoder for this key + */ virtual class PKCS8_Decoder* pkcs8_decoder(RandomNumberGenerator&) { return 0; } protected: @@ -51,9 +101,9 @@ class BOTAN_DLL Private_Key : public virtual Public_Key void gen_check(RandomNumberGenerator&) const; }; -/************************************************* -* PK Encrypting Key * -*************************************************/ +/** +* PK Encrypting Key. +*/ class BOTAN_DLL PK_Encrypting_Key : public virtual Public_Key { public: @@ -62,9 +112,9 @@ class BOTAN_DLL PK_Encrypting_Key : public virtual Public_Key virtual ~PK_Encrypting_Key() {} }; -/************************************************* -* PK Decrypting Key * -*************************************************/ +/** +* PK Decrypting Key +*/ class BOTAN_DLL PK_Decrypting_Key : public virtual Private_Key { public: @@ -72,9 +122,9 @@ class BOTAN_DLL PK_Decrypting_Key : public virtual Private_Key virtual ~PK_Decrypting_Key() {} }; -/************************************************* -* PK Signing Key * -*************************************************/ +/** +* PK Signing Key +*/ class BOTAN_DLL PK_Signing_Key : public virtual Private_Key { public: @@ -83,9 +133,9 @@ class BOTAN_DLL PK_Signing_Key : public virtual Private_Key virtual ~PK_Signing_Key() {} }; -/************************************************* -* PK Verifying Key, Message Recovery Version * -*************************************************/ +/** +* PK Verifying Key, Message Recovery Version +*/ class BOTAN_DLL PK_Verifying_with_MR_Key : public virtual Public_Key { public: @@ -93,9 +143,9 @@ class BOTAN_DLL PK_Verifying_with_MR_Key : public virtual Public_Key virtual ~PK_Verifying_with_MR_Key() {} }; -/************************************************* -* PK Verifying Key, No Message Recovery Version * -*************************************************/ +/** +* PK Verifying Key, No Message Recovery Version +*/ class BOTAN_DLL PK_Verifying_wo_MR_Key : public virtual Public_Key { public: @@ -104,9 +154,9 @@ class BOTAN_DLL PK_Verifying_wo_MR_Key : public virtual Public_Key virtual ~PK_Verifying_wo_MR_Key() {} }; -/************************************************* -* PK Secret Value Derivation Key * -*************************************************/ +/** +* PK Secret Value Derivation Key +*/ class BOTAN_DLL PK_Key_Agreement_Key : public virtual Private_Key { public: |