iaik.security.mac

Class PBMAC1

java.lang.Object

javax.crypto.MacSpi

iaik.security.mac.PBMAC1

public class PBMAC1
extends javax.crypto.MacSpi

This class implements the PKCS#5 PBMAC1 password-based Message Authentication Scheme as specified by PKCS#5 v2.1 (RFC 8018).

PBMAC1 uses a message authentication scheme like HMAC for calculating the mac value with a secret key derived from a password by using a key derivation function like PBKDF2. The message authentication scheme and key derivation function to be used have to be specified by PBMAC1 parameters (see RFC 8018):

 PBMAC1-params ::=  SEQUENCE {
   keyDerivationFunc AlgorithmIdentifier {{PBMAC1-KDFs}},
   messageAuthScheme AlgorithmIdentifier {{PBMAC1-MACs}} }

   PBMAC1-MACs ALGORITHM-IDENTIFIER ::= { ... }
 

Currently only PBKDF2 is supported as key derivation function.

After having created a Mac instance by calling a proper getInstance factory method the Mac engine has to be initialized by mac key and parameters specifying message authentication scheme and PBKDF2 parameters to be used. For deriving the mac key from a password at first a PBEKey has to be created from the password by using a PBMAC1 key factory:

 char[] password = ...;
 // create a KeySpec from our password
 PBEKeySpec keySpec = new PBEKeySpec(password);
 // use the "PKCS#5" or "PBE" SecretKeyFactory to convert the password
 SecretKeyFactory kf = SecretKeyFactory.getInstance("PBMAC1", "IAIK");
 // create an appropriate PbeKey
 PBEKey pbeKey = (PBEKey)kf.generateSecret(keySpec);
 

Now use a PBMAC1ParameterSpec or PBKDF2PBMAC1ParameterSpec to specify message authentication scheme and PBKDF2 parameters, e.g.:

 AlgorithmID messageAuthScheme = (AlgorithmID)AlgorithmID.hMAC_SHA256.clone();
 AlgorithmID prf = (AlgorithmID)AlgorithmID.hMAC_SHA256.clone();
 int iterationCount = 10000;
 byte[] salt = new byte[32];
 PBKDF2ParameterSpec pbkdf2ParamSpec = new PBKDF2ParameterSpec(salt, iterationCount,keyLength);
 pbkdf2ParamSpec.setPrf(prf);
 PBKDF2PBMAC1ParameterSpec paramSpec = new PBKDF2PBMAC1ParameterSpec(pbkdf2ParamSpec, messageAuthScheme);
 

Next create the PBMAC1 engine and initialize it with key and parameters:

 Mac mac = Mac.getInstance("PBMAC1", "IAIK");
 mac.init(pbeKey, paramSpec);
 

When using the same (HMAC) algorithm as message authentication scheme and pseudo random function for PBKDF2, it might be more convenient to immediately initialize the Mac engine with PBKDF2 parameters:

 mac.init(pbeKey, pbkdf2ParamSpec);
 

Finally calculate the mac value by applying the data to be integrity protected by one (or more) calls to the update methods. The mac computation is concluded by calling the doFinal method. If the data can be processed without calling any update method, doFinal can be called immediately after initializing the Mac object:

 byte[] data = ...;
 byte[] macValue = mac.doFinal(data);
 

After the MAC finally has been calculated, the Mac engine 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 engine.

Version:

File Revision 24

See Also:

PBMAC1ParameterSpec, PBMAC1Parameters, PBKDF2PBMAC1ParameterSpec, PBKDF2ParameterSpec

Constructor Summary

Constructors

Constructor and Description
PBMAC1() Creates a new PBMAC1 Mac engine.

Method Summary

Modifier and Type	Method and Description
byte[]	engineDoFinal() Returns the calculated MAC value.
int	engineGetMacLength() Returns the length of the calculated MAC value in bytes.
void	engineInit(java.security.Key key, java.security.spec.AlgorithmParameterSpec params) Initializes this Mac object with the given PBE key and algorithm parameter specification.
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.
void	engineUpdate(byte input) Processes the given data byte.
void	engineUpdate(byte[] input, int offset, int len) Processes the given number of data bytes, supplied in a byte array starting at the given position.

Methods inherited from class javax.crypto.MacSpi

clone, engineUpdate

Methods inherited from class java.lang.Object

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

Constructor Detail

PBMAC1

public PBMAC1()

Creates a new PBMAC1 Mac engine.

This constructor shall not be called by an application. Applications shall use a getInstance() factory method for creating a PBMAC1 Mac engine:

 Mac mac = Mac.getInstance("PBMAC1", "IAIK");
 

Method Detail

engineInit

public void engineInit(java.security.Key key,
                       java.security.spec.AlgorithmParameterSpec params)
                throws java.security.InvalidKeyException,
                       java.security.InvalidAlgorithmParameterException

Initializes this Mac object with the given PBE key and algorithm parameter specification.

The key has to be a PBEKey created from the password using a PBMAC1 key factory. The parameters have to specify the underlying message authentication scheme and the PBKDF2 parameters for deriving the mac key by using the PBKDF2 key derivation function.

Specified by:

engineInit in class javax.crypto.MacSpi

Parameters:

key - the PBE key for initializing this Mac engine, must be a PBEKey

params - the algorithm parameter specification, must be a PBMAC1ParameterSpec, PBKDF2PBMAC1ParameterSpec, or PBKDF2ParameterSpec (when using the same (HMAC) algorithm as message authentication scheme and pseudo random function for PBKDF2).

Throws:

java.security.InvalidKeyException - if the given key cannot be used for initializing this Mac engine (e.g. is not a PBEKey)

java.security.InvalidAlgorithmParameterException - if this Mac engine cannot be initialized with the given parameters (e.g. if they are not a PBMAC1ParameterSpec, PBKDF2PBMAC1ParameterSpec, or PBKDF2ParameterSpec)

engineUpdate

public void engineUpdate(byte input)

Processes the given data byte.

Specified by:

engineUpdate in class javax.crypto.MacSpi

Parameters:

input - the data byte to be processed.

engineUpdate

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

Processes the given number of data bytes, supplied in a byte array starting at the given position.

Specified by:

engineUpdate in class javax.crypto.MacSpi

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

engineReset

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

Specified by:

engineReset in class javax.crypto.MacSpi

engineGetMacLength

public int engineGetMacLength()

Returns the length of the calculated MAC value in bytes.

Specified by:

engineGetMacLength in class javax.crypto.MacSpi

Returns:

the MAC value length in bytes.

engineDoFinal

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

Specified by:

engineDoFinal in class javax.crypto.MacSpi

Returns:

the calculated MAC value in a byte array