williamr@4: /* williamr@4: * Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies). williamr@4: * All rights reserved. williamr@4: * This component and the accompanying materials are made available williamr@4: * under the terms of the License "Eclipse Public License v1.0" williamr@4: * which accompanies this distribution, and is available williamr@4: * at the URL "http://www.eclipse.org/legal/epl-v10.html". williamr@4: * williamr@4: * Initial Contributors: williamr@4: * Nokia Corporation - initial contribution. williamr@4: * williamr@4: * Contributors: williamr@4: * williamr@4: * Description: williamr@4: * crypto MAC application interface williamr@4: * williamr@4: */ williamr@4: williamr@4: williamr@4: /** williamr@4: @file williamr@4: @publishedAll williamr@4: @released williamr@4: */ williamr@4: williamr@4: #ifndef __CRYPTOAPI_MACAPI_H__ williamr@4: #define __CRYPTOAPI_MACAPI_H__ williamr@4: williamr@4: #include williamr@4: #include williamr@4: williamr@4: williamr@4: namespace CryptoSpi williamr@4: { williamr@4: class MPlugin; williamr@4: class CCryptoParams; williamr@4: class CKey; williamr@4: class MMac; williamr@4: class MAsyncMac; williamr@4: williamr@4: williamr@4: /** williamr@4: * Mac API, which wraps a synchronous Mac plugin implementation williamr@4: * This Mac interface helps the client application to get the message williamr@4: * authentication code value of a given message which provides williamr@4: * data integrity and data origin authentication. These two goals are williamr@4: * dependent upon the scope of the distribution of the secret key. williamr@4: */ williamr@4: williamr@4: NONSHARABLE_CLASS(CMac) : public CCryptoBase williamr@4: { williamr@4: public: williamr@4: /** williamr@4: * @internalComponent williamr@4: * Create a CMac instance from the given MMac instance williamr@4: * williamr@4: * @param aMac The mac plugin instance williamr@4: * @param aHandle The current plugin DLL loaded. williamr@4: * @return pointer to a CMac instance williamr@4: */ williamr@4: static CMac* NewL(MMac* aMac, TInt aHandle); williamr@4: williamr@4: /** williamr@4: * Adds message to the internal representation of data for which the MAC value williamr@4: * needs to be evaluated and then returns a TPtrC8 of the finalised MAC value williamr@4: * of all the previously appended messages. williamr@4: * williamr@4: * @param aMessage The data for which MAC value is to be evaluated. williamr@4: * @return A descriptor pointer to the buffer containing the williamr@4: * resulting MAC value. williamr@4: * @leave ... Any of the crypto error codes defined in williamr@4: cryptospi_errs.h or any of the system-wide error codes. williamr@4: */ williamr@4: IMPORT_C TPtrC8 MacL(const TDesC8& aMessage); williamr@4: williamr@4: /** williamr@4: * Adds data to the internal representation of messages for which the MAC value williamr@4: * needs to be evaluated. williamr@4: * williamr@4: * @param aMessage The data to be included in the MAC evaluation. williamr@4: * @leave ... Any of the crypto error codes defined in williamr@4: cryptospi_errs.h or any of the system-wide error codes. williamr@4: */ williamr@4: IMPORT_C void UpdateL(const TDesC8& aMessage); williamr@4: williamr@4: /** williamr@4: * Produces a final MAC value from all the previous updates of data to be MACed. williamr@4: * It resets the MAC algorithm in a state similar to creating a new MAC instance williamr@4: * with the same underlying algorithm and supplied symmetric key. williamr@4: * williamr@4: * @param aMessage The data to be included in the MAC evaluation. williamr@4: * @return A descriptor pointer to the buffer containing the williamr@4: * resulting MAC value. williamr@4: * @leave ... Any of the crypto error codes defined in williamr@4: cryptospi_errs.h or any of the system-wide error codes. williamr@4: */ williamr@4: IMPORT_C TPtrC8 FinalL(const TDesC8& aMessage); williamr@4: williamr@4: /** williamr@4: * This re-initialises the underlying MAC algorithm with a new symmetric key. williamr@4: * It resets the MAC algorithm in a state similar to creating a new MAC instance williamr@4: * with the same underlying algorithm but a new symmetric key. williamr@4: * williamr@4: * @param aKey Symmetric key for calculating message authentication code value. williamr@4: * @leave ... Any of the crypto error codes defined in williamr@4: cryptospi_errs.h or any of the system-wide error codes. williamr@4: */ williamr@4: IMPORT_C void ReInitialiseAndSetKeyL(const CKey& aKey); williamr@4: williamr@4: /** williamr@4: * Creates a brand new reset CMac object containing no state williamr@4: * information from the current object. williamr@4: * williamr@4: * @return A pointer to the new reset CMac object williamr@4: * @leave ... Any of the crypto error codes defined in williamr@4: cryptospi_errs.h or any of the system-wide error codes. williamr@4: */ williamr@4: IMPORT_C CMac* ReplicateL(); williamr@4: williamr@4: /** williamr@4: * Creates a new CMac object with the exact same state as williamr@4: * the current object. williamr@4: * This function copies all internal state of the message digest. williamr@4: * williamr@4: * @return A pointer to the new CMac object williamr@4: * @leave ... Any of the crypto error codes defined in williamr@4: cryptospi_errs.h or any of the system-wide error codes. williamr@4: */ williamr@4: IMPORT_C CMac* CopyL(); williamr@4: williamr@4: /** williamr@4: * This destructor is exported so that the client application after using williamr@4: * a specific plug-in implementation can destroy its instance. Both the framework williamr@4: * and the plug-in use/derived from the same interface 'MPlugin. williamr@4: * By exporting the destructor we are destroying the plug-in instance at williamr@4: * client side via the CryptoSPI framework. williamr@4: */ williamr@4: IMPORT_C ~CMac(); williamr@4: williamr@4: private: williamr@4: /** williamr@4: * The constructor of this class is private. An user application will use williamr@4: * CMacFactory::CreateMacL for the object's initialisation. williamr@4: * williamr@4: * @param aMac The mac plug-in instance williamr@4: * @param aHandle The current plug-in DLL loaded williamr@4: */ williamr@4: CMac(MMac* aMac, TInt aHandle); williamr@4: }; williamr@4: williamr@4: williamr@4: /** williamr@4: * This is the asynchronous version of CMac class typically used by the williamr@4: * client applications if hardware plug-in implementation of williamr@4: * the MAC interface is present. williamr@4: */ williamr@4: williamr@4: NONSHARABLE_CLASS(CAsyncMac) : public CCryptoBase williamr@4: { williamr@4: public: williamr@4: /** williamr@4: * @internalComponent williamr@4: * Create a CAsyncMac instance from the given MAsyncMac instance williamr@4: * williamr@4: * @param aMac The mac plugin instance williamr@4: * @param aHandle The current plugin DLL loaded. williamr@4: * @return pointer to a CMac instance williamr@4: */ williamr@4: static CAsyncMac* NewL(MAsyncMac* aMac, TInt aHandle); williamr@4: williamr@4: /** williamr@4: * Adds message to the internal representation of data for which the MAC value williamr@4: * needs to be evaluated and then returns a TPtrC8 of the finalised MAC value williamr@4: * of all the previously appended messages. williamr@4: * williamr@4: * @param aMessage The data for which MAC value is to be evaluated. williamr@4: * @param aStatus Holds the completion status of an asynchronous williamr@4: * request for MAC evaluation. williamr@4: * @return A descriptor pointer to the buffer containing the williamr@4: * resulting MAC value. williamr@4: * @leave ... Any of the crypto error codes defined in williamr@4: cryptospi_errs.h or any of the system-wide error codes. williamr@4: */ williamr@4: IMPORT_C TPtrC8 MacL(const TDesC8& aMessage, TRequestStatus& aStatus); williamr@4: williamr@4: /** williamr@4: * Adds data to the internal representation of messages for which the MAC value williamr@4: * needs to be evaluated. williamr@4: * williamr@4: * @param aMessage The data to be included in the MAC evaluation. williamr@4: * @param aStatus Holds the completion status of an asynchronous williamr@4: * request for MAC evaluation. williamr@4: * @leave ... Any of the crypto error codes defined in williamr@4: cryptospi_errs.h or any of the system-wide error codes. williamr@4: */ williamr@4: IMPORT_C void UpdateL(const TDesC8& aMessage, TRequestStatus& aStatus); williamr@4: williamr@4: /** williamr@4: * Produces a final MAC value from all the previous updates of data to be MACed. williamr@4: * It resets the MAC algorithm in a state similar to creating a new MAC instance williamr@4: * with the same underlying algorithm and supplied symmetric key. williamr@4: * williamr@4: * @param aMessage The data to be included in the MAC evaluation. williamr@4: * @param aStatus Holds the completion status of an asynchronous williamr@4: * request for MAC evaluation. williamr@4: * @return A descriptor pointer to the buffer containing the williamr@4: * resulting MAC value. williamr@4: * @leave ... Any of the crypto error codes defined in williamr@4: cryptospi_errs.h or any of the system-wide error codes. williamr@4: */ williamr@4: IMPORT_C TPtrC8 FinalL(const TDesC8& aMessage, TRequestStatus& aStatus); williamr@4: williamr@4: /** williamr@4: * This re-initialises the underlying MAC algorithm with a new symmetric key. williamr@4: * It resets the MAC algorithm in a state similar to creating a new MAC instance williamr@4: * with the same underlying algorithm but a new symmetric key. williamr@4: * williamr@4: * @param aKey Symmetric key for calculating message authentication code value. williamr@4: * @leave ... Any of the crypto error codes defined in williamr@4: cryptospi_errs.h or any of the system-wide error codes. williamr@4: */ williamr@4: IMPORT_C void ReInitialiseAndSetKeyL(const CKey& aKey); williamr@4: williamr@4: /** williamr@4: * Creates a brand new reset CAsyncMac object containing no state williamr@4: * information from the current object. williamr@4: * williamr@4: * @return A pointer to the new reset CAsyncMac object williamr@4: * @leave ... Any of the crypto error codes defined in williamr@4: cryptospi_errs.h or any of the system-wide error codes. williamr@4: */ williamr@4: IMPORT_C CAsyncMac* ReplicateL(); williamr@4: williamr@4: /** williamr@4: * Creates a new CAsyncMac object with the exact same state as williamr@4: * the current object. williamr@4: * This function copies all internal state of the message digest. williamr@4: * williamr@4: * @return A pointer to the new CAsyncHash object williamr@4: * @leave ... Any of the crypto error codes defined in williamr@4: cryptospi_errs.h or any of the system-wide error codes. williamr@4: */ williamr@4: IMPORT_C CAsyncMac* CopyL(); williamr@4: williamr@4: /** williamr@4: * Cancels an outstanding request from the client. williamr@4: */ williamr@4: IMPORT_C void Cancel(); williamr@4: williamr@4: /** williamr@4: * This destructor is exported so that the client application after using williamr@4: * a specific plug-in implementation can destroy its instance. Both the framework williamr@4: * and the plug-in use/derived from the same interface 'MPlugin. williamr@4: * By exporting the destructor we are destroying the plug-in instance at williamr@4: * client side via the CryptoSPI framework. williamr@4: */ williamr@4: IMPORT_C ~CAsyncMac(); williamr@4: williamr@4: private: williamr@4: /** williamr@4: * The constructor of this class is private. An user application will use williamr@4: * CMacFactory::CreateAsyncMacL for the object's initialisation. williamr@4: * williamr@4: * @param aMac The mac plug-in instance williamr@4: * @param aHandle The current plug-in DLL loaded williamr@4: */ williamr@4: CAsyncMac(MAsyncMac* aMac, TInt aHandle); williamr@4: }; williamr@4: williamr@4: williamr@4: /** williamr@4: * The Factory to create synchronous and asynchronous Mac instances williamr@4: */ williamr@4: williamr@4: class CMacFactory williamr@4: { williamr@4: public: williamr@4: williamr@4: /** williamr@4: * Create a CMac instance (for software based MAC plug-in dll implementation) williamr@4: * williamr@4: * @param aMac The pointer to CMac. This will be initialised with williamr@4: * the plug-in implementation of the desired MAC algorithm. williamr@4: * @param aAlgorithmUid The specific MAC algorithm desired for evaluation of MAC value. williamr@4: * e.g. MD2, SHA1 or AES-XCBC-MAC-96, AES-XCBC-PRF-128 williamr@4: * @param aKey Symmetric key for calculating message authentication code value. williamr@4: * @param aAlgorithmParams The parameters those are specific to a particular MAC algorithm. williamr@4: * This is for extendibility and will normally be null. williamr@4: * @leave KErrNone if successful; otherwise, leaves with a system wide error code. williamr@4: */ williamr@4: IMPORT_C static void CreateMacL(CMac*& aMac, williamr@4: const TUid aAlgorithmUid, williamr@4: const CKey& aKey, williamr@4: const CCryptoParams* aAlgorithmParams); williamr@4: williamr@4: /** williamr@4: * Create a CAsyncMac instance (for hardware based MAC plug-in dll implementation) williamr@4: * williamr@4: * @param aMac The pointer to CMac. This will be initialised with williamr@4: * the plug-in implementation of the desired MAC algorithm. williamr@4: * @param aAlgorithmUid The specific MAC algorithm desired for evaluation of MAC value. williamr@4: * e.g. MD2, SHA1 or AES-XCBC-MAC-96, AES-XCBC-PRF-128 williamr@4: * @param aKey Symmetric key for calculating message authentication code value. williamr@4: * @param aAlgorithmParams The parameters those are specific to a particular MAC algorithm. williamr@4: * This is for extendibility and will normally be null. williamr@4: * @leave KErrNone if successful; otherwise, leaves with a system wide error code. williamr@4: */ williamr@4: IMPORT_C static void CreateAsyncMacL(CAsyncMac*& aMac, williamr@4: const TUid aAlgorithmUid, williamr@4: const CKey& aKey, williamr@4: const CCryptoParams* aAlgorithmParams); williamr@4: williamr@4: private: williamr@4: /** williamr@4: * The class is used as a static class since there is no data williamr@4: * or behaviour in the class that depends on object identity. williamr@4: * Therefore the default constructor of this class is made private. williamr@4: */ williamr@4: CMacFactory(); williamr@4: }; williamr@4: williamr@4: } williamr@4: williamr@4: #endif //__CRYPTOAPI_MACAPI_H__