javax.crypto

Class Mac

java.lang.Object

javax.crypto.Mac

All Implemented Interfaces:

java.lang.Cloneable

public class Mac
extends java.lang.Object
implements java.lang.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

Constructors

Modifier	Constructor and Description
protected	Mac(MacSpi macSpi, java.security.Provider provider, java.lang.String algorithm) Creates a new Mac instance.

Method Summary

Methods

Modifier and Type	Method and Description
java.lang.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.
java.lang.String	getAlgorithm() Returns the name of this MAC algorithm.
static Mac	getInstance(java.lang.String algorithm) Create an instance of the named algorithm from the first provider with an appropriate implementation.
static Mac	getInstance(java.lang.String algorithm, java.security.Provider provider) Create an instance of the named algorithm from a provider.
static Mac	getInstance(java.lang.String algorithm, java.lang.String provider) Create an instance of the named algorithm from the named provider.
int	getMacLength() Get the size of the MAC.
java.security.Provider	getProvider() Get the provider of the underlying implementation.
void	init(java.security.Key key) Initialize this MAC with a key and no parameters.
void	init(java.security.Key key, java.security.spec.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(java.nio.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,
   java.security.Provider provider,
   java.lang.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(java.lang.String algorithm)
                             throws java.security.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:

java.security.NoSuchAlgorithmException - If no implementation of the named algorithm is installed.

java.lang.IllegalArgumentException - if algorithm is null or is an empty string.

getInstance

public static final Mac getInstance(java.lang.String algorithm,
              java.lang.String provider)
                             throws java.security.NoSuchAlgorithmException,
                                    java.security.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:

java.security.NoSuchAlgorithmException - If the named provider has no implementation of the algorithm.

java.security.NoSuchProviderException - If the named provider does not exist.

java.lang.IllegalArgumentException - if either algorithm or provider is null, or if algorithm is an empty string.

getInstance

public static final Mac getInstance(java.lang.String algorithm,
              java.security.Provider provider)
                             throws java.security.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:

java.security.NoSuchAlgorithmException - If the provider has no implementation of the algorithm.

java.lang.IllegalArgumentException - if either algorithm or provider is null, or if algorithm is an empty string.

doFinal

public final byte[] doFinal()
                     throws java.lang.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:

java.lang.IllegalStateException - If this instnace has not been initialized.

doFinal

public final byte[] doFinal(byte[] input)
                     throws java.lang.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:

java.lang.IllegalStateException - If this instnace has not been initialized.

doFinal

public final void doFinal(byte[] output,
           int outOffset)
                   throws java.lang.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:

java.lang.IllegalStateException - If this instnace has not been initialized.

ShortBufferException - If output is not large enough to hold the result.

getAlgorithm

public final java.lang.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 java.security.Provider getProvider()

Get the provider of the underlying implementation.

Returns:

The provider.

init

public final void init(java.security.Key key)
                throws java.security.InvalidKeyException

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(java.security.Key key,
        java.security.spec.AlgorithmParameterSpec params)
                throws java.security.InvalidAlgorithmParameterException,
                       java.security.InvalidKeyException

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)
                  throws java.lang.IllegalStateException

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)
                  throws java.lang.IllegalStateException

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

java.lang.IllegalStateException - If this instance has not been initialized.

update

public final void update(java.nio.ByteBuffer buffer)

Update this MAC with the remaining bytes in the given buffer

Parameters:

buffer - The input buffer.

Since:

1.5

clone

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

Clone this instance, if the underlying implementation supports it.

Overrides:

clone in class java.lang.Object

Returns:

A clone of this instance.

Throws:

java.lang.CloneNotSupportedException - If the underlying implementation is not cloneable.

See Also:

Cloneable