/**
@page secure_stream_encryption Secure Stream Encryption
	
	This document describes secure stream encryption and its use (with the \c crypto API). 
 
 	- @ref secure_stream_encryption_What
	- @ref secure_stream_encryption_Why
	- @ref secure_stream_encryption_How
		- @ref secure_stream_encryption_Writing
		- @ref secure_stream_encryption_Reading
		- @ref secure_stream_encryption_element_set
		- @ref secure_stream_encryption_data
	- @ref secure_stream_examples

<hr>

@section secure_stream_encryption_What What is secure stream encryption?	
		
		Secure stream encryption provides subclasses of <code>RReadStream</code>, <code>RWriteStream</code> and 
		<code>CStreamStore</code> that allow transparent access to encryted streams and stores. 		
		It is implemented in terms of @ref mainpage_pbe "PBE" (Password Based Encryption) -- i.e., %PBE does most of the 
		work, the stream encryption classes are just wrappers that call %PBE.
		The word "secure" refers to the fact that it uses well-known cryptographic algorithms.
		
<hr>

@section secure_stream_encryption_Why What is it used for?
	
	Secure stream encryption is used for example:
		- to password protect a database file
		- to store contacts encrypted on a mobile phone.
	
<hr>

@section secure_stream_encryption_How How do I use the secure stream encryption API?

	@section secure_stream_encryption_Writing Encrypting a stream
	
		- An encryption object (i.e., a <code>CPBEncryptElement</code> or <code>CPBEncryptSet</code> object) is necessary 
			to	allow the @ref mainpage_pbe "password based encryption" of elements or multiple elements. Objects of this 
			type contain the encryption key with its encryption data (i.e., password, cipher, @ref salt, @ref IV, 
			iterations). Note that encryption objects can be recreated at a later stage from existing encryption data 
			(see @ref secure_stream_encryption_data).
		- An <code>RWriteStream</code> object (such as an <code>RFileWriteStream</code>, or <code>RStoreWriteStream</code>
			object) representing a target stream needs to be created in order to write the stream to a file or store .
		- To support the encryption, an <code>REncryptStream</code> object is required, which forms an encryption filter or
			layer over the <code>RWriteStream</code> object. 		
		- Data can now be encrypted as it is externalized through the <code>REncryptStream</code> to the stream 
			represented by the <code>RWriteStream</code> object. 

	@section secure_stream_encryption_Reading Decrypting a stream
	
		Reading from an encrypted stream is a similar process to that of writing to one.
		
		- An encryption object, i.e., a <code>CPBEncryptElement</code> or a <code>CPBEncryptSet</code> object, is 
			needed to allow the @ref mainpage_pbe "password based decryption" of elements or multiple elements, 
			respectively. 
		- An <code>RReadStream</code> object (such as an <code>RFileReadStream</code>, or <code>RStoreReadStream</code> 
			object) needs to be created in order to read the stream from a file or store .
		- An <code>RDecryptStream</code> object is needed to form an encryption wrapper around the existing 
			<code>RReadStream</code> object.
		- The encrypted data is internalized from the stream represented by the <code>RReadStream</code> object by way of
			the	<code>RDecryptStream</code> object. 

	@section secure_stream_encryption_element_set Handling multiple elements
	
		<code>CPBEncryptElement</code> is good for handling individual elements, but for encrypting/decrypting information
		with multiple, independent elements it is advisable to use <code>CPBEncryptSet</code>; for instance, if you wished 
		to store contacts encrypted on a mobile phone. \n
		When you create a <code>CPBEncryptSet</code> object a <i>master</i> key is generated for you. This master key, 
		which is encrypted with the password provided by the user of the class, enables the encryption/decryption of 
		individual elements. The password may be changed by using the <code>CPBEncryptSet::ChangePasswordL()</code> 
		function, which re-encrypts the master key with the new password.

	@section secure_stream_encryption_data Storing encryption data
		
		In order to decrypt any information previously encrypted with a <code>CPBEncryptElement</code> or 
		<code>CPBEncryptSet</code> object, you <i><b>must</b></i> store its encryption data along with it. Externalizing the 
		<code>CPBEncryptionData</code> object will achieve this; for example:\n\n 
		<code>writeStream << encryption->EncryptionData();</code> \n\n
		where <code>writeStream</code> is a <code>RFileWriteStream</code> object, and encryption is a 
		<code>CPBEncryptElement</code> object. Failure to do this will result in the permanent loss of the encrypted 
		information. See @ref secure_stream_example_code.

<hr>

@section secure_stream_examples Example code

		- @ref pbe_example_code
		- @ref secure_stream_example_code
		- @ref secure_store_example_code
	

*/