javax.crypto
Class MacSpi

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

Direct Known Subclasses:

HMac

public abstract class MacSpi

extends Object

Service Provider Interface (SPI) for the MAC class.

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 SPI MAC class and has to be implemented by a particular provider for every MAC algorithm to be supported.

This class contains a set of abstract engine methods which have to be implemented by a provider and are called by their appertaining MAC equivalents for accessing provider specific implementations.

Any application dealing with MAC computation, uses the getInstance method of the MAC class for creating a MAC object.

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

IAIK-JCE supports HMAC computation based on the SHA-1 and Md5 hash algorithms.

Version:

File Revision 17

See Also:

HMac, HMacSha, HMacMd5

Constructor Summary

MacSpi()
Default constructor for creating a MACSpi object.

Method Summary

Object	clone() Returns a clone of this MAC object.
protected abstract byte[]	engineDoFinal() Returns the calculated MAC value.
protected abstract int	engineGetMacLength() Returns the length of the calculated MAC value in bytes.
protected abstract void	engineInit(Key key, AlgorithmParameterSpec params) Initializes this Mac object with given secret key and algorithm parameter specification.
protected abstract 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.
protected abstract void	engineUpdate(byte input) Processes the given byte.
protected abstract 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 java.lang.Object

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

Constructor Detail

MacSpi

public MacSpi()

Default constructor for creating a MACSpi object.

Method Detail

engineGetMacLength

protected abstract int engineGetMacLength()

Returns the length of the calculated MAC value in bytes.

Returns:

the MAC value length in bytes.

engineInit

protected abstract void engineInit(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

engineUpdate

protected abstract void engineUpdate(byte input)

Processes the given byte.

Parameters:

input - the byte to be processed.

engineUpdate

protected abstract void engineUpdate(byte[] input,
                                     int offset,
                                     int len)

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

engineDoFinal

protected abstract 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.

Returns:

the calculated MAC value in a byte array

engineReset

protected abstract 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.

clone

public Object clone()
             throws CloneNotSupportedException

Returns a clone of this MAC object.

Overrides:

clone in class Object

Returns:

a clone of this MAC object

Throws:

CloneNotSupportedException - if this provider-specific MAC implementation is not cloneable