<?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-0C7CDC47-6B42-5A20-BED8-086DA81D272E" xml:lang="en"><title>PBE

-- guide</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<ul>

<li id="GUID-BE431C93-15F3-5A3E-B461-6D0B8CAA50CA"><p> <xref href="GUID-0C7CDC47-6B42-5A20-BED8-086DA81D272E.dita#GUID-0C7CDC47-6B42-5A20-BED8-086DA81D272E/GUID-297963A8-4FD2-5350-AE7C-18D6C7C11179">What is PBE?</xref>  </p> </li>

<li id="GUID-3A2686D3-6A20-5E45-AB34-256BE39862FF"><p> <xref href="GUID-0C7CDC47-6B42-5A20-BED8-086DA81D272E.dita#GUID-0C7CDC47-6B42-5A20-BED8-086DA81D272E/GUID-CC39624C-D78C-5AD4-A5CA-8E9C09C4C80F">What is PBE used for?</xref>  </p> </li>

<li id="GUID-9E2294EF-D5B2-5C80-ABB4-1E5A100FF96F"><p> <xref href="GUID-0C7CDC47-6B42-5A20-BED8-086DA81D272E.dita#GUID-0C7CDC47-6B42-5A20-BED8-086DA81D272E/GUID-6EFD52CC-D8C7-57A3-8607-6EA6DD09ABEE">Base classes and their derived classes</xref>  </p> </li>

<li id="GUID-B433029C-EF44-5536-ADE8-2DA4A64E2A4C"><p> <xref href="GUID-18358882-A4DD-5010-BED7-4ACAE021495D.dita">Example

code</xref>  </p> </li>

</ul>

<section id="GUID-297963A8-4FD2-5350-AE7C-18D6C7C11179"><title>What is PBE?</title> <p>PBE

provides an API to encrypt and decrypt data with a user-supplied password.

It is intended to be used by applications, such as editors or database programs,

that might provide the ability to encrypt a user's documents. It aims to be

secure and easy to use, and attempts to overcome the common pitfalls of encryption

based on user-supplied passwords. Specifically, it uses a <xref href="http://www.rsasecurity.com/rsalabs/pkcs/pkcs-5/index.html" scope="external">PKCS#5</xref> -based key derivation function to create the

symmetric key based on the user's password. </p> <p> <xref href="http://www.rsasecurity.com/rsalabs/pkcs/pkcs-5/index.html" scope="external">PKCS#5</xref> is the Password Based Encryption standard produced

by RSA laboratories. It describes a method to generate a symmetric key based

on a password. We use PKCS#5 v2.0 (specified in <xref href="ftp://ftp.rfc-editor.org/in-notes/rfc2898.txt" scope="external">RFC 2898</xref>), which is able to generate unlimited key

length. </p> <p>The PBE algorithm generates a symmetric key based on a password,

which is provided by the user. To impede dictionary attacks, the password

is appended with a salt before being digested to produce the key; the salt

is generated using a pseudo random number generator. Furthermore, the PBE

algorithm by which the keys are derived is iterated a number of times, the

default being <codeph>KDefaultIterations</codeph>. As the ciphers operate

in CBC mode, a randomly selected Initialization Vector (IV) is passed to them

as a seed. Note that the salt value, iteration count value, and the IV (i.e.,

the <codeph>CPBEncryptParms</codeph> object) do not have to be kept secret

and can be sent along with the ciphertext. </p> <p>PBE provides APIs for encrypting

a single object (<codeph>CPBEncryptElement</codeph>) and multiple objects

(<codeph>CPBEncryptSet</codeph>). The latter is useful in the situation if

one wants random access to an encrypted source consisting of multiple, independent

elements; for example a database or a store. </p> </section>

<section id="GUID-CC39624C-D78C-5AD4-A5CA-8E9C09C4C80F"><title>What is PBE

used for?</title> <p>PBE is used to implement <xref href="GUID-D6B1B658-0582-511A-8583-758F9338E5CB.dita">Secure

Stream Encryption</xref>, which can be used, for example: </p> <ul>

<li id="GUID-13D8CD70-E1A2-5635-8515-C6C8811F468D"><p>to password protect

a database file </p> </li>

<li id="GUID-2F2CC007-18BA-5254-AAF6-428C57F12DDE"><p>to store contacts encrypted

on a mobile phone. </p> </li>

</ul> </section>

<section id="GUID-6EFD52CC-D8C7-57A3-8607-6EA6DD09ABEE"><title>Base classes

and their derived classes</title> <p>The diagrams below show the main classes

used in password based encryption and which are implemented in <filepath>pbe.dll</filepath>.

Blue dotted arrows indicate that a class is contained or used by another class.

The arrows are labelled with the variable(s) through which the pointed class

is accessible. The color of the boxes indicates the type of Symbian class,

i.e., <codeph>M</codeph>, <codeph>C</codeph>, <codeph>R</codeph> or <codeph>T</codeph> class.

For detailed information on each component see the Cryptography API Reference

material. </p> <fig id="GUID-E3F6C83F-6B73-52A1-88F2-B996E2FD1D5C">

<title>The inheritance diagram above shows the <codeph>CPBEncryptionBase</codeph> abstract

base class. Also shown are the following classes from the Cryptography API: <codeph>CPBEncryptElement</codeph>, <codeph>CPBEncryptSet</codeph>, <codeph>CPBAuthData</codeph>, <codeph>CPBEncryptionData</codeph>, and <codeph>CPBEncryptParams</codeph>.</title>

<image href="GUID-FB45BC8B-FE99-5616-9270-132C4174DAE7_d0e383750_href.png" placement="inline"/>

</fig> <fig id="GUID-3843237A-3246-5179-8481-426A0E0CD095">

<title>The inheritance diagram above shows the <codeph>CPBEncryptor</codeph> abstract

base class. Also shown are the following classes from the Cryptography API: <codeph>CPBDecryptor</codeph>, <codeph>CPBDecryptorElement</codeph>, <codeph>CPBDecryptorSet</codeph>, <codeph>CSymmetricCipher</codeph>, <codeph>CPBEncryptorElement</codeph>, <codeph>CPBEncryptorSet</codeph>.</title>

<image href="GUID-383A96FD-99C3-593C-B7A2-58153F4050DE_d0e383779_href.png" placement="inline"/>

</fig> </section>

</conbody></concept>