KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > crypto > Mac


1 /*
2  * @(#)Mac.java 1.7 03/12/19
3  *
4  * Copyright (c) 2004 Sun Microsystems, Inc. All Rights Reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7   
8 /*
9  * NOTE:
10  * Because of various external restrictions (i.e. US export
11  * regulations, etc.), the actual source code can not be provided
12  * at this time. This file represents the skeleton of the source
13  * file, so that javadocs of the API can be created.
14  */
15
16 package javax.crypto;
17
18 import java.security.*;
19
20 import java.security.spec.AlgorithmParameterSpec;
21 import java.nio.ByteBuffer;
22
23 /**
24  * This class provides the functionality of a "Message Authentication Code"
25  * (MAC) algorithm.
26  *
27  * <p> A MAC provides a way to check
28  * the integrity of information transmitted over or stored in an unreliable
29  * medium, based on a secret key. Typically, message
30  * authentication codes are used between two parties that share a secret
31  * key in order to validate information transmitted between these
32  * parties.
33  *
34  * <p> A MAC mechanism that is based on cryptographic hash functions is
35  * referred to as HMAC. HMAC can be used with any cryptographic hash function,
36  * e.g., MD5 or SHA-1, in combination with a secret shared key. HMAC is
37  * specified in RFC 2104.
38  *
39  * @author Jan Luehe
40  *
41  * @version 1.18, 04/30/03
42  * @since 1.4
43  */
44 public class Mac implements Cloneable
45 {
46
47     /**
48      * Creates a MAC object.
49      *
50      * @param macSpi the delegate
51      * @param provider the provider
52      * @param algorithm the algorithm
53      */
54     protected Mac(MacSpi macSpi, Provider provider, String algorithm) { }
55
56     /**
57      * Returns the algorithm name of this <code>Mac</code> object.
58      *
59      * <p>This is the same name that was specified in one of the
60      * <code>getInstance</code> calls that created this
61      * <code>Mac</code> object.
62      *
63      * @return the algorithm name of this <code>Mac</code> object.
64      */
65     public final String getAlgorithm() { }
66
67     /**
68      * Generates an <code>Mac</code> object that implements the
69      * specified MAC algorithm.
70      * If the default provider package provides an implementation of the
71      * requested MAC algorithm, an instance of
72      * <code>Mac</code> containing that implementation is returned.
73      * If the algorithm is not available in the default provider package,
74      * other provider packages are searched.
75      *
76      * @param algorithm the standard name of the requested MAC algorithm.
77      * See Appendix A in the
78      * <a HREF="../../../guide/security/jce/JCERefGuide.html#AppA">
79      * Java Cryptography Extension Reference Guide</a>
80      * for information about standard algorithm names.
81      *
82      * @return the new <code>Mac</code> object.
83      *
84      * @exception NoSuchAlgorithmException if the specified algorithm is not
85      * available in the default provider package or any of the other provider
86      * packages that were searched.
87      */
88     public static final Mac getInstance(String algorithm)
89         throws NoSuchAlgorithmException
90     { }
91
92     /**
93      * Generates an <code>Mac</code> object for the specified MAC
94      * algorithm from the specified provider.
95      *
96      * @param algorithm the standard name of the requested MAC algorithm.
97      * See Appendix A in the
98      * <a HREF="../../../guide/security/jce/JCERefGuide.html#AppA">
99      * Java Cryptography Extension Reference Guide</a>
100      * for information about standard algorithm names.
101      * @param provider the name of the provider.
102      *
103      * @return the new <code>Mac</code> object.
104      *
105      * @exception NoSuchAlgorithmException if the specified algorithm is not
106      * available from the specified provider.
107      * @exception NoSuchProviderException if the specified provider has not
108      * been configured.
109      * @exception IllegalArgumentException if the <code>provider</code>
110      * is null.
111      */
112     public static final Mac getInstance(String algorithm, String provider)
113         throws NoSuchAlgorithmException, NoSuchProviderException
114     { }
115
116     /**
117      * Generates an <code>Mac</code> object for the specified MAC
118      * algorithm from the specified provider. Note: the <code>provider</code>
119      * doesn't have to be registered.
120      *
121      * @param algorithm the standard name of the requested MAC algorithm.
122      * See Appendix A in the
123      * <a HREF="../../../guide/security/jce/JCERefGuide.html#AppA">
124      * Java Cryptography Extension Reference Guide</a>
125      * for information about standard algorithm names.
126      * @param provider the name of the provider.
127      *
128      * @return the new <code>Mac</code> object.
129      *
130      * @exception NoSuchAlgorithmException if the specified algorithm is not
131      * available from the specified provider.
132      * @exception IllegalArgumentException if the <code>provider</code>
133      * is null.
134      */
135     public static final Mac getInstance(String algorithm, Provider provider)
136         throws NoSuchAlgorithmException
137     { }
138
139     /**
140      * Returns the provider of this <code>Mac</code> object.
141      *
142      * @return the provider of this <code>Mac</code> object.
143      */
144     public final Provider getProvider() { }
145
146     /**
147      * Returns the length of the MAC in bytes.
148      *
149      * @return the MAC length in bytes.
150      */
151     public final int getMacLength() { }
152
153     /**
154      * Initializes this <code>Mac</code> object with the given key.
155      *
156      * @param key the key.
157      *
158      * @exception InvalidKeyException if the given key is inappropriate for
159      * initializing this MAC.
160      */
161     public final void init(Key key) throws InvalidKeyException { }
162
163     /**
164      * Initializes this <code>Mac</code> object with the given key and
165      * algorithm parameters.
166      *
167      * @param key the key.
168      * @param params the algorithm parameters.
169      *
170      * @exception InvalidKeyException if the given key is inappropriate for
171      * initializing this MAC.
172      * @exception InvalidAlgorithmParameterException if the given algorithm
173      * parameters are inappropriate for this MAC.
174      */
175     public final void init(Key key, AlgorithmParameterSpec params)
176         throws InvalidKeyException, InvalidAlgorithmParameterException
177     { }
178
179     /**
180      * Processes the given byte.
181      *
182      * @param input the input byte to be processed.
183      *
184      * @exception IllegalStateException if this <code>Mac</code> has not been
185      * initialized.
186      */
187     public final void update(byte input) throws IllegalStateException { }
188
189     /**
190      * Processes the given array of bytes.
191      *
192      * @param input the array of bytes to be processed.
193      *
194      * @exception IllegalStateException if this <code>Mac</code> has not been
195      * initialized.
196      */
197     public final void update(byte[] input) throws IllegalStateException { }
198
199     /**
200      * Processes the first <code>len</code> bytes in <code>input</code>,
201      * starting at <code>offset</code> inclusive.
202      *
203      * @param input the input buffer.
204      * @param offset the offset in <code>input</code> where the input starts.
205      * @param len the number of bytes to process.
206      *
207      * @exception IllegalStateException if this <code>Mac</code> has not been
208      * initialized.
209      */
210     public final void update(byte[] input, int offset, int len)
211         throws IllegalStateException
212     { }
213
214     /**
215      * Processes <code>input.remaining()</code> bytes in the ByteBuffer
216      * <code>input</code>, starting at <code>input.position()</code>.
217      * Upon return, the buffer's position will be equal to its limit;
218      * its limit will not have changed.
219      *
220      * @param input the ByteBuffer
221      *
222      * @exception IllegalStateException if this <code>Mac</code> has not been
223      * initialized.
224      * @since 1.5
225      */
226     public final void update(ByteBuffer input) { }
227
228     /**
229      * Finishes the MAC operation.
230      *
231      * <p>A call to this method resets this <code>Mac</code> object to the
232      * state it was in when previously initialized via a call to
233      * <code>init(Key)</code> or
234      * <code>init(Key, AlgorithmParameterSpec)</code>.
235      * That is, the object is reset and available to generate another MAC from
236      * the same key, if desired, via new calls to <code>update</code> and
237      * <code>doFinal</code>.
238      * (In order to reuse this <code>Mac</code> object with a different key,
239      * it must be reinitialized via a call to <code>init(Key)</code> or
240      * <code>init(Key, AlgorithmParameterSpec)</code>.
241      *
242      * @return the MAC result.
243      *
244      * @exception IllegalStateException if this <code>Mac</code> has not been
245      * initialized.
246      */
247     public final byte[] doFinal() throws IllegalStateException { }
248
249     /**
250      * Finishes the MAC operation.
251      *
252      * <p>A call to this method resets this <code>Mac</code> object to the
253      * state it was in when previously initialized via a call to
254      * <code>init(Key)</code> or
255      * <code>init(Key, AlgorithmParameterSpec)</code>.
256      * That is, the object is reset and available to generate another MAC from
257      * the same key, if desired, via new calls to <code>update</code> and
258      * <code>doFinal</code>.
259      * (In order to reuse this <code>Mac</code> object with a different key,
260      * it must be reinitialized via a call to <code>init(Key)</code> or
261      * <code>init(Key, AlgorithmParameterSpec)</code>.
262      *
263      * <p>The MAC result is stored in <code>output</code>, starting at
264      * <code>outOffset</code> inclusive.
265      *
266      * @param output the buffer where the MAC result is stored
267      * @param outOffset the offset in <code>output</code> where the MAC is
268      * stored
269      *
270      * @exception ShortBufferException if the given output buffer is too small
271      * to hold the result
272      * @exception IllegalStateException if this <code>Mac</code> has not been
273      * initialized.
274      */
275     public final void doFinal(byte[] output, int outOffset)
276         throws ShortBufferException, IllegalStateException
277     { }
278
279     /**
280      * Processes the given array of bytes and finishes the MAC operation.
281      *
282      * <p>A call to this method resets this <code>Mac</code> object to the
283      * state it was in when previously initialized via a call to
284      * <code>init(Key)</code> or
285      * <code>init(Key, AlgorithmParameterSpec)</code>.
286      * That is, the object is reset and available to generate another MAC from
287      * the same key, if desired, via new calls to <code>update</code> and
288      * <code>doFinal</code>.
289      * (In order to reuse this <code>Mac</code> object with a different key,
290      * it must be reinitialized via a call to <code>init(Key)</code> or
291      * <code>init(Key, AlgorithmParameterSpec)</code>.
292      *
293      * @param input data in bytes
294      * @return the MAC result.
295      *
296      * @exception IllegalStateException if this <code>Mac</code> has not been
297      * initialized.
298      */
299     public final byte[] doFinal(byte[] input) throws IllegalStateException { }
300
301     /**
302      * Resets this <code>Mac</code> object.
303      *
304      * <p>A call to this method resets this <code>Mac</code> object to the
305      * state it was in when previously initialized via a call to
306      * <code>init(Key)</code> or
307      * <code>init(Key, AlgorithmParameterSpec)</code>.
308      * That is, the object is reset and available to generate another MAC from
309      * the same key, if desired, via new calls to <code>update</code> and
310      * <code>doFinal</code>.
311      * (In order to reuse this <code>Mac</code> object with a different key,
312      * it must be reinitialized via a call to <code>init(Key)</code> or
313      * <code>init(Key, AlgorithmParameterSpec)</code>.
314      */
315     public final void reset() { }
316
317     /**
318      * Returns a clone if the provider implementation is cloneable.
319      *
320      * @return a clone if the provider implementation is cloneable.
321      *
322      * @exception CloneNotSupportedException if this is called on a
323      * delegate that does not support <code>Cloneable</code>.
324      */
325     public final Object clone() throws CloneNotSupportedException { }
326 }
327
Popular Tags