iaik.pkcs.pkcs5

Class PBMAC1ParameterSpec

java.lang.Object

iaik.pkcs.pkcs5.PBMAC1ParameterSpec

All Implemented Interfaces:

java.security.spec.AlgorithmParameterSpec

Direct Known Subclasses:

PBKDF2PBMAC1ParameterSpec

public class PBMAC1ParameterSpec
extends java.lang.Object
implements java.security.spec.AlgorithmParameterSpec

This class represents a parameter specification for 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 a PBMAC1ParameterSpec 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();
 AlgorithmID pbkdf2 = (AlgorithmID)AlgorithmID.pbkf2.clone();
 int iterationCount = 10000;
 byte[] salt = new byte[32];
 PBKDF2ParameterSpec pbkdf2ParamSpec = new PBKDF2ParameterSpec(salt, iterationCount,keyLength);
 pbkdf2ParamSpec.setPrf(prf);
 PBMAC1ParameterSpec paramSpec = new PBMAC1ParameterSpec(pbkdf2, messageAuthScheme);
 paramSpec.setKDFParameterSpec(pbkdf2ParamSpec);
 

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);
 

Version:

File Revision 24

See Also:

PBMAC1Parameters, PBKDF2PBMAC1ParameterSpec, PBKDF2ParameterSpec, PBMAC1

Constructor Summary

Constructors

Constructor and Description
PBMAC1ParameterSpec(AlgorithmID keyDerivationFunc, AlgorithmID messageAuthScheme) Creates a PBMAC1ParameterSpec for the given key derivation function and message authentication scheme.

Method Summary

Modifier and Type	Method and Description
java.security.spec.AlgorithmParameterSpec	getKDFParameterSpec() Gets the parameters of the (PBKFD2) key derivation function.
AlgorithmID	getKeyDerivationFunction() Gets the AlgorithmID of the key derivation function.
AlgorithmID	getMessageAuthScheme() Gets the AlgorithmID of the message authentication scheme.
void	setKDFParameterSpec(java.security.spec.AlgorithmParameterSpec kdfParamSpec) Sets the parameters of the (PBKDF2) key derivation function.

Methods inherited from class java.lang.Object

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

Constructor Detail

PBMAC1ParameterSpec

public PBMAC1ParameterSpec(AlgorithmID keyDerivationFunc,
                           AlgorithmID messageAuthScheme)

Creates a PBMAC1ParameterSpec for the given key derivation function and message authentication scheme.

Parameters:

keyDerivationFunc - the key derivation function

messageAuthScheme - the message authentication scheme

Method Detail

getKeyDerivationFunction

public AlgorithmID getKeyDerivationFunction()

Gets the AlgorithmID of the key derivation function.

Returns:

the AlgorithmID of the key derivation function

getMessageAuthScheme

public AlgorithmID getMessageAuthScheme()

Gets the AlgorithmID of the message authentication scheme.

Returns:

the AlgorithmID of the message authentication scheme

getKDFParameterSpec

public java.security.spec.AlgorithmParameterSpec getKDFParameterSpec()
                                                              throws java.security.InvalidAlgorithmParameterException

Gets the parameters of the (PBKFD2) key derivation function.

Returns:

the parameters of the key derivation function

Throws:

java.security.InvalidAlgorithmParameterException - if an error occurs when getting the KDF parameters

setKDFParameterSpec

public void setKDFParameterSpec(java.security.spec.AlgorithmParameterSpec kdfParamSpec)
                         throws java.security.InvalidAlgorithmParameterException

Sets the parameters of the (PBKDF2) key derivation function.

The parameters are also added to the AlgorithmID of the key derivation function.

Parameters:

kdfParamSpec - the parameters of the (PBKDF2) key derivation function

Throws:

java.security.InvalidAlgorithmParameterException - if the parameters cannot be added to the KDF AlgorithmID