--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/crypto/weakcrypto/docs/pbe.dox	Wed Jul 08 11:25:26 2009 +0100
@@ -0,0 +1,80 @@
+/**
+	@page mainpage_pbe Password Based Encryption (PBE)
+
+
+	- @ref pbe_What
+	- @ref pbe_How
+	- @ref pbe_example
+	- @ref pbe_files
+	
+	@section pbe_What What is PBE?
+				
+		%PBE provides an API to encrypt and decrypt data with a user-supplied password. It is intended to be used by 
+		applications, such as editors or database programs, that might provide the ability to encrypt a user's documents.
+		It aims to be secure and easy to use, and attempts to overcome the common pitfalls of encryption based on 
+		user-supplied passwords.  Specifically, it uses a 
+		<A HREF="http://www.rsasecurity.com/rsalabs/pkcs/pkcs-5/index.html">PKCS#5</A>-based key derivation function to 
+		create the symmetric key based on the user's password.
+
+		<A HREF="http://www.rsasecurity.com/rsalabs/pkcs/pkcs-5/index.html">PKCS#5</A> is the Password Based Encryption 
+		standard produced by RSA laboratories. It describes a method to generate a symmetric key based on a password.
+		We use PKCS#5 v2.0, which is able to generate unlimited key length.
+	
+		The %PBE algorithm generates a symmetric key based on a password, which is provided by the user. To impede
+		dictionary attacks, the password is appended with a @ref salt before being digested to produce the key; 
+		the salt is generated using a @ref mainpage_rng "pseudo random number generator". Furthermore, the %PBE algorithm 
+		by which the keys are derived is iterated a number of times, the default being @ref KDefaultIterations.
+		As @ref TPBECipher "the ciphers" operate in @ref CBC mode, a randomly selected Initialization Vector (@ref IV) is 
+		passed to them as a seed.	Note that the salt value, iteration count value, and the @ref IV 
+		(i.e., the <code>CPBEncryptParms</code> object) do not have to be kept secret and can be sent along with the 
+		ciphertext.
+
+		%PBE provides APIs for encrypting a single object (<code>CPBEncryptElement</code>) and multiple objects 
+		(<code>CPBEncryptSet</code>). The latter is useful in the situation if one wants random access to an encrypted 
+		source consisting of multiple, independent elements; for example a database or a store. 
+	
+	@section pbe_How What is PBE used for?
+	
+		%PBE is used to implement @ref secure_stream_encryption, which can be used, for example,:
+		- to password protect a database file
+		- to store contacts encrypted on a mobile phone.
+		
+	@section pbe_example PBE example code
+	
+		- @ref pbe_example_code
+
+	@section pbe_files Relevant files and classes
+	
+		- <code>pbe.h</code>
+			- <code>CPBEncryptElement</code>
+			- <code>CPBEncryptSet</code>
+			- <code>TPBPassword</code>
+			- <code>@ref TPBECipher</code>
+		- <code>pbebase.h</code>
+			- <code>CPBEncryptor</code>
+			- <code>CPBDecryptor</code>
+			- <code>CPBEncryptionBase</code>
+		- <code>pbedata.h</code> 
+			- <code>CPBEncryptParms</code>
+			- <code>CPBAuthData</code>
+			- <code>CPBEncryptionData </code>
+		- <code>pbesymmetricfactory.h</code> 
+			- <code>PBE</code>
+			- <code>constants</code>
+	<!--
+		- <code>pbencryptor.h</code> 
+			- <code>CPBEncryptorElement</code>
+			- <code>CPBDecryptorElement</code>
+			- <code>CPBEncryptorSet</code>
+			- <code>CPBDecryptorSet</code>
+		- <code>pkcs5kdf.h</code> 
+			- <code>TPKCS5KDF</code>
+			- <code>@ref KDefaultIterations</code>
+ 	-->
+
+	<!--
+	Also, see <A HREF="http://www.rsasecurity.com/rsalabs/pkcs/pkcs-12/index.html">PKCS#12</A> 
+	The Personal Information Exchange Syntax Standard
+	-->
+	
+*/