javax.crypto
Class Mac

java.lang.Object
  |
  +--javax.crypto.Mac

public class Mac

extends java.lang.Object

implements java.lang.Cloneable

Engine class for algorithm independent MAC object creation.

Attention: This is not a SUN implementation!

This class has been developed by IAIK according to the documentation publicly available.
For SUN´s documentation of this class see http://java.sun.com/security/JCE1.2/spec/apidoc/index.html

This class represents the super API class to be used for providing data integrity based on a Message Authentication Code (MAC).

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 this 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.

See Also:

HMac, HMacSha, HMacMd5

Constructor Summary

protected

Mac(MacSpi macSpi, Provider provider, java.lang.String algorithm) Creates a MAC object.

Method Summary

java.lang.Object	clone() Returns a clone of this MAC object.
byte[]	doFinal() Returns the calculated MAC value.
byte[]	doFinal(byte[] input) Returns the calculated MAC value after finishing this MAC computation by processing the given data, supplied in a byte array.
void	doFinal(byte[] output, int outOffset) Finishes this MAC computation and writes the calculated MAC value to the given output byte array, beginning at the given position.
java.lang.String	getAlgorithm() Returns the standard name of the MAC algorithm in use.
static Mac	getInstance(java.lang.String algorithm) Returns the default provider MAC object implementation of the specified algorithm.
static Mac	getInstance(java.lang.String algorithm, java.lang.String provider) Returns a Mac object for the specified algorithm, implemented by the given provider.
int	getMacLength() Returns the length of the created MAC value in bytes.
Provider	getProvider() Returns the provider supplying this Mac object.
void	init(Key key) Initializes this Mac object with the given secret key.
void	init(Key key, AlgorithmParameterSpec params) Initializes this Mac object with given secret key and algorithm parameter specification.
void	reset() 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	update(byte input) Processes the given byte.
void	update(byte[] input) Processes the given data, supplied as a byte array
void	update(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 java.lang.Object

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

Constructor Detail

Mac

protected Mac(MacSpi macSpi,
              Provider provider,
              java.lang.String algorithm)

Creates a MAC object. Only internally used for creating a MAC object. Applications shall use one of the getInstance factory methods for obtaining a MAC object.

Parameters:

macSpi - the SPI MAC implementation of the given provider

provider - the provider

algorithm - the MAC algorithm to be used

Method Detail

getAlgorithm

public final java.lang.String getAlgorithm()

Returns the standard name of the MAC algorithm in use.

Returns:

the standard name of the algorithm

getInstance

public static final Mac getInstance(java.lang.String algorithm)
                             throws NoSuchAlgorithmException

Returns the default provider MAC object implementation of the specified algorithm. If the default provider does not support the requested algorithm, other available provider packages are searched for it.

Parameters:

algorithm - the name of the requested MAC algorithm

Returns:

the Mac object for the requested algorithm

Throws:

NoSuchAlgorithmException - if the requested MAC algorithm is not implemented.

getInstance

public static final Mac getInstance(java.lang.String algorithm,
                                    java.lang.String provider)
                             throws NoSuchAlgorithmException,
                                    NoSuchProviderException

Returns a Mac object for the specified algorithm, implemented by the given provider.

Parameters:

algorithm - the name of the requested MAC algorithm

provider - the name of the provider implementing this algorithm

Throws:

NoSuchAlgorithmException - if the requested MAC algorithm is not implemented by the given provider

NoSuchProviderException - if the requested provider cannot be fetched

getProvider

public final Provider getProvider()

Returns the provider supplying this Mac object.

Returns:

the provider of this Mac object.

getMacLength

public final int getMacLength()

Returns the length of the created MAC value in bytes.

Returns:

the MAC value length in bytes.

init

public final void init(Key key)
                throws InvalidKeyException

Initializes this Mac object with the given secret key.

Parameters:

key - the secret key for initializing this MAC object.

Throws:

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

init

public final void init(Key key,
                       AlgorithmParameterSpec params)
                throws InvalidKeyException,
                       InvalidAlgorithmParameterException

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

Parameters:

key - the secret key for initializing this MAC object.

params - the algorithm parameter specification.

Throws:

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

InvalidAlgorithmParameterException - if the given algorithm parameters do not match to this MAC object

update

public final void update(byte input)
                  throws java.lang.IllegalStateException

Processes the given byte.

Parameters:

input - the byte to be processed.

Throws:

java.lang.IllegalStateException - if this MAC object is not in a proper state for performing an update operation

update

public final void update(byte[] input)
                  throws java.lang.IllegalStateException

Processes the given data, supplied as a byte array

Parameters:

input - byte array holding the data to be processed

Throws:

java.lang.IllegalStateException - if this MAC object is not in a proper state for performing an update operation

update

public final void update(byte[] input,
                         int offset,
                         int len)
                  throws java.lang.IllegalStateException

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

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

Throws:

java.lang.IllegalStateException - if this MAC object is not in a proper state for performing an update operation

doFinal

public final byte[] doFinal()
                     throws java.lang.IllegalStateException

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.

Returns:

the calculated MAC value in a byte array

Throws:

java.lang.IllegalStateException - if this cipher is in not in a proper state for performing a doFinal operation

doFinal

public final void doFinal(byte[] output,
                          int outOffset)
                   throws ShortBufferException,
                          java.lang.IllegalStateException

Finishes this MAC computation and writes the calculated MAC value to the given output byte array, beginning at the given position. 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.

Parameters:

output - the byte array for holding the calculated MAC value

outOffset - - the offset indicating the start position within the output byte array to which the calculated MAC value is written

Throws:

ShortBufferException - if the given output buffer is too small for holding the result

java.lang.IllegalStateException - if this cipher is in not in a proper state for performing a doFinal operation

doFinal

public final byte[] doFinal(byte[] input)
                     throws java.lang.IllegalStateException

Returns the calculated MAC value after finishing this MAC computation by processing the given data, supplied in a byte array. 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.

Parameters:

input - the byte array holding the data to be processed

Returns:

the calculated MAC value in a byte array

Throws:

java.lang.IllegalStateException - if this cipher is in not in a proper state for performing a doFinal operation

reset

public final void reset()

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.

clone

public final java.lang.Object clone()
                             throws java.lang.CloneNotSupportedException

Returns a clone of this MAC object.

Overrides:

clone in class java.lang.Object

Returns:

a clone of this MAC object

Throws:

java.lang.CloneNotSupportedException - if this provider-specific MAC implementation is not cloneable