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 __PBEDATA_H__

    28 #define __PBEDATA_H__

    29 

    30 #include <s32strm.h>

    31 #include <pbe.h>

    32 

    33 /**

    34  * Contains the Password Based Encryption parameters.

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

    36  *

    37  * @since v7.0s

    38  */

    39 class CPBEncryptParms : public CBase

    40 	{

    41 public:

    42 	enum TKdf

    43 	/**

    44 		Key derivation function.

    45 		This does not affect the authentication key,

    46 		which always uses PKCS#5.

    47 	 */

    48 		{

    49 		EKdfPkcs5,

    50 		EKdfPkcs12

    51 		};

    52 	

    53 	/**

    54 	 * Creates a new CPBEncryptParms object.

    55 	 *

    56 	 * @param aCipher		The cipher to use

    57 	 * @param aSalt			The salt

    58 	 * @param aIV			The Initialization Vector

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

    60 	 * @return				A pointer to the new CPBEncryptParms object

    61 	 */

    62 	IMPORT_C static CPBEncryptParms* NewL(TPBECipher aCipher,

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

    64 

    65 	/**

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

    67 	 *

    68 	 * @param aCipher		The cipher to use

    69 	 * @param aSalt			The salt

    70 	 * @param aIV			The Initialization Vector

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

    72 	 * @return				A pointer to the new CPBEncryptParms object

    73 	 */

    74 	IMPORT_C static CPBEncryptParms* NewLC(TPBECipher aCipher,

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

    76 

    77 	/**

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

    79 	 *

    80 	 * @param aParms		The existing encryption parameters object

    81 	 * @return				A pointer to the new CPBEncryptParms object

    82 	 */

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

    84 

    85 	/**

    86 	 * Creates a new CPBEncryptParms object from an existing object

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

    88 	 *

    89 	 * @param aParms		The existing encryption parameters object

    90 	 * @return				A pointer to the new CPBEncryptParms object

    91 	 */

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

    93 

    94 	/**

    95 	 * Internalizes encryption parameter data from a read stream.

    96 	 *

    97 	 * @param aStream	The read stream to be internalized

    98 	 * @return			A pointer to the new CPBEncryptParms object

    99 	 * 

   100 	 */

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

   102 

   103 	/**

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

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

   106 	 *

   107 	 * @param aStream	The read stream to be internalized

   108 	 * @return			A pointer to the new CPBEncryptParms object

   109 	 */

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

   111 

   112 	/**

   113 	 * Gets the PBE cipher

   114 	 *

   115 	 * @return	The cipher to use

   116 	 */

   117 	IMPORT_C TPBECipher Cipher() const;

   118 	/**

   119 		Gets the key derivation function (KDF.)

   120 		

   121 		@return The key derivation function (KDF) which

   122 			transforms the password into an encryption key.

   123 	 */

   124 	IMPORT_C TKdf Kdf() const;

   125 

   126 	/**

   127 	 * Gets the PBE salt

   128 	 *

   129 	 * @return	The salt

   130 	 */

   131 	IMPORT_C TPtrC8 Salt() const;

   132 

   133 	/**

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

   135 	 *

   136 	 * @return	The number of iterations

   137 	 */

   138 	IMPORT_C TInt Iterations() const;

   139 

   140 	/**

   141 	 * Gets the PBE Initialization Vector

   142 	 *

   143 	 * @return	The IV

   144 	 */

   145 	IMPORT_C TPtrC8 IV() const;

   146 

   147 	IMPORT_C void SetIV(const TDesC8& aNewIv);

   148 

   149 	/**

   150 	 * Externalizes the encryption parameters into a write stream.

   151 	 *

   152 	 * @param aStream	The stream to write to

   153 	 */

   154 	IMPORT_C void ExternalizeL(RWriteStream& aStream) const;

   155 	IMPORT_C static CPBEncryptParms* NewL();

   156 	IMPORT_C static CPBEncryptParms* NewLC();

   157 	

   158 	IMPORT_C void SetCipher(TPBECipher aCipher);

   159 

   160    /**

   161     * Replace the current cipher.  This function resizes the

   162     * IV and replaces its existing contents.

   163     *	

   164     * @param aCipher	New cipher.

   165     * @leave			System wide error code.

   166     */

   167 	inline void SetCipherL(TPBECipher aCipher)

   168 		{

   169 		SetCipher(aCipher);

   170 		}

   171 

   172 	IMPORT_C void SetKdf(TKdf aKdf);

   173 	IMPORT_C void ResizeSaltL(TInt aNewLen);

   174 	IMPORT_C void SetIterations(TInt aIterCount);

   175 

   176 	/** Destructor */

   177 	virtual ~CPBEncryptParms(void);

   178 	/** @internalAll */

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

   180 

   181 	

   182 protected:	

   183 #ifdef PBEDATA_NO_EXPORTED_CONSTRUCTORS

   184 	/** @internalAll */

   185 	CPBEncryptParms(void);

   186 #else

   187 	/** Constructor */

   188 	IMPORT_C CPBEncryptParms(void);

   189 #endif

   190 

   191 	/** @internalAll */

   192 	void ConstructL();

   193 

   194 	/** @internalAll*/

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

   196 		const TDesC8& aIV, TUint aIterations);

   197 	/** @internalAll*/

   198 	void ConstructL(const CPBEncryptParms& aParms);

   199 	/** @internalAll*/

   200 	void ConstructL(RReadStream& aStream);

   201 private:

   202 	CPBEncryptParms(const CPBEncryptParms&);

   203 	CPBEncryptParms& operator= (const CPBEncryptParms&);

   204 private:

   205 	class TParamsData

   206 	/**

   207 		This class contains multiple objects.  Its

   208 		pointer is stored in CPBEncryptParms to preserve

   209 		BC, because CPBEncryptParms has an exported,

   210 		protected constructor.

   211 	 */

   212 		{

   213 	public:

   214 		TPBECipher iCipher;

   215 		/**

   216 			The password is processed with this function

   217 			to generate the encryption key.

   218 		 */

   219 		TKdf iKdf;

   220 		};

   221 	TParamsData* iData;

   222 

   223 	HBufC8* iSalt;

   224 	HBufC8* iIV;

   225 	TUint iIterations;

   226 	};

   227 

   228 /**

   229  * Contains the password based authentication data.

   230  * Used to check the passphrase when decrypting.

   231  *

   232  * @since v7.0s

   233  */

   234 class CPBAuthData : public CBase

   235 	{

   236 public:

   237 	/**

   238 	 * Derives an authentication key.

   239 	 *

   240 	 * @param aPassword		The user's initial password

   241 	 * @param aSalt			The salt

   242 	 * @param aKeySize		The key size

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

   244 	 * @return				A pointer to the new CPBAuthData object

   245 	 */

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

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

   248 

   249 	/**

   250 	 * Derives an authentication key.

   251 	 *

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

   253 	 *

   254 	 * @param aPassword		The user's initial password

   255 	 * @param aSalt			The salt

   256 	 * @param aKeySize		The key size

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

   258 	 * @return				A pointer to the new CPBAuthData object

   259 	 */

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

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

   262 

   263 	/**

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

   265 	 *

   266 	 * @param aData	The existing CPBAuthData object

   267 	 * @return		A pointer to the new CPBAuthData object

   268 	 */

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

   270 

   271 	/**

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

   273 	 *

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

   275 	 *

   276 	 * @param aData	The existing CPBAuthData object

   277 	 * @return		A pointer to the new CPBAuthData object

   278 	 */

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

   280 

   281 	/**

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

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

   284 	 *

   285 	 * @param aStream	The stream to read from

   286 	 * @return			A pointer to the new CPBAuthData object

   287 	 */

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

   289 

   290 	/**

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

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

   293 	 *

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

   295 	 *

   296 	 * @param aStream	The stream to read from

   297 	 * @return			A pointer to the new CPBAuthData object

   298 	 */

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

   300 

   301 	/**

   302 	 * Gets the authentication key

   303 	 *

   304 	 * @return	The key

   305 	 */

   306 	IMPORT_C TPtrC8 Key() const;

   307 

   308 	/**

   309 	 * Gets the salt used for the authentication 

   310 	 *

   311 	 * @return	The salt

   312 	 */

   313 	IMPORT_C TPtrC8 Salt() const;

   314 

   315 	/**

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

   317 	 *

   318 	 * @return	The number of iterations

   319 	 */

   320 	IMPORT_C TInt Iterations() const;

   321 

   322 	/**

   323 	 * Tests whether two authentication keys are identical 

   324 	 *

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

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

   327 	 */

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

   329 

   330 	/**

   331 	 * Externalizes the encryption parameters into a write stream.

   332 	 *

   333 	 * @param aStream	The stream to write to

   334 	 */

   335 	IMPORT_C void ExternalizeL(RWriteStream& aStream) const;

   336 

   337 	/** Destructor */

   338 	virtual ~CPBAuthData(void);

   339 protected:

   340 #ifdef PBEDATA_NO_EXPORTED_CONSTRUCTORS

   341 	CPBAuthData(void);

   342 #else

   343 	/** Constructor */

   344 	IMPORT_C CPBAuthData(void);

   345 #endif

   346 	/** @internalAll */

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

   348 		TUint aKeySize, TUint aIterations);

   349 	/** @internalAll */

   350 	void ConstructL(const CPBAuthData& aData);

   351 	/** @internalAll */

   352 	void ConstructL(RReadStream& aStream);

   353 private:

   354 	CPBAuthData(const CPBAuthData&);

   355 	CPBAuthData& operator= (const CPBAuthData&);

   356 private:

   357 	HBufC8* iAuthKey;

   358 	HBufC8* iSalt;

   359 	TUint iIterations;

   360 	};

   361 

   362 /** 

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

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

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

   366  *

   367  * @see CPBEncryptParms

   368  * @see CPBAuthData

   369  *

   370  * @since v7.0s

   371  */

   372 class CPBEncryptionData : public CBase

   373 	{

   374 public:

   375 	/**

   376 	 * Creates a new CPBEncryptionData object 

   377 	 *

   378 	 * @param aPassword		The user's initial password

   379 	 * @param aCipher		The cipher to use

   380 	 * @param aAuthSalt		The salt used for the authentication

   381 	 * @param aEncryptSalt	The salt used for the encryption

   382 	 * @param aIV			The Initialization Vector

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

   384 	 * @return				A pointer to the new CPBEncryptionData object

   385 	 */

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

   387 		TPBECipher aCipher, const TDesC8& aAuthSalt, 

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

   389 

   390 	/**

   391 	 * Creates a new CPBEncryptionData object 

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

   393 	 *

   394 	 * @param aPassword		The user's initial password

   395 	 * @param aCipher		The cipher to use

   396 	 * @param aAuthSalt		The salt used for the authentication

   397 	 * @param aEncryptSalt	The salt used for the encryption

   398 	 * @param aIV			The Initialization Vector

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

   400 	 * @return				A pointer to the new CPBEncryptionData object

   401 	 */

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

   403 		TPBECipher aCipher, const TDesC8& aAuthSalt, 

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

   405 

   406 	/**

   407 	 * Creates a new CPBEncryptionData from an existing one.

   408 	 *

   409 	 * @param aData	The existing CPBEncryptionData object

   410 	 * @return		A pointer to the new CPBEncryptionData object

   411 	 */

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

   413 

   414 	/**

   415 	 * Creates a new CPBEncryptionData from an existing one,

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

   417 	 *

   418 	 * @param aData	The existing CPBEncryptionData object

   419 	 * @return		A pointer to the new CPBEncryptionData object

   420 	 */

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

   422 

   423 	/**

   424 	 * Internalizes the encryption data from a read stream.

   425 	 *

   426 	 * @param aStream	The stream to read from

   427 	 * @return			A pointer to the new CPBEncryptionData object

   428 	 */

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

   430 

   431 	/**

   432 	 * Internalizes the encryption data from a read stream,

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

   434 	 *

   435 	 * @param aStream	The stream to read from

   436 	 * @return			A pointer to the new CPBEncryptionData object

   437 	 */

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

   439 	IMPORT_C static CPBEncryptionData* NewL(

   440 		const TDesC8& aPassword, const TDesC8& aAuthSalt,

   441 		const CPBEncryptParms& aParms);

   442 

   443 

   444 	/**

   445 	 * Returns the encryption parameter object.

   446 	 *

   447 	 * @return	The CPBEncryptParms object

   448 	 */

   449 	IMPORT_C const CPBEncryptParms& EncryptParms() const;

   450 

   451 	/**

   452 	 * Returns the authentication data object.

   453 	 *

   454 	 * @return	The CPBAuthData object

   455 	 */

   456 	IMPORT_C const CPBAuthData& AuthData() const;

   457 

   458 	/**

   459 	 * Externalizes the encryption data into a write stream.

   460 	 *

   461 	 * @param aStream	The stream to write to

   462 	 */

   463 	IMPORT_C void ExternalizeL(RWriteStream& aStream) const;

   464 

   465 	/** Destructor */

   466 	virtual ~CPBEncryptionData(void);

   467 protected:

   468 #ifdef PBEDATA_NO_EXPORTED_CONSTRUCTORS

   469 	CPBEncryptionData(void);

   470 #else

   471 	/** Constructor */

   472 	IMPORT_C CPBEncryptionData(void);

   473 #endif

   474 	/** @internalAll */

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

   476 		const TDesC8& aAuthSalt, const TDesC8& aEncryptSalt, const TDesC8& aIV,

   477 		TUint aIterations);

   478 	/** @internalAll */

   479 	void ConstructL(const CPBEncryptionData& aData);

   480 	/** @internalAll */

   481 	void ConstructL(

   482 		const TDesC8& aPassword, const TDesC8& aAuthSalt,

   483 		const CPBEncryptParms& aParms);

   484 	/** @internalAll */

   485 	void ConstructL(RReadStream& aStream);

   486 private:

   487 	CPBEncryptionData(const CPBEncryptionData&);

   488 	CPBEncryptionData& operator= (const CPBEncryptionData&);

   489 private:

   490 	CPBEncryptParms* iParms;

   491 	CPBAuthData* iAuth;

   492 	};

   493 

   494 #endif