PBE -- guide

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.

Figure 1. The inheritance diagram above shows the CPBEncryptionBase abstract base class. Also shown are the following classes from the Cryptography API: CPBEncryptElement, CPBEncryptSet, CPBAuthData, CPBEncryptionData, and CPBEncryptParams.

Figure 2. The inheritance diagram above shows the CPBEncryptor abstract base class. Also shown are the following classes from the Cryptography API: CPBDecryptor, CPBDecryptorElement, CPBDecryptorSet, CSymmetricCipher, CPBEncryptorElement, CPBEncryptorSet.