iaik.security.mac

Class HMac

java.lang.Object

javax.crypto.MacSpi

iaik.security.mac.HMac

Direct Known Subclasses:

HMacGOST, HMacMd5, HMacRipeMd128, HMacRipeMd160, HMacSha, HMacSha224, HMacSha256, HMacSha3_224, HMacSha3_256, HMacSha3_384, HMacSha3_512, HMacSha384, HMacSha512, HMacSha512_224, HMacSha512_256, HMacWhirlpool

public class HMac
extends javax.crypto.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.

For HMAC computation based the secret authentication key to be used may be of any length up to the hash algorithm block size. If the key is longer than the block size, it is hashed by the 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 Authentication Code (MAC) denotes a cryptographic 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 is able to verify 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.

Version:

File Revision 24

See Also:

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

Constructor Summary

Constructors

Constructor and Description
HMac(java.lang.String hashAlgorithm) Creates a new HMac for the specified hash algorithm.
HMac(java.lang.String hashAlgorithm, int blockSize) Creates a new HMac for the specified hash algorithm.

Method Summary

Methods

Modifier and Type	Method and Description
byte[]	engineDoFinal() Returns the calculated MAC value.
int	engineGetMacLength() Returns the length of the calculated MAC value in bytes.
void	engineInit(java.security.Key key, java.security.spec.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, engineUpdate

Methods inherited from class java.lang.Object

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

Constructor Detail

HMac

public HMac(java.lang.String hashAlgorithm)
     throws java.security.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:

java.security.NoSuchAlgorithmException - if the specified hash algorithm is not supported

HMac

public HMac(java.lang.String hashAlgorithm,
    int blockSize)
     throws java.security.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:

java.security.NoSuchAlgorithmException - if the specified hash algorithm is not supported

Method Detail

engineInit

public void engineInit(java.security.Key key,
              java.security.spec.AlgorithmParameterSpec params)
                throws java.security.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 hash algorithm block size. If the key is longer than the block size, it is automatically 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.

Specified by:

engineInit in class javax.crypto.MacSpi

Parameters:

key - the secret key for initializing this MAC object.

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

Throws:

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

engineUpdate

public void engineUpdate(byte input)

Processes the given byte.

Specified by:

engineUpdate in class javax.crypto.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.

Specified by:

engineUpdate in class javax.crypto.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.

Specified by:

engineReset in class javax.crypto.MacSpi

engineGetMacLength

public int engineGetMacLength()

Returns the length of the calculated MAC value in bytes.

Specified by:

engineGetMacLength in class javax.crypto.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.

Specified by:

engineDoFinal in class javax.crypto.MacSpi

Returns:

the calculated MAC value in a byte array