iaik.pkcs.pkcs1
Class MaskGenerationAlgorithm

java.lang.Object
  |
  +--iaik.pkcs.pkcs1.MaskGenerationAlgorithmSpi
        |
        +--iaik.pkcs.pkcs1.MaskGenerationAlgorithm

Direct Known Subclasses:

MGF1

public abstract class MaskGenerationAlgorithm

extends MaskGenerationAlgorithmSpi

JCA compliant engine that provides the functionality of a PKCS#1v2.1 mask generation function.

Mask generation functions are used by the PKCS#1v2.1 PSS signature and OAEP encryption schemes:

 A mask generation function takes an octet string of variable length
 and a desired output length as input, and outputs an octet string of
 the desired length.  There may be restrictions on the length of the
 input and output octet strings, but such bounds are generally very
 large.  Mask generation functions are deterministic; the octet string
 output is completely determined by the input octet string.  The
 output of a mask generation function should be pseudorandom: Given
 one part of the output but not the input, it should be infeasible to
 predict another part of the output.  The provable security of RSAES-
 OAEP and RSASSA-PSS relies on the random nature of the output of the
 mask generation function, which in turn relies on the random nature
 of the underlying hash.
 

This class implements both interfaces of the JCA, the API as used by the application and the SPI (engine methods) as implemented by the provider.

An application wishing to use some specific mask generation function, first tries to get an engine instance for the desired algorithm (e.g. MGF1):

 MaskGenerationAlgorithm mgf = MaskGenerationAlgorithm.getInstance("MGF1", "IAIK");
 

After supplying the engine with parameters (if required), method mask has to be called to "mask" the input data by XORing it with the mask generated from some seed by using the mask generation algorithm. For example, the only mask generation function specified by PKCS#1, MGF1, is based on a hash algorithm which may be supplied as MGF1ParameterSpec:

 AlgorithmID hashAlgID = ...;
 MGF1ParameterSpec paramSpec = new MGF1ParameterSpec(hashAlgID);
 // optionally set the hash engine to be used:
 MessageDigest hashEngine = ...;
 paramSpec.setHashEngine(hashEngine);
 // set the parameters
 mgf.setParameters(paramSpec);
 // mask the data
 byte[] data = ...;
 byte[] dataOff = ...;
 byte[] seed = ...;
 int seedOff = ...;
 int seedLen = ...;
 int maskLen = ...;
 mgf.mask(seed, seedOff, seedLen, maskLen, data, dataOff);
 

Version:

File Revision 19

Constructor Summary

protected

MaskGenerationAlgorithm(String algorithm) Creates a MaskGenerationAlgorithm with the given algorithm name.

Method Summary

String	getAlgorithm() Gets the name of the mask generation algorithm this engine implements.
static MaskGenerationAlgorithm	getInstance(String algorithm) Creates an MaskGenerationAlgorithm engine for the given algorithm name.
static MaskGenerationAlgorithm	getInstance(String algorithm, String provider) Creates a provider-specific MaskGenerationAlgorithm engine for the given algorithm name.
AlgorithmParameters	getParameters() Gets the algorithm parameters required by this MGF engine.
void	mask(byte[] mgfSeed, int mgfSeedOff, int mgfSeedLen, int maskLen, byte[] dst, int dstOff) Uses the mask generation function to generate maskLen bytes from the supplied seed mgfSeed[mgfSeedOff:mgfSeedLen] and XORs the result with dst[off:maskLen].
void	reset() Resets this engine to the state before mask has been called.
void	setParameters(AlgorithmParameters params) Sets any algorithm parameters required by this MGF engine.
void	setParameters(AlgorithmParameterSpec paramSpec) Sets any algorithm parameters required by this MGF engine.
String	toString() Returns a string representation.

Methods inherited from class iaik.pkcs.pkcs1.MaskGenerationAlgorithmSpi

clone, engineGetParameters, engineMask, engineReset, engineSetParameters, engineSetParameters

Methods inherited from class java.lang.Object

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

Constructor Detail

MaskGenerationAlgorithm

protected MaskGenerationAlgorithm(String algorithm)

Creates a MaskGenerationAlgorithm with the given algorithm name.

Method Detail

getInstance

public static final MaskGenerationAlgorithm getInstance(String algorithm)
                                                 throws NoSuchAlgorithmException

Creates an MaskGenerationAlgorithm engine for the given algorithm name.

Parameters:

algorithm - the name of the mgf algorithm for which an engine should be created

Throws:

NoSuchAlgorithmException - if no implementation for the requested algorithm is available

getInstance

public static final MaskGenerationAlgorithm getInstance(String algorithm,
                                                        String provider)
                                                 throws NoSuchAlgorithmException,
                                                        NoSuchProviderException

Creates a provider-specific MaskGenerationAlgorithm engine for the given algorithm name.

Parameters:

algorithm - the name of the mgf algorithm for which an engine should be created

provider - the name of the provider whose MGF implementation is requested

Throws:

NoSuchAlgorithmException - if no implementation for the requested algorithm is available

NoSuchProviderException - if the requested provider is not available

mask

public final void mask(byte[] mgfSeed,
                       int mgfSeedOff,
                       int mgfSeedLen,
                       int maskLen,
                       byte[] dst,
                       int dstOff)

Uses the mask generation function to generate maskLen bytes from the supplied seed mgfSeed[mgfSeedOff:mgfSeedLen] and XORs the result with dst[off:maskLen].

A call to this method resets this engine to the state before mask has been called.

Parameters:

mgfSeed - the seed from which the mask is generated

mgfSeedOff - the offest indicating the start position within the seed array

mgfSeedLen - the actual number of seed bytes

maskLen - the number of required mask bytes

dst - the destination array to which to XOR the mask result

dstOff - the offset indicating the start position within the destination array

reset

public final void reset()

Resets this engine to the state before mask has been called.

getAlgorithm

public final String getAlgorithm()

Gets the name of the mask generation algorithm this engine implements.

Returns:

the mask generation algorithm name

toString

public String toString()

Returns a string representation.

Overrides:

toString in class Object

Returns:

a string representation

setParameters

public final void setParameters(AlgorithmParameterSpec paramSpec)
                         throws InvalidAlgorithmParameterException

Sets any algorithm parameters required by this MGF engine.

Parameters:

paramSpec - the parameters to be set

Throws:

InvalidAlgorithmParameterException - if the parameters are inappropriate for this engine or are invalid

setParameters

public final void setParameters(AlgorithmParameters params)
                         throws InvalidAlgorithmParameterException

Sets any algorithm parameters required by this MGF engine.

Parameters:

params - the parameters to be set

Throws:

InvalidAlgorithmParameterException - if the parameters are inappropriate for this engine or are invalid

getParameters

public final AlgorithmParameters getParameters()

Gets the algorithm parameters required by this MGF engine.

Returns:

the parameters used by this engine