diff -r 000000000000 -r 2c201484c85f crypto/weakcrypto/docs/pbe.dox
--- /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
+ PKCS#5-based key derivation function to
+ create the symmetric key based on the user's password.
+
+ PKCS#5 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 CPBEncryptParms object) do not have to be kept secret and can be sent along with the
+ ciphertext.
+
+ %PBE provides APIs for encrypting a single object (CPBEncryptElement) and multiple objects
+ (CPBEncryptSet). 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
+
+ - pbe.h
+ - CPBEncryptElement
+ - CPBEncryptSet
+ - TPBPassword
+ - @ref TPBECipher
+ - pbebase.h
+ - CPBEncryptor
+ - CPBDecryptor
+ - CPBEncryptionBase
+ - pbedata.h
+ - CPBEncryptParms
+ - CPBAuthData
+ - CPBEncryptionData
+ - pbesymmetricfactory.h
+ - PBE
+ - constants
+
+
+
+
+*/