iaik.security.mac
Class HMac

java.lang.Object
  |
  +--javax.crypto.MacSpi
        |
        +--iaik.security.mac.HMac

Direct Known Subclasses:

HMacMd5, HMacRipeMd128, HMacRipeMd160, HMacSha, HMacSha256, HMacSha384, HMacSha512

public class HMac

extends MacSpi

This class extends the javax.crypto.MACSpi class for providing the functionality of the HMAC(Keyed-Hashing for Message Authentication) algorithm, as specified in RFC 2104.

This class itself is extended by HMacMd5 and HMacSha for using the Md5 respectively SHA message digest algorithm as hash functions for HMAC computation.

Both hash functions stated above process data in blocks of 64 bytes. For HMAC computation based on Md5 or SHA, the secret authentication key to be used may be of any length up to 64 bytes. If the key is longer than 64 bytes, it is hashed by the actual hash function in use (before feeding it to the HMAC algorithm), yielding to a key length denoted by the hash size of the actual hash function (i.e. 16 bytes for Md5 and 20 bytes for SHA). It is recommended by RFC 2104 not to use keys of a length shorter than the hash output size of the hash function in use.

Any application dealing with MAC computation, uses the getInstance method of the MAC class for creating a MAC object.

A Message Authentiction Code (MAC) denotes a cryptocraphic checksum, which is derived by processing some given message (or the authentication elements of the message) using a secret key. A MAC computation that involves some cryptographic hash function is denoted as HMAC (as specified in RFC 2104). Since a secret key is used for processing the message, the resulting (H)MAC only can be verified with the same key, meaning that - in contrast to digital signing where anyone can verify a signature by using the public key matching to the private key that have been used for signing - only the holder of the same secret key ís able to verifiy the MAC. Commonly, only the addressed receiver(s) of the message should hold the same secret key.

MAC computation can be used for providing integrity without secrecy. The sender uses his secret key for computing the MAC of the message to be sent, appends the MAC to the original message and sends both to the communication partner. The receiver recalculates the MAC and compares it with the transmitted MAC to ensure the integrity of the received data.

An application wishing to perform a MAC computation, at first has to create a MAC object by instantiating the MAC class through a proper getInstance factory method thereby specifying the MAC algorithm to be used. Calculating, for instance, a HMAC based on the SHA-1 hash algorithm, may be initiated as follows:

 MAC sha_HMAC = MAC.getInstance("HMAC/SHA");
 

After properly initializing the MAC object with one entity´s secret key, the data to be processed is applied by one (or more) calls to the update methods. The MAC computation is concluded by using doFinal. If the data can be processed without calling any update method, doFinal can be called immediately after initializing the MAC object:

 sha_HMAC.init(secret_key);
 byte[] mac_data = sha_HMAC.doFinal(data);
 

After the MAC finally has been calculated, the MAC object automatically is reset for being able to be used for further MAC computations, either by using the same secret key again, or using a new key by properly re-initializing this MAC object.

IAIK-JCE supports HMAC computation based on the SHA-1 and Md5 hash algorithms.

Version:

File Revision 20

See Also:

HMacSha, HMacMd5

Constructor Summary

HMac(String hashAlgorithm)
Creates a new HMac for the specified hash algorithm.

HMac(String hashAlgorithm, int blockSize)
Creates a new HMac for the specified hash algorithm.

Method Summary

byte[]	engineDoFinal() Returns the calculated MAC value.
int	engineGetMacLength() Returns the length of the calculated MAC value in bytes.
void	engineInit(Key key, AlgorithmParameterSpec params) Initializes this Mac object with given secret key and algorithm parameter specification.
void	engineReset() Resets this Mac object for being able to be used for further MAC computations, either by using the same secret key again, or using a new key by properly re-initializing this MAC object.
void	engineUpdate(byte input) Processes the given byte.
void	engineUpdate(byte[] input, int offset, int len) Processes the given number of bytes, supplied in a byte array starting at the given position.

Methods inherited from class javax.crypto.MacSpi

clone

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HMac

public HMac(String hashAlgorithm)
     throws NoSuchAlgorithmException

Creates a new HMac for the specified hash algorithm.

This constructor is called by every subclass for specifying the particular hash algorithm to be used for HMAC computation. The block size of the underlying hash algorithm defaults to 64;

Parameters:

hashAlgorithm - the hash algorithm to use

Throws:

NoSuchAlgorithmException - if the specified hash algorithm is not supported

HMac

public HMac(String hashAlgorithm,
            int blockSize)
     throws NoSuchAlgorithmException

Creates a new HMac for the specified hash algorithm.

This constructor maybe called by any subclass for specifying the particular hash algorithm to be used for HMAC computation.

Parameters:

hashAlgorithm - the hash algorithm to use

blockSize - the block size of the hash algorithm

Throws:

NoSuchAlgorithmException - if the specified hash algorithm is not supported

Method Detail

engineInit

public void engineInit(Key key,
                       AlgorithmParameterSpec params)
                throws InvalidKeyException

Initializes this Mac object with given secret key and algorithm parameter specification.

The length of the authentication key to be used may be of any length up to 64 bytes, which is equal to the block size data is processed by the Md5 or SHA hash algorithms, both used by IAIK-JCE for hash computations within the HMAC algorithm. If the key is longer than 64 bytes, it is autiomatically hashed by the actual hash function in use before feeding it to the HMAC algorithm, yielding to a key length denoted by the hash size of the actual hash function (i.e. 16 bytes for Md5 and 20 bytes for SHA). It is recommended by RFC 2104 not to use keys of a length shorter than the hash output size of the hash function in use.

Overrides:

engineInit in class MacSpi

Parameters:

key - the secret key for initializing this MAC object.

params - the algorithm parameter specification; ignored because not required.

Throws:

InvalidKeyException - if the given key cannot be used for initializing this MAC object

engineUpdate

public void engineUpdate(byte input)

Processes the given byte.

Overrides:

engineUpdate in class MacSpi

Parameters:

input - the byte to be processed.

engineUpdate

public void engineUpdate(byte[] input,
                         int offset,
                         int len)

Processes the given number of bytes, supplied in a byte array starting at the given position.

Overrides:

engineUpdate in class MacSpi

Parameters:

input - the byte array holding the data to be processed

offset - the offset indicating the start position within the input byte array

len - the number of bytes to be processed

engineReset

public void engineReset()

Resets this Mac object for being able to be used for further MAC computations, either by using the same secret key again, or using a new key by properly re-initializing this MAC object.

Overrides:

engineReset in class MacSpi

engineGetMacLength

public int engineGetMacLength()

Returns the length of the calculated MAC value in bytes.

Overrides:

engineGetMacLength in class MacSpi

Returns:

the MAC value length in bytes.

engineDoFinal

public byte[] engineDoFinal()

Returns the calculated MAC value. After the MAC finally has been calculated, the MAC object is reset for being able to be used for further MAC computations, either by using the same secret key again, or using a new key by properly re-initializing this MAC object.

Overrides:

engineDoFinal in class MacSpi

Returns:

the calculated MAC value in a byte array