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 

    23 /**

    24  @file

    25  @publishedPartner

    26  @released

    27 */

    28 

    29 #ifndef __PBEDATA_H__

    30 #define __PBEDATA_H__

    31 

    32 #include <s32strm.h>

    33 #include <pbe.h>

    34 

    35 /**

    36  * Contains the Password Based Encryption parameters.

    37  * An object of this class can be input for CPBEncryptElement or CPBEncryptSet objects.

    38  *

    39  * @since v7.0s

    40  */

    41 class CPBEncryptParms : public CBase

    42 	{

    43 public:

    44 	enum TKdf

    45 	/**

    46 		Key derivation function.

    47 		This does not affect the authentication key,

    48 		which always uses PKCS#5.

    49 	 */

    50 		{

    51 		EKdfPkcs5,

    52 		EKdfPkcs12

    53 		};

    54 	

    55 	/**

    56 	 * Creates a new CPBEncryptParms object.

    57 	 *

    58 	 * @param aCipher		The cipher to use

    59 	 * @param aSalt			The salt

    60 	 * @param aIV			The Initialization Vector

    61 	 * @param aIterations	The number of iterations of the PBE algorithm

    62 	 * @return				A pointer to the new CPBEncryptParms object

    63 	 */

    64 	IMPORT_C static CPBEncryptParms* NewL(TPBECipher aCipher,

    65 		const TDesC8& aSalt, const TDesC8& aIV, TUint aIterations);

    66 

    67 	/**

    68 	 * Creates a new CPBEncryptParms object and puts a pointer to it onto the cleanup stack.

    69 	 *

    70 	 * @param aCipher		The cipher to use

    71 	 * @param aSalt			The salt

    72 	 * @param aIV			The Initialization Vector

    73 	 * @param aIterations	The number of iterations of the PBE algorithm

    74 	 * @return				A pointer to the new CPBEncryptParms object

    75 	 */

    76 	IMPORT_C static CPBEncryptParms* NewLC(TPBECipher aCipher,

    77 		const TDesC8& aSalt, const TDesC8& aIV, TUint aIterations);

    78 

    79 	/**

    80 	 * Creates a new CPBEncryptParms object from an existing object.

    81 	 *

    82 	 * @param aParms		The existing encryption parameters object

    83 	 * @return				A pointer to the new CPBEncryptParms object

    84 	 */

    85 	IMPORT_C static CPBEncryptParms* NewL(const CPBEncryptParms& aParms);

    86 

    87 	/**

    88 	 * Creates a new CPBEncryptParms object from an existing object

    89 	 * and puts a pointer to it onto the cleanup stack.

    90 	 *

    91 	 * @param aParms		The existing encryption parameters object

    92 	 * @return				A pointer to the new CPBEncryptParms object

    93 	 */

    94 	IMPORT_C static CPBEncryptParms* NewLC(const CPBEncryptParms& aParms);

    95 

    96 	/**

    97 	 * Internalizes encryption parameter data from a read stream.

    98 	 *

    99 	 * @param aStream	The read stream to be internalized

   100 	 * @return			A pointer to the new CPBEncryptParms object

   101 	 * 

   102 	 */

   103 	IMPORT_C static CPBEncryptParms* NewL(RReadStream& aStream);

   104 

   105 	/**

   106 	 * Internalizes encryption parameter data from a read stream, and 

   107 	 * puts a pointer to the new object onto the cleanup stack.

   108 	 *

   109 	 * @param aStream	The read stream to be internalized

   110 	 * @return			A pointer to the new CPBEncryptParms object

   111 	 */

   112 	IMPORT_C static CPBEncryptParms* NewLC(RReadStream& aStream);

   113 

   114 	/**

   115 	 * Gets the PBE cipher

   116 	 *

   117 	 * @return	The cipher to use

   118 	 */

   119 	IMPORT_C TPBECipher Cipher() const;

   120 	/**

   121 		Gets the key derivation function (KDF.)

   122 		

   123 		@return The key derivation function (KDF) which

   124 			transforms the password into an encryption key.

   125 	 */

   126 	IMPORT_C TKdf Kdf() const;

   127 

   128 	/**

   129 	 * Gets the PBE salt

   130 	 *

   131 	 * @return	The salt

   132 	 */

   133 	IMPORT_C TPtrC8 Salt() const;

   134 

   135 	/**

   136 	 * Gets the number of iterations for the PKCS#5 algorithm.

   137 	 *

   138 	 * @return	The number of iterations

   139 	 */

   140 	IMPORT_C TInt Iterations() const;

   141 

   142 	/**

   143 	 * Gets the PBE Initialization Vector

   144 	 *

   145 	 * @return	The IV

   146 	 */

   147 	IMPORT_C TPtrC8 IV() const;

   148 

   149 	IMPORT_C void SetIV(const TDesC8& aNewIv);

   150 

   151 	/**

   152 	 * Externalizes the encryption parameters into a write stream.

   153 	 *

   154 	 * @param aStream	The stream to write to

   155 	 */

   156 	IMPORT_C void ExternalizeL(RWriteStream& aStream) const;

   157 	IMPORT_C static CPBEncryptParms* NewL();

   158 	IMPORT_C static CPBEncryptParms* NewLC();

   159 	

   160 	IMPORT_C void SetCipher(TPBECipher aCipher);

   161 

   162     /**

   163      * Replace the current cipher.  This function resizes the

   164      * IV and replaces its existing contents.

   165      *	

   166      * @param aCipher	New cipher.

   167      * @leave			System wide error code.

   168      */

   169   	inline void SetCipherL(TPBECipher aCipher)

   170   		{

   171   		SetCipher(aCipher);

   172   		}

   173 

   174 	IMPORT_C void SetKdf(TKdf aKdf);

   175 	IMPORT_C void ResizeSaltL(TInt aNewLen);

   176 	IMPORT_C void SetIterations(TInt aIterCount);

   177 

   178 	/** Destructor */

   179 	virtual ~CPBEncryptParms(void);

   180 	/** @internalAll */

   181 	void DeriveKeyL(const TDesC8& aPassword, TDes8& aKeyBuf) const;

   182 

   183 	

   184 protected:	

   185 #ifdef PBEDATA_NO_EXPORTED_CONSTRUCTORS

   186 	/** @internalAll */

   187 	CPBEncryptParms(void);

   188 #else

   189 	/** Constructor */

   190 	IMPORT_C CPBEncryptParms(void);

   191 #endif

   192 

   193 	/** @internalAll */

   194 	void ConstructL();

   195 

   196 	/** @internalAll*/

   197 	void ConstructL(TPBECipher aCipher, const TDesC8& aSalt,

   198 		const TDesC8& aIV, TUint aIterations);

   199 	/** @internalAll*/

   200 	void ConstructL(const CPBEncryptParms& aParms);

   201 	/** @internalAll*/

   202 	void ConstructL(RReadStream& aStream);

   203 private:

   204 	CPBEncryptParms(const CPBEncryptParms&);

   205 	CPBEncryptParms& operator= (const CPBEncryptParms&);

   206 private:

   207 	class TParamsData

   208 	/**

   209 		This class contains multiple objects.  Its

   210 		pointer is stored in CPBEncryptParms to preserve

   211 		BC, because CPBEncryptParms has an exported,

   212 		protected constructor.

   213 	 */

   214 		{

   215 	public:

   216 		TPBECipher iCipher;

   217 		/**

   218 			The password is processed with this function

   219 			to generate the encryption key.

   220 		 */

   221 		TKdf iKdf;

   222 		};

   223 	TParamsData* iData;

   224 

   225 	HBufC8* iSalt;

   226 	HBufC8* iIV;

   227 	TUint iIterations;

   228 	};

   229 

   230 

   231 /**

   232  * Contains the password based authentication data.

   233  * Used to check the passphrase when decrypting.

   234  *

   235  * @since v7.0s

   236  */

   237 class CPBAuthData : public CBase

   238 	{

   239 public:

   240 	/**

   241 	 * Derives an authentication key.

   242 	 *

   243 	 * @param aPassword		The user's initial password

   244 	 * @param aSalt			The salt

   245 	 * @param aKeySize		The key size

   246 	 * @param aIterations	The number of iterations of the PBE algorithm

   247 	 * @return				A pointer to the new CPBAuthData object

   248 	 */

   249 	IMPORT_C static CPBAuthData* NewL(const TDesC8& aPassword, 

   250 		const TDesC8& aSalt, TUint aKeySize, TUint aIterations);

   251 

   252 	/**

   253 	 * Derives an authentication key.

   254 	 *

   255 	 * The returned pointer is put onto the cleanup stack.

   256 	 *

   257 	 * @param aPassword		The user's initial password

   258 	 * @param aSalt			The salt

   259 	 * @param aKeySize		The key size

   260 	 * @param aIterations	The number of iterations of the PBE algorithm

   261 	 * @return				A pointer to the new CPBAuthData object

   262 	 */

   263 	IMPORT_C static CPBAuthData* NewLC(const TDesC8& aPassword, 

   264 		const TDesC8& aSalt, TUint aKeySize, TUint aIterations);

   265 

   266 	/**

   267 	 * Creates a new CPBAuthData object from an existing authentication key.

   268 	 *

   269 	 * @param aData	The existing CPBAuthData object

   270 	 * @return		A pointer to the new CPBAuthData object

   271 	 */

   272 	IMPORT_C static CPBAuthData* NewL(const CPBAuthData& aData);

   273 

   274 	/**

   275 	 * Creates a new CPBAuthData object from an existing authentication key.

   276 	 *

   277 	 * The returned pointer is put onto the cleanup stack.

   278 	 *

   279 	 * @param aData	The existing CPBAuthData object

   280 	 * @return		A pointer to the new CPBAuthData object

   281 	 */

   282 	IMPORT_C static CPBAuthData* NewLC(const CPBAuthData& aData);

   283 

   284 	/**

   285 	 * Creates a new CPBAuthData object from an existing authentication key

   286 	 * by internalizing the authentication data from a read stream.

   287 	 *

   288 	 * @param aStream	The stream to read from

   289 	 * @return			A pointer to the new CPBAuthData object

   290 	 */

   291 	IMPORT_C static CPBAuthData* NewL(RReadStream& aStream);

   292 

   293 	/**

   294 	 * Creates a new CPBAuthData object from an existing authentication key

   295 	 * by internalizing the authentication data from a read stream.

   296 	 *

   297 	 * The returned pointer is put onto the cleanup stack.

   298 	 *

   299 	 * @param aStream	The stream to read from

   300 	 * @return			A pointer to the new CPBAuthData object

   301 	 */

   302 	IMPORT_C static CPBAuthData* NewLC(RReadStream& aStream);

   303 

   304 	/**

   305 	 * Gets the authentication key

   306 	 *

   307 	 * @return	The key

   308 	 */

   309 	IMPORT_C TPtrC8 Key() const;

   310 

   311 	/**

   312 	 * Gets the salt used for the authentication 

   313 	 *

   314 	 * @return	The salt

   315 	 */

   316 	IMPORT_C TPtrC8 Salt() const;

   317 

   318 	/**

   319 	 * Gets the number of iterations of the hashing algorithm.

   320 	 *

   321 	 * @return	The number of iterations

   322 	 */

   323 	IMPORT_C TInt Iterations() const;

   324 

   325 	/**

   326 	 * Tests whether two authentication keys are identical 

   327 	 *

   328 	 * @param aAuth	The authentication data object which holds the key to be tested

   329 	 * @return		ETrue, if they are identical; EFalse, otherwise

   330 	 */

   331 	IMPORT_C TBool operator==(const CPBAuthData& aAuth) const;

   332 

   333 	/**

   334 	 * Externalizes the encryption parameters into a write stream.

   335 	 *

   336 	 * @param aStream	The stream to write to

   337 	 */

   338 	IMPORT_C void ExternalizeL(RWriteStream& aStream) const;

   339 

   340 	/** Destructor */

   341 	virtual ~CPBAuthData(void);

   342 protected:

   343 #ifdef PBEDATA_NO_EXPORTED_CONSTRUCTORS

   344 	/** @internalAll */

   345 	CPBAuthData(void);

   346 #else

   347 	/** Constructor */

   348 	IMPORT_C CPBAuthData(void);

   349 #endif

   350 	/** @internalAll */

   351 	void ConstructL(const TDesC8& aPassword, const TDesC8& aSalt,

   352 		TUint aKeySize, TUint aIterations);

   353 	/** @internalAll */

   354 	void ConstructL(const CPBAuthData& aData);

   355 	/** @internalAll */

   356 	void ConstructL(RReadStream& aStream);

   357 private:

   358 	CPBAuthData(const CPBAuthData&);

   359 	CPBAuthData& operator= (const CPBAuthData&);

   360 private:

   361 	HBufC8* iAuthKey;

   362 	HBufC8* iSalt;

   363 	TUint iIterations;

   364 	};

   365 

   366 /** 

   367  * Represents the information needed to decrypt encrypted data given the correct password.  

   368  * Contains the authentication key, and the parameters used to derive the encryption key.

   369  * A CPBEncryptionData object needs to be stored to recover any data for later use.

   370  *

   371  * @see CPBEncryptParms

   372  * @see CPBAuthData

   373  *

   374  * @since v7.0s

   375  */

   376 class CPBEncryptionData : public CBase

   377 	{

   378 public:

   379 	/**

   380 	 * Creates a new CPBEncryptionData object 

   381 	 *

   382 	 * @param aPassword		The user's initial password

   383 	 * @param aCipher		The cipher to use

   384 	 * @param aAuthSalt		The salt used for the authentication

   385 	 * @param aEncryptSalt	The salt used for the encryption

   386 	 * @param aIV			The Initialization Vector

   387 	 * @param aIterations	The number of iterations of the PBE algorithm

   388 	 * @return				A pointer to the new CPBEncryptionData object

   389 	 */

   390 	IMPORT_C static CPBEncryptionData* NewL(const TDesC8& aPassword,

   391 		TPBECipher aCipher, const TDesC8& aAuthSalt, 

   392 		const TDesC8& aEncryptSalt, const TDesC8& aIV, TUint aIterations);

   393 

   394 	/**

   395 	 * Creates a new CPBEncryptionData object 

   396 	 * and puts a pointer to it onto the cleanup stack.

   397 	 *

   398 	 * @param aPassword		The user's initial password

   399 	 * @param aCipher		The cipher to use

   400 	 * @param aAuthSalt		The salt used for the authentication

   401 	 * @param aEncryptSalt	The salt used for the encryption

   402 	 * @param aIV			The Initialization Vector

   403 	 * @param aIterations	The number of iterations of the PBE algorithm

   404 	 * @return				A pointer to the new CPBEncryptionData object

   405 	 */

   406 	IMPORT_C static CPBEncryptionData* NewLC(const TDesC8& aPassword,

   407 		TPBECipher aCipher, const TDesC8& aAuthSalt, 

   408 		const TDesC8& aEncryptSalt, const TDesC8& aIV, TUint aIterations);

   409 

   410 	/**

   411 	 * Creates a new CPBEncryptionData from an existing one.

   412 	 *

   413 	 * @param aData	The existing CPBEncryptionData object

   414 	 * @return		A pointer to the new CPBEncryptionData object

   415 	 */

   416 	IMPORT_C static CPBEncryptionData* NewL(const CPBEncryptionData& aData);

   417 

   418 	/**

   419 	 * Creates a new CPBEncryptionData from an existing one,

   420 	 * and puts a pointer to it onto the cleanup stack.

   421 	 *

   422 	 * @param aData	The existing CPBEncryptionData object

   423 	 * @return		A pointer to the new CPBEncryptionData object

   424 	 */

   425 	IMPORT_C static CPBEncryptionData* NewLC(const CPBEncryptionData& aData);

   426 

   427 	/**

   428 	 * Internalizes the encryption data from a read stream.

   429 	 *

   430 	 * @param aStream	The stream to read from

   431 	 * @return			A pointer to the new CPBEncryptionData object

   432 	 */

   433 	IMPORT_C static CPBEncryptionData* NewL(RReadStream& aStream);

   434 

   435 	/**

   436 	 * Internalizes the encryption data from a read stream,

   437 	 * and puts a pointer to it onto the cleanup stack.

   438 	 *

   439 	 * @param aStream	The stream to read from

   440 	 * @return			A pointer to the new CPBEncryptionData object

   441 	 */

   442 	IMPORT_C static CPBEncryptionData* NewLC(RReadStream& aStream);

   443 	IMPORT_C static CPBEncryptionData* NewL(

   444 		const TDesC8& aPassword, const TDesC8& aAuthSalt,

   445 		const CPBEncryptParms& aParms);

   446 

   447 

   448 	/**

   449 	 * Returns the encryption parameter object.

   450 	 *

   451 	 * @return	The CPBEncryptParms object

   452 	 */

   453 	IMPORT_C const CPBEncryptParms& EncryptParms() const;

   454 

   455 	/**

   456 	 * Returns the authentication data object.

   457 	 *

   458 	 * @return	The CPBAuthData object

   459 	 */

   460 	IMPORT_C const CPBAuthData& AuthData() const;

   461 

   462 	/**

   463 	 * Externalizes the encryption data into a write stream.

   464 	 *

   465 	 * @param aStream	The stream to write to

   466 	 */

   467 	IMPORT_C void ExternalizeL(RWriteStream& aStream) const;

   468 

   469 	/** Destructor */

   470 	virtual ~CPBEncryptionData(void);

   471 protected:

   472 #ifdef PBEDATA_NO_EXPORTED_CONSTRUCTORS

   473 	/** @internalAll */

   474 	CPBEncryptionData(void);

   475 #else

   476 	/** Constructor */

   477 	IMPORT_C CPBEncryptionData(void);

   478 #endif

   479 	/** @internalAll */

   480 	void ConstructL(const TDesC8& aPassword, TPBECipher aCipher,

   481 		const TDesC8& aAuthSalt, const TDesC8& aEncryptSalt, const TDesC8& aIV,

   482 		TUint aIterations);

   483 	/** @internalAll */

   484 	void ConstructL(const CPBEncryptionData& aData);

   485 	/** @internalAll */

   486 	void ConstructL(

   487 		const TDesC8& aPassword, const TDesC8& aAuthSalt,

   488 		const CPBEncryptParms& aParms);

   489 	/** @internalAll */

   490 	void ConstructL(RReadStream& aStream);

   491 private:

   492 	CPBEncryptionData(const CPBEncryptionData&);

   493 	CPBEncryptionData& operator= (const CPBEncryptionData&);

   494 private:

   495 	CPBEncryptParms* iParms;

   496 	CPBAuthData* iAuth;

   497 	};

   498 

   499 #endif