--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-D6B1B658-0582-511A-8583-758F9338E5CB.dita	Fri Jun 11 12:39:03 2010 +0100
@@ -0,0 +1,99 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
+<!-- This component and the accompanying materials are made available under the terms of the License 
+"Eclipse Public License v1.0" which accompanies this distribution, 
+and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
+<!-- Initial Contributors:
+    Nokia Corporation - initial contribution.
+Contributors: 
+-->
+<!DOCTYPE concept
+  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
+<concept id="GUID-D6B1B658-0582-511A-8583-758F9338E5CB" xml:lang="en"><title>Secure
+stream encryption -- guide/HowTo</title><prolog><metadata><keywords/></metadata></prolog><conbody>
+<p>This document describes secure stream encryption and its use (with the <codeph>Cryptography</codeph> API). </p>
+<ul>
+<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>
+<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>
+<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>
+<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>
+<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>
+<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>
+<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>
+</ul> </li>
+<li id="GUID-48532ACC-A8A4-52AF-930C-3254C68FD23D"><p> <xref href="GUID-18358882-A4DD-5010-BED7-4ACAE021495D.dita">Example
+code</xref>  </p> </li>
+</ul>
+<section id="GUID-AFCA2350-8528-50BE-A3B5-BDAEC3022B80"><title>What is secure
+stream encryption?</title> <p>Secure stream encryption provides subclasses
+of <codeph>RReadStream</codeph>, <codeph>RWriteStream</codeph> and <codeph>CStreamStore</codeph> that
+allow transparent access to encrypted streams and stores. It is implemented
+in terms of PBE (<xref href="GUID-8119A243-2EF1-582A-BB94-BA2A18D02D2C.dita">Password
+Based Encryption</xref>) -- that is, PBE does most of the work, the stream
+encryption classes are just wrappers that call PBE. The word "secure" refers
+to the fact that it uses well-known cryptographic algorithms. </p> </section>
+<section id="GUID-E3DE6C97-565F-5FAD-B7EA-7B73B14CAF7F"><title>What is secure
+stream encryption used for?</title> <p>Secure stream encryption is used for
+example: </p> <ul>
+<li id="GUID-1F0F962C-92A7-5B2D-B30D-CC3419FCB421"><p>to password protect
+a database file </p> </li>
+<li id="GUID-0E92A1F3-F20A-5AAA-A955-018F8D494E87"><p>to store contacts encrypted
+on a mobile phone. </p> </li>
+</ul> </section>
+<section id="GUID-B227B613-9459-52B1-86EA-8A8D76DE8175"><title>How do I use
+the secure stream encryption API?</title> <p id="GUID-9303C0E5-09A8-53A8-B1D6-14ECA045E560"><b>Encrypting
+a stream</b> </p> <ul>
+<li id="GUID-FCBF60C2-33E6-5F65-B909-A608D9F69203"><p>An encryption object
+(i.e., a <codeph>CPBEncryptElement</codeph> or <codeph>CPBEncryptSet</codeph> object)
+is necessary to allow the <xref href="GUID-8119A243-2EF1-582A-BB94-BA2A18D02D2C.dita">password
+based encryption</xref> of elements or multiple elements. Objects of this
+type contain the encryption key with its encryption data (i.e. password, cipher,
+salt, IV, iterations). Note that encryption objects can be recreated at a
+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
+encryption data</xref>) </p> </li>
+<li id="GUID-B0440E22-7F0E-5562-B729-9C9AB5DE3741"><p>An <codeph>RWriteStream</codeph> object
+(such as an <codeph>RFileWriteStream</codeph>, or <codeph>RStoreWriteStream</codeph> object)
+representing a target stream needs to be created in order to write the stream
+to a file or store </p> </li>
+<li id="GUID-706B4F52-3633-5E8B-A7AF-836B0D3D916A"><p>To support the encryption,
+an <codeph>REncryptStream</codeph> object is required, which forms an encryption
+filter or layer over the <codeph>RWriteStream</codeph> object. </p> </li>
+<li id="GUID-BB0E43D7-0AEF-5718-8DC1-095CC6704729"><p>Data can now be encrypted
+as it is externalized through the <codeph>REncryptStream</codeph> to the stream
+represented by the <codeph>RWriteStream</codeph> object. </p> </li>
+</ul> <p id="GUID-5CFD8921-4AF9-5C06-8250-E8791C15969E"><b>Decrypting a stream</b> </p> <p>Reading
+from an encrypted stream is a similar process to that of writing to one. </p> <ul>
+<li id="GUID-39667E19-E7BE-55C2-9E7D-5F3F9FF310D5"><p>An encryption object
+(i.e., a <codeph>CPBEncryptElement</codeph> or a <codeph>CPBEncryptSet</codeph> object)
+is needed to allow the <xref href="GUID-8119A243-2EF1-582A-BB94-BA2A18D02D2C.dita">password
+based decryption</xref> of elements or multiple elements. </p> </li>
+<li id="GUID-3F2160E6-4CD5-50EE-A222-0A206E06C885"><p>An <codeph>RReadStream</codeph> object
+(such as an <codeph>RFileReadStream</codeph>, or <codeph>RStoreReadStream</codeph> object)
+needs to be created to read the stream from a file or store. </p> </li>
+<li id="GUID-2EF007A9-9A74-5408-9DB8-8C542BDA7CE4"><p>An <codeph>RDecryptStream</codeph> object
+is needed to form an encryption wrapper around the existing <codeph>RReadStream</codeph> object. </p> </li>
+<li id="GUID-3E3C26E3-388B-52E6-A3C1-2359ACD76898"><p>The encrypted data is
+internalized from the stream represented by the <codeph>RReadStream</codeph> object
+by way of the <codeph>RDecryptStream</codeph> object. </p> </li>
+</ul> <p id="GUID-DCC5388B-F777-51C0-9D4B-BB2BFE6552AF"><b>Handling multiple
+elements</b> </p> <p> <codeph>CPBEncryptElement</codeph> is good
+for handling individual elements, but for encrypting/decrypting information
+with multiple, independent elements it is advisable to use <codeph>CPBEncryptSet</codeph>;
+for instance, if you wished to store contacts encrypted on a mobile phone. </p> <p>When
+you create a <codeph>CPBEncryptSet</codeph> object a master key is generated
+for you. This master key, which is encrypted with the password provided by
+the user of the class, enables the encryption/decryption of individual elements.
+The password may be changed by using the <codeph>CPBEncryptSet::ChangePasswordL()</codeph> function,
+which re-encrypts the master key with the new password. </p> <p id="GUID-93DDDA90-742A-5867-9074-9D0849ACE5F6"><b>Storing
+encryption data</b> </p> <p>In order to decrypt any information previously
+encrypted with a <codeph>CPBEncryptElement</codeph> or <codeph>CPBEncryptSet</codeph> object,
+you must store its encryption data along with it. Externalizing the <codeph>CPBEncryptionData</codeph> object
+will achieve this; for example: </p> <codeblock id="GUID-78A24676-ABE9-58FC-ADCE-1F7A3EF5B8F8" xml:space="preserve">writeStream &lt;&lt; encryption-&gt;EncryptionData();</codeblock> <p>where <codeph>writeStream</codeph> is a <codeph>RFileWriteStream</codeph> object,
+and encryption is a <codeph>CPBEncryptElement</codeph> object. Failure to
+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>
+<section id="GUID-18EF3A5E-9BF2-4542-BF0F-10E04EA09D87"><title>Note</title> <p>The
+Secure Store APIs <codeph>REncryptStream</codeph> and <codeph>RDecryptStream</codeph> currently
+support both the old <codeph>CSecurityBase</codeph> methods and the new PBE-based
+methods. In the near future, the old methods will be marked as officially
+deprecated. </p> </section>
+</conbody></concept>
\ No newline at end of file