PBE +-- guide

What is PBE?
What is PBE used for?
Base classes and their derived classes
Example +code

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 (specified in RFC 2898), 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 salt before being digested to produce the key; the salt +is generated using a pseudo random number generator. Furthermore, the PBE +algorithm by which the keys are derived is iterated a number of times, the +default being KDefaultIterations. As the ciphers operate +in CBC mode, a randomly selected Initialization Vector (IV) is passed to them +as a seed. Note that the salt value, iteration count value, and the 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.

What is PBE +used for?

PBE is used to implement Secure +Stream Encryption, which can be used, for example:

to password protect +a database file
to store contacts encrypted +on a mobile phone.

Base classes +and their derived classes

The diagrams below show the main classes +used in password based encryption and which are implemented in pbe.dll. +Blue dotted arrows indicate that a class is contained or used by another class. +The arrows are labelled with the variable(s) through which the pointed class +is accessible. The color of the boxes indicates the type of Symbian class, +i.e., M, C, R or T class. +For detailed information on each component see the Cryptography API Reference +material.

+The inheritance diagram above shows the <codeph>CPBEncryptionBase</codeph> abstract +base class. Also shown are the following classes from the Cryptography API: <codeph>CPBEncryptElement</codeph>, <codeph>CPBEncryptSet</codeph>, <codeph>CPBAuthData</codeph>, <codeph>CPBEncryptionData</codeph>, and <codeph>CPBEncryptParams</codeph>. + + +The inheritance diagram above shows the <codeph>CPBEncryptor</codeph> abstract +base class. Also shown are the following classes from the Cryptography API: <codeph>CPBDecryptor</codeph>, <codeph>CPBDecryptorElement</codeph>, <codeph>CPBDecryptorSet</codeph>, <codeph>CSymmetricCipher</codeph>, <codeph>CPBEncryptorElement</codeph>, <codeph>CPBEncryptorSet</codeph>. + +