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

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

    14 <ul>

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

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

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

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

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

    20 </ul>

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

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

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

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

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

    26 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

    27 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

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

    29 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    48 a database file </p> </li>

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

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

    51 </ul> </section>

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

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

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

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

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

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

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

    59 For detailed information on each component see the Cryptography API Reference

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

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

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

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

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

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

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

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

    68 </fig> </section>

    69 </conbody></concept>