diff -r 000000000000 -r bde4ae8d615e os/security/crypto/weakcryptospi/inc/spi/macplugin.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/os/security/crypto/weakcryptospi/inc/spi/macplugin.h Fri Jun 15 03:10:57 2012 +0200 @@ -0,0 +1,206 @@ +/* +* 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 + +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