|
1 /** |
|
2 @page secure_stream_encryption Secure Stream Encryption |
|
3 |
|
4 This document describes secure stream encryption and its use (with the \c crypto API). |
|
5 |
|
6 - @ref secure_stream_encryption_What |
|
7 - @ref secure_stream_encryption_Why |
|
8 - @ref secure_stream_encryption_How |
|
9 - @ref secure_stream_encryption_Writing |
|
10 - @ref secure_stream_encryption_Reading |
|
11 - @ref secure_stream_encryption_element_set |
|
12 - @ref secure_stream_encryption_data |
|
13 - @ref secure_stream_examples |
|
14 |
|
15 <hr> |
|
16 |
|
17 @section secure_stream_encryption_What What is secure stream encryption? |
|
18 |
|
19 Secure stream encryption provides subclasses of <code>RReadStream</code>, <code>RWriteStream</code> and |
|
20 <code>CStreamStore</code> that allow transparent access to encryted streams and stores. |
|
21 It is implemented in terms of @ref mainpage_pbe "PBE" (Password Based Encryption) -- i.e., %PBE does most of the |
|
22 work, the stream encryption classes are just wrappers that call %PBE. |
|
23 The word "secure" refers to the fact that it uses well-known cryptographic algorithms. |
|
24 |
|
25 <hr> |
|
26 |
|
27 @section secure_stream_encryption_Why What is it used for? |
|
28 |
|
29 Secure stream encryption is used for example: |
|
30 - to password protect a database file |
|
31 - to store contacts encrypted on a mobile phone. |
|
32 |
|
33 <hr> |
|
34 |
|
35 @section secure_stream_encryption_How How do I use the secure stream encryption API? |
|
36 |
|
37 @section secure_stream_encryption_Writing Encrypting a stream |
|
38 |
|
39 - An encryption object (i.e., a <code>CPBEncryptElement</code> or <code>CPBEncryptSet</code> object) is necessary |
|
40 to allow the @ref mainpage_pbe "password based encryption" of elements or multiple elements. Objects of this |
|
41 type contain the encryption key with its encryption data (i.e., password, cipher, @ref salt, @ref IV, |
|
42 iterations). Note that encryption objects can be recreated at a later stage from existing encryption data |
|
43 (see @ref secure_stream_encryption_data). |
|
44 - An <code>RWriteStream</code> object (such as an <code>RFileWriteStream</code>, or <code>RStoreWriteStream</code> |
|
45 object) representing a target stream needs to be created in order to write the stream to a file or store . |
|
46 - To support the encryption, an <code>REncryptStream</code> object is required, which forms an encryption filter or |
|
47 layer over the <code>RWriteStream</code> object. |
|
48 - Data can now be encrypted as it is externalized through the <code>REncryptStream</code> to the stream |
|
49 represented by the <code>RWriteStream</code> object. |
|
50 |
|
51 @section secure_stream_encryption_Reading Decrypting a stream |
|
52 |
|
53 Reading from an encrypted stream is a similar process to that of writing to one. |
|
54 |
|
55 - An encryption object, i.e., a <code>CPBEncryptElement</code> or a <code>CPBEncryptSet</code> object, is |
|
56 needed to allow the @ref mainpage_pbe "password based decryption" of elements or multiple elements, |
|
57 respectively. |
|
58 - An <code>RReadStream</code> object (such as an <code>RFileReadStream</code>, or <code>RStoreReadStream</code> |
|
59 object) needs to be created in order to read the stream from a file or store . |
|
60 - An <code>RDecryptStream</code> object is needed to form an encryption wrapper around the existing |
|
61 <code>RReadStream</code> object. |
|
62 - The encrypted data is internalized from the stream represented by the <code>RReadStream</code> object by way of |
|
63 the <code>RDecryptStream</code> object. |
|
64 |
|
65 @section secure_stream_encryption_element_set Handling multiple elements |
|
66 |
|
67 <code>CPBEncryptElement</code> is good for handling individual elements, but for encrypting/decrypting information |
|
68 with multiple, independent elements it is advisable to use <code>CPBEncryptSet</code>; for instance, if you wished |
|
69 to store contacts encrypted on a mobile phone. \n |
|
70 When you create a <code>CPBEncryptSet</code> object a <i>master</i> key is generated for you. This master key, |
|
71 which is encrypted with the password provided by the user of the class, enables the encryption/decryption of |
|
72 individual elements. The password may be changed by using the <code>CPBEncryptSet::ChangePasswordL()</code> |
|
73 function, which re-encrypts the master key with the new password. |
|
74 |
|
75 @section secure_stream_encryption_data Storing encryption data |
|
76 |
|
77 In order to decrypt any information previously encrypted with a <code>CPBEncryptElement</code> or |
|
78 <code>CPBEncryptSet</code> object, you <i><b>must</b></i> store its encryption data along with it. Externalizing the |
|
79 <code>CPBEncryptionData</code> object will achieve this; for example:\n\n |
|
80 <code>writeStream << encryption->EncryptionData();</code> \n\n |
|
81 where <code>writeStream</code> is a <code>RFileWriteStream</code> object, and encryption is a |
|
82 <code>CPBEncryptElement</code> object. Failure to do this will result in the permanent loss of the encrypted |
|
83 information. See @ref secure_stream_example_code. |
|
84 |
|
85 <hr> |
|
86 |
|
87 @section secure_stream_examples Example code |
|
88 |
|
89 - @ref pbe_example_code |
|
90 - @ref secure_stream_example_code |
|
91 - @ref secure_store_example_code |
|
92 |
|
93 |
|
94 */ |
|
95 |