The Mac Class

Creating a Mac Object

Like other engine classes in the API, Mac objects are created using the getInstance factory methods of the Mac class. A factory method is a static method that returns an instance of a class, in this case, an instance of Mac, which provides the requested MAC algorithm.

getInstance takes as its argument the name of a MAC algorithm. Optionally, a package provider name can be specified:

 public static Mac getInstance(String algorithm);

 public static Mac getInstance(String algorithm,
 String provider);

If just an algorithm name is specified, the system will determine if there is an implementation of the requested MAC algorithm available in the environment, and if there is more than one, whether there is a preferred one.

If both an algorithm name and a package provider are specified, the system will determine if there is an implementation of the requested MAC algorithm in the package requested, and throw an exception if there is not.

Initializing a Mac Object

A Mac object is always initialized with a (secret) key and can optionally be initialized with a set of parameters, depending on the underlying MAC algorithm.

To initialize a Mac object, call one of its init methods:

 public void init(Key key);

 public void init(Key key, AlgorithmParameterSpec params);

You can initialize your Mac object with any (secret-)key object that implements the javax.crypto.SecretKey interface. This object could be one that is returned by javax.crypto.KeyGenerator.generateKey(), or one that is the result of a key agreement protocol, as returned by javax.crypto.KeyAgreement.generateSecret(), or an instance of javax.crypto.spec.SecretKeySpec.

With some MAC algorithms, the (secret-)key algorithm associated with the (secret-)key object used to initialize the Mac object does not matter (this is the case with the HMAC-MD5 and HMAC-SHA1 implementations of the IBMJCE provider). With others, however, the (secret-)key algorithm does matter, and an InvalidKeyException is thrown if a (secret-)key object with an inappropriate (secret-)key algorithm is used.

Computing a MAC

A MAC can be computed in one step (single-part operation) or in multiple steps (multiple-part operation). A multiple-part operation is useful if you do not know in advance how long the data is going to be, or if the data is too long to be stored in memory all at once.

To compute the MAC of some data in a single step, call the following doFinal method:

 public byte[] doFinal(byte[] input);

To compute the MAC of some data in multiple steps, call one of the update methods:

 public void update(byte input);

 public void update(byte[] input);

 public void update(byte[] input, int inputOffset, int inputLen);

A multiple-part operation must be terminated by the doFinal method listed previously (if there is still some input data remaining for the last step), or by one of the following doFinal methods (if there is no input data remaining for the last step) :

 public byte[] doFinal();

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