javax.crypto

Class Mac

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, String provider) Create an instance of the named algorithm from the named provider.
static Mac	getInstance(String algorithm, Provider provider) Create an instance of the named algorithm from a 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

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

clone

public final Object clone()

Clone this instance, if the underlying implementation supports it.

Returns: A clone of this instance.

Throws: java.lang.CloneNotSupportedException If the underlying implementation is not cloneable.

doFinal

public final byte[] doFinal()

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: java.lang.IllegalStateException If this instnace has not been initialized.

doFinal

public final 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.

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: java.lang.IllegalStateException If this instnace has not been initialized.

doFinal

public final void doFinal(byte[] output, int outOffset)

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.

Returns: The message authentication code.

Throws: java.lang.IllegalStateException If this instnace has not been initialized. javax.crypto.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.

getInstance

public static final Mac getInstance(String algorithm)

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)

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)

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.

getMacLength

public final int getMacLength()

Get the size of the MAC. This is the size of the array returned by {@link #doFinal()} and {@link #doFinal(byte[])}, and the minimum number of bytes that must be available in the byte array passed to {@link #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)

Initialize this MAC with a key and no parameters.

Parameters: key The key to initialize this instance with.

Throws: java.security.InvalidKeyException If the key is unacceptable.

init

public final void init(Key key, AlgorithmParameterSpec params)

Initialize this MAC with a key and parameters.

Parameters: key The key to initialize this instance with. params The algorithm-specific parameters.

Throws: java.security.InvalidAlgorithmParameterException If the algorithm parameters are unacceptable. java.security.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)

Update the computation with a single byte.

Parameters: input The next byte.

Throws: java.lang.IllegalStateException If this instance has not been initialized.

update

public final void update(byte[] input)

Update the computation with a byte array.

Parameters: input The next bytes.

Throws: java.lang.IllegalStateException If this instance has not been initialized.

update

public final void update(byte[] input, int offset, int length)

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: java.lang.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