1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/cryptospi/cryptohashapi.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -0,0 +1,329 @@
1.4 +/*
1.5 +* Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* All rights reserved.
1.7 +* This component and the accompanying materials are made available
1.8 +* under the terms of the License "Eclipse Public License v1.0"
1.9 +* which accompanies this distribution, and is available
1.10 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.11 +*
1.12 +* Initial Contributors:
1.13 +* Nokia Corporation - initial contribution.
1.14 +*
1.15 +* Contributors:
1.16 +*
1.17 +* Description:
1.18 +* crypto hash application interface
1.19 +*
1.20 +*/
1.21 +
1.22 +
1.23 +/**
1.24 + @file
1.25 + @publishedAll
1.26 + @released
1.27 +*/
1.28 +
1.29 +#ifndef __CRYPTOAPI_HASHAPI_H__
1.30 +#define __CRYPTOAPI_HASHAPI_H__
1.31 +
1.32 +#include <e32base.h>
1.33 +#include <cryptospi/cryptobaseapi.h>
1.34 +
1.35 +
1.36 +namespace CryptoSpi
1.37 + {
1.38 + class MPlugin;
1.39 + class MHash;
1.40 + class MAsyncHash;
1.41 + class CCryptoParams;
1.42 + class CKey;
1.43 +
1.44 + /**
1.45 + Hash API, which wraps a synchronous Hash plugin implementation
1.46 + */
1.47 + NONSHARABLE_CLASS(CHash) : public CCryptoBase
1.48 + {
1.49 + public:
1.50 + /**
1.51 + * @internalComponent
1.52 + *
1.53 + * Create a CHash instance from the given MHash instance
1.54 + * @param aHash The hash plugin instance
1.55 + * @return A pointer to a CHash instance
1.56 + **/
1.57 + static CHash* NewL(MHash* aHash, TInt aHandle);
1.58 +
1.59 + /**
1.60 + Destructor
1.61 + */
1.62 + IMPORT_C ~CHash();
1.63 +
1.64 + /**
1.65 + Adds aMessage to the internal representation of data to be hashed,
1.66 + then returns a TPtrC8 of the finalised hash of all the previously
1.67 + appended messages.
1.68 + @param aMessage The data to be included in the hash.
1.69 + @return A descriptor pointer to the buffer containing the resulting hash.
1.70 + */
1.71 + IMPORT_C TPtrC8 Hash(const TDesC8& aMessage); // Combination of Update and Final
1.72 +
1.73 + /**
1.74 + Adds data to the internal representation of messages to be hashed.
1.75 + @param aMessage The data to be included in the hash.
1.76 + */
1.77 + IMPORT_C void Update(const TDesC8& aMessage);
1.78 +
1.79 + /**
1.80 + Produces a final hash value from all the previous updates of data
1.81 + to be hashed.
1.82 + @param aMessage The data to be included in the hash.
1.83 + */
1.84 + IMPORT_C TPtrC8 Final(const TDesC8& aMessage);
1.85 +
1.86 + /**
1.87 + Creates a brand new reset CHash object containing no state
1.88 + information from the current object. This API is only to support
1.89 + the old crypto API for BC reason. It is strongly recommended not to use this API.
1.90 +
1.91 + To make a copy of a message digest with its internal state intact,
1.92 + see CopyL().
1.93 +
1.94 + @return A pointer to the new reset CHash object.
1.95 + @leave ... Any of the crypto error codes defined in
1.96 + cryptospi_errs.h or any of the system-wide error codes.
1.97 + */
1.98 + IMPORT_C CHash* ReplicateL();
1.99 +
1.100 + /**
1.101 + Creates a new CHash object with the exact same state as
1.102 + the current object.This API is only to support
1.103 + the old crypto API for BC reason. It is strongly recommended not to use this API.
1.104 +
1.105 + This function copies all internal state of the message digest.
1.106 + To create a new CHash object without the state of
1.107 + the current object, see ReplicateL().
1.108 +
1.109 + @return A pointer to the new CHash object.
1.110 + @leave ... Any of the crypto error codes defined in
1.111 + cryptospi_errs.h or any of the system-wide error codes.
1.112 + */
1.113 + IMPORT_C CHash* CopyL();
1.114 +
1.115 + /**
1.116 + * @deprecated
1.117 + *
1.118 + * Set the key used for HMAC mode operation.
1.119 + * @param aKey The key for HMAC
1.120 + * @leave KErrArgument if aKey is not of the expected type.
1.121 + * @leave ... Any of the crypto error codes defined in
1.122 + cryptospi_errs.h or any of the system-wide error codes.
1.123 + */
1.124 + IMPORT_C void SetKeyL(const CKey& aKey);
1.125 +
1.126 + /**
1.127 + * @deprecated
1.128 + *
1.129 + * Set the operation mode, ie hash or hmac
1.130 + * @param aOperationMode The UID to identifiy the operation mode
1.131 + * @leave KErrNotSupported if the specified operation mode is not supported.
1.132 + * @leave ... Any of the crypto error codes defined in
1.133 + cryptospi_errs.h or any of the system-wide error codes.
1.134 + */
1.135 + IMPORT_C void SetOperationModeL(TUid aOperationMode);
1.136 +
1.137 + private:
1.138 + /**
1.139 + Constructor
1.140 + */
1.141 + CHash(MHash* aHash, TInt aHandle);
1.142 + };
1.143 +
1.144 +
1.145 + /**
1.146 + Asynchronous Hash API, which wraps an asynchronous Hash plugin implementation
1.147 + */
1.148 + NONSHARABLE_CLASS(CAsyncHash) : public CCryptoBase
1.149 + {
1.150 + public:
1.151 + /**
1.152 + * @internalComponent
1.153 + *
1.154 + * Create a CAsyncHash instance from the given MAsyncHash instance
1.155 + * @param aAsyncHash The async hash plugin instance
1.156 + * @return A pointer to a CAsyncHash instance
1.157 + **/
1.158 + static CAsyncHash* NewL(MAsyncHash* aAsyncHash, TInt aHandle);
1.159 +
1.160 + /**
1.161 + Destructor
1.162 + */
1.163 + IMPORT_C ~CAsyncHash();
1.164 +
1.165 + /**
1.166 + Adds aMessage to the internal representation of data to be hashed,
1.167 + then returns a TPtrC8 of the finalised hash of all the previously
1.168 + appended messages.
1.169 + @param aMessage The data to be included in the hash.
1.170 + @param aHash A descriptor pointer to the buffer containing the hash result.
1.171 + @param aStatus
1.172 + */
1.173 + IMPORT_C void Hash(const TDesC8& aMessage, TPtrC8& aHash, TRequestStatus& aStatus);
1.174 +
1.175 + /**
1.176 + Adds data to the internal representation of messages to be hashed.
1.177 + @param aMessage The data to be included in the hash.
1.178 + @param aStatus
1.179 + */
1.180 + IMPORT_C void Update(const TDesC8& aMessage, TRequestStatus& aStatus);
1.181 +
1.182 + /**
1.183 + Produces a final hash value from all the previous updates of data
1.184 + to be hashed.
1.185 + @param aMessage The data to be included in the hash.
1.186 + @param aFinal A descriptor pointer to the buffer containing the hash result.
1.187 + @param aStatus
1.188 + @return A descriptor pointer to the buffer containing the resulting hash.
1.189 + */
1.190 + IMPORT_C void Final(const TDesC8& aMessage, TPtrC8& aFinal, TRequestStatus& aStatus);
1.191 +
1.192 + /**
1.193 + Cancel the outstanding request
1.194 + */
1.195 + IMPORT_C void Cancel();
1.196 +
1.197 + /**
1.198 + Creates a brand new reset CAsyncHash object containing no state
1.199 + information from the current object. This API is only to support
1.200 + the old crypto API for BC reason. It is strongly recommended not to use this API.
1.201 +
1.202 + To make a copy of a message digest with its internal state intact,
1.203 + see CopyL().
1.204 +
1.205 + @return A pointer to the new reset CAsyncHash object.
1.206 + @leave ... Any of the crypto error codes defined in
1.207 + cryptospi_errs.h or any of the system-wide error codes.
1.208 + */
1.209 + IMPORT_C CAsyncHash* ReplicateL();
1.210 +
1.211 + /**
1.212 + Creates a new CAsyncHash object with the exact same state as
1.213 + the current object. This API is only to support
1.214 + the old crypto API for BC reason. It is strongly recommended not to use this API.
1.215 +
1.216 + This function copies all internal state of the message digest.
1.217 + To create a new CAsyncHash object without the state of
1.218 + the current object, see ReplicateL().
1.219 +
1.220 + @return A pointer to the new CAsyncHash object.
1.221 + @leave ... Any of the crypto error codes defined in
1.222 + cryptospi_errs.h or any of the system-wide error codes.
1.223 + */
1.224 + IMPORT_C CAsyncHash* CopyL();
1.225 +
1.226 + /**
1.227 + * @deprecated
1.228 + *
1.229 + * Set the key used for HMAC mode operation.
1.230 + * @param aKey the key for HMAC
1.231 + * @leave KErrArgument if aKey is not of the expected type.
1.232 + * @leave ... Any of the crypto error codes defined in
1.233 + cryptospi_errs.h or any of the system-wide error codes.
1.234 + */
1.235 + IMPORT_C void SetKeyL(const CKey& aKey);
1.236 +
1.237 + /**
1.238 + * @deprecated
1.239 + *
1.240 + * Set the operation mode, ie hash or hmac
1.241 + * @param aOperationMode The UID to identifiy the operation mode
1.242 + * @leave KErrNotSupported if the specified mode is not supported.
1.243 + * @leave ... Any of the crypto error codes defined in
1.244 + cryptospi_errs.h or any of the system-wide error codes.
1.245 + */
1.246 + IMPORT_C void SetOperationModeL(TUid aOperationMode);
1.247 +
1.248 + private:
1.249 +
1.250 + /**
1.251 + Constructor
1.252 + */
1.253 + CAsyncHash(MAsyncHash* aAsyncHash, TInt aHandle);
1.254 + };
1.255 +
1.256 + /**
1.257 + the Factory to create synchronous and asynchronous hash instances
1.258 + */
1.259 + class CHashFactory
1.260 + {
1.261 + public:
1.262 +
1.263 + /**
1.264 + * @deprecated
1.265 + *
1.266 + * Create a CHash instance
1.267 + *
1.268 + * @param aHash The pointer to CHash
1.269 + * @param aAlgorithmUid The specific hash algorithm e.g. MD2, SHA1, MD4
1.270 + * @param aOperationMode The operation mode of the hash e.g. Hash mode, Hmac mode
1.271 + * @param aKey The key for Hmac mode, which should be NULL in Hash mode
1.272 + * @param aAlgorithmParams The parameters that are specific to a particular
1.273 + * algorithm. This is for extendibility and will normally be null.
1.274 + * @return KErrNone if successful; otherwise, a system wide error code.
1.275 + */
1.276 + IMPORT_C static void CreateHashL(CHash*& aHash,
1.277 + TUid aAlgorithmUid,
1.278 + TUid aOperationMode,
1.279 + const CKey* aKey,
1.280 + const CCryptoParams* aAlgorithmParams);
1.281 +
1.282 + /**
1.283 + * @deprecated
1.284 + *
1.285 + * Create a CAsyncHash instance
1.286 + *
1.287 + * @param aAsyncHash The pointer to CAsyncHash
1.288 + * @param aAlgorithmUid The specific hash algorithm e.g. MD2, SHA1, MD4
1.289 + * @param aOperationMode The operation mode of the hash e.g. Hash mode, Hmac mode
1.290 + * @param aKey The key for Hmac mode, which should be NULL in Hash mode
1.291 + * @param aAlgorithmParams The parameters that are specific to a particular
1.292 + * algorithm. This is for extendibility and will normally be null.
1.293 + * @return KErrNone if successful; otherwise, a system wide error code.
1.294 + */
1.295 + IMPORT_C static void CreateAsyncHashL(CAsyncHash*& aAsyncHash,
1.296 + TUid aAlgorithmUid,
1.297 + TUid aOperationMode,
1.298 + const CKey* aKey,
1.299 + const CCryptoParams* aAlgorithmParams);
1.300 +
1.301 +#ifdef SYMBIAN_SDP_IPSEC_VOIP_SUPPORT
1.302 + /**
1.303 + * Create a CHash instance
1.304 + *
1.305 + * @param aHash The pointer to CHash
1.306 + * @param aAlgorithmUid The specific hash algorithm e.g. MD2, SHA1, MD4
1.307 + * @param aAlgorithmParams The parameters that are specific to a particular
1.308 + * algorithm. This is for extendibility and will normally be null.
1.309 + * @return KErrNone if successful; otherwise, a system wide error code.
1.310 + */
1.311 + IMPORT_C static void CreateHashL(CHash*& aHash,
1.312 + TUid aAlgorithmUid,
1.313 + const CCryptoParams* aAlgorithmParams);
1.314 +
1.315 + /**
1.316 + * Create a CAsyncHash instance
1.317 + *
1.318 + * @param aAsyncHash The pointer to CAsyncHash
1.319 + * @param aAlgorithmUid The specific hash algorithm e.g. MD2, SHA1, MD4
1.320 + * @param aAlgorithmParams The parameters that are specific to a particular
1.321 + * algorithm. This is for extendibility and will normally be null.
1.322 + * @return KErrNone if successful; otherwise, a system wide error code.
1.323 + */
1.324 + IMPORT_C static void CreateAsyncHashL(CAsyncHash*& aAsyncHash,
1.325 + TUid aAlgorithmUid,
1.326 + const CCryptoParams* aAlgorithmParams);
1.327 +#endif
1.328 +
1.329 + };
1.330 + }
1.331 +
1.332 +#endif //__CRYPTOAPI_HASHAPI_H__