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