/**

@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

*/