2 * Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).
4 * This component and the accompanying materials are made available
5 * under the terms of the License "Eclipse Public License v1.0"
6 * which accompanies this distribution, and is available
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".
9 * Initial Contributors:
10 * Nokia Corporation - initial contribution.
15 * MAC(message authentication code) plugin interface
26 #ifndef __MAC_PLUGIN_H
27 #define __MAC_PLUGIN_H
29 #include <cryptospi/cryptoplugin.h>
36 * The generic CryptoSPI MAC definition. This allow plug-ins
37 * to implement extensible MAC functionality and to work with all
38 * known existing hash based or symmetric cipher based MAC algorithms
39 * for e.g. MD2, MD4, MD5, SHA-1, SHA-256, SHA-512, RIPEMD-160, etc. or
40 * AES-XCBC-MAC-96, AES-XCBC-PRF-128 etc. respectively.
42 class MMac : public MPlugin
47 * Adds message to the internal representation of data for which the MAC value
48 * needs to be evaluated and then returns a TPtrC8 of the finalised MAC value
49 * of all the previously appended messages.
51 * @param aMessage The data for which MAC value is to be evaluated.
52 * @return A descriptor pointer to the buffer containing the
53 * resulting MAC value.
54 * @leave ... Any of the crypto error codes defined in
55 cryptospi_errs.h or any of the system-wide error codes.
57 virtual TPtrC8 MacL(const TDesC8& aMessage) = 0;
60 * Adds data to the internal representation of messages for which the MAC value
61 * needs to be evaluated.
63 * @param aMessage The data to be included in the MAC evaluation.
64 * @leave ... Any of the crypto error codes defined in
65 cryptospi_errs.h or any of the system-wide error codes.
67 virtual void UpdateL(const TDesC8& aMessage) = 0;
70 * Produces a final MAC value from all the previous updates of data to be MACed.
71 * It resets the MAC algorithm in a state similar to creating a new MAC instance
72 * with the same underlying algorithm and supplied symmetric key.
74 * @param aMessage The data to be included in the MAC evaluation.
75 * @return A descriptor pointer to the buffer containing the
76 * resulting MAC value.
77 * @leave ... Any of the crypto error codes defined in
78 cryptospi_errs.h or any of the system-wide error codes.
80 virtual TPtrC8 FinalL(const TDesC8& aMessage) = 0;
83 * This re-initialises the underlying MAC algorithm with a new symmetric key.
84 * It resets the MAC algorithm in a state similar to creating a new MAC instance
85 * with the same underlying algorithm but a new symmetric key.
87 * @param aKey Symmetric key for calculating message authentication code value.
88 * @leave ... Any of the crypto error codes defined in
89 cryptospi_errs.h or any of the system-wide error codes.
91 virtual void ReInitialiseAndSetKeyL(const CKey& aKey) = 0;
94 * Creates a brand new reset MMac object containing no state
95 * information from the current object.
97 * @return A pointer to the new reset MMac object
98 * @leave ... Any of the crypto error codes defined in
99 cryptospi_errs.h or any of the system-wide error codes.
101 virtual MMac* ReplicateL() = 0;
104 * Creates a new MMac object with the exact same state as
105 * the current object.
106 * This function copies all internal state of the message digest.
108 * @return A pointer to the new MMac object
109 * @leave ... Any of the crypto error codes defined in
110 cryptospi_errs.h or any of the system-wide error codes.
112 virtual MMac* CopyL() = 0;
116 * Asynchronous MAC interface typically used by the plug-in implementations
117 * that are based for dedicated crypto hardware.
119 class MAsyncMac : public MPlugin
124 * Adds message to the internal representation of data for which the MAC value,
125 * needs to be evaluated and then returns a TPtrC8 of the finalised MAC value
126 * of all the previously appended messages.
128 * @param aMessage The data for which MAC value is to be evaluated.
129 * @param aStatus Holds the completion status of an asynchronous
130 * request for MAC evaluation.
131 * @return A descriptor pointer to the buffer containing the
132 * resulting MAC value.
133 * @leave ... Any of the crypto error codes defined in
134 cryptospi_errs.h or any of the system-wide error codes.
136 virtual TPtrC8 MacL(const TDesC8& aMessage, TRequestStatus& aStatus) = 0;
139 * Adds data to the internal representation of messages for which the MAC value
140 * needs to be evaluated.
142 * @param aMessage The data to be included in the MAC evaluation.
143 * @param aStatus Holds the completion status of an asynchronous
144 * request for MAC evaluation.
145 * @leave ... Any of the crypto error codes defined in
146 cryptospi_errs.h or any of the system-wide error codes.
148 virtual void UpdateL(const TDesC8& aMessage, TRequestStatus& aStatus) = 0;
151 * Produces a final MAC value from all the previous updates of data to be MACed.
152 * It resets the MAC algorithm in a state similar to creating a new MAC instance
153 * with the same underlying algorithm and supplied symmetric key.
155 * @param aMessage The data to be included in the MAC evaluation.
156 * @param aStatus Holds the completion status of an asynchronous
157 * request for MAC evaluation.
158 * @return A descriptor pointer to the buffer containing the
159 * resulting MAC value.
160 * @leave ... Any of the crypto error codes defined in
161 cryptospi_errs.h or any of the system-wide error codes.
163 virtual TPtrC8 FinalL(const TDesC8& aMessage, TRequestStatus& aStatus) = 0;
166 * This re-initialises the underlying MAC algorithm with a new symmetric key.
167 * It resets the MAC algorithm in a state similar to creating a new MAC instance
168 * with the same underlying algorithm but a new symmetric key.
170 * @param aKey Symmetric key for calculating message authentication code value.
171 * @param aStatus Holds the completion status of an asynchronous
172 * request for MAC evaluation.
173 * @leave ... Any of the crypto error codes defined in
174 cryptospi_errs.h or any of the system-wide error codes.
176 virtual void ReInitialiseAndSetKeyL(const CKey& aKey) = 0;
179 * Cancels an outstanding request from the client.
181 virtual void Cancel() = 0;
184 * Creates a brand new reset MAsyncMac object containing no state
185 * information from the current object.
187 * @return A pointer to the new reset MAsyncHash object
188 * @leave ... Any of the crypto error codes defined in
189 cryptospi_errs.h or any of the system-wide error codes.
191 virtual MAsyncMac* ReplicateL() = 0;
194 * Creates a new MAsyncMac object with the exact same state as
195 * the current object.
196 * This function copies all internal state of the message digest.
198 * @return A pointer to the new MAsyncMac object
199 * @leave ... Any of the crypto error codes defined in
200 cryptospi_errs.h or any of the system-wide error codes.
202 virtual MAsyncMac* CopyL() = 0;
206 #endif __MAC_PLUGIN_H