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 		*/

    93 		IMPORT_C CHash* ReplicateL();		

    94 

    95 		/** 

    96 		Creates a new CHash object with the exact same state as

    97 		the current object.This API is only to support  

    98 		the old crypto API for BC reason. It is strongly recommended not to use this API.

    99 

   100 		This function copies all internal state of the message digest.

   101 		To create a new CHash object without the state of

   102 		the current object, see ReplicateL().

   103 

   104 		@return A pointer to the new CHash object.

   105 		*/

   106 		IMPORT_C CHash* CopyL();

   107 				

   108 		/**

   109 		 * @deprecated

   110 		 * 

   111 		 * Set the key used for HMAC mode operation.

   112 		 * @param aKey	The key for HMAC

   113 		 */

   114 		IMPORT_C void SetKeyL(const CKey& aKey);

   115 			

   116 		/**

   117 		 * @deprecated

   118 		 * 

   119 		 * Set the operation mode, ie hash or hmac

   120 		 * @param aOperationMode	The UID to identifiy the operation mode

   121 		 */		

   122 		IMPORT_C void SetOperationModeL(TUid aOperationMode);

   123 		

   124 	private:

   125 		/**

   126 		Constructor

   127 		*/

   128 		CHash(MHash* aHash, TInt aHandle);

   129 		};

   130 

   131 

   132 	/**

   133 	Asynchronous Hash API, which wraps an asynchronous Hash plugin implementation

   134 	*/

   135 	NONSHARABLE_CLASS(CAsyncHash) : public CCryptoBase

   136 		{

   137 	public:

   138 		/**

   139 		 * @internalComponent

   140 		 * 

   141 		 * Create a CAsyncHash instance from the given MAsyncHash instance

   142 		 * @param aAsyncHash The async hash plugin instance

   143 		 * @return A pointer to a CAsyncHash instance

   144 		 **/

   145 		static CAsyncHash* NewL(MAsyncHash* aAsyncHash, TInt aHandle);

   146 		

   147 		/**

   148 		Destructor

   149 		*/

   150 		IMPORT_C ~CAsyncHash();

   151 		

   152 		/**

   153 		Adds aMessage to the internal representation of data to be hashed,

   154 		then returns a TPtrC8 of the finalised hash of all the previously

   155 		appended messages.

   156 		@param aMessage The data to be included in the hash.

   157 		@param aHash A descriptor pointer to the buffer containing the hash result.

   158 		@param aStatus

   159 		*/

   160 		IMPORT_C void Hash(const TDesC8& aMessage, TPtrC8& aHash, TRequestStatus& aStatus);

   161 

   162 		/**

   163 		Adds data to the internal representation of messages to be hashed.

   164 		@param aMessage	The data to be included in the hash.

   165 		@param aStatus

   166 		*/

   167 		IMPORT_C void Update(const TDesC8& aMessage, TRequestStatus& aStatus);

   168 

   169 		/**

   170 		Produces a final hash value from all the previous updates of data

   171 		to be hashed.

   172 		@param aMessage	The data to be included in the hash.

   173 		@param aFinal A descriptor pointer to the buffer containing the hash result.

   174 		@param aStatus

   175 		@return A descriptor pointer to the buffer containing the resulting hash.

   176 		*/

   177 		IMPORT_C void Final(const TDesC8& aMessage, TPtrC8& aFinal, TRequestStatus& aStatus);

   178 

   179 		/**

   180 		Cancel the outstanding request

   181 		*/

   182 		IMPORT_C void Cancel();

   183 		

   184 		/**

   185 		Creates a brand new reset CAsyncHash object containing no state

   186 		information from the current object. This API is only to support  

   187 		the old crypto API for BC reason. It is strongly recommended not to use this API.

   188 

   189 		To make a copy of a message digest with its internal state intact,

   190 		see CopyL().

   191 

   192 		@return A pointer to the new reset CAsyncHash object.

   193 		*/

   194 		IMPORT_C CAsyncHash* ReplicateL();		

   195 

   196 		/** 

   197 		Creates a new CAsyncHash object with the exact same state as

   198 		the current object. This API is only to support  

   199 		the old crypto API for BC reason. It is strongly recommended not to use this API.

   200 

   201 		This function copies all internal state of the message digest.

   202 		To create a new CAsyncHash object without the state of

   203 		the current object, see ReplicateL().

   204 

   205 		@return A pointer to the new CAsyncHash object.

   206 		*/

   207 		IMPORT_C CAsyncHash* CopyL();

   208 		

   209 		/**

   210 		 * @deprecated

   211 		 * 

   212 		 * Set the key used for HMAC mode operation.

   213 		 * @param aKey the key for HMAC

   214 		 */

   215 		IMPORT_C void SetKeyL(const CKey& aKey);

   216 			

   217 		/**

   218 		 * @deprecated

   219 		 * 

   220 		 * Set the operation mode, ie hash or hmac

   221 		 * @param aOperationMode The UID to identifiy the operation mode

   222 		 */		

   223 		IMPORT_C void SetOperationModeL(TUid aOperationMode);

   224 		

   225 	private:

   226 		

   227 		/**

   228 		Constructor

   229 		*/

   230 		CAsyncHash(MAsyncHash* aAsyncHash, TInt aHandle);

   231 		};

   232 

   233 	/**

   234 	the Factory to create synchronous and asynchronous hash instances

   235 	*/

   236 	class CHashFactory

   237 		{

   238 	public:

   239 

   240 		/**

   241 		 * @deprecated

   242 		 * 

   243 		 * Create a CHash instance

   244 		 * 

   245 		 * @param aHash 			The pointer to CHash

   246 		 * @param aAlgorithmUid 	The specific hash algorithm e.g. MD2, SHA1, MD4

   247 		 * @param aOperationMode 	The operation mode of the hash e.g. Hash mode, Hmac mode

   248 		 * @param aKey 				The key for Hmac mode, which should be NULL in Hash mode

   249 		 * @param aAlgorithmParams 	The parameters that are specific to a particular 

   250 		 * 							algorithm. This is for extendibility and will normally be null.

   251 		 * @return 					KErrNone if successful; otherwise, a system wide error code.

   252 		 */

   253 		IMPORT_C static void CreateHashL(CHash*& aHash,

   254 										TUid aAlgorithmUid,

   255 										TUid aOperationMode,

   256 										const CKey* aKey,

   257 										const CCryptoParams* aAlgorithmParams);

   258 

   259 		/**

   260 		 * @deprecated

   261 		 * 

   262 		 * Create a CAsyncHash instance

   263 		 * 	

   264 		 * @param aAsyncHash 		The pointer to CAsyncHash

   265 		 * @param aAlgorithmUid 	The specific hash algorithm e.g. MD2, SHA1, MD4

   266 		 * @param aOperationMode 	The operation mode of the hash e.g. Hash mode, Hmac mode

   267 		 * @param aKey 				The key for Hmac mode, which should be NULL in Hash mode

   268 		 * @param aAlgorithmParams 	The parameters that are specific to a particular 

   269 		 * 							algorithm. This is for extendibility and will normally be null.

   270 		 * @return 					KErrNone if successful; otherwise, a system wide error code.

   271 		 */

   272 		IMPORT_C static void CreateAsyncHashL(CAsyncHash*& aAsyncHash, 

   273 										TUid aAlgorithmUid,

   274 										TUid aOperationMode,

   275 										const CKey* aKey,

   276 										const CCryptoParams* aAlgorithmParams);

   277 

   278 #ifdef SYMBIAN_SDP_IPSEC_VOIP_SUPPORT		

   279 		/**

   280 		 * Create a CHash instance

   281 		 * 

   282 		 * @param 	aHash The pointer to CHash

   283 		 * @param 	aAlgorithmUid The specific hash algorithm e.g. MD2, SHA1, MD4

   284 		 * @param 	aAlgorithmParams The parameters that are specific to a particular 

   285 		 * 			algorithm. This is for extendibility and will normally be null.

   286 		 * @return 	KErrNone if successful; otherwise, a system wide error code.

   287 		 */

   288 		IMPORT_C static void CreateHashL(CHash*& aHash,

   289 										 TUid aAlgorithmUid,

   290 										 const CCryptoParams* aAlgorithmParams);

   291 

   292 		/**

   293 		 * Create a CAsyncHash instance

   294 		 * 	

   295 		 * @param 	aAsyncHash The pointer to CAsyncHash

   296 		 * @param 	aAlgorithmUid The specific hash algorithm e.g. MD2, SHA1, MD4

   297 		 * @param 	aAlgorithmParams The parameters that are specific to a particular 

   298 		 * 			algorithm. This is for extendibility and will normally be null.

   299 		 * @return 	KErrNone if successful; otherwise, a system wide error code.

   300 		 */

   301 		IMPORT_C static void CreateAsyncHashL(CAsyncHash*& aAsyncHash, 

   302 										      TUid aAlgorithmUid,

   303 										      const CCryptoParams* aAlgorithmParams);

   304 #endif	

   305 		

   306 		};

   307 	}

   308 

   309 #endif //__CRYPTOAPI_HASHAPI_H__