libjava/classpath/gnu/javax/crypto/mac/IMac.java

   1 /* IMac.java --
   2    Copyright (C) 2001, 2002, 2006 Free Software Foundation, Inc.
   3
   4 This file is a part of GNU Classpath.
   5
   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.
  10
  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.
  15
  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
  19 USA
  20
  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
  24 combination.
  25
  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.  */
  37
  38
  39 package gnu.javax.crypto.mac;
  40
  41 import java.util.Map;
  42 import java.security.InvalidKeyException;
  43
  44 /**
  45  * <p>The basic visible methods of any MAC (Message Authentication Code)
  46  * algorithm.</p>
  47  *
  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>
  52  *
  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>
  56  *
  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>
  61  *
  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>
  64  *
  65  * <ul>
  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>
  71  *
  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>.
  75  *    </li>
  76  * </ul>
  77  *
  78  * <p>References:</p>
  79  *
  80  * <ol>
  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>
  84  *
  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>
  88  * </ol>
  89  */
  90 public interface IMac
  91 {
  92
  93   // Constants
  94   // -------------------------------------------------------------------------
  95
  96   /**
  97    * Property name of the user-supplied key material. The value associated to
  98    * this property name is taken to be a byte array.
  99    */
 100   String MAC_KEY_MATERIAL = "gnu.crypto.mac.key.material";
 101
 102   /**
 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>
 107    *
 108    * <p>This implementation, follows the recommendation of the <i>RFC 2104</i>
 109    * authors; specifically:</p>
 110    *
 111    * <pre>
 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).
 116    * </pre>
 117    */
 118   String TRUNCATED_SIZE = "gnu.crypto.mac.truncated.size";
 119
 120   // Methods
 121   // -------------------------------------------------------------------------
 122
 123   /**
 124    * <p>Returns the canonical name of this algorithm.</p>
 125    *
 126    * @return the canonical name of this algorithm.
 127    */
 128   String name();
 129
 130   /**
 131    * <p>Returns the output length in bytes of this <i>MAC</i> algorithm.</p>
 132    *
 133    * @return the output length in bytes of this <i>MAC</i> algorithm.
 134    */
 135   int macSize();
 136
 137   /**
 138    * <p>Initialises the algorithm with designated attributes. Permissible names
 139    * and values are described in the class documentation above.</p>
 140    *
 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
 146    */
 147   void init(Map attributes) throws InvalidKeyException, IllegalStateException;
 148
 149   /**
 150    * <p>Continues a <i>MAC</i> operation using the input byte.</p>
 151    *
 152    * @param b the input byte to digest.
 153    */
 154   void update(byte b);
 155
 156   /**
 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
 160    * operation.</p>
 161    *
 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.
 165    */
 166   void update(byte[] in, int offset, int length);
 167
 168   /**
 169    * <p>Completes the <i>MAC</i> by performing final operations such as
 170    * padding and resetting the instance.</p>
 171    *
 172    * @return the array of bytes representing the <i>MAC</i> value.
 173    */
 174   byte[] digest();
 175
 176   /**
 177    * <p>Resets the algorithm instance for re-initialisation and use with other
 178    * characteristics. This method always succeeds.</p>
 179    */
 180   void reset();
 181
 182   /**
 183    * <p>A basic test. Ensures that the MAC of a pre-determined message is equal
 184    * to a known pre-computed value.</p>
 185    *
 186    * @return <code>true</code> if the implementation passes a basic self-test.
 187    * Returns <code>false</code> otherwise.
 188    */
 189   boolean selfTest();
 190
 191   /**
 192    * <p>Returns a clone copy of this instance.</p>
 193    *
 194    * @return a clone copy of this instance.
 195    */
 196   Object clone() throws CloneNotSupportedException;
 197 }