com.oracle.crypto.mac

Class Mac

java.lang.Object

com.oracle.crypto.mac.Mac

public abstract class Mac
extends java.lang.Object

Mac interface provides applications the functionality of Message Authentication Code (MAC) algorithm, or "keyed hashing". A MAC provides a way to check the integrity of information transmitted over or stored in an unreliable medium, based on a secret key. Typically, message authentication codes are used between two parties that share a secret secretKey in order to validate information transmitted between these parties. A MAC mechanism that is based on cryptographic hash functions is referred to as HMAC. HMAC can be used with any cryptographic hash function, e.g., MD5 or SHA-1, in combination with a secret shared secretKey. HMAC is specified in RFC 2104. Every implementation of the Java platform is required to support the following standard Mac algorithms:

• HmacMD5
• HmacSHA1
• HmacSHA256

Additionally, implementation may or may not support the following Mac algorithms:

• HmacSHA384
• HmacSHA512
• HmacDESCBC
• HmacAESCBC

A Mac object starts out initialized in getInstance(java.lang.String) method. The secret secretKey must be set with init(java.security.Key) method, prior to process any data. The data is processed with update(byte[], int, int) method. At any point reset can be called to reset the digest to its initialized state. Once all the data to be updated has been updated, the doFinal() method should be called to complete the hash computation and output the result. The doFinal() method can be called once for a given number of updates. After doFinal() has been called, the Mac object is reset to its initialized state.

Therefore, here are three phases to the use of a Mac object for message authentication:

1. Initialization with:
   • the algorithm name (see above)
   • a secret secretKey, which initializes the Mac (see init(java.security.Key))

2. Updating. See the update(byte[], int, int) method.
3. Computing a MAC hash for all updated bytes. See the doFinal() method.

Hash function-based MAC algorithms are defined under RFC 2104. CBC-mode DES based MAC algorithm is implemented in accordance with FIPS PUB 113 (obsolete) definition. AES-CMAC algorithm is defined under RFC 4493 and recommended by NIST SP 800-38B. It's strongly advised to favour AES-CMAC over DES-CBC-MAC for variable length messages.

See Also:

RFC 2104 #2, NIST SP 800-38B

Constructor Summary

Constructors

Constructor and Description
Mac()

Method Summary

Modifier and Type	Method and Description
abstract byte[]	doFinal() Returns the MAC bytes of all the data consumed and reset the object to its initialized state.
abstract java.lang.String	getAlgorithm() Gets the MAC algorithm.
static Mac	getInstance(java.lang.String algorithm) Generates a Mac object that implements the specified digest algorithm.
abstract int	getMacLength() Gets the byte length of the MAC result.
abstract void	init(java.security.Key key) Initialize this object for hashing.
abstract void	reset() Resets the Mac object its initialized state.
abstract void	update(byte[] data, int off, int len) Updates the data to be secretKey-hashed, using the specified array of bytes, starting at the specified offset.

Methods inherited from class java.lang.Object

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

Constructor Detail

Mac

public Mac()

Method Detail

getAlgorithm

public abstract java.lang.String getAlgorithm()

Gets the MAC algorithm.

Returns:

the algorithm string

getMacLength

public abstract int getMacLength()

Gets the byte length of the MAC result.

Returns:

the byte length of MAC data

getInstance

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

Generates a Mac object that implements the specified digest algorithm.

Parameters:

algorithm - the standard name of the algorithm requested. See Appendix A in the Java Cryptography Architecture API Specification & Reference for information about standard algorithm names.

Returns:

the new Mac object.

Throws:

java.security.NoSuchAlgorithmException - if the algorithm is not available in the environment.

init

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

Initialize this object for hashing. If this method is called again with a different argument, it negates the effect of this call.

Parameters:

key - a raw secret secretKey to use in MAC computation.

Throws:

java.security.InvalidKeyException - invalid secret key

reset

public abstract void reset()
                    throws IllegalMacStateException

Resets the Mac object its initialized state. Use init(java.security.Key) to set a different secretKey.

Throws:

IllegalMacStateException - Mac object cannot be reset to initialized state

doFinal

public abstract byte[] doFinal()
                        throws IllegalMacStateException,
                               java.security.DigestException

Returns the MAC bytes of all the data consumed and reset the object to its initialized state.

A call to this method resets the MAC object to the state it was in when previously initialized for hashing via a call to init(Key). That is, the object is reset and available to generate another MAC with the same Key, if desired, via new calls to update and doFinal.

Returns:

the MAC bytes of the hashing operation result.

Throws:

IllegalMacStateException - if this MAC object is not initialized properly or if this MAC algorithm is unable to process the input data provided.

java.security.DigestException - corresponding digest algorithm cannot be initialized with the current key

update

public abstract void update(byte[] data,
                            int off,
                            int len)
                     throws IllegalMacStateException

Updates the data to be secretKey-hashed, using the specified array of bytes, starting at the specified offset.

Parameters:

data - the array of bytes.

off - the offset to start from in the array of bytes.

len - the number of bytes to use, starting at offset.

Throws:

IllegalMacStateException - if this MAC object is not initialized properly.