/*

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

* MAC(message authentication code) plugin interface

*

*/

/**

 @file

 @publishedPartner

 @released

*/

#ifndef __MAC_PLUGIN_H

#define __MAC_PLUGIN_H

#include <cryptospi/cryptoplugin.h>

namespace CryptoSpi

	{

	class CKey;

	/**

	 * The generic CryptoSPI MAC definition. This allow plug-ins

	 * to implement extensible MAC functionality and to work with all

	 * known existing hash based or symmetric cipher based MAC algorithms

	 * for e.g. MD2, MD4, MD5, SHA-1, SHA-256, SHA-512, RIPEMD-160, etc. or 

	 * AES-XCBC-MAC-96, AES-XCBC-PRF-128 etc. respectively. 

	 */

	class MMac : public MPlugin

	    {

	public:

		/**

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

		 */

		virtual TPtrC8 MacL(const TDesC8& aMessage) = 0;    

        /**

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

         */

        virtual void UpdateL(const TDesC8& aMessage) = 0;

        /**

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

		 */

        virtual TPtrC8 FinalL(const TDesC8& aMessage) = 0;

		/**

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

		 */

		virtual void ReInitialiseAndSetKeyL(const CKey& aKey) = 0;

		/**

		 * Creates a brand new reset MMac object containing no state

		 * information from the current object.  

		 * 

		 * @return 	A pointer to the new reset MMac object

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

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

		 */

		virtual MMac* ReplicateL() = 0;		

		/** 

		 * Creates a new MMac 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 MMac object

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

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

		 */

		virtual MMac* CopyL() = 0;

	    };

	/**

	 * Asynchronous MAC interface typically used by the plug-in implementations 

	 * that are based for dedicated crypto hardware.

	 */    

	class MAsyncMac : public MPlugin

	    {

	public:

		/**

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

		 */

		virtual TPtrC8 MacL(const TDesC8& aMessage, TRequestStatus& aStatus) = 0;    

        /**

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

         */

        virtual void UpdateL(const TDesC8& aMessage, TRequestStatus& aStatus) = 0;

        /**

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

         */

        virtual TPtrC8 FinalL(const TDesC8& aMessage, TRequestStatus& aStatus) = 0;

	    /**

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

		 * @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.

		 */

		virtual void ReInitialiseAndSetKeyL(const CKey& aKey) = 0;    

		/**

		 * Cancels an outstanding request from the client.

		 */

		virtual void Cancel() = 0;

		/**

		 * Creates a brand new reset MAsyncMac object containing no state

		 * information from the current object.  

		 * 

		 * @return	A pointer to the new reset MAsyncHash object

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

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

		 */

		virtual MAsyncMac* ReplicateL() = 0;		

		/** 

		 * Creates a new MAsyncMac 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 MAsyncMac object

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

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

		 */

		virtual MAsyncMac* CopyL() = 0;

	    };

	}

#endif  __MAC_PLUGIN_H