iaik.pkcs.pkcs1

Class RSAOaepParameters

java.lang.Object

java.security.AlgorithmParametersSpi

iaik.pkcs.pkcs1.PKCS1AlgorithmParameters

iaik.pkcs.pkcs1.RSAOaepParameters

public class RSAOaepParameters
extends PKCS1AlgorithmParameters

Algorithm parameters for the PKCS#1 RSASES-OAEP encryption scheme.

PKCS#1v2.1 defines the following parameters for the OAEP signature scheme:

 RSASES-OAEP-params :: = SEQUENCE {
      hashAlgorithm            [0] HashAlgorithm     DEFAULT sha1,
      maskGenerationAlgorithm  [1] MaskGenAlgorithm  DEFAULT mgf1SHA1,
      pSourceAlgorithm         [2] PSourceAlgorithm  DEFAULT pSpecifiedEmpty,
 }
 
 HashAlgorithm ::= Algorithmidentifier { {OAEP-PSSDigestAlgorithms} }
 
 MaskGenAlgorithm ::= AlgorithmIdentifier { {PKCS1MGFAlgorithms} }
 
 PSourceAlgorithm ::= AlgorithmIdentifier { {PKCS1PSourceAlgorithms} }
 

By default OAEP uses SHA-1 as hash function, MGF1 (with SHA-1 as hash function parameter) as mask generation algorithm, and id-pSpecified as PSourceAlgorithm (with an empty OCTET STRING as parameter).

RSAOaepParameters can be generated provider independently by calling one of the AlgorithmParameters.getInstance methods. Subsequently the new AlgorithmParameters object must be initialized with a proper RSA-OAEP parameter specification or a DER encoded byte array, e.g.:

 RSAOaepParameterSpec oaepParamSpec = ...;
 AlgorithmParameters params = AlgorithmParameters.getInstance("RSAES-OAEP", "IAIK");
 params.init(oaepParamSpec);
 

respectively:

 byte[] encodedOaepParams = ...;
 AlgorithmParameters params = AlgorithmParameters.getInstance("RSAES-OAEP", "IAIK");
 params.init(encodedOaepParams);
 

For obtaining OAEP parameters in transparent representation from an opaque RSAOaepParameters object, the getParameterSpec method can be used; for obtaining the parameters as DER encoded ASN.1 object, use method getEncoded:

 RSAOaepParameterSpec oaepParamSpec = (RSAOaepParameterSpec) params
     .getParameterSpec(RSAOaepParameterSpec.class);
 

respectively

 byte[] encodedOaepParams = params.getEncoded();
 

Version:

File Revision 14

See Also:

RSAOaepParameterSpec, AlgorithmParameters

Constructor Summary

Constructors

Constructor and Description
RSAOaepParameters() The default constructor.

Method Summary

Methods

Modifier and Type	Method and Description
void	decode(ASN1Object asn1Params) Initializes this RSAOaepParameters object from the given ASN1Object.
protected byte[]	engineGetEncoded() Returns the parameters as DER byte array.
protected byte[]	engineGetEncoded(java.lang.String format) Returns the parameters as a DER byte array.
protected java.security.spec.AlgorithmParameterSpec	engineGetParameterSpec(java.lang.Class paramSpec) Returns the RSA-OAEP parameters as transparent parameter specification of the given class type.
protected void	engineInit(java.security.spec.AlgorithmParameterSpec paramSpec) Initializes this RSAOaepParameters from the given RSAOaepParameterSpec.
protected void	engineInit(byte[] params) Initializes this RSAOaepParameters object from the given DER encoded byte array.
protected void	engineInit(byte[] params, java.lang.String format) Inits the parameters from an DER encoded byte array.
protected java.lang.String	engineToString() Returns a String representation of this object.
static boolean	getEncodeDefaultValues() This method shows if parameter values should be encoded even if they have the default values; e.g.
static void	setEncodeDefaultValues(boolean encode) With this method, the application can define that parameter values should be encoded even if they have the default values; e.g.
static void	setUseSHA1ForMGF1WithJCAStandardName(boolean useSHA1) Sets whether to use SHA-1 for MGF1 if hash algorithm and mask generation function name are specified in the padding scheme name.
ASN1Object	toASN1Object() Gets an ASN.1 representation of this RSA OAEP parameters.

Methods inherited from class java.lang.Object

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

Constructor Detail

RSAOaepParameters

public RSAOaepParameters()

The default constructor. Only internally used for creating a RSAOaepParameters object. Applications shall use one of the AlgorithmParameters.getInstance factory methods for obtaining RSAOaepParameters.

Method Detail

setEncodeDefaultValues

public static void setEncodeDefaultValues(boolean encode)

With this method, the application can define that parameter values should be encoded even if they have the default values; e.g. if the hashAlgorithm is sha1.

Note that the settings given by the RSAOaepParameterSpec have higher priority.

Note that only a value of false results in a fully correct DER encoding, because DER encoding required default values to be omitted.

Parameters:

encode - true to encode default values, false to omit default values in the encoding.

See Also:

RSAOaepParameterSpec.setEncodeDefaultValues(Boolean), RSAOaepParameterSpec.getEncodeDefaultValues()

getEncodeDefaultValues

public static boolean getEncodeDefaultValues()

This method shows if parameter values should be encoded even if they have the default values; e.g. if the hashAlgorithm is sha1.

Note that the settings given by the RSAOaepParameterSpec have higher priority.

Per default, this is false.

Note that only a value of false results in a fully correct DER encoding, because DER encoding required default values to be omitted.

Returns:

true if default values are encoded, false if default values are omitted.

See Also:

RSAOaepParameterSpec.setEncodeDefaultValues(Boolean), RSAOaepParameterSpec.getEncodeDefaultValues()

setUseSHA1ForMGF1WithJCAStandardName

public static void setUseSHA1ForMGF1WithJCAStandardName(boolean useSHA1)

Sets whether to use SHA-1 for MGF1 if hash algorithm and mask generation function name are specified in the padding scheme name. When using RSA OAEP the required parameters may be specified in one of two ways:

1. Hash algorithm and mask generation function may be specified by the padding scheme name (OAEPWith<digest>And<mgf>Padding) immediately when instantiating the Cipher engine, e.g.:

          Cipher cipher = Cipher.getInstance("RSA/ECB/OAEPWithSHA-256AndMGF1Padding");
          

2. The parameters may be specified as AlgorithmParameterSpec object, either as iaik.pkcs.pkcs1.RSAOaepParameterSpec or as javax.crypto.spec.OAEPParameterSpec object, e.g.:
   • iaik.pkcs.pkcs1.RSAOaepParameterSpec:

                  // hash, mgf and pSource algorithm parameters
                  AlgorithmID hashID = (AlgorithmID) AlgorithmID.sha256.clone();
                  AlgorithmID mgfID = (AlgorithmID) AlgorithmID.mgf1.clone();
                  mgfID.setParameter(hashID.toASN1Object());
                  AlgorithmID pSourceID = (AlgorithmID) AlgorithmID.pSpecified.clone();
                  pSourceID.setParameter(new OCTET_STRING());
                  // create the RSAOaepParameterSpec
                  RSAOaepParameterSpec oaepParamSpec = 
                    new RSAOaepParameterSpec(hashID, mgfID, pSourceID);
                  Cipher rsa = Cipher.getInstance("RSA/ECB/OAEPPadding", "IAIK");
                  PublicKey pubKey = ...;
                  rsa.init(Cipher.ENCRYPT_MODE, pubKey, oaepParamSpec);
                  byte[] encrypted = rsa.doFinal(data);
                  

   • javax.crypto.spec.OAEPParameterSpec:

                  String hashAlg = "SHA-256";
                  String mgfAlg = "MGF1";
                  MGF1ParameterSpec mgfParameterSpec = new MGF1ParameterSpec(hashAlg);
                  PSource.PSpecified pSpecified = PSource.PSpecified.DEFAULT;
                  OAEPParameterSpec oaepParameterSpec = 
                    new  OAEPParameterSpec(hashAlg, mgfAlg, mgfParameterSpec, pSpecified);
                  Cipher rsa = Cipher.getInstance("RSA/ECB/OAEPPadding", "IAIK");
                  PublicKey pubKey = ...;
                  rsa.init(Cipher.ENCRYPT_MODE, pubKey, oaepParamSpec);
                  byte[] encrypted = rsa.doFinal(data);               
                  

When using the first option (specifying hash algorithm name and mask generation function name in the padding scheme name (OAEPWith<digest>And<mgf>Padding), the hash algorithm for the MGF1 mask generation function cannot be explicitly specified. Whereas the IAIK provider uses the same hash algorithm for both the RSAES-OAEP en/decryption scheme as well as the MGF1 mask generation function, the SunJCE provider anytime uses SHA-1 as hash algorithm for the MGF1 mask generation function. This means that -- when specifying the hash algorithm name in the padding scheme name -- IAIK and SunJCE provider are only compatible when using SHA-1 as hash algorithm:

 Cipher cipher = Cipher.getInstance("RSA/ECB/OAEPWithSHA-1AndMGF1Padding", "IAIK");
 

In any other case (e.g. "OAEPWithSHA-256AndMGF1Padding") decrypting IAIK encrypted data with the SunJCE provider will fail (and vice verca). To solve the problem the parameters have to be explicitly specified at the en- or decryption side, e.g.:

Encryption:

 Cipher cipher = Cipher.getInstance("RSA/ECB/OAEPWithSHA-256AndMGF1Padding", "IAIK");
 PublicKey pubKey = ...;
 rsa.init(Cipher.ENCRYPT_MODE, pubKey);
 byte[] encrypted = rsa.doFinal(data);
 

Decryption:

 String hashAlg = "SHA-256";
 String mgfAlg = "MGF1";
 MGF1ParameterSpec mgfParameterSpec = new MGF1ParameterSpec(hashAlg);
 PSource.PSpecified pSpecified = PSource.PSpecified.DEFAULT;
 OAEPParameterSpec oaepParameterSpec = 
   new  OAEPParameterSpec(hashAlg, mgfAlg, mgfParameterSpec, pSpecified);
 Cipher rsa = Cipher.getInstance("RSA/ECB/OAEPPadding", "SunJCE");
 PrivateKey privKey = ...;
 rsa.init(Cipher.DECRYPT_MODE, privKey, oaepParamSpec);
 byte[] decrypted = rsa.doFinal(encrypted);               
 

Alternatively you may use this method to globally configure the IAIK provider to anytime use SHA-1 as hash algorithm for the mask generation function regardless of which hash algorithm is specified in the "OAEPWith<digest>And<mgf>Padding" padding scheme name:

 RsaOaepParameters.setUseSHA1ForMGF1WithJCAStandardName(true);
 

Of course this configuration setting will have no effect for Ciphers that are explicitly initialized with OAEP parameters.

Note that the problem only arises due to the possibility of specifying hash algorithm and mask generation function name in the padding scheme name. Generally the sender includes these parameters in the OAEP and MGF1 algorithm identifiers and the receiver parses and uses the parameters from the algorithm ids.

Parameters:

useSHA1 - whether to use SHA-1 for MGF1 or to use the hash algorithm specified in the padding scheme name for MGF1, too

engineGetEncoded

protected byte[] engineGetEncoded()
                           throws java.io.IOException

Returns the parameters as DER byte array.

Specified by:

engineGetEncoded in class java.security.AlgorithmParametersSpi

Returns:

the DER encoded parameters

Throws:

java.io.IOException - if an encoding error occurs

engineGetEncoded

protected byte[] engineGetEncoded(java.lang.String format)
                           throws java.io.IOException

Returns the parameters as a DER byte array.

Format is ignored. Only DER encoding is supported. This method only calls engineGetEncoded(), regardless of what is specified in the format string.

Specified by:

engineGetEncoded in class java.security.AlgorithmParametersSpi

Parameters:

format - the encoding format; ignored

Returns:

the DER encoded parameters

Throws:

java.io.IOException - if an encoding error occurs

toASN1Object

public ASN1Object toASN1Object()

Gets an ASN.1 representation of this RSA OAEP parameters.

Returns:

this RSA OAEP parameters as ASN1Objet

engineGetParameterSpec

protected java.security.spec.AlgorithmParameterSpec engineGetParameterSpec(java.lang.Class paramSpec)
                                                                    throws java.security.spec.InvalidParameterSpecException

Returns the RSA-OAEP parameters as transparent parameter specification of the given class type.

Specified by:

engineGetParameterSpec in class java.security.AlgorithmParametersSpi

Parameters:

paramSpec - the desired parameter specification class (RSAOaepParameterSpec)

Returns:

the parameters as RSAOaepParameterSpec

Throws:

java.security.spec.InvalidParameterSpecException - if the parameters cannot be converted to the desired parameter specification

engineInit

protected void engineInit(java.security.spec.AlgorithmParameterSpec paramSpec)
                   throws java.security.spec.InvalidParameterSpecException

Initializes this RSAOaepParameters from the given RSAOaepParameterSpec.

Overrides:

engineInit in class PKCS1AlgorithmParameters

Parameters:

paramSpec - the parameter specification, which has to be a RSAOaepParameterSpec

Throws:

java.security.spec.InvalidParameterSpecException - if the given parameter specification is not a RSAOaepParameterSpec or OAEPParameterSpec or is invalid

engineInit

protected void engineInit(byte[] params)
                   throws java.io.IOException

Initializes this RSAOaepParameters object from the given DER encoded byte array.

Overrides:

engineInit in class PKCS1AlgorithmParameters

Parameters:

params - the DER encoded byte array

Throws:

java.io.IOException - if an error occurs when decoding the given byte array

decode

public void decode(ASN1Object asn1Params)
            throws CodingException

Initializes this RSAOaepParameters object from the given ASN1Object.

Parameters:

asn1Params - the OAEP parameters in ASN.1 representation

Throws:

CodingException - if an error occurs when parsing the parameters

engineInit

protected void engineInit(byte[] params,
              java.lang.String format)
                   throws java.io.IOException

Inits the parameters from an DER encoded byte array. Format is ignored. Only calls {engineInit(params) for initializing this RSAOaepParameters object from the given DER encoded byte array, regardless of what is specified in the format string.

Specified by:

engineInit in class java.security.AlgorithmParametersSpi

Parameters:

params - the DER encoded byte array

format - the encoding format; ignored

Throws:

java.io.IOException - if an error occurs when decoding the given byte array

engineToString

protected java.lang.String engineToString()

Returns a String representation of this object.

Specified by:

engineToString in class java.security.AlgorithmParametersSpi

Returns:

a String representation this object