iaik.security.rsa

Class RSAOaepPrivateKey

java.lang.Object

iaik.pkcs.pkcs8.PrivateKeyInfo

iaik.security.rsa.RSAPrivateKey

iaik.security.rsa.RSAOaepPrivateKey

All Implemented Interfaces:

ASN1Type, java.io.Serializable, java.lang.Cloneable, java.security.interfaces.RSAKey, java.security.interfaces.RSAPrivateCrtKey, java.security.interfaces.RSAPrivateKey, java.security.Key, java.security.PrivateKey

public class RSAOaepPrivateKey
extends RSAPrivateKey

This class implements a RSAES-OAEP private key according to RFC 4055. This class is derived from iaik.pkcs.pkcs8.PrivateKeyInfo for supporting the PKCS#8 Private Key Information Standard for RSA-OAEP private keys. This class implements the java.security.interfaces.RSAPrivateKey interface for providing the functionality of a private key, as used for decryption based on the RSAES-OAEP encryption scheme as specified by PKCS#1v2.1.

The ASN.1 object identifier for RSAES-OAEP key derived from PKCS-1:

 pkcs-1  OBJECT IDENTIFIER  ::=  { iso(1) member-body(2)
                         us(840) rsadsi(113549) pkcs(1) 1 }
                         
 id-RSAES-OAEP  OBJECT IDENTIFIER  ::=  { pkcs-1 7 }                        
 

This corresponds to the OID string "1.2.840.113549.1.1.7".

A RSAES-OAEP private key differs from an ordinary PKCS#1 RSA private key only in that a RSAES-OAEP key may contain OAEP parameters; modulus, privateExponent and CRT (Chinese Remainder Theorem) fields are encoded in the same way as ASN.1 SEQUENCE according to PKCS#1:

 RSAPrivateKey ::= SEQUENCE {
   version Version, -- a INTEGER version number; 0 for this standard
   modulus INTEGER, -- n
   publicExponent INTEGER, -- e
   privateExponent INTEGER, -- d
   prime1 INTEGER, -- primeP (p) (first prime factor of n)
   prime2 INTEGER, -- primeQ (q) (second prime factor of n)
   exponent1 INTEGER, -- primeExponentP: d mod (p - 1)
   exponent2 INTEGER, -- primeExponentQ: d mod (q - 1)
   crtCoefficient INTEGER -- Chinese Remainder Theorem ((inverse of q) mod p) }
 

If a private RSAES-OAEP key does not contain parameters it may be used for OAEP based decryption with any OAEP parameters. However, if a RSAES-OAEP key contains OAEP parameters it must be only used with the hash algorithm and mask generation function that are specified by its parameters (see RFC 4055):

 RSAES-OAEP-params  ::=  SEQUENCE  {
   hashFunc          [0] AlgorithmIdentifier DEFAULT
                            sha1Identifier,
   maskGenFunc       [1] AlgorithmIdentifier DEFAULT
                            mgf1SHA1Identifier,
   pSourceFunc       [2] AlgorithmIdentifier DEFAULT
                            pSpecifiedEmptyIdentifier  }


  pSpecifiedEmptyIdentifier  AlgorithmIdentifier  ::=
                      { id-pSpecified, nullOctetString }

  nullOctetString  OCTET STRING (SIZE (0))  ::=  { ''H }
 

An application wishing to create a RSAOaepPrivateKey to be used for OAEP based encryption with the RSA algorithm, uses a proper getInstance method of the java.security.KeyPairGenerator class, which subsequently maybe casted to RSAOaepKeyPairGenerator for performing an algorithm-specific initialization with proper RSAES-OAEP parameters. If an algorithm-specific initialization is not required, the cast to RSAOaepKeyPairGenerator can be omitted (in this case no parameters will be included in the RSA-OAEP generated keys and they maybe used with any OAEP parameters).

Generally four steps have to be performed for creating a RSAOaepPrivateKey by using a proper KeyPairGenerator:

• First the KeyPairGenerator has to be instantiated thereby specifying "RSAES-OAEP" as algorithm name:

   KeyPairGenerator keyGen = KeyPairGenerator.getInstance("RSAES-OAEP", "IAIK");
   

• Second, the KeyPairGenerator just created may be initialized using a proper initialize method. For initializing the generator to create keys with a modulus length of, e.g., 2048 bits, this can be explicitly specified (when not initializing the generator explicitly, per default the modulus length is set to 1024 bits):

   keyGen.initialize(2048);
   

• Third the key pair is created by calling generateKeyPair():

   KeyPair keyPair = keyGen.generateKeyPair();
   

• And finally the keys have to be got from the key pair just created:

   RSAOaepPrivateKey privateKey = (RSAOaepPrivateKey)keyPair.getPrivate();
   RSAOaepPublicKey publicKey = (RSAOaepPublicKey)keyPair.getPublic();
   

For performing an algorithm-specific initialization with particular RSA OAEP parameters an explicit cast of the KeyPairGenerator may be necessary for obtaining a specific RSAOaepKeyPairGenerator to be initialized with the desired RSA-OAEP parameters which have to be supplied as RSAOaepParameterSpec object, e.g.:

 RSAOaepKeyPairGenerator rsaOaepkeyGen = (RSAOaepKeyPairGenerator)keyGen;
 // create OAEP parameters for specifying hash, mgf and pSource algorithms:
 // hash, mgf and pSource algorithm ids
 AlgorithmID hashID = (AlgorithmID)AlgorithmID.sha512.clone();
 AlgorithmID mgfID = (AlgorithmID)AlgorithmID.mgf1.clone();
 mgfID.setParameter(hashID.toASN1Object());
 AlgorithmID pSourceID = (AlgorithmID)AlgorithmID.pSpecified.clone();
 pSourceID.setParameter(new OCTET_STRING());
 // hash and mgf engines
 MessageDigest hashEngine = hashID.getMessageDigestInstance();
 MaskGenerationAlgorithm mgfEngine = mgfID.getMaskGenerationAlgorithmInstance();
 MGF1ParameterSpec mgf1ParamSpec = new MGF1ParameterSpec(hashID);
 mgf1ParamSpec.setHashEngine(hashEngine);
 mgfEngine.setParameters(mgf1ParamSpec);
 // create the RSAOaepParameterSpec
 RSAOaepParameterSpec oaepParamSpec = new RSAOaepParameterSpec(hashID, mgfID, pSourceID);
 // set engines
 oaepParamSpec.setHashEngine(hashEngine);
 oaepParamSpec.setMGFEngine(mgfEngine); 
 // initialize key pair generator
 rsaOaepkeyGen.initialize(2048, oaepParamSpec);
 KeyPair keyPair = rsaOaepkeyGen.generateKeyPair();
 RSAOaepPublicKey publicKey = (RSAOaepPublicKey)keyPair.getPublic();
 RSAOaepPrivateKey privateKey = (RSAOaepPrivateKey)keyPair.getPrivate();
 

RSAES-OAEP keys must be only used for en/decryption purposes with the RSAES-OAEP encryption scheme. For using a RSAOaepPublicKey with a Cipher engine, "OAEP" has to be specified as padding scheme when instantiating the Cipher object:

 Cipher rsaOaep = Cipher.getInstance("RSA/ECB/OAEP", "IAIK");
 

When now initializing the Cipher with an RSAES-OAEP key that contains OAEP parameters, the hash algorithm, mask generation function and pSource algorithm are taken from the public key parameters:

 rsaOaep.init(Cipher.ENCRYPT_MODE, publicKey); 
 // the data to be encrypted (e.g. secret key material):
 byte[] data = ...;
 // encrypt data  
 byte[] encrypted = rsaOaep.doFinal(data);
 

For decrypting the encrypted data you will have to use the right RSAES-OAEP RSAOaepPrivateKey:

 Cipher rsaOaep = Cipher.getInstance("RSA/ECB/OAEP", "IAIK");
 rsaOaep.init(Cipher.DECRYPT_MODE, privateKey); 
 // decrypt data  
 byte[] decrypted = rsaOaep.doFinal(encrypted);
 

Version:

File Revision 4

See Also:

PrivateKeyInfo, RSAPrivateKey, RSAOaepPublicKey, RSAOaepKeyPairGenerator, RSAOaepKeyFactory, RSAOaepParameterSpec, RSACipher, RSAPrivateKey, KeyPairGenerator, KeyPair, Serialized Form

Field Summary

Fields inherited from class iaik.pkcs.pkcs8.PrivateKeyInfo

private_key_algorithm

Fields inherited from interface java.security.interfaces.RSAPrivateCrtKey

serialVersionUID

Constructor Summary

Constructors

Constructor and Description
RSAOaepPrivateKey(ASN1Object obj) Creates a new RSAOaepPrivateKey key from an ASN1Object.
RSAOaepPrivateKey(java.math.BigInteger modulus, java.math.BigInteger privateExponent) Creates a new RSAOaepPrivate key from given modulus and private exponent.
RSAOaepPrivateKey(java.math.BigInteger modulus, java.math.BigInteger privateExponent, java.security.spec.AlgorithmParameterSpec oaepParams) Creates a new RSAOaepPrivate key from given modulus and private exponent and OAEP parameters.
RSAOaepPrivateKey(java.math.BigInteger modulus, java.math.BigInteger publicExponent, java.math.BigInteger privateExponent, java.math.BigInteger primeP, java.math.BigInteger primeQ, java.math.BigInteger primeExponentP, java.math.BigInteger primeExponentQ, java.math.BigInteger crtCoefficient) Creates a RSAOaepPrivateKey from the given values.
RSAOaepPrivateKey(java.math.BigInteger modulus, java.math.BigInteger publicExponent, java.math.BigInteger privateExponent, java.math.BigInteger primeP, java.math.BigInteger primeQ, java.math.BigInteger primeExponentP, java.math.BigInteger primeExponentQ, java.math.BigInteger crtCoefficient, java.security.spec.AlgorithmParameterSpec oaepParams) Creates a RSAOaepPrivateKey from the given values and OAEP parameters.
RSAOaepPrivateKey(byte[] pk) Creates a new RSAOaepPrivateKey from a DER encoded ASN.1 data structure.
RSAOaepPrivateKey(java.io.InputStream is) Creates a new RSAOaepPrivateKey from an InputStream.

Method Summary

Methods

Modifier and Type	Method and Description
protected void	decode(byte[] privateKey) Decodes a DER encoded RSAOaepPrivateKey (PKCS#1).
boolean	equals(java.lang.Object obj) Compares this RSAOaepPrivateKey object with the supplied object.
java.lang.String	getAlgorithm() Returns the name of the key algorithm.
java.security.spec.AlgorithmParameterSpec	getParams() Gets the OAEP parameters from this RSA-OAEP key (if included).
java.security.PublicKey	getPublicKey() Returns the public parts (modulus n and public exponent e of this private key.
int	hashCode() Returns a hash code for this object.
java.lang.String	toString() Returns a string that represents the contents of this RSA OAEP private key.
boolean	validateParameters(java.security.spec.AlgorithmParameterSpec rsaOaepParamSpec) Validates the given parameters for this OAEP key.

Methods inherited from class iaik.security.rsa.RSAPrivateKey

crypt, encode, getCrtCoefficient, getModulus, getPrimeExponentP, getPrimeExponentQ, getPrimeP, getPrimeQ, getPrivateExponent, getPublicExponent, parse

Methods inherited from class iaik.pkcs.pkcs8.PrivateKeyInfo

clone, createPrivateKeyInfo, decode, getAlgorithmID, getEncoded, getFormat, getPrivateKey, getPrivateKey, getPrivateKey, getPrivateKey, toASN1Object, writeTo

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.security.Key

getEncoded, getFormat

Constructor Detail

RSAOaepPrivateKey

public RSAOaepPrivateKey(java.math.BigInteger modulus,
                 java.math.BigInteger privateExponent)

Creates a new RSAOaepPrivate key from given modulus and private exponent. Public exponent, prime factors p and q, primeExponentP and primeExponentQ, and Chinese Remainder Theorem Coefficient are set to ZERO (0).
When using this constructor for creating an OAEP key, no parameters are explicitly specified. This means that no parameters will be encoded with the algorithm id of this OAEP key and the key may be used with any OAEP parameters.

Parameters:

privateExponent - the private exponent d

modulus - the modulus n

RSAOaepPrivateKey

public RSAOaepPrivateKey(java.math.BigInteger modulus,
                 java.math.BigInteger privateExponent,
                 java.security.spec.AlgorithmParameterSpec oaepParams)
                  throws java.security.spec.InvalidParameterSpecException

Creates a new RSAOaepPrivate key from given modulus and private exponent and OAEP parameters. Public exponent, prime factors p and q, primeExponentP and primeExponentQ, and Chinese Remainder Theorem Coefficient are set to ZERO (0).
If no parameters are specified no parameters will be encoded with the algorithm id of this OAEP key and the key may be used with any OAEP parameters.

Parameters:

privateExponent - the private exponent d

modulus - the modulus n

oaepParams - the OAEP parameters (hash-, mgf- and psource-algorithm)

Throws:

java.security.spec.InvalidParameterSpecException - if the parameters are not specified as RSAOaepParameterSpec object or are invalid

RSAOaepPrivateKey

public RSAOaepPrivateKey(java.math.BigInteger modulus,
                 java.math.BigInteger publicExponent,
                 java.math.BigInteger privateExponent,
                 java.math.BigInteger primeP,
                 java.math.BigInteger primeQ,
                 java.math.BigInteger primeExponentP,
                 java.math.BigInteger primeExponentQ,
                 java.math.BigInteger crtCoefficient)

Creates a RSAOaepPrivateKey from the given values.
When using this constructor for creating an OAEP key, no parameters are explicitly specified. This means that no parameters will be encoded with the algorithm id of this OAEP key and the key may be used with any OAEP parameters.

Parameters:

modulus - the modulus n

publicExponent - the public exponent e

privateExponent - the private exponent d

primeP - first prime factor of the modulus

primeQ - second prime factor of the modulus

primeExponentP - privateExponent mod (primeP-1)

primeExponentQ - privateExponent mod (primeQ-1)

crtCoefficient - the Chinese Remainder Theorem coefficient (multiplic inverse of primeP mod primeQ)

RSAOaepPrivateKey

public RSAOaepPrivateKey(java.math.BigInteger modulus,
                 java.math.BigInteger publicExponent,
                 java.math.BigInteger privateExponent,
                 java.math.BigInteger primeP,
                 java.math.BigInteger primeQ,
                 java.math.BigInteger primeExponentP,
                 java.math.BigInteger primeExponentQ,
                 java.math.BigInteger crtCoefficient,
                 java.security.spec.AlgorithmParameterSpec oaepParams)
                  throws java.security.spec.InvalidParameterSpecException

Creates a RSAOaepPrivateKey from the given values and OAEP parameters. If no parameters are specified no parameters will be encoded with the algorithm id of this OAEP key and the key may be used with any OAEP parameters.

Parameters:

modulus - the modulus n

publicExponent - the public exponent e

privateExponent - the private exponent d

primeP - first prime factor of the modulus

primeQ - second prime factor of the modulus

primeExponentP - privateExponent mod (primeP-1)

primeExponentQ - privateExponent mod (primeQ-1)

crtCoefficient - the Chinese Remainder Theorem coefficient (multiplic inverse of primeP mod primeQ)

oaepParams - the OAEP parameters (hash-, mgf- and psource-algorithm)

Throws:

java.security.spec.InvalidParameterSpecException - if the parameters are not specified as RSAOaepParameterSpec object or are invalid

RSAOaepPrivateKey

public RSAOaepPrivateKey(byte[] pk)
                  throws java.security.InvalidKeyException

Creates a new RSAOaepPrivateKey from a DER encoded ASN.1 data structure.

This constructor may be used for parsing an already existing RSAES-OAEP private key, wrapped into a PKCS#8 PrivateKeyInfo that is supplied as DER encoded byte array.

Parameters:

pk - the byte array holding the DER encoded private key info

Throws:

java.security.InvalidKeyException - if something is wrong with the key encoding

RSAOaepPrivateKey

public RSAOaepPrivateKey(ASN1Object obj)
                  throws java.security.InvalidKeyException

Creates a new RSAOaepPrivateKey key from an ASN1Object. The supplied ASN1Object represents a PKCS#8 PrivateKeyInfo holding the RSAES-OAEP private key.

Parameters:

obj - the private key as ASN1Object

Throws:

java.security.InvalidKeyException - if something is wrong with the key encoding

RSAOaepPrivateKey

public RSAOaepPrivateKey(java.io.InputStream is)
                  throws java.io.IOException,
                         java.security.InvalidKeyException

Creates a new RSAOaepPrivateKey from an InputStream.

This constructor may be used for parsing an already existing RSAES-OAEP private key, wrapped into a PKCS#8 PrivateKeyInfo that is supplied as DER encoded byte array.

Parameters:

is - the input stream with the data to be read to initialize the private key

Throws:

java.io.IOException - if an I/O error occurs

java.security.InvalidKeyException - if something is wrong with the key encoding

Method Detail

decode

protected void decode(byte[] privateKey)
               throws java.security.InvalidKeyException

Decodes a DER encoded RSAOaepPrivateKey (PKCS#1).

From the given DER encoded byte array an ASN.1 object is created and parsed for the RSAPrivateKey fields according to PKCS#1: version, modulus n, public and private exponent (e and d), prime factor primeP of n, prime factor primeQ of n, primeExponentP (d mod(p-1)), primeExponentQ (d mod(q-1)), and crtCoefficient, the Chinese Remainder Thereom coefficient q^-1 mod p. If OAEP parameters included they are parsed from the algorithm id.

This method is protected and typically will not be used by an application. Rather it is used by the parent PKCS#8 PrivateKeyInfo class for decoding the inherent RSAES-OAEP private key.

Overrides:

decode in class RSAPrivateKey

Parameters:

privateKey - the RSAES-OAEP private key as DER encoded byte array

Throws:

java.security.InvalidKeyException - if something is wrong with the encoding of the key

getPublicKey

public java.security.PublicKey getPublicKey()

Returns the public parts (modulus n and public exponent e of this private key.

Overrides:

getPublicKey in class RSAPrivateKey

Returns:

the public key part of this private key

getAlgorithm

public java.lang.String getAlgorithm()

Returns the name of the key algorithm.

Specified by:

getAlgorithm in interface java.security.Key

Overrides:

getAlgorithm in class RSAPrivateKey

Returns:

"RSAES-OAEP"

getParams

public java.security.spec.AlgorithmParameterSpec getParams()

Gets the OAEP parameters from this RSA-OAEP key (if included). This method returns null if there are no parameters included. In this case the key may be used with any OAEP parameters.

Returns:

the OAEP parameters, or null if there are no parameters are included

validateParameters

public boolean validateParameters(java.security.spec.AlgorithmParameterSpec rsaOaepParamSpec)
                           throws java.security.spec.InvalidParameterSpecException

Validates the given parameters for this OAEP key.
This method may be used for validating the parameters that have been used with RSA OAEP encryption against the OAEP parameters that are contained in the private decryption key. RFC 4055 requires that a RSAES-OAEP key, if it contains OAEP parameters, only must be used with the hash algorithm and mask generation function that are specified by the key parameters. If there are no parameters included in the key, the key may be used with any OAEP parameters.

Parameters:

rsaOaepParamSpec - the OAEP parameters to be validated

Returns:

true if the given parameters can be used with this key (i.e. if the key does not contain any parameters at all, or if it contains parameters that specify the same hash algorithm and mask generation function as the given parameters); false if not

Throws:

java.security.spec.InvalidParameterSpecException

hashCode

public int hashCode()

Returns a hash code for this object.

Overrides:

hashCode in class RSAPrivateKey

Returns:

the hash code

equals

public boolean equals(java.lang.Object obj)

Compares this RSAOaepPrivateKey object with the supplied object.

Overrides:

equals in class PrivateKeyInfo

Parameters:

obj - the object to be compared

Returns:

true if the two objects are RSAOaepPrivateKey objects with same values and parameters, false otherwise

toString

public java.lang.String toString()

Returns a string that represents the contents of this RSA OAEP private key.

Overrides:

toString in class RSAPrivateKey

Returns:

the string representation