<?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>