sl@0: /*
sl@0: * Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0: * All rights reserved.
sl@0: * This component and the accompanying materials are made available
sl@0: * under the terms of the License "Eclipse Public License v1.0"
sl@0: * which accompanies this distribution, and is available
sl@0: * at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: *
sl@0: * Initial Contributors:
sl@0: * Nokia Corporation - initial contribution.
sl@0: *
sl@0: * Contributors:
sl@0: *
sl@0: * Description: 
sl@0: * ** IMPORTANT ** PublishedPartner API's in this file are published to 3rd party developers via the 
sl@0: * Symbian website. Changes to these API's should be treated as PublishedAll API changes and the Security TA should be consulted.
sl@0: *
sl@0: */
sl@0: 
sl@0: 
sl@0: /**
sl@0:  @file
sl@0:  @publishedPartner
sl@0:  @released
sl@0: */
sl@0: 
sl@0: #ifndef __PBEDATA_H__
sl@0: #define __PBEDATA_H__
sl@0: 
sl@0: #include <s32strm.h>
sl@0: #include <pbe.h>
sl@0: 
sl@0: /**
sl@0:  * Contains the Password Based Encryption parameters.
sl@0:  * An object of this class can be input for CPBEncryptElement or CPBEncryptSet objects.
sl@0:  *
sl@0:  * @since v7.0s
sl@0:  */
sl@0: class CPBEncryptParms : public CBase
sl@0: 	{
sl@0: public:
sl@0: 	enum TKdf
sl@0: 	/**
sl@0: 		Key derivation function.
sl@0: 		This does not affect the authentication key,
sl@0: 		which always uses PKCS#5.
sl@0: 	 */
sl@0: 		{
sl@0: 		EKdfPkcs5,
sl@0: 		EKdfPkcs12
sl@0: 		};
sl@0: 	
sl@0: 	/**
sl@0: 	 * Creates a new CPBEncryptParms object.
sl@0: 	 *
sl@0: 	 * @param aCipher		The cipher to use
sl@0: 	 * @param aSalt			The salt
sl@0: 	 * @param aIV			The Initialization Vector
sl@0: 	 * @param aIterations	The number of iterations of the PBE algorithm
sl@0: 	 * @return				A pointer to the new CPBEncryptParms object
sl@0: 	 */
sl@0: 	IMPORT_C static CPBEncryptParms* NewL(TPBECipher aCipher,
sl@0: 		const TDesC8& aSalt, const TDesC8& aIV, TUint aIterations);
sl@0: 
sl@0: 	/**
sl@0: 	 * Creates a new CPBEncryptParms object and puts a pointer to it onto the cleanup stack.
sl@0: 	 *
sl@0: 	 * @param aCipher		The cipher to use
sl@0: 	 * @param aSalt			The salt
sl@0: 	 * @param aIV			The Initialization Vector
sl@0: 	 * @param aIterations	The number of iterations of the PBE algorithm
sl@0: 	 * @return				A pointer to the new CPBEncryptParms object
sl@0: 	 */
sl@0: 	IMPORT_C static CPBEncryptParms* NewLC(TPBECipher aCipher,
sl@0: 		const TDesC8& aSalt, const TDesC8& aIV, TUint aIterations);
sl@0: 
sl@0: 	/**
sl@0: 	 * Creates a new CPBEncryptParms object from an existing object.
sl@0: 	 *
sl@0: 	 * @param aParms		The existing encryption parameters object
sl@0: 	 * @return				A pointer to the new CPBEncryptParms object
sl@0: 	 */
sl@0: 	IMPORT_C static CPBEncryptParms* NewL(const CPBEncryptParms& aParms);
sl@0: 
sl@0: 	/**
sl@0: 	 * Creates a new CPBEncryptParms object from an existing object
sl@0: 	 * and puts a pointer to it onto the cleanup stack.
sl@0: 	 *
sl@0: 	 * @param aParms		The existing encryption parameters object
sl@0: 	 * @return				A pointer to the new CPBEncryptParms object
sl@0: 	 */
sl@0: 	IMPORT_C static CPBEncryptParms* NewLC(const CPBEncryptParms& aParms);
sl@0: 
sl@0: 	/**
sl@0: 	 * Internalizes encryption parameter data from a read stream.
sl@0: 	 *
sl@0: 	 * @param aStream	The read stream to be internalized
sl@0: 	 * @return			A pointer to the new CPBEncryptParms object
sl@0: 	 * 
sl@0: 	 */
sl@0: 	IMPORT_C static CPBEncryptParms* NewL(RReadStream& aStream);
sl@0: 
sl@0: 	/**
sl@0: 	 * Internalizes encryption parameter data from a read stream, and 
sl@0: 	 * puts a pointer to the new object onto the cleanup stack.
sl@0: 	 *
sl@0: 	 * @param aStream	The read stream to be internalized
sl@0: 	 * @return			A pointer to the new CPBEncryptParms object
sl@0: 	 */
sl@0: 	IMPORT_C static CPBEncryptParms* NewLC(RReadStream& aStream);
sl@0: 
sl@0: 	/**
sl@0: 	 * Gets the PBE cipher
sl@0: 	 *
sl@0: 	 * @return	The cipher to use
sl@0: 	 */
sl@0: 	IMPORT_C TPBECipher Cipher() const;
sl@0: 	/**
sl@0: 		Gets the key derivation function (KDF.)
sl@0: 		
sl@0: 		@return The key derivation function (KDF) which
sl@0: 			transforms the password into an encryption key.
sl@0: 	 */
sl@0: 	IMPORT_C TKdf Kdf() const;
sl@0: 
sl@0: 	/**
sl@0: 	 * Gets the PBE salt
sl@0: 	 *
sl@0: 	 * @return	The salt
sl@0: 	 */
sl@0: 	IMPORT_C TPtrC8 Salt() const;
sl@0: 
sl@0: 	/**
sl@0: 	 * Gets the number of iterations for the PKCS#5 algorithm.
sl@0: 	 *
sl@0: 	 * @return	The number of iterations
sl@0: 	 */
sl@0: 	IMPORT_C TInt Iterations() const;
sl@0: 
sl@0: 	/**
sl@0: 	 * Gets the PBE Initialization Vector
sl@0: 	 *
sl@0: 	 * @return	The IV
sl@0: 	 */
sl@0: 	IMPORT_C TPtrC8 IV() const;
sl@0: 
sl@0: 	IMPORT_C void SetIV(const TDesC8& aNewIv);
sl@0: 
sl@0: 	/**
sl@0: 	 * Externalizes the encryption parameters into a write stream.
sl@0: 	 *
sl@0: 	 * @param aStream	The stream to write to
sl@0: 	 */
sl@0: 	IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
sl@0: 	IMPORT_C static CPBEncryptParms* NewL();
sl@0: 	IMPORT_C static CPBEncryptParms* NewLC();
sl@0: 	
sl@0: 	IMPORT_C void SetCipher(TPBECipher aCipher);
sl@0: 
sl@0:    /**
sl@0:     * Replace the current cipher.  This function resizes the
sl@0:     * IV and replaces its existing contents.
sl@0:     *	
sl@0:     * @param aCipher	New cipher.
sl@0:     * @leave			System wide error code.
sl@0:     */
sl@0: 	inline void SetCipherL(TPBECipher aCipher)
sl@0: 		{
sl@0: 		SetCipher(aCipher);
sl@0: 		}
sl@0: 
sl@0: 	IMPORT_C void SetKdf(TKdf aKdf);
sl@0: 	IMPORT_C void ResizeSaltL(TInt aNewLen);
sl@0: 	IMPORT_C void SetIterations(TInt aIterCount);
sl@0: 
sl@0: 	/** Destructor */
sl@0: 	virtual ~CPBEncryptParms(void);
sl@0: 	/** @internalAll */
sl@0: 	void DeriveKeyL(const TDesC8& aPassword, TDes8& aKeyBuf) const;
sl@0: 
sl@0: 	
sl@0: protected:	
sl@0: #ifdef PBEDATA_NO_EXPORTED_CONSTRUCTORS
sl@0: 	/** @internalAll */
sl@0: 	CPBEncryptParms(void);
sl@0: #else
sl@0: 	/** Constructor */
sl@0: 	IMPORT_C CPBEncryptParms(void);
sl@0: #endif
sl@0: 
sl@0: 	/** @internalAll */
sl@0: 	void ConstructL();
sl@0: 
sl@0: 	/** @internalAll*/
sl@0: 	void ConstructL(TPBECipher aCipher, const TDesC8& aSalt,
sl@0: 		const TDesC8& aIV, TUint aIterations);
sl@0: 	/** @internalAll*/
sl@0: 	void ConstructL(const CPBEncryptParms& aParms);
sl@0: 	/** @internalAll*/
sl@0: 	void ConstructL(RReadStream& aStream);
sl@0: private:
sl@0: 	CPBEncryptParms(const CPBEncryptParms&);
sl@0: 	CPBEncryptParms& operator= (const CPBEncryptParms&);
sl@0: private:
sl@0: 	class TParamsData
sl@0: 	/**
sl@0: 		This class contains multiple objects.  Its
sl@0: 		pointer is stored in CPBEncryptParms to preserve
sl@0: 		BC, because CPBEncryptParms has an exported,
sl@0: 		protected constructor.
sl@0: 	 */
sl@0: 		{
sl@0: 	public:
sl@0: 		TPBECipher iCipher;
sl@0: 		/**
sl@0: 			The password is processed with this function
sl@0: 			to generate the encryption key.
sl@0: 		 */
sl@0: 		TKdf iKdf;
sl@0: 		};
sl@0: 	TParamsData* iData;
sl@0: 
sl@0: 	HBufC8* iSalt;
sl@0: 	HBufC8* iIV;
sl@0: 	TUint iIterations;
sl@0: 	};
sl@0: 
sl@0: /**
sl@0:  * Contains the password based authentication data.
sl@0:  * Used to check the passphrase when decrypting.
sl@0:  *
sl@0:  * @since v7.0s
sl@0:  */
sl@0: class CPBAuthData : public CBase
sl@0: 	{
sl@0: public:
sl@0: 	/**
sl@0: 	 * Derives an authentication key.
sl@0: 	 *
sl@0: 	 * @param aPassword		The user's initial password
sl@0: 	 * @param aSalt			The salt
sl@0: 	 * @param aKeySize		The key size
sl@0: 	 * @param aIterations	The number of iterations of the PBE algorithm
sl@0: 	 * @return				A pointer to the new CPBAuthData object
sl@0: 	 */
sl@0: 	IMPORT_C static CPBAuthData* NewL(const TDesC8& aPassword, 
sl@0: 		const TDesC8& aSalt, TUint aKeySize, TUint aIterations);
sl@0: 
sl@0: 	/**
sl@0: 	 * Derives an authentication key.
sl@0: 	 *
sl@0: 	 * The returned pointer is put onto the cleanup stack.
sl@0: 	 *
sl@0: 	 * @param aPassword		The user's initial password
sl@0: 	 * @param aSalt			The salt
sl@0: 	 * @param aKeySize		The key size
sl@0: 	 * @param aIterations	The number of iterations of the PBE algorithm
sl@0: 	 * @return				A pointer to the new CPBAuthData object
sl@0: 	 */
sl@0: 	IMPORT_C static CPBAuthData* NewLC(const TDesC8& aPassword, 
sl@0: 		const TDesC8& aSalt, TUint aKeySize, TUint aIterations);
sl@0: 
sl@0: 	/**
sl@0: 	 * Creates a new CPBAuthData object from an existing authentication key.
sl@0: 	 *
sl@0: 	 * @param aData	The existing CPBAuthData object
sl@0: 	 * @return		A pointer to the new CPBAuthData object
sl@0: 	 */
sl@0: 	IMPORT_C static CPBAuthData* NewL(const CPBAuthData& aData);
sl@0: 
sl@0: 	/**
sl@0: 	 * Creates a new CPBAuthData object from an existing authentication key.
sl@0: 	 *
sl@0: 	 * The returned pointer is put onto the cleanup stack.
sl@0: 	 *
sl@0: 	 * @param aData	The existing CPBAuthData object
sl@0: 	 * @return		A pointer to the new CPBAuthData object
sl@0: 	 */
sl@0: 	IMPORT_C static CPBAuthData* NewLC(const CPBAuthData& aData);
sl@0: 
sl@0: 	/**
sl@0: 	 * Creates a new CPBAuthData object from an existing authentication key
sl@0: 	 * by internalizing the authentication data from a read stream.
sl@0: 	 *
sl@0: 	 * @param aStream	The stream to read from
sl@0: 	 * @return			A pointer to the new CPBAuthData object
sl@0: 	 */
sl@0: 	IMPORT_C static CPBAuthData* NewL(RReadStream& aStream);
sl@0: 
sl@0: 	/**
sl@0: 	 * Creates a new CPBAuthData object from an existing authentication key
sl@0: 	 * by internalizing the authentication data from a read stream.
sl@0: 	 *
sl@0: 	 * The returned pointer is put onto the cleanup stack.
sl@0: 	 *
sl@0: 	 * @param aStream	The stream to read from
sl@0: 	 * @return			A pointer to the new CPBAuthData object
sl@0: 	 */
sl@0: 	IMPORT_C static CPBAuthData* NewLC(RReadStream& aStream);
sl@0: 
sl@0: 	/**
sl@0: 	 * Gets the authentication key
sl@0: 	 *
sl@0: 	 * @return	The key
sl@0: 	 */
sl@0: 	IMPORT_C TPtrC8 Key() const;
sl@0: 
sl@0: 	/**
sl@0: 	 * Gets the salt used for the authentication 
sl@0: 	 *
sl@0: 	 * @return	The salt
sl@0: 	 */
sl@0: 	IMPORT_C TPtrC8 Salt() const;
sl@0: 
sl@0: 	/**
sl@0: 	 * Gets the number of iterations of the hashing algorithm.
sl@0: 	 *
sl@0: 	 * @return	The number of iterations
sl@0: 	 */
sl@0: 	IMPORT_C TInt Iterations() const;
sl@0: 
sl@0: 	/**
sl@0: 	 * Tests whether two authentication keys are identical 
sl@0: 	 *
sl@0: 	 * @param aAuth	The authentication data object which holds the key to be tested
sl@0: 	 * @return		ETrue, if they are identical; EFalse, otherwise
sl@0: 	 */
sl@0: 	IMPORT_C TBool operator==(const CPBAuthData& aAuth) const;
sl@0: 
sl@0: 	/**
sl@0: 	 * Externalizes the encryption parameters into a write stream.
sl@0: 	 *
sl@0: 	 * @param aStream	The stream to write to
sl@0: 	 */
sl@0: 	IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
sl@0: 
sl@0: 	/** Destructor */
sl@0: 	virtual ~CPBAuthData(void);
sl@0: protected:
sl@0: #ifdef PBEDATA_NO_EXPORTED_CONSTRUCTORS
sl@0: 	CPBAuthData(void);
sl@0: #else
sl@0: 	/** Constructor */
sl@0: 	IMPORT_C CPBAuthData(void);
sl@0: #endif
sl@0: 	/** @internalAll */
sl@0: 	void ConstructL(const TDesC8& aPassword, const TDesC8& aSalt,
sl@0: 		TUint aKeySize, TUint aIterations);
sl@0: 	/** @internalAll */
sl@0: 	void ConstructL(const CPBAuthData& aData);
sl@0: 	/** @internalAll */
sl@0: 	void ConstructL(RReadStream& aStream);
sl@0: private:
sl@0: 	CPBAuthData(const CPBAuthData&);
sl@0: 	CPBAuthData& operator= (const CPBAuthData&);
sl@0: private:
sl@0: 	HBufC8* iAuthKey;
sl@0: 	HBufC8* iSalt;
sl@0: 	TUint iIterations;
sl@0: 	};
sl@0: 
sl@0: /** 
sl@0:  * Represents the information needed to decrypt encrypted data given the correct password.  
sl@0:  * Contains the authentication key, and the parameters used to derive the encryption key.
sl@0:  * A CPBEncryptionData object needs to be stored to recover any data for later use.
sl@0:  *
sl@0:  * @see CPBEncryptParms
sl@0:  * @see CPBAuthData
sl@0:  *
sl@0:  * @since v7.0s
sl@0:  */
sl@0: class CPBEncryptionData : public CBase
sl@0: 	{
sl@0: public:
sl@0: 	/**
sl@0: 	 * Creates a new CPBEncryptionData object 
sl@0: 	 *
sl@0: 	 * @param aPassword		The user's initial password
sl@0: 	 * @param aCipher		The cipher to use
sl@0: 	 * @param aAuthSalt		The salt used for the authentication
sl@0: 	 * @param aEncryptSalt	The salt used for the encryption
sl@0: 	 * @param aIV			The Initialization Vector
sl@0: 	 * @param aIterations	The number of iterations of the PBE algorithm
sl@0: 	 * @return				A pointer to the new CPBEncryptionData object
sl@0: 	 */
sl@0: 	IMPORT_C static CPBEncryptionData* NewL(const TDesC8& aPassword,
sl@0: 		TPBECipher aCipher, const TDesC8& aAuthSalt, 
sl@0: 		const TDesC8& aEncryptSalt, const TDesC8& aIV, TUint aIterations);
sl@0: 
sl@0: 	/**
sl@0: 	 * Creates a new CPBEncryptionData object 
sl@0: 	 * and puts a pointer to it onto the cleanup stack.
sl@0: 	 *
sl@0: 	 * @param aPassword		The user's initial password
sl@0: 	 * @param aCipher		The cipher to use
sl@0: 	 * @param aAuthSalt		The salt used for the authentication
sl@0: 	 * @param aEncryptSalt	The salt used for the encryption
sl@0: 	 * @param aIV			The Initialization Vector
sl@0: 	 * @param aIterations	The number of iterations of the PBE algorithm
sl@0: 	 * @return				A pointer to the new CPBEncryptionData object
sl@0: 	 */
sl@0: 	IMPORT_C static CPBEncryptionData* NewLC(const TDesC8& aPassword,
sl@0: 		TPBECipher aCipher, const TDesC8& aAuthSalt, 
sl@0: 		const TDesC8& aEncryptSalt, const TDesC8& aIV, TUint aIterations);
sl@0: 
sl@0: 	/**
sl@0: 	 * Creates a new CPBEncryptionData from an existing one.
sl@0: 	 *
sl@0: 	 * @param aData	The existing CPBEncryptionData object
sl@0: 	 * @return		A pointer to the new CPBEncryptionData object
sl@0: 	 */
sl@0: 	IMPORT_C static CPBEncryptionData* NewL(const CPBEncryptionData& aData);
sl@0: 
sl@0: 	/**
sl@0: 	 * Creates a new CPBEncryptionData from an existing one,
sl@0: 	 * and puts a pointer to it onto the cleanup stack.
sl@0: 	 *
sl@0: 	 * @param aData	The existing CPBEncryptionData object
sl@0: 	 * @return		A pointer to the new CPBEncryptionData object
sl@0: 	 */
sl@0: 	IMPORT_C static CPBEncryptionData* NewLC(const CPBEncryptionData& aData);
sl@0: 
sl@0: 	/**
sl@0: 	 * Internalizes the encryption data from a read stream.
sl@0: 	 *
sl@0: 	 * @param aStream	The stream to read from
sl@0: 	 * @return			A pointer to the new CPBEncryptionData object
sl@0: 	 */
sl@0: 	IMPORT_C static CPBEncryptionData* NewL(RReadStream& aStream);
sl@0: 
sl@0: 	/**
sl@0: 	 * Internalizes the encryption data from a read stream,
sl@0: 	 * and puts a pointer to it onto the cleanup stack.
sl@0: 	 *
sl@0: 	 * @param aStream	The stream to read from
sl@0: 	 * @return			A pointer to the new CPBEncryptionData object
sl@0: 	 */
sl@0: 	IMPORT_C static CPBEncryptionData* NewLC(RReadStream& aStream);
sl@0: 	IMPORT_C static CPBEncryptionData* NewL(
sl@0: 		const TDesC8& aPassword, const TDesC8& aAuthSalt,
sl@0: 		const CPBEncryptParms& aParms);
sl@0: 
sl@0: 
sl@0: 	/**
sl@0: 	 * Returns the encryption parameter object.
sl@0: 	 *
sl@0: 	 * @return	The CPBEncryptParms object
sl@0: 	 */
sl@0: 	IMPORT_C const CPBEncryptParms& EncryptParms() const;
sl@0: 
sl@0: 	/**
sl@0: 	 * Returns the authentication data object.
sl@0: 	 *
sl@0: 	 * @return	The CPBAuthData object
sl@0: 	 */
sl@0: 	IMPORT_C const CPBAuthData& AuthData() const;
sl@0: 
sl@0: 	/**
sl@0: 	 * Externalizes the encryption data into a write stream.
sl@0: 	 *
sl@0: 	 * @param aStream	The stream to write to
sl@0: 	 */
sl@0: 	IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
sl@0: 
sl@0: 	/** Destructor */
sl@0: 	virtual ~CPBEncryptionData(void);
sl@0: protected:
sl@0: #ifdef PBEDATA_NO_EXPORTED_CONSTRUCTORS
sl@0: 	CPBEncryptionData(void);
sl@0: #else
sl@0: 	/** Constructor */
sl@0: 	IMPORT_C CPBEncryptionData(void);
sl@0: #endif
sl@0: 	/** @internalAll */
sl@0: 	void ConstructL(const TDesC8& aPassword, TPBECipher aCipher,
sl@0: 		const TDesC8& aAuthSalt, const TDesC8& aEncryptSalt, const TDesC8& aIV,
sl@0: 		TUint aIterations);
sl@0: 	/** @internalAll */
sl@0: 	void ConstructL(const CPBEncryptionData& aData);
sl@0: 	/** @internalAll */
sl@0: 	void ConstructL(
sl@0: 		const TDesC8& aPassword, const TDesC8& aAuthSalt,
sl@0: 		const CPBEncryptParms& aParms);
sl@0: 	/** @internalAll */
sl@0: 	void ConstructL(RReadStream& aStream);
sl@0: private:
sl@0: 	CPBEncryptionData(const CPBEncryptionData&);
sl@0: 	CPBEncryptionData& operator= (const CPBEncryptionData&);
sl@0: private:
sl@0: 	CPBEncryptParms* iParms;
sl@0: 	CPBAuthData* iAuth;
sl@0: 	};
sl@0: 
sl@0: #endif