diff -r 000000000000 -r 2c201484c85f crypto/weakcrypto/inc/pbe.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/crypto/weakcrypto/inc/pbe.h Wed Jul 08 11:25:26 2009 +0100 @@ -0,0 +1,613 @@ +/* +* 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 +#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 must 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 master + * 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