--- a/crypto/weakcrypto/inc/pbe.h Tue Jul 21 01:04:32 2009 +0100
+++ b/crypto/weakcrypto/inc/pbe.h Thu Sep 10 14:01:51 2009 +0300
@@ -1,613 +1,611 @@
-/*
-* 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 __PBE_H__
-#define __PBE_H__
-
-#include <e32std.h>
-#include "pbebase.h"
-
-class CPBEncryptionData;
-class CPBEncryptor;
-class CPBDecryptor;
-
-/**
- * Password Based Encryption ciphers.
- *
- * Note that RC2 has an additional key parameter, the "effective key length".
- *
- * Used in the construction of CPBEncryptElement, CPBEncryptSet, CPBEncryptParms,
- * and CPBEncryptionData objects and in the CPBEncryptParms::Cipher() function.
- */
-enum TPBECipher
- {
- /** AES cipher in CBC mode with a supplied key size of 128 bits. */
- ECipherAES_CBC_128,
- /** AES cipher in CBC mode with a supplied key size of 192 bits. */
- ECipherAES_CBC_192,
- /** AES cipher in CBC mode with a supplied key size of 256 bits. */
- ECipherAES_CBC_256,
- /** DES cipher in CBC mode (with a supplied key size of 56 bits). */
- ECipherDES_CBC,
- /** Triple-DES cipher in CBC mode. */
- ECipher3DES_CBC,
- /**
- * RC2 cipher in CBC mode with a supplied key length of 40 bits.
- *
- * It has an effective key length of 1024 bits (128 bytes), which is compatible
- * with OpenSSL RC2 encryption.
- */
- ECipherRC2_CBC_40,
- /**
- * RC2 cipher in CBC mode with a supplied key length of 128 bits.
- *
- * It has an effective key length of 1024 bits (128 bytes), which is compatible
- * with OpenSSL RC2 encryption.
- */
- ECipherRC2_CBC_128,
- /**
- * RC2 cipher in CBC mode with a supplied key length of 40 bits.
- *
- * It has an effective key length of 128 bits (16 bytes), which is compatible
- * with the RC2 encryption used in PKCS#8 encryption keys generated by OpenSSL
- */
- ECipherRC2_CBC_40_16,
- /**
- * RC2 cipher in CBC mode with a supplied key length of 128 bits.
- *
- * It has an effective key length of 128 bits (16 bytes), which is compatible
- * with the RC2 encryption used in PKCS#8 encryption keys generated by OpenSSL
- */
- ECipherRC2_CBC_128_16,
- /**
- * ARC4 cipher with a supplied key length of 128 bits.
- * PKCS#12 PBE encryption algorithm
- */
- ECipherARC4_128,
- /**
- * ARC4 cipher with a supplied key length of 40 bits.
- * PKCS#12 PBE encryption algorithm
- */
- ECipherARC4_40,
- /**
- * 2_KeyTriple-DES cipher in CBC mode.
- * PKCS#12 PBE encryption algorithm
- */
- ECipher2Key3DES_CBC,
- /**
- * RC2 Cipher in CBC mode with a supplied & effective key length of 40 bits.
- * PKCS#12 PBE encryption algorithm
- */
- ECipherRC2_CBC_40_5,
- };
-
-/**
- * Allows the password based encryption and decryption of elements.
- * Contains the encryption key and its associated encryption data.
- * See the Cryptography api-guide documentation for more information
- * and sample code.
- */
-class CPBEncryptElement : public CPBEncryptionBase
- {
-public:
- /**
- * Creates a new CPBEncryptElement object for encryption of new data.
- *
- * If strong cryptography is present, a 128 bit AES cipher is used;
- * otherwise, for weak cryptography, a 56 bit DES cipher is used.
- *
- * The symmetric key is derived from the password and a random salt using TPKCS5KDF::DeriveKeyL().
- *
- * @param aPassword The user supplied password
- * @return The new CPBEncryptElement object
- */
- IMPORT_C static CPBEncryptElement* NewL(const TPBPassword& aPassword);
-
- /**
- * Creates a new CPBEncryptElement object for encryption of new data.
- *
- * If strong cryptography is present, a 128 bit AES cipher is used;
- * otherwise, for weak cryptography, a 56 bit DES cipher is used.
- *
- * The symmetric key is derived from the password and a random salt using TPKCS5KDF::DeriveKeyL().
- *
- * A pointer to the returned object is put onto the cleanup stack.
- *
- * @param aPassword The user supplied password
- * @return The new CPBEncryptElement object
- */
- IMPORT_C static CPBEncryptElement* NewLC(const TPBPassword& aPassword);
-
- /**
- * Creates a new CPBEncryptElement object for encryption of new data.
- *
- * The symmetric key is derived from the password and a random salt using TPKCS5KDF::DeriveKeyL().
- *
- * @param aPassword The user supplied password
- * @param aCipher The cipher to use
- * @return The new CPBEncryptElement object
- */
- IMPORT_C static CPBEncryptElement* NewL(const TPBPassword& aPassword,
- TPBECipher aCipher);
-
- /**
- * Creates a new CPBEncryptElement object for encryption of new data.
- *
- * The symmetric key is derived from the password and a random salt using TPKCS5KDF::DeriveKeyL().
- *
- * A pointer to the returned object is put onto the cleanup stack.
- *
- * @param aPassword The user supplied password
- * @param aCipher The cipher to use
- * @return The new CPBEncryptElement object
- */
- IMPORT_C static CPBEncryptElement* NewLC(const TPBPassword& aPassword,
- TPBECipher aCipher);
-
- /**
- * Creates a new CPBEncryptElement object for encryption of new data.
- *
- * The symmetric key is derived from the password using TPKCS5KDF::DeriveKeyL().
- *
- * @param aPassword The user supplied password
- * @param aParms An encryption parameter object comprising the cipher,
- * salt, IV, and iteration count value.
- * @return The new CPBEncryptElement object
- */
- IMPORT_C static CPBEncryptElement* NewL(const TPBPassword& aPassword,
- const CPBEncryptParms& aParms);
-
- /**
- * Creates a new CPBEncryptElement object for encryption of new data.
- *
- * The symmetric key is derived from the password using TPKCS5KDF::DeriveKeyL().
- *
- * A pointer to the returned object is put onto the cleanup stack.
- *
- * @param aPassword The user supplied password
- * @param aParms An encryption parameter object comprising the cipher,
- * salt, IV, and iteration count value.
- * @return The new CPBEncryptElement object
- */
- IMPORT_C static CPBEncryptElement* NewLC(const TPBPassword& aPassword,
- const CPBEncryptParms& aParms);
-
- /**
- * Creates a new CPBEncryptElement object for decryption of existing data.
- *
- * If the specified password is valid, the function regenerates the encryption key;
- * otherwise, it leaves with KErrBadPassphrase.
- *
- * @param aData The encryption data object
- * @param aPassword The user supplied password
- * @return The new CPBEncryptElement object
- * @leave KErrBadPassphrase If the specified password is incorrect
- */
- IMPORT_C static CPBEncryptElement* NewL(const CPBEncryptionData& aData,
- const TPBPassword& aPassword);
-
- /**
- * Creates a new CPBEncryptElement object for decryption of existing data.
- *
- * If the specified password is valid, the function regenerates the encryption key;
- * otherwise, it leaves with KErrBadPassphrase.
- *
- * A pointer to the returned object is put onto the cleanup stack.
- *
- * @param aData The encryption data object
- * @param aPassword The user supplied password
- * @return The new CPBEncryptElement object
- * @leave KErrBadPassphrase If the specified password is incorrect
- */
- IMPORT_C static CPBEncryptElement* NewLC(const CPBEncryptionData& aData,
- const TPBPassword& aPassword);
-
- /**
- * Gets the parameters allowing one to re-create the object with the
- * same state at another point in the future.
- *
- * In order to decrypt any information previously encrypted with this object,
- * you <B><I>must</I></B> store this encryption data along with it. Failure
- * to do this will result in the permanent loss of the encrypted information.
- *
- * @return The data allowing one to re-create this object at a later time.
- */
- const CPBEncryptionData& EncryptionData(void) const;
-
- /**
- * Constructs a CPBEncryptor object allowing the encryption of data.
- *
- * @return A pointer to a CPBEncryptor object.
- * The caller assumes ownership of the returned object.
- */
- CPBEncryptor* NewEncryptL(void) const;
-
- /**
- * Constructs a CPBEncryptor object allowing the encryption of data.
- *
- * @return A pointer to a CPBEncryptor object.
- * The caller assumes ownership of the returned object.
- * The returned pointer is left on the cleanup stack.
- */
- CPBEncryptor* NewEncryptLC(void) const;
-
- /**
- * Constructs a CPBDecryptor object allowing the decryption of data.
- *
- * @return A pointer to a CPBDecryptor object.
- * The caller assumes ownership of the returned object.
- */
- CPBDecryptor* NewDecryptL(void) const;
-
- /**
- * Constructs a CPBDecryptor object allowing the decryption of data.
- *
- * @return A pointer to a CPBDecryptor object.
- * The caller assumes ownership of the returned object.
- * The returned pointer is left on the cleanup stack.
- */
- CPBDecryptor* NewDecryptLC(void) const;
-
- /**
- * Gets the maximum output ciphertext length given a specified input plaintext length.
- *
- * @param aPlaintextLength The plaintext length
- * @return The maximum ciphertext length given a plaintext length.
- */
- TInt MaxCiphertextLength(TInt aPlaintextLength) const;
-
- /**
- * Gets the maximum output plaintext length given a specified input ciphertext length.
- *
- * @param aCiphertextLength The ciphertext length
- * @return The maximum plaintext length given a ciphertext length.
- */
- TInt MaxPlaintextLength(TInt aCiphertextLength) const;
-
- /** Destructor */
- virtual ~CPBEncryptElement(void);
-protected:
- /** @internalAll */
- void ConstructL(const TDesC8& aPassword);
- /** @internalAll */
- void ConstructL(const TDesC8& aPassword, const TPBECipher aCipher);
- /** @internalAll */
- void ConstructL(const TDesC8& aPassword, const CPBEncryptParms& aParms);
- /** @internalAll */
- void ConstructL(const CPBEncryptionData& aData, const TPBPassword& aPassword);
- /** @internalAll */
- TBool AuthenticateL(const TPBPassword& aPassword);
- /** @internalAll */
- void MakeEncryptKeyL(TUint aKeySize, const TDesC8& aPassword);
- /** @internalAll */
- CPBEncryptElement(void);
-protected:
- /** The encryption data */
- CPBEncryptionData* iData;
- /** The derived encryption key */
- HBufC8* iEncryptKey;
-private:
- CPBEncryptElement(const CPBEncryptElement&);
- CPBEncryptElement& operator= (const CPBEncryptElement&);
- };
-
-/**
- * Derived class to allow the efficient password based encryption and
- * decryption of multiple elements.
- *
- * This is useful if one wants random access to an encrypted source consisting
- * of multiple independent elements, for example, a database or a store.
- *
- * Since it is unreasonable to force the decryption of an entire set to allow
- * access to just a tiny portion of it, and since it is too costly to derive separate
- * keys for each element within the set, a single randomly generated <I>master</I>
- * key is used. This master key is encrypted with the password provided by the
- * user of the class. Known plaintext attacks against the ciphertext are prevented
- * by using a randomly chosen Initialisation Vector (IV) for each element.
- *
- * Contains the master encryption key.
- *
- * See the Cryptography api-guide documentation for more information and sample code.
- *
- * @see CPBEncryptElement
- *
- * @since v8.0
- */
-class CPBEncryptSet : public CPBEncryptElement
- {
-public:
- /**
- * Creates a new CPBEncryptSet object for encryption of new data
- * (and generates an encrypted master key).
- *
- * If strong cryptography is present, a 128 bit AES cipher is used;
- * otherwise, for weak cryptography, a 56 bit DES cipher is used.
- *
- * The symmetric key is derived from the password and a random salt using TPKCS5KDF::DeriveKeyL().
- *
- * @param aPassword The users password.
- * @return A new CPBEncryptSet object
- */
- IMPORT_C static CPBEncryptSet* NewL(const TPBPassword& aPassword);
-
- /**
- * Creates a new CPBEncryptSet object for encryption of new data
- * (and generates an encrypted master key).
- *
- * The returned pointer is put onto the cleanup stack.
- *
- * If strong cryptography is present, a 128 bit AES cipher is used;
- * otherwise, for weak cryptography, a 56 bit DES cipher is used.
- *
- * The symmetric key is derived from the password and a random salt using TPKCS5KDF::DeriveKeyL().
- *
- * @param aPassword The user supplied password
- * @return The new CPBEncryptSet object
- */
- IMPORT_C static CPBEncryptSet* NewLC(const TPBPassword& aPassword);
-
- /**
- * Creates a new CPBEncryptSet object for encryption of new data
- * (and generates an encrypted master key).
- *
- * The symmetric key is derived from the password and a random salt using TPKCS5KDF::DeriveKeyL().
- *
- * @param aPassword The user supplied password
- * @param aCipher The cipher to use
- * @return The new CPBEncryptSet object
- */
- IMPORT_C static CPBEncryptSet* NewL(const TPBPassword& aPassword,
- TPBECipher aCipher);
-
- /**
- * Creates a new CPBEncryptSet object for encryption of new data
- * (and generates an encrypted master key).
- *
- * The returned pointer is put onto the cleanup stack.
- *
- * The symmetric key is derived from the password and a random salt using TPKCS5KDF::DeriveKeyL().
- *
- * @param aPassword The user supplied password
- * @param aCipher The cipher to use
- * @return The new CPBEncryptSet object
- */
- IMPORT_C static CPBEncryptSet* NewLC(const TPBPassword& aPassword,
- TPBECipher aCipher);
-
- /**
- * Creates a new CPBEncryptSet object for encryption of new data
- * (and generates an encrypted master key).
- *
- * The symmetric key is derived from the password using TPKCS5KDF::DeriveKeyL().
- *
- * @param aPassword The user supplied password
- * @param aParms An encryption parameter object comprising the cipher,
- * salt, IV, and iteration count value.
- * @return The new CPBEncryptSet object
- */
- IMPORT_C static CPBEncryptSet* NewL(const TPBPassword& aPassword,
- const CPBEncryptParms& aParms);
-
- /**
- * Creates a new CPBEncryptSet object for encryption of new data
- * (and generates an encrypted master key).
- *
- * The returned pointer is put onto the cleanup stack.
- *
- * The symmetric key is derived from the password using TPKCS5KDF::DeriveKeyL().
- *
- * @param aPassword The user supplied password
- * @param aParms An encryption parameter object comprising the cipher,
- * salt, IV, and iteration count value.
- * @return The new CPBEncryptSet object
- */
- IMPORT_C static CPBEncryptSet* NewLC(const TPBPassword& aPassword,
- const CPBEncryptParms& aParms);
-
- /**
- * Creates a new CPBEncryptSet object for encryption of new data
- * (and generates an encrypted master key).
- *
- * If the specified password is valid, the function regenerates the encryption key;
- * otherwise, it leaves with KErrBadPassphrase.
- *
- * @param aData The encryption data object to copy
- * @param aEncryptedMasterKey On return, the encrypted master key
- * @param aPassword The user supplied password
- * @return The new CPBEncryptSet object
- * @leave KErrBadPassphrase If the specified password is incorrect
- */
- IMPORT_C static CPBEncryptSet* NewL(const CPBEncryptionData& aData,
- const TDesC8& aEncryptedMasterKey, const TPBPassword& aPassword);
-
- /**
- * Creates a new CPBEncryptSet object for encryption of new data
- * (and generates an encrypted master key).
- *
- * The returned pointer is put onto the cleanup stack.
- *
- * If the specified password is valid, the function regenerates the encryption key;
- * otherwise, it leaves with KErrBadPassphrase.
- *
- * @param aData The encryption data object to copy
- * @param aEncryptedMasterKey On return, the encrypted master key
- * @param aPassword The user supplied password
- * @return The new CPBEncryptSet object
- * @leave KErrBadPassphrase If the specified password is incorrect
- */
- IMPORT_C static CPBEncryptSet* NewLC(const CPBEncryptionData& aData,
- const TDesC8& aEncryptedMasterKey, const TPBPassword& aPassword);
-
- /**
- * Gets the encrypted form of the master key.
- *
- * This must be stored along with the object returned by CPBEncryptElement::EncryptionData()
- * in order for the object to be reconstructed with the same state at
- * some time in the future. Failure to do so will result in the permanent
- * loss of any information encrypted with this object.
- *
- * @return The encrypted master key.
- */
- IMPORT_C const TDesC8& EncryptedMasterKey(void) const;
-
- /**
- * Constructs a CPBEncryptor object based on the state of this object
- * (i.e., the cipher and master key) allowing the encryption of data.
- *
- * @return A pointer to a CPBEncryptor object.
- * The caller assumes ownership of the returned object.
- */
- CPBEncryptor* NewEncryptL(void) const;
-
- /**
- * Constructs a CPBEncryptor object based on the state of this object
- * (i.e., the cipher and master key) allowing the encryption of data.
- *
- * @return A pointer to a CPBEncryptor object.
- * The caller assumes ownership of the returned object.
- * The returned pointer is left on the cleanup stack.
- */
- CPBEncryptor* NewEncryptLC(void) const;
-
- /**
- * Constructs a CPBDecryptor object based on the state of this object
- * (i.e., the cipher and master key) allowing the decryption of data.
- *
- * @return A pointer to a CPBDecryptor object.
- * The caller assumes ownership of the returned object.
- */
- CPBDecryptor* NewDecryptL(void) const;
-
- /**
- * Constructs a CPBDecryptor object based on the state of this object
- * (i.e., the cipher and master key) allowing the decryption of data.
- *
- * @return A pointer to a CPBDecryptor object.
- * The caller assumes ownership of the returned object.
- * The returned pointer is left on the cleanup stack.
- */
- CPBDecryptor* NewDecryptLC(void) const;
-
- /**
- * Re-encrypts the master key with the specified new password.
- *
- * @param aNewPassword The new password
- */
- IMPORT_C void ChangePasswordL(const TPBPassword& aNewPassword);
-
- /**
- * Gets the maximum output ciphertext length given a specified input plaintext length.
- *
- * @param aPlaintextLength The plaintext length
- * @return The maximum ciphertext length given a plaintext length.
- */
- TInt MaxCiphertextLength(TInt aPlaintextLength) const;
-
- /**
- * Gets the maximum output plaintext length given a specified input ciphertext length.
- *
- * @param aCiphertextLength The ciphertext length
- * @return The maximum plaintext length given a ciphertext length.
- */
- TInt MaxPlaintextLength(TInt aCiphertextLength) const;
-
- /** Destructor */
- virtual ~CPBEncryptSet(void);
-protected:
- /** @internalAll */
- void ConstructL(const TDesC8& aPassword);
- /** @internalAll */
- void ConstructL(const TDesC8& aPassword, TPBECipher aCipher);
- /** @internalAll */
- void ConstructL(const TDesC8& aPassword, const CPBEncryptParms& aParms);
- /** @internalAll */
- void ConstructMasterKeyL(void);
- /** @internalAll */
- void ConstructL(const CPBEncryptionData& aData,
- const TDesC8& aEncryptedMasterKey, const TPBPassword& aPassword);
- /** @internalAll */
- void DecryptMasterKeyL(TDes8& aMasterKey) const;
- /** @internalAll */
- void EncryptMasterKeyL(const TDesC8& aMasterKey);
-protected:
- /** @internalAll */
- CPBEncryptSet(void);
- /** The derived encrypted master key*/
- HBufC8* iEncryptedMasterKey;
-private:
- CPBEncryptSet(const CPBEncryptSet&);
- CPBEncryptSet& operator= (const CPBEncryptSet&);
- };
-
-/**
- * Class representing both 8 and 16 bit descriptor passwords.
- * Internally these are stored as 8 bit passwords.
- */
-class TPBPassword
- {
-public:
- /**
- * Sets the password.
- *
- * Constructs a TPBPassword object with an 8 bit descriptor.
- *
- * Internally this is represented as an octet byte sequence
- * (aka 8 bit TPtrC8 descriptor).
- *
- * @param aPassword A const reference to an 8 bit descriptor.
- * representing the users initial password.
- */
- IMPORT_C TPBPassword(const TDesC8& aPassword);
-
- /**
- * Sets the password.
- *
- * Constructs a TPBPassword object with a 16 bit descriptor.
- *
- * Internally this is represented as an octet byte sequence
- * (aka 8 bit TPtrC8 descriptor).
- *
- * @param aPassword A const reference to a 16 bit descriptor
- * representing the users initial password.
- */
- IMPORT_C TPBPassword(const TDesC16& aPassword);
-
- /**
- * Gets the password.
- *
- * Gets a const reference to an 8 bit descriptor representing the users
- * initial password (which could have been either 8 or 16 bit).
- *
- * @return A const reference to an 8 bit descriptor.
- */
- IMPORT_C const TDesC8& Password(void) const;
-private:
- TPtrC8 iPassword;
- };
-
-#endif
+/*
+* 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 __PBE_H__
+#define __PBE_H__
+
+#include <e32std.h>
+#include "pbebase.h"
+
+class CPBEncryptionData;
+class CPBEncryptor;
+class CPBDecryptor;
+
+/**
+ * Password Based Encryption ciphers.
+ *
+ * Note that RC2 has an additional key parameter, the "effective key length".
+ *
+ * Used in the construction of CPBEncryptElement, CPBEncryptSet, CPBEncryptParms,
+ * and CPBEncryptionData objects and in the CPBEncryptParms::Cipher() function.
+ */
+enum TPBECipher
+ {
+ /** AES cipher in CBC mode with a supplied key size of 128 bits. */
+ ECipherAES_CBC_128,
+ /** AES cipher in CBC mode with a supplied key size of 192 bits. */
+ ECipherAES_CBC_192,
+ /** AES cipher in CBC mode with a supplied key size of 256 bits. */
+ ECipherAES_CBC_256,
+ /** DES cipher in CBC mode (with a supplied key size of 56 bits). */
+ ECipherDES_CBC,
+ /** Triple-DES cipher in CBC mode. */
+ ECipher3DES_CBC,
+ /**
+ * RC2 cipher in CBC mode with a supplied key length of 40 bits.
+ *
+ * It has an effective key length of 1024 bits (128 bytes), which is compatible
+ * with OpenSSL RC2 encryption.
+ */
+ ECipherRC2_CBC_40,
+ /**
+ * RC2 cipher in CBC mode with a supplied key length of 128 bits.
+ *
+ * It has an effective key length of 1024 bits (128 bytes), which is compatible
+ * with OpenSSL RC2 encryption.
+ */
+ ECipherRC2_CBC_128,
+ /**
+ * RC2 cipher in CBC mode with a supplied key length of 40 bits.
+ *
+ * It has an effective key length of 128 bits (16 bytes), which is compatible
+ * with the RC2 encryption used in PKCS#8 encryption keys generated by OpenSSL
+ */
+ ECipherRC2_CBC_40_16,
+ /**
+ * RC2 cipher in CBC mode with a supplied key length of 128 bits.
+ *
+ * It has an effective key length of 128 bits (16 bytes), which is compatible
+ * with the RC2 encryption used in PKCS#8 encryption keys generated by OpenSSL
+ */
+ ECipherRC2_CBC_128_16,
+ /**
+ * ARC4 cipher with a supplied key length of 128 bits.
+ * PKCS#12 PBE encryption algorithm
+ */
+ ECipherARC4_128,
+ /**
+ * ARC4 cipher with a supplied key length of 40 bits.
+ * PKCS#12 PBE encryption algorithm
+ */
+ ECipherARC4_40,
+ /**
+ * 2_KeyTriple-DES cipher in CBC mode.
+ * PKCS#12 PBE encryption algorithm
+ */
+ ECipher2Key3DES_CBC,
+ /**
+ * RC2 Cipher in CBC mode with a supplied & effective key length of 40 bits.
+ * PKCS#12 PBE encryption algorithm
+ */
+ ECipherRC2_CBC_40_5,
+ };
+
+/**
+ * Allows the password based encryption and decryption of elements.
+ * Contains the encryption key and its associated encryption data.
+ * See the Cryptography api-guide documentation for more information
+ * and sample code.
+ */
+class CPBEncryptElement : public CPBEncryptionBase
+ {
+public:
+ /**
+ * Creates a new CPBEncryptElement object for encryption of new data.
+ *
+ * If strong cryptography is present, a 128 bit AES cipher is used;
+ * otherwise, for weak cryptography, a 56 bit DES cipher is used.
+ *
+ * The symmetric key is derived from the password and a random salt using TPKCS5KDF::DeriveKeyL().
+ *
+ * @param aPassword The user supplied password
+ * @return The new CPBEncryptElement object
+ */
+ IMPORT_C static CPBEncryptElement* NewL(const TPBPassword& aPassword);
+
+ /**
+ * Creates a new CPBEncryptElement object for encryption of new data.
+ *
+ * If strong cryptography is present, a 128 bit AES cipher is used;
+ * otherwise, for weak cryptography, a 56 bit DES cipher is used.
+ *
+ * The symmetric key is derived from the password and a random salt using TPKCS5KDF::DeriveKeyL().
+ *
+ * A pointer to the returned object is put onto the cleanup stack.
+ *
+ * @param aPassword The user supplied password
+ * @return The new CPBEncryptElement object
+ */
+ IMPORT_C static CPBEncryptElement* NewLC(const TPBPassword& aPassword);
+
+ /**
+ * Creates a new CPBEncryptElement object for encryption of new data.
+ *
+ * The symmetric key is derived from the password and a random salt using TPKCS5KDF::DeriveKeyL().
+ *
+ * @param aPassword The user supplied password
+ * @param aCipher The cipher to use
+ * @return The new CPBEncryptElement object
+ */
+ IMPORT_C static CPBEncryptElement* NewL(const TPBPassword& aPassword,
+ TPBECipher aCipher);
+
+ /**
+ * Creates a new CPBEncryptElement object for encryption of new data.
+ *
+ * The symmetric key is derived from the password and a random salt using TPKCS5KDF::DeriveKeyL().
+ *
+ * A pointer to the returned object is put onto the cleanup stack.
+ *
+ * @param aPassword The user supplied password
+ * @param aCipher The cipher to use
+ * @return The new CPBEncryptElement object
+ */
+ IMPORT_C static CPBEncryptElement* NewLC(const TPBPassword& aPassword,
+ TPBECipher aCipher);
+
+ /**
+ * Creates a new CPBEncryptElement object for encryption of new data.
+ *
+ * The symmetric key is derived from the password using TPKCS5KDF::DeriveKeyL().
+ *
+ * @param aPassword The user supplied password
+ * @param aParms An encryption parameter object comprising the cipher,
+ * salt, IV, and iteration count value.
+ * @return The new CPBEncryptElement object
+ */
+ IMPORT_C static CPBEncryptElement* NewL(const TPBPassword& aPassword,
+ const CPBEncryptParms& aParms);
+
+ /**
+ * Creates a new CPBEncryptElement object for encryption of new data.
+ *
+ * The symmetric key is derived from the password using TPKCS5KDF::DeriveKeyL().
+ *
+ * A pointer to the returned object is put onto the cleanup stack.
+ *
+ * @param aPassword The user supplied password
+ * @param aParms An encryption parameter object comprising the cipher,
+ * salt, IV, and iteration count value.
+ * @return The new CPBEncryptElement object
+ */
+ IMPORT_C static CPBEncryptElement* NewLC(const TPBPassword& aPassword,
+ const CPBEncryptParms& aParms);
+
+ /**
+ * Creates a new CPBEncryptElement object for decryption of existing data.
+ *
+ * If the specified password is valid, the function regenerates the encryption key;
+ * otherwise, it leaves with KErrBadPassphrase.
+ *
+ * @param aData The encryption data object
+ * @param aPassword The user supplied password
+ * @return The new CPBEncryptElement object
+ * @leave KErrBadPassphrase If the specified password is incorrect
+ */
+ IMPORT_C static CPBEncryptElement* NewL(const CPBEncryptionData& aData,
+ const TPBPassword& aPassword);
+
+ /**
+ * Creates a new CPBEncryptElement object for decryption of existing data.
+ *
+ * If the specified password is valid, the function regenerates the encryption key;
+ * otherwise, it leaves with KErrBadPassphrase.
+ *
+ * A pointer to the returned object is put onto the cleanup stack.
+ *
+ * @param aData The encryption data object
+ * @param aPassword The user supplied password
+ * @return The new CPBEncryptElement object
+ * @leave KErrBadPassphrase If the specified password is incorrect
+ */
+ IMPORT_C static CPBEncryptElement* NewLC(const CPBEncryptionData& aData,
+ const TPBPassword& aPassword);
+
+ /**
+ * Gets the parameters allowing one to re-create the object with the
+ * same state at another point in the future.
+ *
+ * In order to decrypt any information previously encrypted with this object,
+ * you <B><I>must</I></B> store this encryption data along with it. Failure
+ * to do this will result in the permanent loss of the encrypted information.
+ *
+ * @return The data allowing one to re-create this object at a later time.
+ */
+ const CPBEncryptionData& EncryptionData(void) const;
+
+ /**
+ * Constructs a CPBEncryptor object allowing the encryption of data.
+ *
+ * @return A pointer to a CPBEncryptor object.
+ * The caller assumes ownership of the returned object.
+ */
+ CPBEncryptor* NewEncryptL(void) const;
+
+ /**
+ * Constructs a CPBEncryptor object allowing the encryption of data.
+ *
+ * @return A pointer to a CPBEncryptor object.
+ * The caller assumes ownership of the returned object.
+ * The returned pointer is left on the cleanup stack.
+ */
+ CPBEncryptor* NewEncryptLC(void) const;
+
+ /**
+ * Constructs a CPBDecryptor object allowing the decryption of data.
+ *
+ * @return A pointer to a CPBDecryptor object.
+ * The caller assumes ownership of the returned object.
+ */
+ CPBDecryptor* NewDecryptL(void) const;
+
+ /**
+ * Constructs a CPBDecryptor object allowing the decryption of data.
+ *
+ * @return A pointer to a CPBDecryptor object.
+ * The caller assumes ownership of the returned object.
+ * The returned pointer is left on the cleanup stack.
+ */
+ CPBDecryptor* NewDecryptLC(void) const;
+
+ /**
+ * Gets the maximum output ciphertext length given a specified input plaintext length.
+ *
+ * @param aPlaintextLength The plaintext length
+ * @return The maximum ciphertext length given a plaintext length.
+ */
+ TInt MaxCiphertextLength(TInt aPlaintextLength) const;
+
+ /**
+ * Gets the maximum output plaintext length given a specified input ciphertext length.
+ *
+ * @param aCiphertextLength The ciphertext length
+ * @return The maximum plaintext length given a ciphertext length.
+ */
+ TInt MaxPlaintextLength(TInt aCiphertextLength) const;
+
+ /** Destructor */
+ virtual ~CPBEncryptElement(void);
+protected:
+ /** @internalAll */
+ void ConstructL(const TDesC8& aPassword);
+ /** @internalAll */
+ void ConstructL(const TDesC8& aPassword, const TPBECipher aCipher);
+ /** @internalAll */
+ void ConstructL(const TDesC8& aPassword, const CPBEncryptParms& aParms);
+ /** @internalAll */
+ void ConstructL(const CPBEncryptionData& aData, const TPBPassword& aPassword);
+ /** @internalAll */
+ TBool AuthenticateL(const TPBPassword& aPassword);
+ /** @internalAll */
+ void MakeEncryptKeyL(TUint aKeySize, const TDesC8& aPassword);
+ /** @internalAll */
+ CPBEncryptElement(void);
+protected:
+ /** The encryption data */
+ CPBEncryptionData* iData;
+ /** The derived encryption key */
+ HBufC8* iEncryptKey;
+private:
+ CPBEncryptElement(const CPBEncryptElement&);
+ CPBEncryptElement& operator= (const CPBEncryptElement&);
+ };
+
+/**
+ * Derived class to allow the efficient password based encryption and
+ * decryption of multiple elements.
+ *
+ * This is useful if one wants random access to an encrypted source consisting
+ * of multiple independent elements, for example, a database or a store.
+ *
+ * Since it is unreasonable to force the decryption of an entire set to allow
+ * access to just a tiny portion of it, and since it is too costly to derive separate
+ * keys for each element within the set, a single randomly generated <I>master</I>
+ * key is used. This master key is encrypted with the password provided by the
+ * user of the class. Known plaintext attacks against the ciphertext are prevented
+ * by using a randomly chosen Initialisation Vector (IV) for each element.
+ *
+ * Contains the master encryption key.
+ *
+ * See the Cryptography api-guide documentation for more information and sample code.
+ *
+ * @see CPBEncryptElement
+ *
+ * @since v8.0
+ */
+class CPBEncryptSet : public CPBEncryptElement
+ {
+public:
+ /**
+ * Creates a new CPBEncryptSet object for encryption of new data
+ * (and generates an encrypted master key).
+ *
+ * If strong cryptography is present, a 128 bit AES cipher is used;
+ * otherwise, for weak cryptography, a 56 bit DES cipher is used.
+ *
+ * The symmetric key is derived from the password and a random salt using TPKCS5KDF::DeriveKeyL().
+ *
+ * @param aPassword The users password.
+ * @return A new CPBEncryptSet object
+ */
+ IMPORT_C static CPBEncryptSet* NewL(const TPBPassword& aPassword);
+
+ /**
+ * Creates a new CPBEncryptSet object for encryption of new data
+ * (and generates an encrypted master key).
+ *
+ * The returned pointer is put onto the cleanup stack.
+ *
+ * If strong cryptography is present, a 128 bit AES cipher is used;
+ * otherwise, for weak cryptography, a 56 bit DES cipher is used.
+ *
+ * The symmetric key is derived from the password and a random salt using TPKCS5KDF::DeriveKeyL().
+ *
+ * @param aPassword The user supplied password
+ * @return The new CPBEncryptSet object
+ */
+ IMPORT_C static CPBEncryptSet* NewLC(const TPBPassword& aPassword);
+
+ /**
+ * Creates a new CPBEncryptSet object for encryption of new data
+ * (and generates an encrypted master key).
+ *
+ * The symmetric key is derived from the password and a random salt using TPKCS5KDF::DeriveKeyL().
+ *
+ * @param aPassword The user supplied password
+ * @param aCipher The cipher to use
+ * @return The new CPBEncryptSet object
+ */
+ IMPORT_C static CPBEncryptSet* NewL(const TPBPassword& aPassword,
+ TPBECipher aCipher);
+
+ /**
+ * Creates a new CPBEncryptSet object for encryption of new data
+ * (and generates an encrypted master key).
+ *
+ * The returned pointer is put onto the cleanup stack.
+ *
+ * The symmetric key is derived from the password and a random salt using TPKCS5KDF::DeriveKeyL().
+ *
+ * @param aPassword The user supplied password
+ * @param aCipher The cipher to use
+ * @return The new CPBEncryptSet object
+ */
+ IMPORT_C static CPBEncryptSet* NewLC(const TPBPassword& aPassword,
+ TPBECipher aCipher);
+
+ /**
+ * Creates a new CPBEncryptSet object for encryption of new data
+ * (and generates an encrypted master key).
+ *
+ * The symmetric key is derived from the password using TPKCS5KDF::DeriveKeyL().
+ *
+ * @param aPassword The user supplied password
+ * @param aParms An encryption parameter object comprising the cipher,
+ * salt, IV, and iteration count value.
+ * @return The new CPBEncryptSet object
+ */
+ IMPORT_C static CPBEncryptSet* NewL(const TPBPassword& aPassword,
+ const CPBEncryptParms& aParms);
+
+ /**
+ * Creates a new CPBEncryptSet object for encryption of new data
+ * (and generates an encrypted master key).
+ *
+ * The returned pointer is put onto the cleanup stack.
+ *
+ * The symmetric key is derived from the password using TPKCS5KDF::DeriveKeyL().
+ *
+ * @param aPassword The user supplied password
+ * @param aParms An encryption parameter object comprising the cipher,
+ * salt, IV, and iteration count value.
+ * @return The new CPBEncryptSet object
+ */
+ IMPORT_C static CPBEncryptSet* NewLC(const TPBPassword& aPassword,
+ const CPBEncryptParms& aParms);
+
+ /**
+ * Creates a new CPBEncryptSet object for encryption of new data
+ * (and generates an encrypted master key).
+ *
+ * If the specified password is valid, the function regenerates the encryption key;
+ * otherwise, it leaves with KErrBadPassphrase.
+ *
+ * @param aData The encryption data object to copy
+ * @param aEncryptedMasterKey On return, the encrypted master key
+ * @param aPassword The user supplied password
+ * @return The new CPBEncryptSet object
+ * @leave KErrBadPassphrase If the specified password is incorrect
+ */
+ IMPORT_C static CPBEncryptSet* NewL(const CPBEncryptionData& aData,
+ const TDesC8& aEncryptedMasterKey, const TPBPassword& aPassword);
+
+ /**
+ * Creates a new CPBEncryptSet object for encryption of new data
+ * (and generates an encrypted master key).
+ *
+ * The returned pointer is put onto the cleanup stack.
+ *
+ * If the specified password is valid, the function regenerates the encryption key;
+ * otherwise, it leaves with KErrBadPassphrase.
+ *
+ * @param aData The encryption data object to copy
+ * @param aEncryptedMasterKey On return, the encrypted master key
+ * @param aPassword The user supplied password
+ * @return The new CPBEncryptSet object
+ * @leave KErrBadPassphrase If the specified password is incorrect
+ */
+ IMPORT_C static CPBEncryptSet* NewLC(const CPBEncryptionData& aData,
+ const TDesC8& aEncryptedMasterKey, const TPBPassword& aPassword);
+
+ /**
+ * Gets the encrypted form of the master key.
+ *
+ * This must be stored along with the object returned by CPBEncryptElement::EncryptionData()
+ * in order for the object to be reconstructed with the same state at
+ * some time in the future. Failure to do so will result in the permanent
+ * loss of any information encrypted with this object.
+ *
+ * @return The encrypted master key.
+ */
+ IMPORT_C const TDesC8& EncryptedMasterKey(void) const;
+
+ /**
+ * Constructs a CPBEncryptor object based on the state of this object
+ * (i.e., the cipher and master key) allowing the encryption of data.
+ *
+ * @return A pointer to a CPBEncryptor object.
+ * The caller assumes ownership of the returned object.
+ */
+ CPBEncryptor* NewEncryptL(void) const;
+
+ /**
+ * Constructs a CPBEncryptor object based on the state of this object
+ * (i.e., the cipher and master key) allowing the encryption of data.
+ *
+ * @return A pointer to a CPBEncryptor object.
+ * The caller assumes ownership of the returned object.
+ * The returned pointer is left on the cleanup stack.
+ */
+ CPBEncryptor* NewEncryptLC(void) const;
+
+ /**
+ * Constructs a CPBDecryptor object based on the state of this object
+ * (i.e., the cipher and master key) allowing the decryption of data.
+ *
+ * @return A pointer to a CPBDecryptor object.
+ * The caller assumes ownership of the returned object.
+ */
+ CPBDecryptor* NewDecryptL(void) const;
+
+ /**
+ * Constructs a CPBDecryptor object based on the state of this object
+ * (i.e., the cipher and master key) allowing the decryption of data.
+ *
+ * @return A pointer to a CPBDecryptor object.
+ * The caller assumes ownership of the returned object.
+ * The returned pointer is left on the cleanup stack.
+ */
+ CPBDecryptor* NewDecryptLC(void) const;
+
+ /**
+ * Re-encrypts the master key with the specified new password.
+ *
+ * @param aNewPassword The new password
+ */
+ IMPORT_C void ChangePasswordL(const TPBPassword& aNewPassword);
+
+ /**
+ * Gets the maximum output ciphertext length given a specified input plaintext length.
+ *
+ * @param aPlaintextLength The plaintext length
+ * @return The maximum ciphertext length given a plaintext length.
+ */
+ TInt MaxCiphertextLength(TInt aPlaintextLength) const;
+
+ /**
+ * Gets the maximum output plaintext length given a specified input ciphertext length.
+ *
+ * @param aCiphertextLength The ciphertext length
+ * @return The maximum plaintext length given a ciphertext length.
+ */
+ TInt MaxPlaintextLength(TInt aCiphertextLength) const;
+
+ /** Destructor */
+ virtual ~CPBEncryptSet(void);
+protected:
+ /** @internalAll */
+ void ConstructL(const TDesC8& aPassword);
+ /** @internalAll */
+ void ConstructL(const TDesC8& aPassword, TPBECipher aCipher);
+ /** @internalAll */
+ void ConstructL(const TDesC8& aPassword, const CPBEncryptParms& aParms);
+ /** @internalAll */
+ void ConstructMasterKeyL(void);
+ /** @internalAll */
+ void ConstructL(const CPBEncryptionData& aData,
+ const TDesC8& aEncryptedMasterKey, const TPBPassword& aPassword);
+ /** @internalAll */
+ void DecryptMasterKeyL(TDes8& aMasterKey) const;
+ /** @internalAll */
+ void EncryptMasterKeyL(const TDesC8& aMasterKey);
+protected:
+ /** @internalAll */
+ CPBEncryptSet(void);
+ /** The derived encrypted master key*/
+ HBufC8* iEncryptedMasterKey;
+private:
+ CPBEncryptSet(const CPBEncryptSet&);
+ CPBEncryptSet& operator= (const CPBEncryptSet&);
+ };
+
+/**
+ * Class representing both 8 and 16 bit descriptor passwords.
+ * Internally these are stored as 8 bit passwords.
+ */
+class TPBPassword
+ {
+public:
+ /**
+ * Sets the password.
+ *
+ * Constructs a TPBPassword object with an 8 bit descriptor.
+ *
+ * Internally this is represented as an octet byte sequence
+ * (aka 8 bit TPtrC8 descriptor).
+ *
+ * @param aPassword A const reference to an 8 bit descriptor.
+ * representing the users initial password.
+ */
+ IMPORT_C TPBPassword(const TDesC8& aPassword);
+
+ /**
+ * Sets the password.
+ *
+ * Constructs a TPBPassword object with a 16 bit descriptor.
+ *
+ * Internally this is represented as an octet byte sequence
+ * (aka 8 bit TPtrC8 descriptor).
+ *
+ * @param aPassword A const reference to a 16 bit descriptor
+ * representing the users initial password.
+ */
+ IMPORT_C TPBPassword(const TDesC16& aPassword);
+
+ /**
+ * Gets the password.
+ *
+ * Gets a const reference to an 8 bit descriptor representing the users
+ * initial password (which could have been either 8 or 16 bit).
+ *
+ * @return A const reference to an 8 bit descriptor.
+ */
+ IMPORT_C const TDesC8& Password(void) const;
+private:
+ TPtrC8 iPassword;
+ };
+
+#endif