2 Copyright (C) 2001, 2002, 2006 Free Software Foundation, Inc.
4 This file is a part of GNU Classpath.
6 GNU Classpath is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 2 of the License, or (at
9 your option) any later version.
11 GNU Classpath is distributed in the hope that it will be useful, but
12 WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 General Public License for more details.
16 You should have received a copy of the GNU General Public License
17 along with GNU Classpath; if not, write to the Free Software
18 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301
21 Linking this library statically or dynamically with other modules is
22 making a combined work based on this library. Thus, the terms and
23 conditions of the GNU General Public License cover the whole
26 As a special exception, the copyright holders of this library give you
27 permission to link this library with independent modules to produce an
28 executable, regardless of the license terms of these independent
29 modules, and to copy and distribute the resulting executable under
30 terms of your choice, provided that you also meet, for each linked
31 independent module, the terms and conditions of the license of that
32 module. An independent module is a module which is not derived from
33 or based on this library. If you modify this library, you may extend
34 this exception to your version of the library, but you are not
35 obligated to do so. If you do not wish to do so, delete this
36 exception statement from your version. */
39 package gnu
.javax
.crypto
.mac
;
42 import java
.security
.InvalidKeyException
;
45 * <p>The basic visible methods of any MAC (Message Authentication Code)
48 * <p>A <i>MAC</i> provides a way to check the integrity of information
49 * transmitted over, or stored in, an unreliable medium, based on a secret key.
50 * Typically, <i>MAC</i>s are used between two parties, that share a common
51 * secret key, in order to validate information transmitted between them.</p>
53 * <p>When a <i>MAC</i> algorithm is based on a cryptographic hash function, it
54 * is then called to a <i>HMAC</i> (Hashed Message Authentication Code) --see
55 * <a href="http://www.ietf.org/rfc/rfc-2104.txt">RFC-2104</a>.</p>
57 * Another type of <i>MAC</i> algorithms exist: UMAC or <i>Universal Message
58 * Authentication Code</i>, described in
59 * <a href="http://www.ietf.org/internet-drafts/draft-krovetz-umac-01.txt">
60 * draft-krovetz-umac-01.txt</a>.</p>
62 * <p>With <i>UMAC</i>s, the sender and receiver share a common secret key (the
63 * <i>MAC</i> key) which determines:</p>
66 * <li>The key for a <i>universal hash function</i>. This hash function is
67 * <i>non-cryptographic</i>, in the sense that it does not need to have any
68 * cryptographic <i>hardness</i> property. Rather, it needs to satisfy some
69 * combinatorial property, which can be proven to hold without relying on
70 * unproven hardness assumptions.</li>
72 * <li>The key for a <i>pseudorandom function</i>. This is where one needs a
73 * cryptographic hardness assumption. The pseudorandom function may be
74 * obtained from a <i>block cipher</i> or a <i>cryptographic hash function</i>.
81 * <li><a href="http://www.ietf.org/rfc/rfc-2104.txt">RFC 2104</a>HMAC:
82 * Keyed-Hashing for Message Authentication.<br>
83 * H. Krawczyk, M. Bellare, and R. Canetti.</li>
85 * <li><a href="http://www.ietf.org/internet-drafts/draft-krovetz-umac-01.txt">
86 * UMAC</a>: Message Authentication Code using Universal Hashing.<br>
87 * T. Krovetz, J. Black, S. Halevi, A. Hevia, H. Krawczyk, and P. Rogaway.</li>
94 // -------------------------------------------------------------------------
97 * Property name of the user-supplied key material. The value associated to
98 * this property name is taken to be a byte array.
100 String MAC_KEY_MATERIAL
= "gnu.crypto.mac.key.material";
103 * <p>Property name of the desired truncated output size in bytes. The value
104 * associated to this property name is taken to be an integer. If no value
105 * is specified in the attributes map at initialisation time, then all bytes
106 * of the underlying hash algorithm's output are emitted.</p>
108 * <p>This implementation, follows the recommendation of the <i>RFC 2104</i>
109 * authors; specifically:</p>
112 * We recommend that the output length t be not less than half the
113 * length of the hash output (to match the birthday attack bound)
114 * and not less than 80 bits (a suitable lower bound on the number
115 * of bits that need to be predicted by an attacker).
118 String TRUNCATED_SIZE
= "gnu.crypto.mac.truncated.size";
121 // -------------------------------------------------------------------------
124 * <p>Returns the canonical name of this algorithm.</p>
126 * @return the canonical name of this algorithm.
131 * <p>Returns the output length in bytes of this <i>MAC</i> algorithm.</p>
133 * @return the output length in bytes of this <i>MAC</i> algorithm.
138 * <p>Initialises the algorithm with designated attributes. Permissible names
139 * and values are described in the class documentation above.</p>
141 * @param attributes a set of name-value pairs that describe the desired
142 * future instance behaviour.
143 * @exception InvalidKeyException if the key data is invalid.
144 * @exception IllegalStateException if the instance is already initialised.
145 * @see #MAC_KEY_MATERIAL
147 void init(Map attributes
) throws InvalidKeyException
, IllegalStateException
;
150 * <p>Continues a <i>MAC</i> operation using the input byte.</p>
152 * @param b the input byte to digest.
157 * <p>Continues a <i>MAC</i> operation, by filling the buffer, processing
158 * data in the algorithm's MAC_SIZE-bit block(s), updating the context and
159 * count, and buffering the remaining bytes in buffer for the next
162 * @param in the input block.
163 * @param offset start of meaningful bytes in input block.
164 * @param length number of bytes, in input block, to consider.
166 void update(byte[] in
, int offset
, int length
);
169 * <p>Completes the <i>MAC</i> by performing final operations such as
170 * padding and resetting the instance.</p>
172 * @return the array of bytes representing the <i>MAC</i> value.
177 * <p>Resets the algorithm instance for re-initialisation and use with other
178 * characteristics. This method always succeeds.</p>
183 * <p>A basic test. Ensures that the MAC of a pre-determined message is equal
184 * to a known pre-computed value.</p>
186 * @return <code>true</code> if the implementation passes a basic self-test.
187 * Returns <code>false</code> otherwise.
192 * <p>Returns a clone copy of this instance.</p>
194 * @return a clone copy of this instance.
196 Object
clone() throws CloneNotSupportedException
;