|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-D6B1B658-0582-511A-8583-758F9338E5CB" xml:lang="en"><title>Secure |
|
13 stream encryption -- guide/HowTo</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>This document describes secure stream encryption and its use (with the <codeph>Cryptography</codeph> API). </p> |
|
15 <ul> |
|
16 <li id="GUID-3AAC9A1E-2722-5AB1-8284-5EEEF097ED17"><p> <xref href="GUID-D6B1B658-0582-511A-8583-758F9338E5CB.dita#GUID-D6B1B658-0582-511A-8583-758F9338E5CB/GUID-AFCA2350-8528-50BE-A3B5-BDAEC3022B80">What is secure stream encryption?</xref> </p> </li> |
|
17 <li id="GUID-D22F5F63-4569-513D-A410-96DD6E4650B9"><p> <xref href="GUID-D6B1B658-0582-511A-8583-758F9338E5CB.dita#GUID-D6B1B658-0582-511A-8583-758F9338E5CB/GUID-E3DE6C97-565F-5FAD-B7EA-7B73B14CAF7F">What is secure stream encryption used for?</xref> </p> </li> |
|
18 <li id="GUID-417238BF-A14B-5695-A496-4E369B199799"><p> <xref href="GUID-D6B1B658-0582-511A-8583-758F9338E5CB.dita#GUID-D6B1B658-0582-511A-8583-758F9338E5CB/GUID-B227B613-9459-52B1-86EA-8A8D76DE8175">How do I use the secure stream encryption API?</xref> </p> <ul> |
|
19 <li id="GUID-6675E3A7-8495-5B6F-B5DB-8B9CAD0C4C7B"><p> <xref href="GUID-D6B1B658-0582-511A-8583-758F9338E5CB.dita#GUID-D6B1B658-0582-511A-8583-758F9338E5CB/GUID-9303C0E5-09A8-53A8-B1D6-14ECA045E560">Encrypting a stream</xref> </p> </li> |
|
20 <li id="GUID-E21930E0-6053-590D-808A-16E296780D4D"><p> <xref href="GUID-D6B1B658-0582-511A-8583-758F9338E5CB.dita#GUID-D6B1B658-0582-511A-8583-758F9338E5CB/GUID-5CFD8921-4AF9-5C06-8250-E8791C15969E">Decrypting a stream</xref> </p> </li> |
|
21 <li id="GUID-30F9797A-4E5B-54C7-B1A0-DF7FCAD9D4E8"><p> <xref href="GUID-D6B1B658-0582-511A-8583-758F9338E5CB.dita#GUID-D6B1B658-0582-511A-8583-758F9338E5CB/GUID-DCC5388B-F777-51C0-9D4B-BB2BFE6552AF">Handling multiple elements</xref> </p> </li> |
|
22 <li id="GUID-5F9A5B14-C945-5BAA-B643-5DBC9480E3BD"><p> <xref href="GUID-D6B1B658-0582-511A-8583-758F9338E5CB.dita#GUID-D6B1B658-0582-511A-8583-758F9338E5CB/GUID-93DDDA90-742A-5867-9074-9D0849ACE5F6">Storing encryption data</xref> </p> </li> |
|
23 </ul> </li> |
|
24 <li id="GUID-48532ACC-A8A4-52AF-930C-3254C68FD23D"><p> <xref href="GUID-18358882-A4DD-5010-BED7-4ACAE021495D.dita">Example |
|
25 code</xref> </p> </li> |
|
26 </ul> |
|
27 <section id="GUID-AFCA2350-8528-50BE-A3B5-BDAEC3022B80"><title>What is secure |
|
28 stream encryption?</title> <p>Secure stream encryption provides subclasses |
|
29 of <codeph>RReadStream</codeph>, <codeph>RWriteStream</codeph> and <codeph>CStreamStore</codeph> that |
|
30 allow transparent access to encrypted streams and stores. It is implemented |
|
31 in terms of PBE (<xref href="GUID-8119A243-2EF1-582A-BB94-BA2A18D02D2C.dita">Password |
|
32 Based Encryption</xref>) -- that is, PBE does most of the work, the stream |
|
33 encryption classes are just wrappers that call PBE. The word "secure" refers |
|
34 to the fact that it uses well-known cryptographic algorithms. </p> </section> |
|
35 <section id="GUID-E3DE6C97-565F-5FAD-B7EA-7B73B14CAF7F"><title>What is secure |
|
36 stream encryption used for?</title> <p>Secure stream encryption is used for |
|
37 example: </p> <ul> |
|
38 <li id="GUID-1F0F962C-92A7-5B2D-B30D-CC3419FCB421"><p>to password protect |
|
39 a database file </p> </li> |
|
40 <li id="GUID-0E92A1F3-F20A-5AAA-A955-018F8D494E87"><p>to store contacts encrypted |
|
41 on a mobile phone. </p> </li> |
|
42 </ul> </section> |
|
43 <section id="GUID-B227B613-9459-52B1-86EA-8A8D76DE8175"><title>How do I use |
|
44 the secure stream encryption API?</title> <p id="GUID-9303C0E5-09A8-53A8-B1D6-14ECA045E560"><b>Encrypting |
|
45 a stream</b> </p> <ul> |
|
46 <li id="GUID-FCBF60C2-33E6-5F65-B909-A608D9F69203"><p>An encryption object |
|
47 (i.e., a <codeph>CPBEncryptElement</codeph> or <codeph>CPBEncryptSet</codeph> object) |
|
48 is necessary to allow the <xref href="GUID-8119A243-2EF1-582A-BB94-BA2A18D02D2C.dita">password |
|
49 based encryption</xref> of elements or multiple elements. Objects of this |
|
50 type contain the encryption key with its encryption data (i.e. password, cipher, |
|
51 salt, IV, iterations). Note that encryption objects can be recreated at a |
|
52 later stage from existing encryption data (see <xref href="GUID-D6B1B658-0582-511A-8583-758F9338E5CB.dita#GUID-D6B1B658-0582-511A-8583-758F9338E5CB/GUID-93DDDA90-742A-5867-9074-9D0849ACE5F6">Storing |
|
53 encryption data</xref>) </p> </li> |
|
54 <li id="GUID-B0440E22-7F0E-5562-B729-9C9AB5DE3741"><p>An <codeph>RWriteStream</codeph> object |
|
55 (such as an <codeph>RFileWriteStream</codeph>, or <codeph>RStoreWriteStream</codeph> object) |
|
56 representing a target stream needs to be created in order to write the stream |
|
57 to a file or store </p> </li> |
|
58 <li id="GUID-706B4F52-3633-5E8B-A7AF-836B0D3D916A"><p>To support the encryption, |
|
59 an <codeph>REncryptStream</codeph> object is required, which forms an encryption |
|
60 filter or layer over the <codeph>RWriteStream</codeph> object. </p> </li> |
|
61 <li id="GUID-BB0E43D7-0AEF-5718-8DC1-095CC6704729"><p>Data can now be encrypted |
|
62 as it is externalized through the <codeph>REncryptStream</codeph> to the stream |
|
63 represented by the <codeph>RWriteStream</codeph> object. </p> </li> |
|
64 </ul> <p id="GUID-5CFD8921-4AF9-5C06-8250-E8791C15969E"><b>Decrypting a stream</b> </p> <p>Reading |
|
65 from an encrypted stream is a similar process to that of writing to one. </p> <ul> |
|
66 <li id="GUID-39667E19-E7BE-55C2-9E7D-5F3F9FF310D5"><p>An encryption object |
|
67 (i.e., a <codeph>CPBEncryptElement</codeph> or a <codeph>CPBEncryptSet</codeph> object) |
|
68 is needed to allow the <xref href="GUID-8119A243-2EF1-582A-BB94-BA2A18D02D2C.dita">password |
|
69 based decryption</xref> of elements or multiple elements. </p> </li> |
|
70 <li id="GUID-3F2160E6-4CD5-50EE-A222-0A206E06C885"><p>An <codeph>RReadStream</codeph> object |
|
71 (such as an <codeph>RFileReadStream</codeph>, or <codeph>RStoreReadStream</codeph> object) |
|
72 needs to be created to read the stream from a file or store. </p> </li> |
|
73 <li id="GUID-2EF007A9-9A74-5408-9DB8-8C542BDA7CE4"><p>An <codeph>RDecryptStream</codeph> object |
|
74 is needed to form an encryption wrapper around the existing <codeph>RReadStream</codeph> object. </p> </li> |
|
75 <li id="GUID-3E3C26E3-388B-52E6-A3C1-2359ACD76898"><p>The encrypted data is |
|
76 internalized from the stream represented by the <codeph>RReadStream</codeph> object |
|
77 by way of the <codeph>RDecryptStream</codeph> object. </p> </li> |
|
78 </ul> <p id="GUID-DCC5388B-F777-51C0-9D4B-BB2BFE6552AF"><b>Handling multiple |
|
79 elements</b> </p> <p> <codeph>CPBEncryptElement</codeph> is good |
|
80 for handling individual elements, but for encrypting/decrypting information |
|
81 with multiple, independent elements it is advisable to use <codeph>CPBEncryptSet</codeph>; |
|
82 for instance, if you wished to store contacts encrypted on a mobile phone. </p> <p>When |
|
83 you create a <codeph>CPBEncryptSet</codeph> object a master key is generated |
|
84 for you. This master key, which is encrypted with the password provided by |
|
85 the user of the class, enables the encryption/decryption of individual elements. |
|
86 The password may be changed by using the <codeph>CPBEncryptSet::ChangePasswordL()</codeph> function, |
|
87 which re-encrypts the master key with the new password. </p> <p id="GUID-93DDDA90-742A-5867-9074-9D0849ACE5F6"><b>Storing |
|
88 encryption data</b> </p> <p>In order to decrypt any information previously |
|
89 encrypted with a <codeph>CPBEncryptElement</codeph> or <codeph>CPBEncryptSet</codeph> object, |
|
90 you must store its encryption data along with it. Externalizing the <codeph>CPBEncryptionData</codeph> object |
|
91 will achieve this; for example: </p> <codeblock id="GUID-78A24676-ABE9-58FC-ADCE-1F7A3EF5B8F8" xml:space="preserve">writeStream << encryption->EncryptionData();</codeblock> <p>where <codeph>writeStream</codeph> is a <codeph>RFileWriteStream</codeph> object, |
|
92 and encryption is a <codeph>CPBEncryptElement</codeph> object. Failure to |
|
93 do this will result in the permanent loss of the encrypted information. See <xref href="GUID-598B6698-3518-50CA-98DE-D85CB255BA2D.dita">Secure stream example code</xref>. </p> </section> |
|
94 <section id="GUID-18EF3A5E-9BF2-4542-BF0F-10E04EA09D87"><title>Note</title> <p>The |
|
95 Secure Store APIs <codeph>REncryptStream</codeph> and <codeph>RDecryptStream</codeph> currently |
|
96 support both the old <codeph>CSecurityBase</codeph> methods and the new PBE-based |
|
97 methods. In the near future, the old methods will be marked as officially |
|
98 deprecated. </p> </section> |
|
99 </conbody></concept> |