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