|
1 /* |
|
2 * Copyright (c) 2003-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 the License "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 * MKeystoreManager.h |
|
16 * |
|
17 */ |
|
18 |
|
19 |
|
20 |
|
21 |
|
22 /** |
|
23 @file |
|
24 @publishedPartner |
|
25 @released |
|
26 */ |
|
27 |
|
28 #ifndef __MCTKEYSTOREMANAGER_H__ |
|
29 #define __MCTKEYSTOREMANAGER_H__ |
|
30 |
|
31 #include "mctkeystore.h" |
|
32 |
|
33 /** */ |
|
34 const TInt KInterfaceKeyStoreManager = 0x101F7335; |
|
35 |
|
36 class CPBEncryptParms; |
|
37 |
|
38 /** |
|
39 * Defines the interface for a key store manager token. |
|
40 * |
|
41 * This documentation describes the security policy that must be enforced by |
|
42 * implementations of the interface. |
|
43 * |
|
44 * @publishedPartner |
|
45 * @released |
|
46 */ |
|
47 class MCTKeyStoreManager : public MCTKeyStore |
|
48 { |
|
49 public: |
|
50 /** |
|
51 * Key creation |
|
52 */ |
|
53 |
|
54 /** |
|
55 * Generates a new key pair and store it in the keystore. |
|
56 * |
|
57 * @param aReturnedKey This is filled by the caller with required |
|
58 * attributes, leaving the TKeyIdentifier iID and object handle iHandle |
|
59 * uninitialised - these values are set if the key is created successfully |
|
60 * @param aStatus This will be completed with the final status code |
|
61 * |
|
62 * @capability WriteUserData Requires the caller to have WriteUserData capability |
|
63 * @leave KErrPermissionDenied If the caller does not have WriteUserData capability |
|
64 * @leave KErrAlreadyExists If a key with the specified label already |
|
65 * exists in the keystore. |
|
66 * @leave KErrKeySize If the requested key size is not supported. |
|
67 * @leave KErrKeyAccess If an invalid combination of key access flags were specified. |
|
68 * @leave KErrKeyValidity If a validity period was specified, but the end |
|
69 * date was in the past. |
|
70 */ |
|
71 virtual void CreateKey(CCTKeyInfo*& aReturnedKey, |
|
72 TRequestStatus& aStatus) = 0; |
|
73 |
|
74 /** Cancels an ongoing CreateKey() operation. */ |
|
75 virtual void CancelCreateKey() = 0; |
|
76 |
|
77 /** |
|
78 * Import keys |
|
79 */ |
|
80 |
|
81 /** |
|
82 * Imports a cleartext key pair into the keystore. |
|
83 * |
|
84 * The import data is DER-encoded PKCS#8 format. |
|
85 * |
|
86 * @param aKey This is a descriptor representation of the PKCS#8 key data. |
|
87 * @param aReturnedKey This is filled by the caller with required |
|
88 * attributes, leaving the TKeyIdentifier iID and object handle iHandle |
|
89 * uninitialised - these values are set if the key is created successfully. |
|
90 * |
|
91 * @capability WriteUserData Requires the caller to have WriteUserData capability |
|
92 * @leave KErrPermissionDenied If the caller does not have WriteUserData capability |
|
93 * @leave KErrAlreadyExists If a key with the specified label already exists |
|
94 * in the keystore. |
|
95 * @leave KErrKeySize If the requested key size is not supported. |
|
96 * @leave KErrKeyAccess If an invalid combination of key access flags were specified. |
|
97 * @leave KErrKeyValidity If a validity period was specified, but the end |
|
98 * date was in the past. |
|
99 * @leave KErrArgument If there is an error parsing the key data. |
|
100 */ |
|
101 virtual void ImportKey(const TDesC8& aKey, |
|
102 CCTKeyInfo*& aReturnedKey, |
|
103 TRequestStatus& aStatus) = 0; |
|
104 |
|
105 /** Cancels an ongoing ImportKey() operation. */ |
|
106 virtual void CancelImportKey() = 0; |
|
107 |
|
108 /** |
|
109 * Imports an encrypted key pair into the keystore. |
|
110 * |
|
111 * The import data is DER-encoded PKCS#5/PKCS#8 format. |
|
112 * |
|
113 * @param aKey This is a descriptor representation of the PKCS#8 key data |
|
114 * @param aReturnedKey This is filled by the caller with required |
|
115 * attributes, leaving the TKeyIdentifier iID and object handle iHandle |
|
116 * uninitialised - these values are set if the key is created successfully |
|
117 * |
|
118 * @capability WriteUserData Requires the caller to have WriteUserData capability |
|
119 * @leave KErrPermissionDenied If the caller does not have WriteUserData capability |
|
120 * @leave KErrAlreadyExists If a key with the specified label already exists |
|
121 * in the keystore. |
|
122 * @leave KErrKeySize If the requested key size is not supported. |
|
123 * @leave KErrKeyAccess If an invalid combination of key access flags were specified. |
|
124 * @leave KErrKeyValidity If a validity period was specified, but the end |
|
125 * date was in the past. |
|
126 * @leave KErrArgument If there is an error parsing the key data. |
|
127 */ |
|
128 virtual void ImportEncryptedKey(const TDesC8& aKey, |
|
129 CCTKeyInfo*& aReturnedKey, |
|
130 TRequestStatus& aStatus) = 0; |
|
131 |
|
132 /** Cancels an ongoing ImportEncryptedKey() operation. */ |
|
133 virtual void CancelImportEncryptedKey() = 0; |
|
134 |
|
135 /** |
|
136 * Export keys |
|
137 */ |
|
138 |
|
139 /** |
|
140 * Exports a key pair in the clear. |
|
141 * |
|
142 * The key is exported as DER-encoded PKCS#8 data. |
|
143 * |
|
144 * @param aHandle The handle of the key to export |
|
145 * @param aKey A reference to a HBufC8 pointer. The pointer will be set to |
|
146 * a newly allocated buffer containing the key data. It is the caller's |
|
147 * responsibility to delete this buffer. |
|
148 * |
|
149 * @capability Dependent Requires the caller to have any capabilities specified in the |
|
150 * key management security policy. |
|
151 * @leave KErrPermissionDenied If the caller does not conform to the key |
|
152 * management security policy. |
|
153 * @leave KErrNotFound If the key the handle referes to does not exist. |
|
154 * @leave KErrKeyAccess If the sensitive flag is set for the key, or the |
|
155 * exportable flag is not set. |
|
156 * @leave KErrKeyAlgorithm If this type of key cannot be exported. |
|
157 */ |
|
158 virtual void ExportKey(TCTTokenObjectHandle aHandle, |
|
159 HBufC8*& aKey, |
|
160 TRequestStatus& aStatus) = 0; |
|
161 |
|
162 /** Cancels an ongoing ExportKey() operation. */ |
|
163 virtual void CancelExportKey() = 0; |
|
164 |
|
165 /** |
|
166 * Exports an encrypted key pair. |
|
167 * |
|
168 * The key is exported as DER-encoded PKCS#5/PKCS#8 data. |
|
169 * |
|
170 * @param aHandle The handle of the key to export |
|
171 * @param aKey A reference to a HBufC8 pointer. The pointer will be set to |
|
172 * a newly allocated buffer containing the key data. |
|
173 * @param aParams The PBE encryption parameters to use when encrypting the key. |
|
174 * |
|
175 * @capability Dependent Requires the caller to have any capabilities specified in the |
|
176 * key management security policy. |
|
177 * @leave KErrPermissionDenied If the caller does not conform to the key |
|
178 * management security policy. |
|
179 * @leave KErrNotFound If the key the handle referes to does not exist. |
|
180 * @leave KErrKeyAccess If the exportable flag is not set for the key. |
|
181 * @leave KErrKeyAlgorithm If this type of key cannot be exported. |
|
182 */ |
|
183 virtual void ExportEncryptedKey(TCTTokenObjectHandle aHandle, |
|
184 const CPBEncryptParms& aEncryptParams, |
|
185 HBufC8*& aKey, |
|
186 TRequestStatus& aStatus) = 0; |
|
187 |
|
188 /** Cancels an ongoing ExportEncryptedKey() operation. */ |
|
189 virtual void CancelExportEncryptedKey() = 0; |
|
190 |
|
191 /** |
|
192 * Deletes a key. |
|
193 * |
|
194 * @param aHandle The handle of the key to delete |
|
195 * |
|
196 * @capability Dependent Requires the caller to have any capabilities specified in the |
|
197 * key management security policy. |
|
198 * @leave KErrPermissionDenied If the caller does not conform to the key |
|
199 * management security policy. |
|
200 * @leave KErrNotFound If the key the handle referes to does not exist. |
|
201 * @leave KErrAccessDenied If the calling process is not allowed to delete the key. |
|
202 * @leave KErrInUse If another client is currently using the key. |
|
203 */ |
|
204 virtual void DeleteKey(TCTTokenObjectHandle aHandle, |
|
205 TRequestStatus& aStatus) = 0; |
|
206 |
|
207 /** Cancels an ongoing DeleteKey() operation. */ |
|
208 virtual void CancelDeleteKey() = 0; |
|
209 |
|
210 /** |
|
211 * Sets the security policy for key use. |
|
212 * |
|
213 * Specifies which processes are allowed to use the key for cryptographic |
|
214 * operations. |
|
215 * |
|
216 * @param aHandle The handle of the key |
|
217 * @param aPolicy The new security policy. |
|
218 * |
|
219 * @capability Dependent Requires the caller to have any capabilities specified in the |
|
220 * key management security policy. |
|
221 * @leave KErrPermissionDenied If the caller does not conform to the key |
|
222 * management security policy. |
|
223 * @leave KErrNotFound If the key the handle referes to does not exist. |
|
224 */ |
|
225 virtual void SetUsePolicy(TCTTokenObjectHandle aHandle, |
|
226 const TSecurityPolicy& aPolicy, |
|
227 TRequestStatus& aStatus) = 0; |
|
228 |
|
229 /** Cancels an ongoing SetUsePolicy() operation. */ |
|
230 virtual void CancelSetUsePolicy() = 0; |
|
231 |
|
232 /** |
|
233 * Sets the security policy for key management. |
|
234 * |
|
235 * Specifies which processes are allowed to perform management operations on |
|
236 * the key. |
|
237 * |
|
238 * @param aHandle The handle of the key |
|
239 * @param aPolicy The new security policy. |
|
240 * |
|
241 * @capability Dependent Requires the caller to have any capabilities specified in the |
|
242 * current and new key management security policies. |
|
243 * @leave KErrPermissionDenied If the caller does not conform to the current |
|
244 * and new key management security policies. |
|
245 * @leave KErrNotFound If the key the handle referes to does not exist. |
|
246 */ |
|
247 virtual void SetManagementPolicy(TCTTokenObjectHandle aHandle, |
|
248 const TSecurityPolicy& aPolicy, |
|
249 TRequestStatus& aStatus) = 0; |
|
250 |
|
251 /** Cancels an ongoing SetManagementPolicy() operation. */ |
|
252 virtual void CancelSetManagementPolicy() = 0; |
|
253 |
|
254 /** |
|
255 * Sets the passphrase timeout for all keys owned by this process. |
|
256 * |
|
257 * @param aTimeout The timeout in seconds. 0 means that the passphrase is |
|
258 * always asked for, and -1 means that it is never expired |
|
259 * @param aStatus This will be completed with the final status code |
|
260 * |
|
261 * @capability Dependent Requires the caller to have any capabilities specified in the |
|
262 * key management security policy. |
|
263 * @leave KErrPermissionDenied If the caller does not conform to the key |
|
264 * management security policy. |
|
265 * @leave KErrArgument If the timeout specified is invalid. |
|
266 */ |
|
267 virtual void SetPassphraseTimeout(TInt aTimeout, |
|
268 TRequestStatus& aStatus) = 0; |
|
269 |
|
270 /** Cancels an ongoing SetPassphraseTimeout() operation. */ |
|
271 virtual void CancelSetPassphraseTimeout() = 0; |
|
272 |
|
273 /** |
|
274 * Re-locks the entire store (i.e., forget the pasphrase) |
|
275 * |
|
276 * @param aStatus This will be completed with the final status code |
|
277 */ |
|
278 virtual void Relock(TRequestStatus& aStatus) = 0; |
|
279 |
|
280 /** Cancels an ongoing Relock() operation. */ |
|
281 virtual void CancelRelock() = 0; |
|
282 }; |
|
283 |
|
284 |
|
285 #endif // __MCTKEYSTOREMANAGER_H__ |