javax.crypto
Class Mac

java.lang.Object
  extended by javax.crypto.Mac
All Implemented Interfaces:
Cloneable

public class Mac
extends Object
implements Cloneable

This class implements a "message authentication code" (MAC), a method to ensure the integrity of data transmitted between two parties who share a common secret key.

The best way to describe a MAC is as a keyed one-way hash function, which looks like:

D = MAC(K, M)

where K is the key, M is the message, and D is the resulting digest. One party will usually send the concatenation M || D to the other party, who will then verify D by computing D' in a similar fashion. If D == D', then the message is assumed to be authentic.


Constructor Summary
protected Mac(MacSpi macSpi, Provider provider, String algorithm)
          Creates a new Mac instance.
 
Method Summary
 Object clone()
          Clone this instance, if the underlying implementation supports it.
 byte[] doFinal()
          Finishes the computation of a MAC and returns the digest.
 byte[] doFinal(byte[] input)
          Finishes the computation of a MAC with a final byte array (or computes a MAC over those bytes only) and returns the digest.
 void doFinal(byte[] output, int outOffset)
          Finishes the computation of a MAC and places the result into the given array.
 String getAlgorithm()
          Returns the name of this MAC algorithm.
static Mac getInstance(String algorithm)
          Create an instance of the named algorithm from the first provider with an appropriate implementation.
static Mac getInstance(String algorithm, Provider provider)
          Create an instance of the named algorithm from a provider.
static Mac getInstance(String algorithm, String provider)
          Create an instance of the named algorithm from the named provider.
 int getMacLength()
          Get the size of the MAC.
 Provider getProvider()
          Get the provider of the underlying implementation.
 void init(Key key)
          Initialize this MAC with a key and no parameters.
 void init(Key key, AlgorithmParameterSpec params)
          Initialize this MAC with a key and parameters.
 void reset()
          Reset this instance.
 void update(byte input)
          Update the computation with a single byte.
 void update(byte[] input)
          Update the computation with a byte array.
 void update(byte[] input, int offset, int length)
          Update the computation with a portion of a byte array.
 void update(ByteBuffer buffer)
          Update this MAC with the remaining bytes in the given buffer
 
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,
              String algorithm)
Creates a new Mac instance.

Parameters:
macSpi - The underlying MAC implementation.
provider - The provider of this implementation.
algorithm - The name of this MAC algorithm.
Method Detail

getInstance

public static final Mac getInstance(String algorithm)
                             throws NoSuchAlgorithmException
Create an instance of the named algorithm from the first provider with an appropriate implementation.

Parameters:
algorithm - The name of the algorithm.
Returns:
An appropriate Mac instance, if the specified algorithm is implemented by a provider.
Throws:
NoSuchAlgorithmException - If no implementation of the named algorithm is installed.
IllegalArgumentException - if algorithm is null or is an empty string.

getInstance

public static final Mac getInstance(String algorithm,
                                    String provider)
                             throws NoSuchAlgorithmException,
                                    NoSuchProviderException
Create an instance of the named algorithm from the named provider.

Parameters:
algorithm - The name of the algorithm.
provider - The name of the provider.
Returns:
An appropriate Mac instance, if the specified algorithm is implemented by the named provider.
Throws:
NoSuchAlgorithmException - If the named provider has no implementation of the algorithm.
NoSuchProviderException - If the named provider does not exist.
IllegalArgumentException - if either algorithm or provider is null, or if algorithm is an empty string.

getInstance

public static final Mac getInstance(String algorithm,
                                    Provider provider)
                             throws NoSuchAlgorithmException
Create an instance of the named algorithm from a provider.

Parameters:
algorithm - The name of the algorithm.
provider - The provider.
Returns:
An appropriate Mac instance, if the specified algorithm is implemented by the provider.
Throws:
NoSuchAlgorithmException - If the provider has no implementation of the algorithm.
IllegalArgumentException - if either algorithm or provider is null, or if algorithm is an empty string.

doFinal

public final byte[] doFinal()
                     throws IllegalStateException
Finishes the computation of a MAC and returns the digest.

After this method succeeds, it may be used again as just after a call to init, and can compute another MAC using the same key and parameters.

Returns:
The message authentication code.
Throws:
IllegalStateException - If this instnace has not been initialized.

doFinal

public final byte[] doFinal(byte[] input)
                     throws IllegalStateException
Finishes the computation of a MAC with a final byte array (or computes a MAC over those bytes only) and returns the digest.

After this method succeeds, it may be used again as just after a call to init, and can compute another MAC using the same key and parameters.

Parameters:
input - The bytes to add.
Returns:
The message authentication code.
Throws:
IllegalStateException - If this instnace has not been initialized.

doFinal

public final void doFinal(byte[] output,
                          int outOffset)
                   throws IllegalStateException,
                          ShortBufferException
Finishes the computation of a MAC and places the result into the given array.

After this method succeeds, it may be used again as just after a call to init, and can compute another MAC using the same key and parameters.

Parameters:
output - The destination for the result.
outOffset - The index in the output array to start.
Throws:
IllegalStateException - If this instnace has not been initialized.
ShortBufferException - If output is not large enough to hold the result.

getAlgorithm

public final String getAlgorithm()
Returns the name of this MAC algorithm.

Returns:
The MAC name.

getMacLength

public final int getMacLength()
Get the size of the MAC. This is the size of the array returned by doFinal() and doFinal(byte[]), and the minimum number of bytes that must be available in the byte array passed to doFinal(byte[],int).

Returns:
The MAC length.

getProvider

public final Provider getProvider()
Get the provider of the underlying implementation.

Returns:
The provider.

init

public final void init(Key key)
                throws InvalidKeyException
Initialize this MAC with a key and no parameters.

Parameters:
key - The key to initialize this instance with.
Throws:
InvalidKeyException - If the key is unacceptable.

init

public final void init(Key key,
                       AlgorithmParameterSpec params)
                throws InvalidAlgorithmParameterException,
                       InvalidKeyException
Initialize this MAC with a key and parameters.

Parameters:
key - The key to initialize this instance with.
params - The algorithm-specific parameters.
Throws:
InvalidAlgorithmParameterException - If the algorithm parameters are unacceptable.
InvalidKeyException - If the key is unacceptable.

reset

public final void reset()
Reset this instance. A call to this method returns this instance back to the state it was in just after it was initialized.


update

public final void update(byte input)
                  throws IllegalStateException
Update the computation with a single byte.

Parameters:
input - The next byte.
Throws:
IllegalStateException - If this instance has not been initialized.

update

public final void update(byte[] input)
                  throws IllegalStateException
Update the computation with a byte array.

Parameters:
input - The next bytes.
Throws:
IllegalStateException - If this instance has not been initialized.

update

public final void update(byte[] input,
                         int offset,
                         int length)
                  throws IllegalStateException
Update the computation with a portion of a byte array.

Parameters:
input - The next bytes.
offset - The index in input to start.
length - The number of bytes to update.
Throws:
IllegalStateException - If this instance has not been initialized.

update

public final void update(ByteBuffer buffer)
Update this MAC with the remaining bytes in the given buffer

Parameters:
buffer - The input buffer.
Since:
1.5

clone

public final Object clone()
                   throws CloneNotSupportedException
Clone this instance, if the underlying implementation supports it.

Overrides:
clone in class Object
Returns:
A clone of this instance.
Throws:
CloneNotSupportedException - If the underlying implementation is not cloneable.
See Also:
Cloneable