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