|
1 /** |
|
2 * Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
3 * All rights reserved. |
|
4 * This component and the accompanying materials are made available |
|
5 * under the terms of "Eclipse Public License v1.0" |
|
6 * which accompanies this distribution, and is available |
|
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: |
|
15 * Declaration of CSecureBUREncryptKeySource |
|
16 * |
|
17 * |
|
18 */ |
|
19 |
|
20 |
|
21 |
|
22 /** |
|
23 @file |
|
24 */ |
|
25 #ifndef __SBENCRYPT_H__ |
|
26 #define __SBENCRYPT_H__ |
|
27 #include <e32base.h> |
|
28 #include <f32file.h> |
|
29 |
|
30 namespace conn |
|
31 { |
|
32 class CSecureBURKeySourceImpl; |
|
33 |
|
34 class CSecureBUREncryptKeySource : public CBase |
|
35 /** |
|
36 This class is responsible for providing keys for encryption of backup data |
|
37 or decryption of restore data based on drive and SID of the data owner. |
|
38 |
|
39 The class will be included in a separate key-providing DLL provided by licensees |
|
40 at build time. The default Symbian implementation will not provide keys. |
|
41 |
|
42 It is permissible to not provide any keys and to not encrypt data. It is also |
|
43 permissible for one key to be common to all or a set of SIDs or for one key to be |
|
44 common to a set of drives. |
|
45 |
|
46 The class can provide a data buffer with backup keys. If it does then the buffer |
|
47 will be stored (un-encrypted!) with the backup and will be provided when keys are |
|
48 requested for a restore operation. The class supports a default data buffer for a |
|
49 whole backup plus the ability to override it with buffers for specific SIDs. If |
|
50 the buffer is used then the implementor must be aware that is is not encrypted in the |
|
51 backup and so must not contain any sensitive data or any data that would allow an |
|
52 attacker to recreate the key. If a buffer is provided then it is returned at restore |
|
53 time on a per-SID basis - there is no provision to provide a default buffer at restore |
|
54 time. |
|
55 |
|
56 If keys are provided then the implementor needs to consider a number of factors: |
|
57 |
|
58 @li If the key is entered by the user then it should be assumed that the user can |
|
59 decrypt data off the device. |
|
60 |
|
61 @li If the key is local to the device then the data cannot be restored to a new device. |
|
62 |
|
63 @li If the key depends on the drive being backed up or restored then the implementor |
|
64 needs to consider whether a drive may have its letter changed (e.g. if a device has |
|
65 multiple slots for removable media). |
|
66 |
|
67 This class owns a CSecureBURKeySourceImpl instance and publishes the |
|
68 public API to the outside world. The reason for this facade class is twofold: |
|
69 |
|
70 @li Hiding the implementation details of CSecureBURKeySourceImpl |
|
71 |
|
72 @li Future binary compatibility |
|
73 |
|
74 @released |
|
75 @publishedPartner |
|
76 */ |
|
77 { |
|
78 public: |
|
79 /** |
|
80 Static factory method (two phase construction) |
|
81 |
|
82 @return Pointer to the CSecureBUREncryptKeySource instance |
|
83 */ |
|
84 IMPORT_C static CSecureBUREncryptKeySource* NewL(); |
|
85 /** |
|
86 Standard virtual destructor |
|
87 */ |
|
88 IMPORT_C virtual ~CSecureBUREncryptKeySource(); |
|
89 |
|
90 /** |
|
91 Get a default data buffer for all backups of a specified drive. |
|
92 |
|
93 @param aDrive the drive being backed up - may be ignored |
|
94 @param aGotBuffer set to ETrue on return if a buffer is supplied |
|
95 @param aBuffer if aGotBuffer is set to ETrue then this is a buffer of data to be |
|
96 included with backups. |
|
97 */ |
|
98 IMPORT_C void GetDefaultBufferForBackupL(TDriveNumber aDrive, TBool& aGotBuffer, TDes& aBuffer); |
|
99 |
|
100 /** |
|
101 Provides a key to use to encrypt backup data for a specific data owner from a specific |
|
102 drive. It is permissible to provide the same key for some or all data owners. It is |
|
103 permissible to provide the same key for some or all drives. |
|
104 |
|
105 @param aDrive the drive (EDrive A to EDriveZ) which is being backed up |
|
106 @param aSID the secure id of the data owner |
|
107 @param aDoEncrypt returns ETrue if a key is provided, EFalse if data is not to be encrypted |
|
108 @param aKey the key to use to encrypt data - ignored if aDoEncrypt is set to EFalse |
|
109 @param aGotBuffer returns ETrue if a buffer is returned that is specific to this SID |
|
110 @param aBuffer if aGotBuffer is set to ETrue then this is a buffer of data to be |
|
111 included with backups. |
|
112 */ |
|
113 IMPORT_C void GetBackupKeyL(TDriveNumber aDrive, TSecureId aSID, |
|
114 TBool &aDoEncrypt, TDes8& aKey, |
|
115 TBool& aGotBuffer, TDes& aBuffer); |
|
116 |
|
117 /** |
|
118 Provides a key to use to decrypt backup data for a specific data owner from a specific |
|
119 drive. It is permissible to provide the same key for some or all data owners. It is |
|
120 permissible to provide the same key for some or all drives. |
|
121 |
|
122 @param aDrive the drive (EDrive A to EDriveZ) which is being restored |
|
123 @param aSID the secure id of the data owner |
|
124 @param aGotBuffer set to ETrue if a buffer is provided |
|
125 @param aBuffer if aGotBuffer is set to ETrue then this is a buffer of data that was |
|
126 provided with the key for the backup (or the default buffer) |
|
127 @param aGotKey returns ETrue if a key is provided, EFalse if data is not to be decrypted |
|
128 @param aKey the key to use to decrypt data - ignored if aGotKey is set to EFalse |
|
129 */ |
|
130 IMPORT_C void GetRestoreKeyL(TDriveNumber aDrive, TSecureId aSID, |
|
131 TBool aGotBuffer, TDes& aBuffer, |
|
132 TBool &aGotKey, TDes8& aKey); |
|
133 |
|
134 private: |
|
135 /** |
|
136 Standard C++ Constructor |
|
137 */ |
|
138 CSecureBUREncryptKeySource(); |
|
139 /** |
|
140 Symbian Second phase constructor |
|
141 */ |
|
142 void ConstructL(); |
|
143 |
|
144 private: |
|
145 /** Pointer the the CSecureBURKeySourceImpl implementation */ |
|
146 CSecureBURKeySourceImpl* iImpl; |
|
147 }; |
|
148 |
|
149 } // end namespace |
|
150 #endif |
|
151 |