1 /*

     2 * Copyright (c) 2000-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 * ** IMPORTANT ** PublishedPartner API's in this file are published to 3rd party developers via the 

    16 * Symbian website. Changes to these API's should be treated as PublishedAll API changes and the Security TA should be consulted.

    17 * This header contains the definition of the message digest classes

    18 *

    19 */

    20 

    21 

    22 /**

    23  @file 

    24  @publishedAll

    25  @released

    26 */

    27 

    28 #ifndef __HASH_H__

    29 #define __HASH_H__

    30 

    31 #include <e32base.h>

    32 

    33 /**

    34  * Base class for message digests.

    35  */

    36 class CMessageDigest:public CBase

    37 	{

    38 	public:

    39 	/**

    40 	 *	Enumeration to identify hash functions (aka message-digest algorithms).

    41 	 */

    42 	enum THashId

    43 	{

    44 		/** 

    45 		 * Message Digest algorithm developed by Rivest for digital signature

    46 		 * applications (and optimized for 8-bit machines). 

    47 		 * 

    48 		 * Takes a message of arbitrary length and produces a 128-bit message digest. 

    49 		 *

    50 		 * See RFC 1319

    51 		 */

    52 		EMD2,

    53 		/** 

    54 		 * Message Digest algorithm developed by Rivest for digital signature

    55 		 * applications (and optimized for 32-bit machines). 

    56 		 * 

    57 		 * Takes a message of arbitrary length and produces a 128-bit message digest. 

    58 		 * 

    59 		 * See RFC 1321

    60 		 */

    61 		EMD5,

    62 		/** 

    63 		 * Secure Hash Algorithm (version 1) is a message digest algorithm developed by 

    64 		 * NIST, along with the NSA, for use with the Digital Signature Standard (DSS).

    65 		 * 

    66 		 * It takes a message of less than 2^64 bits in length and produces

    67 		 * a 160-bit message digest.

    68 		 *

    69 		 * See FIPS 180-1 and RFC 3174

    70 		 */

    71 		ESHA1,

    72 		/** 

    73 		 * HMAC - Hash function based Message Authentication Code is a mechanism

    74 		 * for message authentication using cryptographic hash functions. (A checksum.)

    75 		 * 

    76 		 * It can be used with any iterative cryptographic hash function,

    77    		 * e.g., MD5, SHA-1, in combination with a secret shared key

    78    		 * to produce a checksum that is appended to the message.

    79    		 * The cryptographic strength of HMAC depends on the properties

    80    		 * of the underlying hash function.

    81 		 *

    82 		 * See RFC 2104 

    83 		 */

    84 		HMAC,

    85 		/** 

    86 		 * Message Digest algorithm developed by Rivest for digital signature

    87 		 * applications (and optimized for 32-bit machines). 

    88 		 * 

    89 		 * Takes a message of arbitrary length and produces a 128-bit message digest. 

    90 		 * 

    91 		 * See RFC 1320

    92 		 */

    93 		EMD4,

    94 		/** 

    95 		 * Secure Hash Algorithm - 224 (version 2) is a message digest algorithm developed by 

    96 		 * NIST, along with the NSA, for use with the Digital Signature Standard (DSS).

    97 		 * 

    98 		 * It takes a message of less than 2^64 bits in length and produces

    99 		 * a 224-bit message digest.

   100 		 *

   101 		 * See FIPS 180-2 (with change notice), RFC3874 and FIPS 180-3

   102 		 */

   103 		ESHA224,

   104 		/** 

   105 		 * Secure Hash Algorithm - 256 (version 2) is a message digest algorithm developed by 

   106 		 * NIST, along with the NSA, for use with the Digital Signature Standard (DSS).

   107 		 * 

   108 		 * It takes a message of less than 2^64 bits in length and produces

   109 		 * a 256-bit message digest.

   110 		 *

   111 		 * See FIPS 180-2 and RFC 4634

   112 		 */

   113 		ESHA256,

   114 		/** 

   115 		 * Secure Hash Algorithm - 384 (version 2) is a message digest algorithm developed by 

   116 		 * NIST, along with the NSA, for use with the Digital Signature Standard (DSS).

   117 		 * 

   118 		 * It takes a message of less than 2^128 bits in length and produces

   119 		 * a 384-bit message digest.

   120 		 *

   121 		 * See FIPS 180-2 and RFC 4634

   122 		 */

   123 		ESHA384,

   124 		/** 

   125 		 * Secure Hash Algorithm - 512 (version 2) is a message digest algorithm developed by 

   126 		 * NIST, along with the NSA, for use with the Digital Signature Standard (DSS).

   127 		 * 

   128 		 * It takes a message of less than 2^128 bits in length and produces

   129 		 * a 512-bit message digest.

   130 		 *

   131 		 * See FIPS 180-2 and RFC 4634

   132 		 */

   133 		ESHA512

   134 	};

   135 	

   136 	public:

   137 		/** 

   138 		 * Creates a brand new reset CMessageDigest object containing no state

   139 		 * information from the current object.  

   140 		 * 

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

   142 		 * see CopyL().

   143 		 *

   144 		 * @return A pointer to the new reset CMessageDigest object

   145 		 */

   146 		IMPORT_C virtual CMessageDigest* ReplicateL(void)=0;		

   147 

   148 		/** 

   149 		 * Adds aMessage to the internal representation of data to be hashed,

   150 		 * then returns a TPtrC8 of the finalised hash of all the previously

   151 		 * appended messages.

   152 		 * 

   153 		 * @param aMessage	Data to be included in the hash.

   154 		 * @return			A descriptor pointer to the buffer containing the

   155 		 *					resulting hash.

   156 		 */

   157 		IMPORT_C virtual TPtrC8 Hash(const TDesC8& aMessage)=0;

   158 

   159 		/** 

   160 		 * Creates a new CMessageDigest object with the exact same state as

   161 		 * the current object.  

   162 		 *

   163 		 * This function copies all internal state of the message digest.

   164 		 * To create a new CMessageDigest object without the state of

   165 		 * the current object, see ReplicateL().

   166 		 *

   167 		 * @return A pointer to the new CMessageDigest object

   168 		 */

   169 		IMPORT_C virtual CMessageDigest* CopyL(void)=0;

   170 		

   171 		/** 

   172 		 * Gets the internal block size of the message digest.

   173 		 * 

   174 		 * @return	Internal block size of message digest in bytes.

   175 		 */

   176 		IMPORT_C virtual TInt BlockSize(void)=0;

   177 		

   178 		/** 

   179 		 * Gets the size of the message digest output.

   180 		 *

   181 		 * @return	Output size of the message digest in bytes.

   182 		 */

   183 		IMPORT_C virtual TInt HashSize(void)=0;

   184 		

   185 		/** 

   186 		 * Resets the internal state of the message digest.  

   187 		 *

   188 		 * A reset hash object loses all internal state representing the hashed

   189 		 * data. A reset message digest is suitable to begin a new, distinct hash

   190 		 * of different data.  Any previously returned TPtrC8 from a call to

   191 		 * Final() remains valid until any subsequent call to Update() or

   192 		 * Final().

   193 		 */

   194 		IMPORT_C virtual void Reset(void)=0;

   195 		

   196 		/**

   197 		 * Destructor.

   198 		 */		

   199 		IMPORT_C ~CMessageDigest(void);

   200 	public:

   201 		/** 

   202 		 * Adds data to the internal representation of messages to be hashed.

   203 		 *

   204 		 * @param aMessage	Data to be included in the hash.

   205 		 * @since v8.0

   206 		 */

   207 		IMPORT_C virtual void Update(const TDesC8& aMessage)=0;

   208 		

   209 		/** 

   210 		 * Adds aMessage to the internal representation of data to be hashed,

   211 		 * returns a TPtrC8 of the finalised hash of all the previously

   212 		 * appended messages, and calls Reset().

   213 		 * 

   214 		 * @param aMessage	Data to be included in the hash 

   215 		 * @return			A descriptor pointer to the buffer containing the

   216 		 *					resulting hash.

   217 		 * @since v8.0

   218 		 */

   219 		IMPORT_C virtual TPtrC8 Final(const TDesC8& aMessage)=0;

   220 		

   221 		/** 

   222 		 * Gets a TPtrC8 of the finalised hash of all the previously

   223 		 * appended messages and then calls Reset().

   224 		 * 

   225 		 * @return	A descriptor pointer to the buffer containing the

   226 		 * 			resulting hash.

   227 		 * @since v8.0

   228 		 */

   229 		IMPORT_C virtual TPtrC8 Final(void)=0;

   230 	public:

   231 		/**

   232 		 * Restores the internal state of the message digest

   233 		 * to a previously stored state.

   234 		 *

   235 		 * @see StoreState()

   236 		 */

   237 		virtual void RestoreState() = 0;

   238 

   239 		/**

   240 		 * Stores the internal state of the message digest. 

   241 		 */

   242 		virtual void StoreState() = 0;

   243 

   244 		/**

   245 		@internalComponent

   246 		Used to retrieve the extended interfaces extension

   247 		*/		

   248 		TInt GetExtension(TUint aExtensionId, TAny*& a0, TAny* a1);		

   249 

   250 	protected:

   251 		/**

   252 		 * Constructor

   253 		 */

   254 		IMPORT_C CMessageDigest(void);

   255 

   256 		/**

   257 		 * Copy constructor

   258 		 *

   259 		 * @param aMD	A CMessageDigest object

   260 		 */

   261 		IMPORT_C CMessageDigest(const CMessageDigest& aMD);

   262 	};

   263 

   264 /** 

   265 The MD2 block size (in bytes) 

   266 */

   267 const TInt MD2_BLOCK=16;

   268 

   269 /** 

   270 The size (in bytes) of the MD2 message digest 

   271 */

   272 const TInt MD2_HASH=16;

   273 

   274 /**

   275  * An MD2 message digest

   276  */

   277 class CMD2:public CMessageDigest

   278 

   279 	{

   280 	public:

   281 		/**

   282 		 * Creates a new MD2 object.

   283 		 *

   284 		 * @return	A pointer to the new CMD2 object

   285 		 */

   286 		IMPORT_C static CMD2* NewL(void);

   287 		IMPORT_C CMessageDigest* ReplicateL(void);

   288 		IMPORT_C TPtrC8 Hash(const TDesC8& aMessage);

   289 		/** Destructor */

   290 		IMPORT_C ~CMD2(void);

   291 		IMPORT_C CMessageDigest* CopyL(void);

   292 		IMPORT_C TInt BlockSize(void);

   293 		IMPORT_C TInt HashSize(void);

   294 		IMPORT_C void Reset(void);

   295 		IMPORT_C void Update(const TDesC8& aMessage);

   296 		IMPORT_C TPtrC8 Final(const TDesC8& aMessage);

   297 		IMPORT_C TPtrC8 Final();

   298 	public:

   299 		void RestoreState();

   300 		void StoreState();

   301 	protected:	

   302 		/** @internalComponent */

   303 		CMD2(void);

   304 	};

   305 

   306 /** 

   307 The MD5 block size (in bytes)

   308 */

   309 const TUint MD5_LBLOCK=16;

   310 

   311 /** 

   312 The size (in bytes) of the MD5 message digest 

   313 */

   314 const TUint MD5_HASH=16;

   315 

   316 /**

   317  * An MD5 message digest

   318  *

   319  * Takes a message of arbitrary length as input and produces a 128-bit message digest. 

   320  * 

   321  * The total input length of data should not be longer than 2^32 in bits(2^31 in bytes)

   322  * which is roughly half a gig.

   323  *

   324  */

   325 class CMD5:public CMessageDigest

   326 	{

   327 	public:

   328 		/**

   329 		 * Creates a new MD5 object.

   330 		 *

   331 		 * @return	A pointer to the new CMD5 object

   332 		 */

   333 		IMPORT_C static CMD5* NewL(void);

   334 		IMPORT_C CMessageDigest* ReplicateL(void);

   335 		IMPORT_C TPtrC8 Hash(const TDesC8& aMessage);

   336 		/** Destructor */

   337 		IMPORT_C ~CMD5(void);

   338 		IMPORT_C CMessageDigest* CopyL(void);

   339 		IMPORT_C TInt BlockSize(void);

   340 		IMPORT_C TInt HashSize(void);

   341 		IMPORT_C void Reset(void);

   342 		IMPORT_C void Update(const TDesC8& aMessage);

   343 		IMPORT_C TPtrC8 Final(const TDesC8& aMessage);

   344 		IMPORT_C TPtrC8 Final();

   345 	public:

   346 		void RestoreState();

   347 		void StoreState();

   348 	protected:

   349 		/** @internalComponent */

   350 		CMD5(void);

   351 	};

   352 

   353 

   354 /** 

   355 The SHA-1 block size (in bytes) 

   356 */

   357 const TUint SHA1_LBLOCK=16;

   358 

   359 /** 

   360 The size (in bytes) of the SHA-1 message digest 

   361 */

   362 const TUint SHA1_HASH=20;

   363 

   364 /** 

   365 The size (in bytes) of the SHA message digest 

   366 */

   367 const TUint SHA_HASH=SHA1_HASH;

   368 

   369 /**

   370  * A SHA-1 message digest

   371  */

   372 class CSHA1:public CMessageDigest

   373 	{

   374 	public:

   375 		/**

   376 		 * Creates a new SHA-1 object.

   377 		 *

   378 		 * @return	A pointer to the new SHA-1 object

   379 		 */

   380 		IMPORT_C static CSHA1* NewL(void);

   381 		IMPORT_C CMessageDigest* ReplicateL(void);

   382 		IMPORT_C TPtrC8 Hash(const TDesC8& aMessage);

   383 		/** Destructor */

   384 		IMPORT_C ~CSHA1(void);

   385 		IMPORT_C CMessageDigest* CopyL(void);

   386 		IMPORT_C TInt BlockSize(void);

   387 		IMPORT_C TInt HashSize(void);

   388 		IMPORT_C void Reset(void);

   389 		IMPORT_C void Update(const TDesC8& aMessage);

   390 		IMPORT_C TPtrC8 Final(const TDesC8& aMessage);

   391 		IMPORT_C TPtrC8 Final();

   392 	public:

   393 		void RestoreState();

   394 		void StoreState();

   395 	protected:

   396 		/** @internalComponent */

   397 		CSHA1(void);

   398 	};

   399 

   400 enum TSH2Algo

   401 	{

   402 	E224Bit,

   403 	E256Bit,

   404 	E384Bit,

   405 	E512Bit

   406 	};

   407 	

   408 /**

   409  * A SHA-2 message digest

   410  * 

   411  * SHA-2 is comprised of SHA-224, SHA256, SHA384 and SHA512

   412  */

   413 class CSHA2 : public CMessageDigest

   414 	{

   415 	public:

   416 		/**

   417 		 * Creates a new SHA-1 object.

   418 		 *

   419 		 * @return	A pointer to the new SHA-1 object

   420 		 */

   421 		IMPORT_C static CSHA2* NewL(TSH2Algo aAlgorithmId);

   422 		IMPORT_C static CSHA2* NewLC(TSH2Algo aAlgorithmId);

   423 		/** Destructor */

   424 		IMPORT_C ~CSHA2(void);

   425 	public:

   426 		void RestoreState();

   427 		void StoreState();		

   428 	protected:

   429 		/** @internalComponent */

   430 		CSHA2(void);

   431 	};	

   432 

   433 

   434 /**

   435  * A SHA message digest

   436  *

   437  * @deprecated Replaced by CSHA1

   438  */

   439 class CSHA:public CMessageDigest

   440 	{

   441 	public:

   442 		/**

   443 		 * Creates a new SHA object.

   444 		 *

   445 		 * @return	A pointer to the new SHA object

   446 		 */

   447 		IMPORT_C static CSHA* NewL(void);

   448 		IMPORT_C CMessageDigest* ReplicateL(void);

   449 		IMPORT_C TPtrC8 Hash(const TDesC8& aMessage);

   450 		/** Destructor */

   451 		IMPORT_C ~CSHA(void);

   452 		IMPORT_C CMessageDigest* CopyL(void);

   453 		IMPORT_C TInt BlockSize(void);

   454 		IMPORT_C TInt HashSize(void);

   455 		IMPORT_C void Reset(void);

   456 		IMPORT_C void Update(const TDesC8& aMessage);

   457 		IMPORT_C TPtrC8 Final(const TDesC8& aMessage);

   458 		IMPORT_C TPtrC8 Final();

   459 	public:

   460 		void RestoreState();

   461 		void StoreState();

   462 	};

   463 

   464 /**

   465  * This is the maximum block size currently supported by HMAC implementation.

   466  */ 

   467 const TUint KMaxBlockSize=128;

   468 

   469 /**

   470  * An HMAC (Hashed Message Authentication Code)

   471  */

   472 class CHMAC:public CMessageDigest

   473 

   474 	{

   475 	public:

   476 		/**

   477 		 * Creates a new HMAC object from a specified type of message digest 

   478 		 * and authentication key.

   479 		 * 

   480 		 * @param aKey		Authentication key.

   481 		 * @param aDigest	A message digest to construct the HMAC from.

   482 		 * @return			A pointer to the new CHMAC object. 

   483 		 *					The resulting HMAC object takes ownership of aDigest

   484 		 *					and is responsible for its deletion.

   485 		 */

   486 		IMPORT_C static CHMAC* NewL(const TDesC8& aKey,CMessageDigest* aDigest);

   487 		IMPORT_C CMessageDigest* ReplicateL(void);

   488 		IMPORT_C TPtrC8 Hash(const TDesC8& aMessage);

   489 		/** Destructor */

   490 		IMPORT_C ~CHMAC(void);

   491 		IMPORT_C CMessageDigest* CopyL(void);

   492 		IMPORT_C TInt BlockSize(void);

   493 		IMPORT_C TInt HashSize(void);

   494 		IMPORT_C void Reset(void);

   495 		IMPORT_C void Update(const TDesC8& aMessage);

   496 		IMPORT_C TPtrC8 Final(const TDesC8& aMessage);

   497 		IMPORT_C TPtrC8 Final();

   498 	public:

   499 		void RestoreState();

   500 		void StoreState();

   501 	protected:

   502 		/** @internalComponent */

   503 		CHMAC(void);

   504 		/** @internalComponent */

   505 		CHMAC(CMessageDigest* aDigest);

   506 		/** @internalComponent */

   507 		CHMAC(const CHMAC& aHMAC);

   508 		/** @internalComponent */

   509 		void InitialiseL(const TDesC8& aKey);

   510 		

   511 	private:

   512 		void InitBlockSizeL();

   513 

   514 	private:

   515 		CMessageDigest* iDigest;

   516 		TBuf8<KMaxBlockSize> iInnerPad;

   517 		TBuf8<KMaxBlockSize> iOuterPad;

   518 		TBuf8<KMaxBlockSize> iInnerPadCopy;

   519 		TBuf8<KMaxBlockSize> iOuterPadCopy;		

   520 		TInt iBlockSize;

   521 

   522 	};

   523 

   524 /** 

   525 The MD4 block size (in bytes)

   526 */

   527 const TUint MD4_LBLOCK=16;

   528 

   529 /** 

   530 The size (in bytes) of the MD4 message digest 

   531 */

   532 const TUint MD4_HASH=16;

   533 

   534 /**

   535  * An MD4 message digest Algorithm.

   536  * Takes a message of arbitrary length as input and produces a 128-bit message digest. 

   537  * 

   538  * The total input length of data should not be longer than 2^32 in bits(2^31 in bytes)

   539  * which is roughly half a gig.

   540  *

   541  */

   542 class CMD4:public CMessageDigest

   543 	{

   544 	public:

   545 		/**

   546 		 * Creates a new MD4 object.

   547 		 *

   548 		 * @return	A pointer to the new CMD4 object

   549 		 */

   550 		IMPORT_C static CMD4* NewL(void);

   551 		IMPORT_C CMessageDigest* ReplicateL(void);

   552 		IMPORT_C TPtrC8 Hash(const TDesC8& aMessage);

   553 		/** Destructor */

   554 		IMPORT_C ~CMD4(void);

   555 		IMPORT_C CMessageDigest* CopyL(void);

   556 		IMPORT_C TInt BlockSize(void);

   557 		IMPORT_C TInt HashSize(void);

   558 		IMPORT_C void Reset(void);

   559 		IMPORT_C void Update(const TDesC8& aMessage);

   560 		IMPORT_C TPtrC8 Final(const TDesC8& aMessage);

   561 		IMPORT_C TPtrC8 Final();

   562 	public:

   563 		virtual void RestoreState();

   564 		virtual void StoreState();

   565 	protected:

   566 		/** @internalComponent */

   567 		CMD4(void);

   568 	};

   569 

   570 

   571 /**

   572  *	Factory to create a CMessageDigest derived object according to the identity of the hash algorithm.

   573  */

   574 class CMessageDigestFactory : public CBase

   575 {

   576 public:

   577 	/**

   578 	 *Creates a CMessageDigest derived object according to the specified type of hash algorithm.

   579 	 *

   580 	 * @param aHashId	The identity of the hash algorithm

   581 	 * @return			A pointer to a CMessageDigest object

   582 	 */

   583 	IMPORT_C static CMessageDigest* NewDigestL(CMessageDigest::THashId aHashId);

   584 

   585 	/**

   586 	 * Creates a CMessageDigest derived object according to the specified type of hash algorithm.

   587 	 * 

   588 	 * The returned pointer is put onto the cleanup stack.

   589 	 *

   590 	 * @param aHashId	The identity of the hash algorithm

   591 	 * @return			A pointer to a CMessageDigest object

   592 	 */

   593 	IMPORT_C static CMessageDigest* NewDigestLC(CMessageDigest::THashId aHashId);

   594 

   595 	/**

   596 	 * Creates a CMessageDigest derived object according to the specified type of hash algorithm

   597 	 * and authentication key.

   598 	 *

   599 	 * @param aHashId	The identity of the hash algorithm

   600 	 * @param aKey		The authentication key 

   601 	 * @return			A pointer to a CMessageDigest object

   602 	 */

   603 	IMPORT_C static CMessageDigest* NewHMACL(CMessageDigest::THashId aHashId, const TDesC8& aKey);

   604 

   605 	/**

   606 	 * Creates a CMessageDigest derived object according to the specified type of hash algorithm

   607 	 * and authentication key.

   608 	 * 

   609 	 * The returned pointer is put onto the cleanup stack.

   610 	 *

   611 	 * @param aHashId	The identity of the hash algorithm

   612 	 * @param aKey		The authentication key 

   613 	 * @return			A pointer to a CMessageDigest object

   614 	 */

   615 	IMPORT_C static CMessageDigest* NewHMACLC(CMessageDigest::THashId aHashId, const TDesC8& aKey);

   616 };

   617 

   618 #endif // __HASH_H__