gnu.javax.crypto.mac

Class UMac32

Implemented Interfaces:
IMac

public class UMac32
extends BaseMac

The implementation of the UMAC (Universal Message Authentication Code).

The UMAC algorithms described are parameterized. This means that various low-level choices, like the endian convention and the underlying cryptographic primitive, have not been fixed. One must choose values for these parameters before the authentication tag generated by UMAC (for a given message, key, and nonce) becomes fully-defined. In this document we provide two collections of parameter settings, and have named the sets UMAC16 and UMAC32. The parameter sets have been chosen based on experimentation and provide good performance on a wide variety of processors. UMAC16 is designed to excel on processors which provide small-scale SIMD parallelism of the type found in Intel's MMX and Motorola's AltiVec instruction sets, while UMAC32 is designed to do well on processors with good 32- and 64- bit support. UMAC32 may take advantage of SIMD parallelism in future processors.

UMAC has been designed to allow implementations which accommodate on-line authentication. This means that pieces of the message may be presented to UMAC at different times (but in correct order) and an on-line implementation will be able to process the message correctly without the need to buffer more than a few dozen bytes of the message. For simplicity, the algorithms in this specification are presented as if the entire message being authenticated were available at once.

To authenticate a message, Msg, one first applies the universal hash function, resulting in a string which is typically much shorter than the original message. The pseudorandom function is applied to a nonce, and the result is used in the manner of a Vernam cipher: the authentication tag is the xor of the output from the hash function and the output from the pseudorandom function. Thus, an authentication tag is generated as

     AuthTag = f(Nonce) xor h(Msg)
 

Here f is the pseudorandom function shared between the sender and the receiver, and h is a universal hash function shared by the sender and the receiver. In UMAC, a shared key is used to key the pseudorandom function f, and then f is used for both tag generation and internally to generate all of the bits needed by the universal hash function.

The universal hash function that we use is called UHASH. It combines several software-optimized algorithms into a multi-layered structure. The algorithm is moderately complex. Some of this complexity comes from extensive speed optimizations.

For the pseudorandom function we use the block cipher of the Advanced Encryption Standard (AES).

The UMAC32 parameters, considered in this implementation are:

                                    UMAC32
                                    ------
         WORD-LEN                        4
         UMAC-OUTPUT-LEN                 8
         L1-KEY-LEN                   1024
         UMAC-KEY-LEN                   16
         ENDIAN-FAVORITE               BIG *
         L1-OPERATIONS-SIGN       UNSIGNED
 

Please note that this UMAC32 differs from the one described in the paper by the ENDIAN-FAVORITE value.

References:

  1. UMAC: Message Authentication Code using Universal Hashing.
    T. Krovetz, J. Black, S. Halevi, A. Hevia, H. Krawczyk, and P. Rogaway.

Field Summary

static String
NONCE_MATERIAL
Property name of the user-supplied Nonce.

Fields inherited from class gnu.javax.crypto.mac.BaseMac

name, truncatedSize, underlyingHash

Fields inherited from interface gnu.javax.crypto.mac.IMac

MAC_KEY_MATERIAL, TRUNCATED_SIZE

Constructor Summary

UMac32()
Trivial 0-arguments constructor.

Method Summary

Object
clone()
Returns a clone copy of this instance.
byte[]
digest()
Completes the MAC by performing final operations such as padding and resetting the instance.
void
init(Map<K,V> attributes)
Initialising a UMAC instance consists of defining values for the following parameters:
  1. Key Material: as the value of the attribute entry keyed by IMac.MAC_KEY_MATERIAL.
int
macSize()
Returns the output length in bytes of this MAC algorithm.
void
reset()
Resets the algorithm instance for re-initialisation and use with other characteristics.
boolean
selfTest()
A basic test.
void
update(byte b)
Continues a MAC operation using the input byte.
void
update(byte[] b, int offset, int len)
Continues a MAC operation, by filling the buffer, processing data in the algorithm's MAC_SIZE-bit block(s), updating the context and count, and buffering the remaining bytes in buffer for the next operation.

Methods inherited from class gnu.javax.crypto.mac.BaseMac

clone, digest, init, macSize, name, reset, selfTest, update, update

Methods inherited from class java.lang.Object

clone, equals, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

NONCE_MATERIAL

public static final String NONCE_MATERIAL
Property name of the user-supplied Nonce. The value associated to this property name is taken to be a byte array.
Field Value:
"gnu.crypto.umac.nonce.material"

Constructor Details

UMac32

public UMac32()
Trivial 0-arguments constructor.

Method Details

clone

public Object clone()
Returns a clone copy of this instance.
Specified by:
clone in interface IMac
Overrides:
clone in interface BaseMac
Returns:
a clone copy of this instance.

digest

public byte[] digest()
Completes the MAC by performing final operations such as padding and resetting the instance.
Specified by:
digest in interface IMac
Overrides:
digest in interface BaseMac
Returns:
the array of bytes representing the MAC value.

init

public void init(Map<K,V> attributes)
            throws InvalidKeyException,
                   IllegalStateException
Initialising a UMAC instance consists of defining values for the following parameters:
  1. Key Material: as the value of the attribute entry keyed by IMac.MAC_KEY_MATERIAL. The value is taken to be a byte array containing the user-specified key material. The length of this array, if/when defined SHOULD be exactly equal to KEY_LEN.
  2. Nonce Material: as the value of the attribute entry keyed by NONCE_MATERIAL. The value is taken to be a byte array containing the user-specified nonce material. The length of this array, if/when defined SHOULD be (a) greater than zero, and (b) less or equal to 16 (the size of the AES block).

For convenience, this implementation accepts that not both parameters be always specified.

  • If the Key Material is specified, but the Nonce Material is not, then this implementation, re-uses the previously set Nonce Material after (a) converting the bytes to an unsigned integer, (b) incrementing the number by one, and (c) converting it back to 16 bytes.
  • If the Nonce Material is specified, but the Key Material is not, then this implementation re-uses the previously set Key Material.

This method throws an exception if no Key Material is specified in the input map, and there is no previously set/defined Key Material (from an earlier invocation of this method). If a Key Material can be used, but no Nonce Material is defined or previously set/defined, then a default value of all-zeroes shall be used.

Specified by:
init in interface IMac
Overrides:
init in interface BaseMac
Parameters:
attributes - one or both of required parameters.
Throws:
InvalidKeyException - the key material specified is not of the correct length.

macSize

public int macSize()
Returns the output length in bytes of this MAC algorithm.
Specified by:
macSize in interface IMac
Overrides:
macSize in interface BaseMac
Returns:
the output length in bytes of this MAC algorithm.

reset

public void reset()
Resets the algorithm instance for re-initialisation and use with other characteristics. This method always succeeds.
Specified by:
reset in interface IMac
Overrides:
reset in interface BaseMac

selfTest

public boolean selfTest()
A basic test. Ensures that the MAC of a pre-determined message is equal to a known pre-computed value.
Specified by:
selfTest in interface IMac
Overrides:
selfTest in interface BaseMac
Returns:
true if the implementation passes a basic self-test. Returns false otherwise.

update

public void update(byte b)
Continues a MAC operation using the input byte.
Specified by:
update in interface IMac
Overrides:
update in interface BaseMac
Parameters:
b - the input byte to digest.

update

public void update(byte[] b,
                   int offset,
                   int len)
Continues a MAC operation, by filling the buffer, processing data in the algorithm's MAC_SIZE-bit block(s), updating the context and count, and buffering the remaining bytes in buffer for the next operation.
Specified by:
update in interface IMac
Overrides:
update in interface BaseMac
Parameters:
offset - start of meaningful bytes in input block.

UMac32.java -- Copyright (C) 2001, 2002, 2003, 2006 Free Software Foundation, Inc. This file is a part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.