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