Source for gnu.javax.crypto.mac.HMac

   1: /* HMac.java --
   2:    Copyright (C) 2001, 2002, 2003, 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 gnu.java.security.Registry;
  42: import gnu.java.security.hash.IMessageDigest;
  43: import gnu.java.security.hash.MD5;
  44: import gnu.java.security.util.Util;
  45: 
  46: import java.security.InvalidKeyException;
  47: import java.util.HashMap;
  48: import java.util.Map;
  49: 
  50: /**
  51:  * The implementation of the <i>HMAC</i> (Keyed-Hash Message Authentication
  52:  * Code).
  53:  * <p>
  54:  * <i>HMAC</i> can be used in combination with any iterated cryptographic hash
  55:  * function. <i>HMAC</i> also uses a <i>secret key</i> for calculation and
  56:  * verification of the message authentication values. The main goals behind this
  57:  * construction are:
  58:  * <ul>
  59:  * <li>To use, without modifications, available hash functions. In particular,
  60:  * hash functions that perform well in software, and for which code is freely
  61:  * and widely available.</li>
  62:  * <li>To preserve the original performance of the hash function without
  63:  * incurring a significant degradation.</li>
  64:  * <li>To use and handle keys in a simple way.</li>
  65:  * <li>To have a well understood cryptographic analysis of the strength of the
  66:  * authentication mechanism based on reasonable assumptions on the underlying
  67:  * hash function.</li>
  68:  * <li>To allow for easy replaceability of the underlying hash function in case
  69:  * that faster or more secure hash functions are found or required.</li>
  70:  * </ul>
  71:  * <p>
  72:  * References:
  73:  * <ol>
  74:  * <li><a href="http://www.ietf.org/rfc/rfc-2104.txt">RFC 2104</a>HMAC:
  75:  * Keyed-Hashing for Message Authentication.<br>
  76:  * H. Krawczyk, M. Bellare, and R. Canetti.</li>
  77:  * </ol>
  78:  */
  79: public class HMac
  80:     extends BaseMac
  81:     implements Cloneable
  82: {
  83:   public static final String USE_WITH_PKCS5_V2 = "gnu.crypto.hmac.pkcs5";
  84:   private static final byte IPAD_BYTE = 0x36;
  85:   private static final byte OPAD_BYTE = 0x5C;
  86:   /** caches the result of the correctness test, once executed. */
  87:   private static Boolean valid;
  88:   protected int macSize;
  89:   protected int blockSize;
  90:   protected IMessageDigest ipadHash;
  91:   protected IMessageDigest opadHash;
  92:   protected byte[] ipad;
  93: 
  94:   /**
  95:    * Trivial constructor for use by concrete subclasses.
  96:    *
  97:    * @param underlyingHash the underlying hash algorithm instance.
  98:    */
  99:   protected HMac(IMessageDigest underlyingHash)
 100:   {
 101:     super(Registry.HMAC_NAME_PREFIX + underlyingHash.name(), underlyingHash);
 102: 
 103:     this.blockSize = underlyingHash.blockSize();
 104:     this.macSize = underlyingHash.hashSize();
 105:     ipadHash = opadHash = null;
 106:   }
 107: 
 108:   public Object clone() throws CloneNotSupportedException
 109:   {
 110:     HMac result = (HMac) super.clone();
 111:     if (this.ipadHash != null)
 112:       result.ipadHash = (IMessageDigest) this.ipadHash.clone();
 113:     if (this.opadHash != null)
 114:       result.opadHash = (IMessageDigest) this.opadHash.clone();
 115:     if (this.ipad != null)
 116:       result.ipad = (byte[]) this.ipad.clone();
 117: 
 118:     return result;
 119:   }
 120: 
 121:   public void init(Map attributes) throws InvalidKeyException,
 122:       IllegalStateException
 123:   {
 124:     Integer ts = (Integer) attributes.get(TRUNCATED_SIZE);
 125:     truncatedSize = (ts == null ? macSize : ts.intValue());
 126:     if (truncatedSize < (macSize / 2))
 127:       throw new IllegalArgumentException("Truncated size too small");
 128:     else if (truncatedSize < 10)
 129:       throw new IllegalArgumentException("Truncated size less than 80 bits");
 130: 
 131:     // we dont use/save the key outside this method
 132:     byte[] K = (byte[]) attributes.get(MAC_KEY_MATERIAL);
 133:     if (K == null)
 134:       { // take it as an indication to re-use previous key if set
 135:         if (ipadHash == null)
 136:           throw new InvalidKeyException("Null key");
 137:         // we already went through the motions; ie. up to step #4.  re-use
 138:         underlyingHash = (IMessageDigest) ipadHash.clone();
 139:         return;
 140:       }
 141: 
 142:     // for HMACs used in key-derivation functions (e.g. PBKDF2) the key material
 143:     // need not be >= the (output) block size of the underlying algorithm
 144:     Boolean pkcs5 = (Boolean) attributes.get(USE_WITH_PKCS5_V2);
 145:     if (pkcs5 == null)
 146:       pkcs5 = Boolean.FALSE;
 147:     if (K.length < macSize && ! pkcs5.booleanValue())
 148:       throw new InvalidKeyException("Key too short");
 149: 
 150:     if (K.length > blockSize)
 151:       {
 152:         // (0) replace K with HASH(K) if K is larger than the hash's block size.
 153:         //     Then pad with zeros until it is the correct size (the next `if').
 154:         underlyingHash.update(K, 0, K.length);
 155:         K = underlyingHash.digest();
 156:       }
 157:     if (K.length < blockSize)
 158:       {
 159:         // (1) append zeros to the end of K to create a B byte string (e.g., if
 160:         //     K is of length 20 bytes and B=64, then K will be appended with 44
 161:         //     zero bytes 0x00)
 162:         int limit = (K.length > blockSize) ? blockSize : K.length;
 163:         byte[] newK = new byte[blockSize];
 164:         System.arraycopy(K, 0, newK, 0, limit);
 165:         K = newK;
 166:       }
 167:     underlyingHash.reset();
 168:     opadHash = (IMessageDigest) underlyingHash.clone();
 169:     if (ipad == null)
 170:       ipad = new byte[blockSize];
 171:     // (2) XOR (bitwise exclusive-OR) the B byte string computed in step (1)
 172:     //     with ipad
 173:     // (3) append the stream of data 'text' to the B byte string resulting from
 174:     //     step (2)
 175:     // (4) apply H to the stream generated in step (3)
 176:     for (int i = 0; i < blockSize; i++)
 177:       ipad[i] = (byte)(K[i] ^ IPAD_BYTE);
 178:     for (int i = 0; i < blockSize; i++)
 179:       opadHash.update((byte)(K[i] ^ OPAD_BYTE));
 180:     underlyingHash.update(ipad, 0, blockSize);
 181:     ipadHash = (IMessageDigest) underlyingHash.clone();
 182:     K = null;
 183:   }
 184: 
 185:   public void reset()
 186:   {
 187:     super.reset();
 188:     if (ipad != null)
 189:       {
 190:         underlyingHash.update(ipad, 0, blockSize);
 191:         ipadHash = (IMessageDigest) underlyingHash.clone();
 192:       }
 193:   }
 194: 
 195:   public byte[] digest()
 196:   {
 197:     if (ipadHash == null)
 198:       throw new IllegalStateException("HMAC not initialised");
 199:     byte[] out = underlyingHash.digest();
 200:     // (5) XOR (bitwise exclusive-OR) the B byte string computed in step (1)
 201:     //     with opad
 202:     underlyingHash = (IMessageDigest) opadHash.clone();
 203:     // (6) append the H result from step (4) to the B byte string resulting from
 204:     //     step (5)
 205:     underlyingHash.update(out, 0, macSize);
 206:     // (7) apply H to the stream generated in step (6) and output the result
 207:     out = underlyingHash.digest(); // which also resets the underlying hash
 208:     // truncate and return
 209:     if (truncatedSize == macSize)
 210:       return out;
 211:     byte[] result = new byte[truncatedSize];
 212:     System.arraycopy(out, 0, result, 0, truncatedSize);
 213:     return result;
 214:   }
 215: 
 216:   public boolean selfTest()
 217:   {
 218:     if (valid == null)
 219:       {
 220:         try
 221:           {
 222:             IMac mac = new HMac(new MD5()); // use rfc-2104 test vectors
 223:             String tv1 = "9294727A3638BB1C13F48EF8158BFC9D";
 224:             String tv3 = "56BE34521D144C88DBB8C733F0E8B3F6";
 225:             byte[] k1 = new byte[] {
 226:                 0x0B, 0x0B, 0x0B, 0x0B, 0x0B, 0x0B, 0x0B, 0x0B,
 227:                 0x0B, 0x0B, 0x0B, 0x0B, 0x0B, 0x0B, 0x0B, 0x0B };
 228:             byte[] k3 = new byte[] {
 229:                 (byte) 0xAA, (byte) 0xAA, (byte) 0xAA, (byte) 0xAA,
 230:                 (byte) 0xAA, (byte) 0xAA, (byte) 0xAA, (byte) 0xAA,
 231:                 (byte) 0xAA, (byte) 0xAA, (byte) 0xAA, (byte) 0xAA,
 232:                 (byte) 0xAA, (byte) 0xAA, (byte) 0xAA, (byte) 0xAA };
 233:             byte[] data = new byte[50];
 234:             for (int i = 0; i < 50;)
 235:               data[i++] = (byte) 0xDD;
 236: 
 237:             HashMap map = new HashMap();
 238:             // test vector #1
 239:             map.put(MAC_KEY_MATERIAL, k1);
 240:             mac.init(map);
 241:             mac.update("Hi There".getBytes("ASCII"), 0, 8);
 242:             if (! tv1.equals(Util.toString(mac.digest())))
 243:               valid = Boolean.FALSE;
 244: 
 245:             // test #2 is not used since it causes a "Key too short" exception
 246: 
 247:             // test vector #3
 248:             map.put(MAC_KEY_MATERIAL, k3);
 249:             mac.init(map);
 250:             mac.update(data, 0, 50);
 251:             if (! tv3.equals(Util.toString(mac.digest())))
 252:               valid = Boolean.FALSE;
 253:             valid = Boolean.TRUE;
 254:           }
 255:         catch (Exception x)
 256:           {
 257:             x.printStackTrace(System.err);
 258:             valid = Boolean.FALSE;
 259:           }
 260:       }
 261:     return valid.booleanValue();
 262:   }
 263: }