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