|
1 /* |
|
2 * Copyright (c) 2006-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 * crypto hash application interface |
|
16 * |
|
17 */ |
|
18 |
|
19 |
|
20 /** |
|
21 @file |
|
22 @publishedAll |
|
23 @released |
|
24 */ |
|
25 |
|
26 #ifndef __CRYPTOAPI_HASHAPI_H__ |
|
27 #define __CRYPTOAPI_HASHAPI_H__ |
|
28 |
|
29 #include <e32base.h> |
|
30 #include <cryptospi/cryptobaseapi.h> |
|
31 |
|
32 |
|
33 namespace CryptoSpi |
|
34 { |
|
35 class MPlugin; |
|
36 class MHash; |
|
37 class MAsyncHash; |
|
38 class CCryptoParams; |
|
39 class CKey; |
|
40 |
|
41 /** |
|
42 Hash API, which wraps a synchronous Hash plugin implementation |
|
43 */ |
|
44 NONSHARABLE_CLASS(CHash) : public CCryptoBase |
|
45 { |
|
46 public: |
|
47 /** |
|
48 * @internalComponent |
|
49 * |
|
50 * Create a CHash instance from the given MHash instance |
|
51 * @param aHash The hash plugin instance |
|
52 * @return A pointer to a CHash instance |
|
53 **/ |
|
54 static CHash* NewL(MHash* aHash, TInt aHandle); |
|
55 |
|
56 /** |
|
57 Destructor |
|
58 */ |
|
59 IMPORT_C ~CHash(); |
|
60 |
|
61 /** |
|
62 Adds aMessage to the internal representation of data to be hashed, |
|
63 then returns a TPtrC8 of the finalised hash of all the previously |
|
64 appended messages. |
|
65 @param aMessage The data to be included in the hash. |
|
66 @return A descriptor pointer to the buffer containing the resulting hash. |
|
67 */ |
|
68 IMPORT_C TPtrC8 Hash(const TDesC8& aMessage); // Combination of Update and Final |
|
69 |
|
70 /** |
|
71 Adds data to the internal representation of messages to be hashed. |
|
72 @param aMessage The data to be included in the hash. |
|
73 */ |
|
74 IMPORT_C void Update(const TDesC8& aMessage); |
|
75 |
|
76 /** |
|
77 Produces a final hash value from all the previous updates of data |
|
78 to be hashed. |
|
79 @param aMessage The data to be included in the hash. |
|
80 */ |
|
81 IMPORT_C TPtrC8 Final(const TDesC8& aMessage); |
|
82 |
|
83 /** |
|
84 Creates a brand new reset CHash object containing no state |
|
85 information from the current object. This API is only to support |
|
86 the old crypto API for BC reason. It is strongly recommended not to use this API. |
|
87 |
|
88 To make a copy of a message digest with its internal state intact, |
|
89 see CopyL(). |
|
90 |
|
91 @return A pointer to the new reset CHash object. |
|
92 @leave ... Any of the crypto error codes defined in |
|
93 cryptospi_errs.h or any of the system-wide error codes. |
|
94 */ |
|
95 IMPORT_C CHash* ReplicateL(); |
|
96 |
|
97 /** |
|
98 Creates a new CHash object with the exact same state as |
|
99 the current object.This API is only to support |
|
100 the old crypto API for BC reason. It is strongly recommended not to use this API. |
|
101 |
|
102 This function copies all internal state of the message digest. |
|
103 To create a new CHash object without the state of |
|
104 the current object, see ReplicateL(). |
|
105 |
|
106 @return A pointer to the new CHash object. |
|
107 @leave ... Any of the crypto error codes defined in |
|
108 cryptospi_errs.h or any of the system-wide error codes. |
|
109 */ |
|
110 IMPORT_C CHash* CopyL(); |
|
111 |
|
112 /** |
|
113 * @deprecated |
|
114 * |
|
115 * Set the key used for HMAC mode operation. |
|
116 * @param aKey The key for HMAC |
|
117 * @leave KErrArgument if aKey is not of the expected type. |
|
118 * @leave ... Any of the crypto error codes defined in |
|
119 cryptospi_errs.h or any of the system-wide error codes. |
|
120 */ |
|
121 IMPORT_C void SetKeyL(const CKey& aKey); |
|
122 |
|
123 /** |
|
124 * @deprecated |
|
125 * |
|
126 * Set the operation mode, ie hash or hmac |
|
127 * @param aOperationMode The UID to identifiy the operation mode |
|
128 * @leave KErrNotSupported if the specified operation mode is not supported. |
|
129 * @leave ... Any of the crypto error codes defined in |
|
130 cryptospi_errs.h or any of the system-wide error codes. |
|
131 */ |
|
132 IMPORT_C void SetOperationModeL(TUid aOperationMode); |
|
133 |
|
134 private: |
|
135 /** |
|
136 Constructor |
|
137 */ |
|
138 CHash(MHash* aHash, TInt aHandle); |
|
139 }; |
|
140 |
|
141 |
|
142 /** |
|
143 Asynchronous Hash API, which wraps an asynchronous Hash plugin implementation |
|
144 */ |
|
145 NONSHARABLE_CLASS(CAsyncHash) : public CCryptoBase |
|
146 { |
|
147 public: |
|
148 /** |
|
149 * @internalComponent |
|
150 * |
|
151 * Create a CAsyncHash instance from the given MAsyncHash instance |
|
152 * @param aAsyncHash The async hash plugin instance |
|
153 * @return A pointer to a CAsyncHash instance |
|
154 **/ |
|
155 static CAsyncHash* NewL(MAsyncHash* aAsyncHash, TInt aHandle); |
|
156 |
|
157 /** |
|
158 Destructor |
|
159 */ |
|
160 IMPORT_C ~CAsyncHash(); |
|
161 |
|
162 /** |
|
163 Adds aMessage to the internal representation of data to be hashed, |
|
164 then returns a TPtrC8 of the finalised hash of all the previously |
|
165 appended messages. |
|
166 @param aMessage The data to be included in the hash. |
|
167 @param aHash A descriptor pointer to the buffer containing the hash result. |
|
168 @param aStatus |
|
169 */ |
|
170 IMPORT_C void Hash(const TDesC8& aMessage, TPtrC8& aHash, TRequestStatus& aStatus); |
|
171 |
|
172 /** |
|
173 Adds data to the internal representation of messages to be hashed. |
|
174 @param aMessage The data to be included in the hash. |
|
175 @param aStatus |
|
176 */ |
|
177 IMPORT_C void Update(const TDesC8& aMessage, TRequestStatus& aStatus); |
|
178 |
|
179 /** |
|
180 Produces a final hash value from all the previous updates of data |
|
181 to be hashed. |
|
182 @param aMessage The data to be included in the hash. |
|
183 @param aFinal A descriptor pointer to the buffer containing the hash result. |
|
184 @param aStatus |
|
185 @return A descriptor pointer to the buffer containing the resulting hash. |
|
186 */ |
|
187 IMPORT_C void Final(const TDesC8& aMessage, TPtrC8& aFinal, TRequestStatus& aStatus); |
|
188 |
|
189 /** |
|
190 Cancel the outstanding request |
|
191 */ |
|
192 IMPORT_C void Cancel(); |
|
193 |
|
194 /** |
|
195 Creates a brand new reset CAsyncHash object containing no state |
|
196 information from the current object. This API is only to support |
|
197 the old crypto API for BC reason. It is strongly recommended not to use this API. |
|
198 |
|
199 To make a copy of a message digest with its internal state intact, |
|
200 see CopyL(). |
|
201 |
|
202 @return A pointer to the new reset CAsyncHash object. |
|
203 @leave ... Any of the crypto error codes defined in |
|
204 cryptospi_errs.h or any of the system-wide error codes. |
|
205 */ |
|
206 IMPORT_C CAsyncHash* ReplicateL(); |
|
207 |
|
208 /** |
|
209 Creates a new CAsyncHash object with the exact same state as |
|
210 the current object. This API is only to support |
|
211 the old crypto API for BC reason. It is strongly recommended not to use this API. |
|
212 |
|
213 This function copies all internal state of the message digest. |
|
214 To create a new CAsyncHash object without the state of |
|
215 the current object, see ReplicateL(). |
|
216 |
|
217 @return A pointer to the new CAsyncHash object. |
|
218 @leave ... Any of the crypto error codes defined in |
|
219 cryptospi_errs.h or any of the system-wide error codes. |
|
220 */ |
|
221 IMPORT_C CAsyncHash* CopyL(); |
|
222 |
|
223 /** |
|
224 * @deprecated |
|
225 * |
|
226 * Set the key used for HMAC mode operation. |
|
227 * @param aKey the key for HMAC |
|
228 * @leave KErrArgument if aKey is not of the expected type. |
|
229 * @leave ... Any of the crypto error codes defined in |
|
230 cryptospi_errs.h or any of the system-wide error codes. |
|
231 */ |
|
232 IMPORT_C void SetKeyL(const CKey& aKey); |
|
233 |
|
234 /** |
|
235 * @deprecated |
|
236 * |
|
237 * Set the operation mode, ie hash or hmac |
|
238 * @param aOperationMode The UID to identifiy the operation mode |
|
239 * @leave KErrNotSupported if the specified mode is not supported. |
|
240 * @leave ... Any of the crypto error codes defined in |
|
241 cryptospi_errs.h or any of the system-wide error codes. |
|
242 */ |
|
243 IMPORT_C void SetOperationModeL(TUid aOperationMode); |
|
244 |
|
245 private: |
|
246 |
|
247 /** |
|
248 Constructor |
|
249 */ |
|
250 CAsyncHash(MAsyncHash* aAsyncHash, TInt aHandle); |
|
251 }; |
|
252 |
|
253 /** |
|
254 the Factory to create synchronous and asynchronous hash instances |
|
255 */ |
|
256 class CHashFactory |
|
257 { |
|
258 public: |
|
259 |
|
260 /** |
|
261 * @deprecated |
|
262 * |
|
263 * Create a CHash instance |
|
264 * |
|
265 * @param aHash The pointer to CHash |
|
266 * @param aAlgorithmUid The specific hash algorithm e.g. MD2, SHA1, MD4 |
|
267 * @param aOperationMode The operation mode of the hash e.g. Hash mode, Hmac mode |
|
268 * @param aKey The key for Hmac mode, which should be NULL in Hash mode |
|
269 * @param aAlgorithmParams The parameters that are specific to a particular |
|
270 * algorithm. This is for extendibility and will normally be null. |
|
271 * @return KErrNone if successful; otherwise, a system wide error code. |
|
272 */ |
|
273 IMPORT_C static void CreateHashL(CHash*& aHash, |
|
274 TUid aAlgorithmUid, |
|
275 TUid aOperationMode, |
|
276 const CKey* aKey, |
|
277 const CCryptoParams* aAlgorithmParams); |
|
278 |
|
279 /** |
|
280 * @deprecated |
|
281 * |
|
282 * Create a CAsyncHash instance |
|
283 * |
|
284 * @param aAsyncHash The pointer to CAsyncHash |
|
285 * @param aAlgorithmUid The specific hash algorithm e.g. MD2, SHA1, MD4 |
|
286 * @param aOperationMode The operation mode of the hash e.g. Hash mode, Hmac mode |
|
287 * @param aKey The key for Hmac mode, which should be NULL in Hash mode |
|
288 * @param aAlgorithmParams The parameters that are specific to a particular |
|
289 * algorithm. This is for extendibility and will normally be null. |
|
290 * @return KErrNone if successful; otherwise, a system wide error code. |
|
291 */ |
|
292 IMPORT_C static void CreateAsyncHashL(CAsyncHash*& aAsyncHash, |
|
293 TUid aAlgorithmUid, |
|
294 TUid aOperationMode, |
|
295 const CKey* aKey, |
|
296 const CCryptoParams* aAlgorithmParams); |
|
297 |
|
298 #ifdef SYMBIAN_SDP_IPSEC_VOIP_SUPPORT |
|
299 /** |
|
300 * Create a CHash instance |
|
301 * |
|
302 * @param aHash The pointer to CHash |
|
303 * @param aAlgorithmUid The specific hash algorithm e.g. MD2, SHA1, MD4 |
|
304 * @param aAlgorithmParams The parameters that are specific to a particular |
|
305 * algorithm. This is for extendibility and will normally be null. |
|
306 * @return KErrNone if successful; otherwise, a system wide error code. |
|
307 */ |
|
308 IMPORT_C static void CreateHashL(CHash*& aHash, |
|
309 TUid aAlgorithmUid, |
|
310 const CCryptoParams* aAlgorithmParams); |
|
311 |
|
312 /** |
|
313 * Create a CAsyncHash instance |
|
314 * |
|
315 * @param aAsyncHash The pointer to CAsyncHash |
|
316 * @param aAlgorithmUid The specific hash algorithm e.g. MD2, SHA1, MD4 |
|
317 * @param aAlgorithmParams The parameters that are specific to a particular |
|
318 * algorithm. This is for extendibility and will normally be null. |
|
319 * @return KErrNone if successful; otherwise, a system wide error code. |
|
320 */ |
|
321 IMPORT_C static void CreateAsyncHashL(CAsyncHash*& aAsyncHash, |
|
322 TUid aAlgorithmUid, |
|
323 const CCryptoParams* aAlgorithmParams); |
|
324 #endif |
|
325 |
|
326 }; |
|
327 } |
|
328 |
|
329 #endif //__CRYPTOAPI_HASHAPI_H__ |