--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/crypto/weakcrypto/docs/secure_stream_encryption.dox	Wed Jul 08 11:25:26 2009 +0100
@@ -0,0 +1,95 @@
+/**
+@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
+	
+
+*/
+