diff -r 000000000000 -r d0791faffa3f backupandrestore/backupengine/inc/sbencrypt.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/backupandrestore/backupengine/inc/sbencrypt.h Tue Feb 02 01:11:40 2010 +0200 @@ -0,0 +1,151 @@ +/** +* Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies). +* All rights reserved. +* This component and the accompanying materials are made available +* under the terms of "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: +* Declaration of CSecureBUREncryptKeySource +* +* +*/ + + + +/** + @file +*/ +#ifndef __SBENCRYPT_H__ +#define __SBENCRYPT_H__ +#include +#include + +namespace conn + { +class CSecureBURKeySourceImpl; + +class CSecureBUREncryptKeySource : public CBase + /** + This class is responsible for providing keys for encryption of backup data + or decryption of restore data based on drive and SID of the data owner. + + The class will be included in a separate key-providing DLL provided by licensees + at build time. The default Symbian implementation will not provide keys. + + It is permissible to not provide any keys and to not encrypt data. It is also + permissible for one key to be common to all or a set of SIDs or for one key to be + common to a set of drives. + + The class can provide a data buffer with backup keys. If it does then the buffer + will be stored (un-encrypted!) with the backup and will be provided when keys are + requested for a restore operation. The class supports a default data buffer for a + whole backup plus the ability to override it with buffers for specific SIDs. If + the buffer is used then the implementor must be aware that is is not encrypted in the + backup and so must not contain any sensitive data or any data that would allow an + attacker to recreate the key. If a buffer is provided then it is returned at restore + time on a per-SID basis - there is no provision to provide a default buffer at restore + time. + + If keys are provided then the implementor needs to consider a number of factors: + + @li If the key is entered by the user then it should be assumed that the user can + decrypt data off the device. + + @li If the key is local to the device then the data cannot be restored to a new device. + + @li If the key depends on the drive being backed up or restored then the implementor + needs to consider whether a drive may have its letter changed (e.g. if a device has + multiple slots for removable media). + + This class owns a CSecureBURKeySourceImpl instance and publishes the + public API to the outside world. The reason for this facade class is twofold: + + @li Hiding the implementation details of CSecureBURKeySourceImpl + + @li Future binary compatibility + + @released + @publishedPartner + */ + { +public: + /** + Static factory method (two phase construction) + + @return Pointer to the CSecureBUREncryptKeySource instance + */ + IMPORT_C static CSecureBUREncryptKeySource* NewL(); + /** + Standard virtual destructor + */ + IMPORT_C virtual ~CSecureBUREncryptKeySource(); + + /** + Get a default data buffer for all backups of a specified drive. + + @param aDrive the drive being backed up - may be ignored + @param aGotBuffer set to ETrue on return if a buffer is supplied + @param aBuffer if aGotBuffer is set to ETrue then this is a buffer of data to be + included with backups. + */ + IMPORT_C void GetDefaultBufferForBackupL(TDriveNumber aDrive, TBool& aGotBuffer, TDes& aBuffer); + + /** + Provides a key to use to encrypt backup data for a specific data owner from a specific + drive. It is permissible to provide the same key for some or all data owners. It is + permissible to provide the same key for some or all drives. + + @param aDrive the drive (EDrive A to EDriveZ) which is being backed up + @param aSID the secure id of the data owner + @param aDoEncrypt returns ETrue if a key is provided, EFalse if data is not to be encrypted + @param aKey the key to use to encrypt data - ignored if aDoEncrypt is set to EFalse + @param aGotBuffer returns ETrue if a buffer is returned that is specific to this SID + @param aBuffer if aGotBuffer is set to ETrue then this is a buffer of data to be + included with backups. + */ + IMPORT_C void GetBackupKeyL(TDriveNumber aDrive, TSecureId aSID, + TBool &aDoEncrypt, TDes8& aKey, + TBool& aGotBuffer, TDes& aBuffer); + + /** + Provides a key to use to decrypt backup data for a specific data owner from a specific + drive. It is permissible to provide the same key for some or all data owners. It is + permissible to provide the same key for some or all drives. + + @param aDrive the drive (EDrive A to EDriveZ) which is being restored + @param aSID the secure id of the data owner + @param aGotBuffer set to ETrue if a buffer is provided + @param aBuffer if aGotBuffer is set to ETrue then this is a buffer of data that was + provided with the key for the backup (or the default buffer) + @param aGotKey returns ETrue if a key is provided, EFalse if data is not to be decrypted + @param aKey the key to use to decrypt data - ignored if aGotKey is set to EFalse + */ + IMPORT_C void GetRestoreKeyL(TDriveNumber aDrive, TSecureId aSID, + TBool aGotBuffer, TDes& aBuffer, + TBool &aGotKey, TDes8& aKey); + +private: + /** + Standard C++ Constructor + */ + CSecureBUREncryptKeySource(); + /** + Symbian Second phase constructor + */ + void ConstructL(); + +private: + /** Pointer the the CSecureBURKeySourceImpl implementation */ + CSecureBURKeySourceImpl* iImpl; + }; + + } // end namespace +#endif +