Automatic Decoder supporting Cryptography ( CryptAutoDecoder )

Definition

The class CryptAutoDecoder is an extension of AutoDecoder. It can be used for decoding encrypted streams (in particular if the coder used for encoding is unknown). In order to decrypt a stream a key must be provided by the user because the key is - of course - not stored in the encrypted stream. There are three possibilities to specify a key: as a CryptKey, as a key stream or as a key file. Sometimes it may be necessary to provide several keys to CryptAutoDecoder. E.g., if you use CoderPipe2< OMACCoder<>, OFBCoder<> > to encode a stream two keys are needed for decoding. Therefore, CryptAutoDecoder maintains a list of keys for decoding.

#include < LEDA/coding/crypt_auto_decoder.h >

Creation

CryptAutoDecoder	C(streambuf* src_stream = 0, streambuf* tgt_stream = 0, bool own_streams = false)
		creates an instance C which uses the given source and target streams. If own_streams is set, then C is responsible for the destruction of the streams, otherwise the pointers src_stream and tgt_stream must be valid during the life-time of C.
CryptAutoDecoder	C(const char* src_file_name, const char* tgt_file_name)
		creates an instance C which uses file-streams for input and output.

Operations

Standard Operations

void	C.decode()	decodes the source stream and writes the output to the target stream.
uint32	C.decode_memory_chunk(const char* in_buf, uint32 in_len, char* out_buf, uint32 out_len)
		decodes the memory chunk starting at in_buf with size in_len into the buffer starting at out_buf with size out_len. The function returns actual length of the encoded chunk which may be smaller than out_len. If the output buffer is too small for the decoded data the failure flag will be set (see below).
streambuf*	C.get_src_stream()	returns the current source stream.
void	C.set_src_stream(streambuf* src_stream, bool own_stream = false)
		sets the source stream (cf. constructor).
void	C.set_src_file(const char* file_name)
		sets a file as source stream.
streambuf*	C.get_tgt_stream()	returns the current target stream.
void	C.set_tgt_stream(streambuf* tgt_stream, bool own_Stream = false)
		sets the target stream (cf. constructor).
void	C.set_tgt_file(const char* file_name)
		sets a file as target stream.
void	C.reset()	puts C in exactly the same state as the default constructor.
bool	C.failed()	returns true if an error occured.
bool	C.finished()	returns true if decoding is finished.
string	C.get_description()	provides a description for C. After decoding this includes a description of the coder that has been used for encoding the stream.

Additional Operations

coder_base*	C.get_coder()	after decoding this function returns the coder that has actually been used to decode the stream.
bool	C.has_key()	returns whether the key list is not empty.
list<CryptKey>	C.get_keys()	returns the current list of keys.
void	C.set_key(const CryptKey& key)
		sets the key that should be used for decoding.
void	C.add_key(const CryptKey& key)
		adds a key to the key list.
void	C.set_keys_in_stream(streambuf* key_stream)
		makes the key list equal to the key(s) in key_stream.
void	C.add_keys_in_stream(streambuf* key_stream)
		adds the key(s) in key_stream to the key list.
void	C.set_keys_in_file(const char* file_name)
		makes the key list equal to the key(s) in the given file.
void	C.add_keys_in_file(const char* file_name)
		adds the key(s) in the given file to the key list.
void	C.clear_keys()	removes all keys.

Example

Example on how to use CryptAutoDecoder with a key file:

  typedef OFBCoder<> Cipher;

  // generate key ...
  CryptByteString passphrase("secret phrase");
  CryptByteString dummy_salt; // will be ignored
  CryptKey key 
    = CryptKey::generate_key_and_salt(16, 16, passphrase, dummy_salt, true);
    // 8*16 = 128 bit salt and key

  // write key
  ofstream key_out("secret.key");
  key_out << key;
  key_out.close();

  // encipher data
  encoding_ofstream<Cipher> data_out("data");
  data_out.get_coder()->set_key(key);
  data_out << "my secret text ..." << endl;
  data_out.close();

  // much later ...

  // decipher data
  decoding_ifstream<CryptAutoDecoder> data_in("data");
  data_in.get_coder()->set_keys_in_file("secret.key");
  string data; data.read_line(data_in); cout << data << endl;
  data_in.close();