crypto/weakcryptospi/inc/pbe.h
changeset 8 35751d3474b7
equal deleted inserted replaced
2:675a964f4eb5 8:35751d3474b7
       
     1 /*
       
     2 * Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies).
       
     3 * All rights reserved.
       
     4 * This component and the accompanying materials are made available
       
     5 * under the terms of the License "Eclipse Public License v1.0"
       
     6 * which accompanies this distribution, and is available
       
     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".
       
     8 *
       
     9 * Initial Contributors:
       
    10 * Nokia Corporation - initial contribution.
       
    11 *
       
    12 * Contributors:
       
    13 *
       
    14 * Description: 
       
    15 * ** IMPORTANT ** PublishedPartner API's in this file are published to 3rd party developers via the 
       
    16 * Symbian website. Changes to these API's should be treated as PublishedAll API changes and the Security TA should be consulted.
       
    17 *
       
    18 */
       
    19 
       
    20 
       
    21 /**
       
    22  @file
       
    23  @publishedPartner
       
    24  @released
       
    25 */
       
    26 
       
    27 #ifndef __PBE_H__
       
    28 #define __PBE_H__
       
    29 
       
    30 #include <e32std.h>
       
    31 #include <pbebase.h>
       
    32 
       
    33 class CPBEncryptionData;
       
    34 class CPBEncryptor;
       
    35 class CPBDecryptor;
       
    36 
       
    37 /** 
       
    38  * Password Based Encryption ciphers.
       
    39  *
       
    40  * Note that RC2 has an additional key parameter, the "effective key length".
       
    41  *
       
    42  * Used in the construction of CPBEncryptElement, CPBEncryptSet, CPBEncryptParms,
       
    43  * and CPBEncryptionData objects and in the CPBEncryptParms::Cipher() function.
       
    44  */
       
    45 enum TPBECipher
       
    46 	{
       
    47 	/** AES cipher in CBC mode with a supplied key size of 128 bits. */
       
    48 	ECipherAES_CBC_128,
       
    49 	/** AES cipher in CBC mode with a supplied key size of 192 bits. */
       
    50 	ECipherAES_CBC_192,
       
    51 	/** AES cipher in CBC mode with a supplied key size of 256 bits. */
       
    52 	ECipherAES_CBC_256,
       
    53 	/** DES cipher in CBC mode (with a supplied key size of 56 bits). */
       
    54 	ECipherDES_CBC,
       
    55 	/** Triple-DES cipher in CBC mode. */
       
    56 	ECipher3DES_CBC,
       
    57 	/** 
       
    58 	 * RC2 cipher in CBC mode with a supplied key length of 40 bits.
       
    59 	 * 
       
    60 	 * It has an effective key length of 1024 bits (128 bytes), which is compatible
       
    61 	 * with OpenSSL RC2 encryption.
       
    62 	 */
       
    63 	ECipherRC2_CBC_40, 
       
    64 	/**
       
    65 	 * RC2 cipher in CBC mode with a supplied key length of 128 bits. 
       
    66 	 * 
       
    67 	 * It has an effective key length of 1024 bits (128 bytes), which is compatible
       
    68 	 * with OpenSSL RC2 encryption.
       
    69 	 */
       
    70 	ECipherRC2_CBC_128,
       
    71 	/**
       
    72 	 * RC2 cipher in CBC mode with a supplied key length of 40 bits.
       
    73 	 * 
       
    74 	 * It has an effective key length of 128 bits (16 bytes), which is compatible 
       
    75 	 * with the RC2 encryption used in PKCS#8 encryption keys generated by OpenSSL
       
    76 	 */
       
    77 	ECipherRC2_CBC_40_16,
       
    78 	/**
       
    79 	 * RC2 cipher in CBC mode with a supplied key length of 128 bits. 
       
    80 	 * 
       
    81 	 * It has an effective key length of 128 bits (16 bytes), which is compatible 
       
    82 	 * with the RC2 encryption used in PKCS#8 encryption keys generated by OpenSSL
       
    83 	 */
       
    84 	ECipherRC2_CBC_128_16,
       
    85 	/**
       
    86 	 * ARC4 cipher with a supplied key length of 128 bits. 
       
    87 	 * PKCS#12 PBE encryption algorithm 
       
    88 	 */
       
    89 	ECipherARC4_128,
       
    90 	/**
       
    91 	 * ARC4 cipher with a supplied key length of 40 bits. 
       
    92 	 * PKCS#12 PBE encryption algorithm 
       
    93 	 */
       
    94     ECipherARC4_40,    
       
    95 	/**
       
    96 	 * 2_KeyTriple-DES cipher in CBC mode. 
       
    97 	 * PKCS#12 PBE encryption algorithm
       
    98 	 */
       
    99     ECipher2Key3DES_CBC,
       
   100 	/** 
       
   101 	 *	RC2 Cipher in CBC mode with a supplied & effective key length of 40 bits. 
       
   102 	 *  PKCS#12 PBE encryption algorithm
       
   103 	 */
       
   104     ECipherRC2_CBC_40_5,
       
   105     };
       
   106 
       
   107 /** 
       
   108  * Allows the password based encryption and decryption of elements.
       
   109  * Contains the encryption key and its associated encryption data.
       
   110  * See the Cryptography api-guide documentation for more information 
       
   111  * and sample code.
       
   112  */
       
   113 class CPBEncryptElement : public CPBEncryptionBase
       
   114 	{
       
   115 public:
       
   116 	/**
       
   117 	 * Creates a new CPBEncryptElement object for encryption of new data.
       
   118 	 *
       
   119 	 * If strong cryptography is present, a 128 bit AES cipher is used; 
       
   120 	 * otherwise, for weak cryptography, a 56 bit DES cipher is used.
       
   121 	 *
       
   122 	 * The symmetric key is derived from the password and a random salt using TPKCS5KDF::DeriveKeyL().
       
   123 	 * 
       
   124 	 * @param aPassword	The user supplied password
       
   125 	 * @return			The new CPBEncryptElement object
       
   126 	 */
       
   127 	IMPORT_C static CPBEncryptElement* NewL(const TPBPassword& aPassword);
       
   128 
       
   129 	/**
       
   130 	 * Creates a new CPBEncryptElement object for encryption of new data.
       
   131 	 * 
       
   132 	 * If strong cryptography is present, a 128 bit AES cipher is used; 
       
   133 	 * otherwise, for weak cryptography, a 56 bit DES cipher is used.
       
   134 	 *
       
   135 	 * The symmetric key is derived from the password and a random salt using TPKCS5KDF::DeriveKeyL().
       
   136 	 *
       
   137 	 * A pointer to the returned object is put onto the cleanup stack.
       
   138 	 *
       
   139 	 * @param aPassword	The user supplied password
       
   140 	 * @return			The new CPBEncryptElement object
       
   141 	 */
       
   142 	IMPORT_C static CPBEncryptElement* NewLC(const TPBPassword& aPassword);
       
   143 
       
   144 	/**
       
   145 	 * Creates a new CPBEncryptElement object for encryption of new data.
       
   146 	 *
       
   147 	 * The symmetric key is derived from the password and a random salt using TPKCS5KDF::DeriveKeyL().
       
   148 	 * 
       
   149 	 * @param aPassword	The user supplied password
       
   150 	 * @param aCipher	The cipher to use
       
   151 	 * @return			The new CPBEncryptElement object
       
   152 	 */
       
   153 	IMPORT_C static CPBEncryptElement* NewL(const TPBPassword& aPassword, 
       
   154 		TPBECipher aCipher);
       
   155 
       
   156 	/**
       
   157 	 * Creates a new CPBEncryptElement object for encryption of new data.
       
   158 	 *
       
   159 	 * The symmetric key is derived from the password and a random salt using TPKCS5KDF::DeriveKeyL().
       
   160 	 * 
       
   161 	 * A pointer to the returned object is put onto the cleanup stack.
       
   162 	 *
       
   163 	 * @param aPassword	The user supplied password
       
   164 	 * @param aCipher	The cipher to use
       
   165 	 * @return			The new CPBEncryptElement object
       
   166 	 */
       
   167 	IMPORT_C static CPBEncryptElement* NewLC(const TPBPassword& aPassword, 
       
   168 		TPBECipher aCipher);
       
   169 
       
   170 	/**
       
   171 	 * Creates a new CPBEncryptElement object for encryption of new data.
       
   172 	 *
       
   173 	 * The symmetric key is derived from the password using TPKCS5KDF::DeriveKeyL().
       
   174 	 * 
       
   175 	 * @param aPassword	The user supplied password
       
   176 	 * @param aParms	An encryption parameter object comprising the cipher,
       
   177 	 *					salt, IV, and iteration count value. 
       
   178 	 * @return			The new CPBEncryptElement object
       
   179 	 */
       
   180 	IMPORT_C static CPBEncryptElement* NewL(const TPBPassword& aPassword, 
       
   181 		const CPBEncryptParms& aParms);
       
   182 
       
   183 	/**
       
   184 	 * Creates a new CPBEncryptElement object for encryption of new data.
       
   185 	 *
       
   186 	 * The symmetric key is derived from the password using TPKCS5KDF::DeriveKeyL().
       
   187 	 * 
       
   188 	 * A pointer to the returned object is put onto the cleanup stack.
       
   189 	 *
       
   190 	 * @param aPassword	The user supplied password
       
   191 	 * @param aParms	An encryption parameter object comprising the cipher,
       
   192 	 *					salt, IV, and iteration count value. 
       
   193 	 * @return			The new CPBEncryptElement object
       
   194 	 */
       
   195 	IMPORT_C static CPBEncryptElement* NewLC(const TPBPassword& aPassword, 
       
   196 		const CPBEncryptParms& aParms);
       
   197 
       
   198 	/**
       
   199 	 * Creates a new CPBEncryptElement object for decryption of existing data.
       
   200 	 *
       
   201 	 * If the specified password is valid, the function regenerates the encryption key;
       
   202 	 * otherwise, it leaves with KErrBadPassphrase.
       
   203 	 *
       
   204 	 * @param aData				The encryption data object
       
   205 	 * @param aPassword			The user supplied password
       
   206 	 * @return					The new CPBEncryptElement object
       
   207 	 * @leave KErrBadPassphrase	If the specified password is incorrect
       
   208 	 */
       
   209 	IMPORT_C static CPBEncryptElement* NewL(const CPBEncryptionData& aData,
       
   210 		const TPBPassword& aPassword);
       
   211 
       
   212 	/**
       
   213 	 * Creates a new CPBEncryptElement object for decryption of existing data.
       
   214 	 *
       
   215 	 * If the specified password is valid, the function regenerates the encryption key;
       
   216 	 * otherwise, it leaves with KErrBadPassphrase.
       
   217 	 *
       
   218 	 * A pointer to the returned object is put onto the cleanup stack.
       
   219 	 *
       
   220 	 * @param aData				The encryption data object
       
   221 	 * @param aPassword			The user supplied password
       
   222 	 * @return					The new CPBEncryptElement object
       
   223 	 * @leave KErrBadPassphrase	If the specified password is incorrect
       
   224 	 */
       
   225 	IMPORT_C static CPBEncryptElement* NewLC(const CPBEncryptionData& aData,
       
   226 		const TPBPassword& aPassword);
       
   227 
       
   228 	/** 
       
   229 	 * Gets the parameters allowing one to re-create the object with the
       
   230 	 * same state at another point in the future.  
       
   231 	 * 
       
   232 	 * In order to decrypt any information previously encrypted with this object, 
       
   233 	 * you <B><I>must</I></B> store this encryption data along with it. Failure 
       
   234 	 * to do this will result in the permanent loss of the encrypted information.
       
   235 	 * 
       
   236 	 * @return The data allowing one to re-create this object at a later time.					
       
   237 	 */
       
   238 	const CPBEncryptionData& EncryptionData(void) const;
       
   239 
       
   240 	/** 
       
   241 	 * Constructs a CPBEncryptor object allowing the encryption of data.
       
   242 	 * 
       
   243 	 * @return	A pointer to a CPBEncryptor object.
       
   244 	 *			The caller assumes ownership of the returned object.
       
   245 	 */
       
   246 	CPBEncryptor* NewEncryptL(void) const;
       
   247 
       
   248 	/** 
       
   249 	 * Constructs a CPBEncryptor object allowing the encryption of data.
       
   250 	 * 
       
   251 	 * @return	A pointer to a CPBEncryptor object.
       
   252 	 *			The caller assumes ownership of the returned object.
       
   253 	 *			The returned pointer is left on the cleanup stack.
       
   254 	 */
       
   255 	CPBEncryptor* NewEncryptLC(void) const;
       
   256 
       
   257 	/** 
       
   258 	 * Constructs a CPBDecryptor object allowing the decryption of data.
       
   259 	 * 
       
   260 	 * @return	A pointer to a CPBDecryptor object.
       
   261 	 *			The caller assumes ownership of the returned object.
       
   262 	 */
       
   263 	CPBDecryptor* NewDecryptL(void) const;
       
   264 
       
   265 	/** 
       
   266 	 * Constructs a CPBDecryptor object allowing the decryption of data.
       
   267 	 * 
       
   268 	 * @return	A pointer to a CPBDecryptor object.
       
   269 	 *			The caller assumes ownership of the returned object.
       
   270 	 *			The returned pointer is left on the cleanup stack.
       
   271 	 */
       
   272 	CPBDecryptor* NewDecryptLC(void) const;
       
   273 
       
   274 	/** 
       
   275 	 * Gets the maximum output ciphertext length given a specified input plaintext length.  
       
   276 	 * 
       
   277 	 * @param aPlaintextLength	The plaintext length 
       
   278 	 * @return					The maximum ciphertext length given a plaintext length.
       
   279 	 */
       
   280 	TInt MaxCiphertextLength(TInt aPlaintextLength) const;
       
   281 
       
   282 	/** 
       
   283 	 * Gets the maximum output plaintext length given a specified input ciphertext length.
       
   284 	 *
       
   285 	 * @param aCiphertextLength	The ciphertext length
       
   286 	 * @return					The maximum plaintext length given a ciphertext length.
       
   287 	 */
       
   288 	TInt MaxPlaintextLength(TInt aCiphertextLength) const;
       
   289 
       
   290 	/** Destructor */
       
   291 	virtual ~CPBEncryptElement(void);
       
   292 protected:
       
   293 	/** @internalAll */
       
   294 	void ConstructL(const TDesC8& aPassword);
       
   295 	/** @internalAll */
       
   296 	void ConstructL(const TDesC8& aPassword, const TPBECipher aCipher);
       
   297 	/** @internalAll */
       
   298 	void ConstructL(const TDesC8& aPassword, const CPBEncryptParms& aParms);
       
   299 	/** @internalAll */
       
   300 	void ConstructL(const CPBEncryptionData& aData, const TPBPassword& aPassword);
       
   301 	/** @internalAll */
       
   302 	TBool AuthenticateL(const TPBPassword& aPassword);
       
   303 	/** @internalAll */
       
   304 	void MakeEncryptKeyL(TUint aKeySize, const TDesC8& aPassword);
       
   305 	/** @internalAll */
       
   306 	CPBEncryptElement(void);
       
   307 protected:
       
   308 	/** The encryption data */
       
   309 	CPBEncryptionData* iData;
       
   310 	/** The derived encryption key */
       
   311 	HBufC8* iEncryptKey;
       
   312 private:
       
   313 	CPBEncryptElement(const CPBEncryptElement&);
       
   314 	CPBEncryptElement& operator= (const CPBEncryptElement&);
       
   315 	};
       
   316 
       
   317 /** 
       
   318  * Derived class to allow the efficient password based encryption and
       
   319  * decryption of multiple elements.
       
   320  * 
       
   321  * This is useful if one wants random access to an encrypted source consisting 
       
   322  * of multiple independent elements, for example, a database or a store. 
       
   323  * 
       
   324  * Since it is unreasonable to force the decryption of an entire set to allow 
       
   325  * access to just a tiny portion of it, and since it is too costly to derive separate 
       
   326  * keys for each element within the set, a single randomly generated <I>master</I> 
       
   327  * key is used.  This master key is encrypted with the password provided by the 
       
   328  * user of the class. Known plaintext attacks against the ciphertext are prevented 
       
   329  * by using a randomly chosen Initialisation Vector (IV) for each element.  
       
   330  * 
       
   331  * Contains the master encryption key.
       
   332  *
       
   333  * See the Cryptography api-guide documentation for more information and sample code.
       
   334  *
       
   335  * @see CPBEncryptElement
       
   336  * 
       
   337  * @since v8.0
       
   338  */
       
   339 class CPBEncryptSet : public CPBEncryptElement
       
   340 	{
       
   341 public:
       
   342 	/**
       
   343 	 * Creates a new CPBEncryptSet object for encryption of new data 
       
   344 	 * (and generates an encrypted master key).
       
   345 	 *
       
   346 	 * If strong cryptography is present, a 128 bit AES cipher is used; 
       
   347 	 * otherwise, for weak cryptography, a 56 bit DES cipher is used.
       
   348 	 *
       
   349 	 * The symmetric key is derived from the password and a random salt using TPKCS5KDF::DeriveKeyL().
       
   350 	 *
       
   351 	 * @param aPassword	The users password.
       
   352 	 * @return			A new CPBEncryptSet object
       
   353 	 */
       
   354 	IMPORT_C static CPBEncryptSet* NewL(const TPBPassword& aPassword);
       
   355 
       
   356 	/**
       
   357 	 * Creates a new CPBEncryptSet object for encryption of new data 
       
   358 	 * (and generates an encrypted master key).
       
   359 	 *
       
   360 	 * The returned pointer is put onto the cleanup stack.
       
   361 	 *
       
   362 	 * If strong cryptography is present, a 128 bit AES cipher is used; 
       
   363 	 * otherwise, for weak cryptography, a 56 bit DES cipher is used.
       
   364 	 *
       
   365 	 * The symmetric key is derived from the password and a random salt using TPKCS5KDF::DeriveKeyL().
       
   366 	 *
       
   367 	 * @param aPassword	The user supplied password
       
   368 	 * @return			The new CPBEncryptSet object
       
   369 	 */
       
   370 	IMPORT_C static CPBEncryptSet* NewLC(const TPBPassword& aPassword);
       
   371 
       
   372 	/**
       
   373 	 * Creates a new CPBEncryptSet object for encryption of new data 
       
   374 	 * (and generates an encrypted master key).
       
   375 	 *
       
   376 	 * The symmetric key is derived from the password and a random salt using TPKCS5KDF::DeriveKeyL().
       
   377 	 * 
       
   378 	 * @param aPassword	The user supplied password
       
   379 	 * @param aCipher	The cipher to use
       
   380 	 * @return			The new CPBEncryptSet object
       
   381 	 */
       
   382 	IMPORT_C static CPBEncryptSet* NewL(const TPBPassword& aPassword, 
       
   383 		TPBECipher aCipher);
       
   384 
       
   385 	/**
       
   386 	 * Creates a new CPBEncryptSet object for encryption of new data 
       
   387 	 * (and generates an encrypted master key).
       
   388 	 *
       
   389 	 * The returned pointer is put onto the cleanup stack.
       
   390 	 *
       
   391 	 * The symmetric key is derived from the password and a random salt using TPKCS5KDF::DeriveKeyL().
       
   392 	 * 
       
   393 	 * @param aPassword	The user supplied password
       
   394 	 * @param aCipher	The cipher to use
       
   395 	 * @return			The new CPBEncryptSet object
       
   396 	 */
       
   397 	IMPORT_C static CPBEncryptSet* NewLC(const TPBPassword& aPassword, 
       
   398 		TPBECipher aCipher);
       
   399 
       
   400 	/**
       
   401 	 * Creates a new CPBEncryptSet object for encryption of new data 
       
   402 	 * (and generates an encrypted master key).
       
   403 	 *
       
   404 	 * The symmetric key is derived from the password using TPKCS5KDF::DeriveKeyL().
       
   405 	 * 
       
   406 	 * @param aPassword	The user supplied password
       
   407 	 * @param aParms	An encryption parameter object comprising the cipher,
       
   408 	 *					salt, IV, and iteration count value. 
       
   409 	 * @return			The new CPBEncryptSet object
       
   410 	 */
       
   411 	IMPORT_C static CPBEncryptSet* NewL(const TPBPassword& aPassword, 
       
   412 		const CPBEncryptParms& aParms);
       
   413 
       
   414 	/**
       
   415 	 * Creates a new CPBEncryptSet object for encryption of new data 
       
   416 	 * (and generates an encrypted master key).
       
   417 	 *
       
   418 	 * The returned pointer is put onto the cleanup stack.
       
   419 	 *
       
   420 	 * The symmetric key is derived from the password using TPKCS5KDF::DeriveKeyL().
       
   421 	 * 
       
   422 	 * @param aPassword	The user supplied password
       
   423 	 * @param aParms	An encryption parameter object comprising the cipher,
       
   424 	 *					salt, IV, and iteration count value. 
       
   425 	 * @return			The new CPBEncryptSet object
       
   426 	 */
       
   427 	IMPORT_C static CPBEncryptSet* NewLC(const TPBPassword& aPassword, 
       
   428 		const CPBEncryptParms& aParms);
       
   429 
       
   430 	/**
       
   431 	 * Creates a new CPBEncryptSet object for encryption of new data 
       
   432 	 * (and generates an encrypted master key).
       
   433 	 *
       
   434 	 * If the specified password is valid, the function regenerates the encryption key;
       
   435 	 * otherwise, it leaves with KErrBadPassphrase.
       
   436 	 *
       
   437 	 * @param aData					The encryption data object to copy 
       
   438 	 * @param aEncryptedMasterKey	On return, the encrypted master key
       
   439 	 * @param aPassword				The user supplied password
       
   440 	 * @return						The new CPBEncryptSet object
       
   441 	 * @leave KErrBadPassphrase		If the specified password is incorrect
       
   442 	 */
       
   443 	IMPORT_C static CPBEncryptSet* NewL(const CPBEncryptionData& aData,
       
   444 		const TDesC8& aEncryptedMasterKey, const TPBPassword& aPassword);
       
   445 
       
   446 	/**
       
   447 	 * Creates a new CPBEncryptSet object for encryption of new data 
       
   448 	 * (and generates an encrypted master key).
       
   449 	 *
       
   450 	 * The returned pointer is put onto the cleanup stack.
       
   451 	 *
       
   452 	 * If the specified password is valid, the function regenerates the encryption key;
       
   453 	 * otherwise, it leaves with KErrBadPassphrase.
       
   454 	 *
       
   455 	 * @param aData					The encryption data object to copy 
       
   456 	 * @param aEncryptedMasterKey	On return, the encrypted master key
       
   457 	 * @param aPassword				The user supplied password
       
   458 	 * @return						The new CPBEncryptSet object
       
   459 	 * @leave KErrBadPassphrase		If the specified password is incorrect
       
   460 	 */
       
   461 	IMPORT_C static CPBEncryptSet* NewLC(const CPBEncryptionData& aData,
       
   462 		const TDesC8& aEncryptedMasterKey, const TPBPassword& aPassword);
       
   463 	
       
   464 	/** 
       
   465 	 * Gets the encrypted form of the master key.  
       
   466 	 *
       
   467 	 * This must be stored along with the object returned by CPBEncryptElement::EncryptionData() 
       
   468 	 * in order for the object to be reconstructed with the same state at
       
   469      * some time in the future. Failure to do so will result in the permanent
       
   470      * loss of any information encrypted with this object.
       
   471      * 
       
   472      * @return		The encrypted master key.
       
   473      */
       
   474 	IMPORT_C const TDesC8& EncryptedMasterKey(void) const;
       
   475 	
       
   476 	/** 
       
   477 	 * Constructs a CPBEncryptor object based on the state of this object
       
   478 	 * (i.e., the cipher and master key) allowing the encryption of data.
       
   479 	 * 
       
   480 	 * @return	A pointer to a CPBEncryptor object.
       
   481 	 *			The caller assumes ownership of the returned object.
       
   482 	 */
       
   483 	CPBEncryptor* NewEncryptL(void) const;
       
   484 
       
   485 	/** 
       
   486 	 * Constructs a CPBEncryptor object based on the state of this object
       
   487 	 * (i.e., the cipher and master key) allowing the encryption of data.
       
   488 	 * 
       
   489 	 * @return	A pointer to a CPBEncryptor object.
       
   490 	 *			The caller assumes ownership of the returned object.
       
   491 	 *			The returned pointer is left on the cleanup stack.
       
   492 	 */
       
   493 	CPBEncryptor* NewEncryptLC(void) const;
       
   494 
       
   495 	/** 
       
   496 	 * Constructs a CPBDecryptor object based on the state of this object
       
   497 	 * (i.e., the cipher and master key) allowing the decryption of data.
       
   498 	 * 
       
   499 	 * @return	A pointer to a CPBDecryptor object.
       
   500 	 *			The caller assumes ownership of the returned object.
       
   501 	 */
       
   502 	CPBDecryptor* NewDecryptL(void) const;
       
   503 
       
   504 	/** 
       
   505 	 * Constructs a CPBDecryptor object based on the state of this object
       
   506 	 * (i.e., the cipher and master key) allowing the decryption of data.
       
   507 	 * 
       
   508 	 * @return	A pointer to a CPBDecryptor object.
       
   509 	 *			The caller assumes ownership of the returned object.
       
   510 	 *			The returned pointer is left on the cleanup stack.
       
   511 	 */
       
   512 	CPBDecryptor* NewDecryptLC(void) const;
       
   513 
       
   514 	/** 
       
   515      * Re-encrypts the master key with the specified new password.
       
   516      *
       
   517      * @param aNewPassword	The new password
       
   518      */
       
   519 	IMPORT_C void ChangePasswordL(const TPBPassword& aNewPassword);
       
   520 
       
   521 	/** 
       
   522 	 * Gets the maximum output ciphertext length given a specified input plaintext length.  
       
   523 	 * 
       
   524 	 * @param aPlaintextLength	The plaintext length 
       
   525 	 * @return					The maximum ciphertext length given a plaintext length.
       
   526 	 */
       
   527 	TInt MaxCiphertextLength(TInt aPlaintextLength) const;
       
   528 
       
   529 	/** 
       
   530 	 * Gets the maximum output plaintext length given a specified input ciphertext length.
       
   531 	 *
       
   532 	 * @param aCiphertextLength	The ciphertext length
       
   533 	 * @return					The maximum plaintext length given a ciphertext length.
       
   534 	 */
       
   535 	TInt MaxPlaintextLength(TInt aCiphertextLength) const;
       
   536 	
       
   537 	/** Destructor */
       
   538 	virtual ~CPBEncryptSet(void);
       
   539 protected:
       
   540 	/** @internalAll */
       
   541 	void ConstructL(const TDesC8& aPassword);
       
   542 	/** @internalAll */
       
   543 	void ConstructL(const TDesC8& aPassword, TPBECipher aCipher);
       
   544 	/** @internalAll */
       
   545 	void ConstructL(const TDesC8& aPassword, const CPBEncryptParms& aParms);
       
   546 	/** @internalAll */
       
   547 	void ConstructMasterKeyL(void);
       
   548 	/** @internalAll */
       
   549 	void ConstructL(const CPBEncryptionData& aData, 
       
   550 		const TDesC8& aEncryptedMasterKey, const TPBPassword& aPassword);
       
   551 	/** @internalAll */
       
   552 	void DecryptMasterKeyL(TDes8& aMasterKey) const;
       
   553 	/** @internalAll */
       
   554 	void EncryptMasterKeyL(const TDesC8& aMasterKey);
       
   555 protected:
       
   556 	/** @internalAll */
       
   557 	CPBEncryptSet(void);
       
   558 	/** The derived encrypted master key*/
       
   559 	HBufC8* iEncryptedMasterKey;
       
   560 private:
       
   561 	CPBEncryptSet(const CPBEncryptSet&);
       
   562 	CPBEncryptSet& operator= (const CPBEncryptSet&);
       
   563 	};
       
   564 
       
   565 /** 
       
   566  * Class representing both 8 and 16 bit descriptor passwords.
       
   567  * Internally these are stored as 8 bit passwords.
       
   568  */
       
   569 class TPBPassword
       
   570 	{
       
   571 public:
       
   572 	/** 
       
   573 	 * Sets the password.
       
   574 	 * 
       
   575 	 * Constructs a TPBPassword object with an 8 bit descriptor.
       
   576 	 * 
       
   577 	 * Internally this is represented as an octet byte sequence 
       
   578 	 * (aka 8 bit TPtrC8 descriptor).
       
   579 	 * 
       
   580 	 * @param aPassword	A const reference to an 8 bit descriptor.
       
   581 	 * 					representing the users initial password.
       
   582 	 */
       
   583 	IMPORT_C TPBPassword(const TDesC8& aPassword);
       
   584 	
       
   585 	/** 
       
   586 	 * Sets the password.
       
   587 	 * 
       
   588 	 * Constructs a TPBPassword object with a 16 bit descriptor.
       
   589 	 *
       
   590 	 * Internally this is represented as an octet byte sequence
       
   591 	 * (aka 8 bit TPtrC8 descriptor).
       
   592 	 * 
       
   593 	 * @param aPassword	A const reference to a 16 bit descriptor
       
   594 	 * 					representing the users initial password.
       
   595 	 */
       
   596 	IMPORT_C TPBPassword(const TDesC16& aPassword);
       
   597 	
       
   598 	/**
       
   599 	 * Gets the password.
       
   600 	 * 
       
   601 	 * Gets a const reference to an 8 bit descriptor representing the users
       
   602 	 * initial password (which could have been either 8 or 16 bit).
       
   603 	 * 
       
   604 	 * @return		A const reference to an 8 bit descriptor.
       
   605 	 */
       
   606 	IMPORT_C const TDesC8& Password(void) const;
       
   607 private:
       
   608 	TPtrC8 iPassword;
       
   609 	};
       
   610 
       
   611 #endif