|
1 /** |
|
2 @page mainpage_pbe Password Based Encryption (PBE) |
|
3 |
|
4 |
|
5 - @ref pbe_What |
|
6 - @ref pbe_How |
|
7 - @ref pbe_example |
|
8 - @ref pbe_files |
|
9 |
|
10 @section pbe_What What is PBE? |
|
11 |
|
12 %PBE provides an API to encrypt and decrypt data with a user-supplied password. It is intended to be used by |
|
13 applications, such as editors or database programs, that might provide the ability to encrypt a user's documents. |
|
14 It aims to be secure and easy to use, and attempts to overcome the common pitfalls of encryption based on |
|
15 user-supplied passwords. Specifically, it uses a |
|
16 <A HREF="http://www.rsasecurity.com/rsalabs/pkcs/pkcs-5/index.html">PKCS#5</A>-based key derivation function to |
|
17 create the symmetric key based on the user's password. |
|
18 |
|
19 <A HREF="http://www.rsasecurity.com/rsalabs/pkcs/pkcs-5/index.html">PKCS#5</A> is the Password Based Encryption |
|
20 standard produced by RSA laboratories. It describes a method to generate a symmetric key based on a password. |
|
21 We use PKCS#5 v2.0, which is able to generate unlimited key length. |
|
22 |
|
23 The %PBE algorithm generates a symmetric key based on a password, which is provided by the user. To impede |
|
24 dictionary attacks, the password is appended with a @ref salt before being digested to produce the key; |
|
25 the salt is generated using a @ref mainpage_rng "pseudo random number generator". Furthermore, the %PBE algorithm |
|
26 by which the keys are derived is iterated a number of times, the default being @ref KDefaultIterations. |
|
27 As @ref TPBECipher "the ciphers" operate in @ref CBC mode, a randomly selected Initialization Vector (@ref IV) is |
|
28 passed to them as a seed. Note that the salt value, iteration count value, and the @ref IV |
|
29 (i.e., the <code>CPBEncryptParms</code> object) do not have to be kept secret and can be sent along with the |
|
30 ciphertext. |
|
31 |
|
32 %PBE provides APIs for encrypting a single object (<code>CPBEncryptElement</code>) and multiple objects |
|
33 (<code>CPBEncryptSet</code>). The latter is useful in the situation if one wants random access to an encrypted |
|
34 source consisting of multiple, independent elements; for example a database or a store. |
|
35 |
|
36 @section pbe_How What is PBE used for? |
|
37 |
|
38 %PBE is used to implement @ref secure_stream_encryption, which can be used, for example,: |
|
39 - to password protect a database file |
|
40 - to store contacts encrypted on a mobile phone. |
|
41 |
|
42 @section pbe_example PBE example code |
|
43 |
|
44 - @ref pbe_example_code |
|
45 |
|
46 @section pbe_files Relevant files and classes |
|
47 |
|
48 - <code>pbe.h</code> |
|
49 - <code>CPBEncryptElement</code> |
|
50 - <code>CPBEncryptSet</code> |
|
51 - <code>TPBPassword</code> |
|
52 - <code>@ref TPBECipher</code> |
|
53 - <code>pbebase.h</code> |
|
54 - <code>CPBEncryptor</code> |
|
55 - <code>CPBDecryptor</code> |
|
56 - <code>CPBEncryptionBase</code> |
|
57 - <code>pbedata.h</code> |
|
58 - <code>CPBEncryptParms</code> |
|
59 - <code>CPBAuthData</code> |
|
60 - <code>CPBEncryptionData </code> |
|
61 - <code>pbesymmetricfactory.h</code> |
|
62 - <code>PBE</code> |
|
63 - <code>constants</code> |
|
64 <!-- |
|
65 - <code>pbencryptor.h</code> |
|
66 - <code>CPBEncryptorElement</code> |
|
67 - <code>CPBDecryptorElement</code> |
|
68 - <code>CPBEncryptorSet</code> |
|
69 - <code>CPBDecryptorSet</code> |
|
70 - <code>pkcs5kdf.h</code> |
|
71 - <code>TPKCS5KDF</code> |
|
72 - <code>@ref KDefaultIterations</code> |
|
73 --> |
|
74 |
|
75 <!-- |
|
76 Also, see <A HREF="http://www.rsasecurity.com/rsalabs/pkcs/pkcs-12/index.html">PKCS#12</A> |
|
77 The Personal Information Exchange Syntax Standard |
|
78 --> |
|
79 |
|
80 */ |