/*

 * Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).

 * All rights reserved.

 * This component and the accompanying materials are made available

 * under the terms of the License "Eclipse Public License v1.0"

 * which accompanies this distribution, and is available

 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

 *

 * Initial Contributors:

 * Nokia Corporation - initial contribution.

 *

 * Contributors:

 *

 * Description: 

 * crypto MAC application interface 

 *

 */

 /**

  @file

  @publishedAll

  @released

 */

 #ifndef __CRYPTOAPI_MACAPI_H__

 #define __CRYPTOAPI_MACAPI_H__

 #include <e32base.h>

 #include <cryptospi/cryptobaseapi.h>

 namespace CryptoSpi

 	{

 	class MPlugin;

 	class CCryptoParams;

 	class CKey;

 	class MMac;

 	class MAsyncMac;

 	/**

 	 * Mac API, which wraps a synchronous Mac plugin implementation

 	 * This Mac interface helps the client application to get the message 

 	 * authentication code value of a given message which provides

 	 * data integrity and data origin authentication. These two goals are 

 	 * dependent upon the scope of the distribution of the secret key.

 	 */

 	NONSHARABLE_CLASS(CMac) : public CCryptoBase

 		{

 	public:

 		/**

 		 * @internalComponent

 		 * Create a CMac instance from the given MMac instance

 		 *

 		 * @param aMac  	The mac plugin instance

 		 * @param aHandle	The current plugin DLL loaded.

 		 * @return      	pointer to a CMac instance

 		 */

 		static CMac* NewL(MMac* aMac, TInt aHandle);

 		/**

 		 * Adds message to the internal representation of data for which the MAC value

 		 * needs to be evaluated and then returns a TPtrC8 of the finalised MAC value 

 		 * of all the previously appended messages. 

 		 * 

 		 * @param aMessage  The data for which MAC value is to be evaluated.

 		 * @return          A descriptor pointer to the buffer containing the

 		 *                  resulting MAC value.

 		 * @leave ...		Any of the crypto error codes defined in 

   							cryptospi_errs.h or any of the system-wide error codes.

 		 */

 		IMPORT_C TPtrC8 MacL(const TDesC8& aMessage);    

         /**

          * Adds data to the internal representation of messages for which the MAC value

 		 * needs to be evaluated.

          * 

          * @param aMessage	The data to be included in the MAC evaluation.

 		 * @leave ...		Any of the crypto error codes defined in 

   							cryptospi_errs.h or any of the system-wide error codes.

          */

 		IMPORT_C void UpdateL(const TDesC8& aMessage);

         /**

          * Produces a final MAC value from all the previous updates of data to be MACed. 

          * It resets the MAC algorithm in a state similar to creating a new MAC instance

          * with the same underlying algorithm and supplied symmetric key.

          *   

          * @param aMessage	The data to be included in the MAC evaluation.

 		 * @return          A descriptor pointer to the buffer containing the

 		 *                  resulting MAC value.

 		 * @leave ...		Any of the crypto error codes defined in 

   							cryptospi_errs.h or any of the system-wide error codes.

 		 */

 		IMPORT_C TPtrC8 FinalL(const TDesC8& aMessage);

 		/**

 		 * This re-initialises the underlying MAC algorithm with a new symmetric key. 

          * It resets the MAC algorithm in a state similar to creating a new MAC instance

          * with the same underlying algorithm but a new symmetric key.

 		 *

 		 * @param aKey  Symmetric key for calculating message authentication code value. 

 		 * @leave ...		Any of the crypto error codes defined in 

   							cryptospi_errs.h or any of the system-wide error codes.

 		 */

 		IMPORT_C void ReInitialiseAndSetKeyL(const CKey& aKey);    

 		/**

 		 * Creates a brand new reset CMac object containing no state

 		 * information from the current object.  

 		 * 

 		 * @return 	A pointer to the new reset CMac object

 		 * @leave ...		Any of the crypto error codes defined in 

   							cryptospi_errs.h or any of the system-wide error codes.

 		 */

 		IMPORT_C CMac* ReplicateL();		

 		/** 

 		 * Creates a new CMac object with the exact same state as

 		 * the current object.  

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

 		 * 

 		 * @return 	A pointer to the new CMac object

 		 * @leave ...		Any of the crypto error codes defined in 

   							cryptospi_errs.h or any of the system-wide error codes.

 		 */

 		IMPORT_C CMac* CopyL();

 		/**

 		 * This destructor is exported so that the client application after using

 		 * a specific plug-in implementation can destroy its instance. Both the framework 

 		 * and the plug-in use/derived from the same interface 'MPlugin. 

 		 * By exporting the destructor we are destroying the plug-in instance at

 		 * client side via the CryptoSPI framework.

 		 */

 		IMPORT_C ~CMac();

 	private:

 		/**

 		 * The constructor of this class is private. An user application will use

 		 * CMacFactory::CreateMacL for the object's initialisation.

 		 * 

 		 * @param aMac 		The mac plug-in instance

 		 * @param aHandle   The current plug-in DLL loaded

 		 */

 		CMac(MMac* aMac, TInt aHandle);

 		};

 	/**

 	 * This is the asynchronous version of CMac class typically used by the 

 	 * client applications if hardware plug-in implementation of 

 	 * the MAC interface is present. 	

 	 */

 	NONSHARABLE_CLASS(CAsyncMac) : public CCryptoBase

 		{

 	public:

 		/**

 		 * @internalComponent

 		 * Create a CAsyncMac instance from the given MAsyncMac instance

 		 *

 		 * @param aMac  The mac plugin instance

 		 * @param aHandle	The current plugin DLL loaded.

 		 * @return      pointer to a CMac instance

 		 */

 		static CAsyncMac* NewL(MAsyncMac* aMac, TInt aHandle);

 		/**

 		 * Adds message to the internal representation of data for which the MAC value

 		 * needs to be evaluated and then returns a TPtrC8 of the finalised MAC value 

 		 * of all the previously appended messages. 

 		 * 

 		 * @param aMessage  The data for which MAC value is to be evaluated.

 		 * @param aStatus   Holds the completion status of an asynchronous

 		 * 					request for MAC evaluation.

 		 * @return          A descriptor pointer to the buffer containing the

 		 *                  resulting MAC value.

 		 * @leave ...		Any of the crypto error codes defined in 

   							cryptospi_errs.h or any of the system-wide error codes.

 		 */

 		IMPORT_C TPtrC8 MacL(const TDesC8& aMessage, TRequestStatus& aStatus);    

         /**

          * Adds data to the internal representation of messages for which the MAC value

 		 * needs to be evaluated.

          * 

          * @param aMessage	The data to be included in the MAC evaluation.

 		 * @param aStatus   Holds the completion status of an asynchronous

 		 * 					request for MAC evaluation.

 		 * @leave ...		Any of the crypto error codes defined in 

   							cryptospi_errs.h or any of the system-wide error codes.

          */

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

 		/**

          * Produces a final MAC value from all the previous updates of data to be MACed. 

          * It resets the MAC algorithm in a state similar to creating a new MAC instance

          * with the same underlying algorithm and supplied symmetric key.

          *  

          * @param aMessage	The data to be included in the MAC evaluation.

 		 * @param aStatus   Holds the completion status of an asynchronous

 		 * 					request for MAC evaluation.

 		 * @return          A descriptor pointer to the buffer containing the

 		 *                  resulting MAC value.

 		 * @leave ...		Any of the crypto error codes defined in 

   							cryptospi_errs.h or any of the system-wide error codes.

 		 */

 		IMPORT_C TPtrC8 FinalL(const TDesC8& aMessage, TRequestStatus& aStatus);

 		/**

 		 * This re-initialises the underlying MAC algorithm with a new symmetric key. 

          * It resets the MAC algorithm in a state similar to creating a new MAC instance

          * with the same underlying algorithm but a new symmetric key.

 		 *

 		 * @param aKey  Symmetric key for calculating message authentication code value. 

 		 * @leave ...		Any of the crypto error codes defined in 

   							cryptospi_errs.h or any of the system-wide error codes.

 		 */

 		IMPORT_C void ReInitialiseAndSetKeyL(const CKey& aKey);    

 		/**

 		 * Creates a brand new reset CAsyncMac object containing no state

 		 * information from the current object.  

 		 * 

 		 * @return	A pointer to the new reset CAsyncMac object

 		 * @leave ...		Any of the crypto error codes defined in 

   							cryptospi_errs.h or any of the system-wide error codes.

 		 */

 		IMPORT_C CAsyncMac* ReplicateL();		

 		/** 

 		 * Creates a new CAsyncMac object with the exact same state as

 		 * the current object.  

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

 		 * 

 		 * @return	A pointer to the new CAsyncHash object

 		 * @leave ...		Any of the crypto error codes defined in 

   							cryptospi_errs.h or any of the system-wide error codes.

 		 */

 		IMPORT_C CAsyncMac* CopyL();

 		/**

 		 * Cancels an outstanding request from the client.

 		 */

 		IMPORT_C void Cancel();

 		/**

 		 * This destructor is exported so that the client application after using

 		 * a specific plug-in implementation can destroy its instance. Both the framework 

 		 * and the plug-in use/derived from the same interface 'MPlugin. 

 		 * By exporting the destructor we are destroying the plug-in instance at

 		 * client side via the CryptoSPI framework.

 		 */

 		IMPORT_C ~CAsyncMac();

 	private:

 		/**

 		 * The constructor of this class is private. An user application will use

 		 * CMacFactory::CreateAsyncMacL for the object's initialisation.

 		 * 

 		 * @param aMac 		The mac plug-in instance

 		 * @param aHandle   The current plug-in DLL loaded

 		 */

 		CAsyncMac(MAsyncMac* aMac, TInt aHandle);

 		};

 	/**

 	 * The Factory to create synchronous and asynchronous Mac instances

 	 */

 	class CMacFactory

 		{

 	public:

 		/**

 		 * Create a CMac instance (for software based MAC plug-in dll implementation)

 		 *

 		 * @param aMac           	The pointer to CMac. This will be initialised with 

 		 * 						  	the plug-in implementation of the desired MAC algorithm.

 		 * @param aAlgorithmUid  	The specific MAC algorithm desired for evaluation of MAC value.

 		 *                       	e.g. MD2, SHA1 or AES-XCBC-MAC-96, AES-XCBC-PRF-128

 		 * @param aKey           	Symmetric key for calculating message authentication code value. 

 		 * @param aAlgorithmParams  The parameters those are specific to a particular MAC algorithm.

 		 * 							This is for extendibility and will normally be null.                     	

 		 * @leave               	KErrNone if successful; otherwise, leaves with a system wide error code.

 		 */

 		IMPORT_C static void CreateMacL(CMac*& aMac,

 										const TUid aAlgorithmUid,

 										const CKey& aKey,

 										const CCryptoParams* aAlgorithmParams);

 		/**

 		 * Create a CAsyncMac instance (for hardware based MAC plug-in dll implementation)

 		 *

 		 * @param aMac           	The pointer to CMac. This will be initialised with 

 		 * 						  	the plug-in implementation of the desired MAC algorithm.

 		 * @param aAlgorithmUid  	The specific MAC algorithm desired for evaluation of MAC value.

 		 *                       	e.g. MD2, SHA1 or AES-XCBC-MAC-96, AES-XCBC-PRF-128

 		 * @param aKey           	Symmetric key for calculating message authentication code value. 

 		 * @param aAlgorithmParams  The parameters those are specific to a particular MAC algorithm.

 		 * 							This is for extendibility and will normally be null.                     	

 		 * @leave               	KErrNone if successful; otherwise, leaves with a system wide error code.

 		 */

 		IMPORT_C static void CreateAsyncMacL(CAsyncMac*& aMac,

 										const TUid aAlgorithmUid,

 										const CKey& aKey,

 										const CCryptoParams* aAlgorithmParams);

 	private:

 		/**

 		 * The class is used as a static class since there is no data 

 		 * or behaviour in the class that depends on object identity.

 		 * Therefore the default constructor of this class is made private. 

 		 */

 		CMacFactory();	

 		};

 	}

 #endif //__CRYPTOAPI_MACAPI_H__