MaskGenerationAlgorithm (6.0 API Documentation)

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 pseudo-random: 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 17

Constructor Summary

Constructors
Modifier Constructor and Description

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

Constructors
Modifier	Constructor and Description
`protected`	`MaskGenerationAlgorithm(java.lang.String algorithm)` Creates a MaskGenerationAlgorithm with the given algorithm name.

Method Summary

Methods
Modifier and Type	Method and Description
`java.lang.String`	`getAlgorithm()` Gets the name of the mask generation algorithm this engine implements.
`static MaskGenerationAlgorithm`	`getInstance(java.lang.String algorithm)` Creates an MaskGenerationAlgorithm engine for the given algorithm name.
`static MaskGenerationAlgorithm`	`getInstance(java.lang.String algorithm, java.security.Provider provider)` Creates a provider-specific MaskGenerationAlgorithm engine for the given algorithm name.
`static MaskGenerationAlgorithm`	`getInstance(java.lang.String algorithm, java.lang.String providerName)` Creates a provider-specific MaskGenerationAlgorithm engine for the given algorithm name.
`java.security.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(java.security.AlgorithmParameters params)` Sets any algorithm parameters required by this MGF engine.
`void`	`setParameters(java.security.spec.AlgorithmParameterSpec paramSpec)` Sets any algorithm parameters required by this MGF engine.
`java.lang.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(java.lang.String algorithm)
```
    Creates a MaskGenerationAlgorithm with the given algorithm name.
- Method Detail
  - getInstance
```
public static final MaskGenerationAlgorithm getInstance(java.lang.String algorithm)
                                                 throws java.security.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:
    
    java.security.NoSuchAlgorithmException - if no implementation for the requested algorithm is available
  - getInstance
```
public static final MaskGenerationAlgorithm getInstance(java.lang.String algorithm,
                                  java.lang.String providerName)
                                                 throws java.security.NoSuchAlgorithmException,
                                                        java.security.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
    providerName - the name of the provider whose MGF implementation is requested
    
    Throws:
    
    java.security.NoSuchAlgorithmException - if no implementation for the requested algorithm is available
    
    java.security.NoSuchProviderException - if the requested provider is not available
  - getInstance
```
public static final MaskGenerationAlgorithm getInstance(java.lang.String algorithm,
                                  java.security.Provider provider)
                                                 throws java.security.NoSuchAlgorithmException,
                                                        java.security.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 provider whose MGF implementation is requested
    
    Throws:
    
    java.security.NoSuchAlgorithmException - if no implementation for the requested algorithm is available
    
    java.lang.IllegalArgumentException - if provider is null
    
    java.security.NoSuchProviderException
  - 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 offset 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 java.lang.String getAlgorithm()
```
    Gets the name of the mask generation algorithm this engine implements.
    
    Returns:
    the mask generation algorithm name
  - toString
```
public java.lang.String toString()
```
    Returns a string representation.
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    a string representation
  - setParameters
```
public final void setParameters(java.security.spec.AlgorithmParameterSpec paramSpec)
                         throws java.security.InvalidAlgorithmParameterException
```
    Sets any algorithm parameters required by this MGF engine.
    
    Parameters:
    paramSpec - the parameters to be set
    
    Throws:
    
    java.security.InvalidAlgorithmParameterException - if the parameters are inappropriate for this engine or are invalid
  - setParameters
```
public final void setParameters(java.security.AlgorithmParameters params)
                         throws java.security.InvalidAlgorithmParameterException
```
    Sets any algorithm parameters required by this MGF engine.
    
    Parameters:
    params - the parameters to be set
    
    Throws:
    
    java.security.InvalidAlgorithmParameterException - if the parameters are inappropriate for this engine or are invalid
  - getParameters
```
public final java.security.AlgorithmParameters getParameters()
```
    Gets the algorithm parameters required by this MGF engine.
    
    Returns:
    the parameters used by this engine

Class MaskGenerationAlgorithm

Constructor Summary

Method Summary

Methods inherited from class iaik.pkcs.pkcs1.MaskGenerationAlgorithmSpi

Methods inherited from class java.lang.Object

Constructor Detail

MaskGenerationAlgorithm

Method Detail

getInstance

getInstance

getInstance

mask

reset

getAlgorithm

toString

setParameters

setParameters

getParameters