iaik.security.rsa

Class RSAOaepPublicKey

java.lang.Object

iaik.x509.PublicKeyInfo

iaik.security.rsa.RSAPublicKey

iaik.security.rsa.RSAOaepPublicKey

All Implemented Interfaces:

ASN1Type, java.io.Serializable, java.lang.Cloneable, java.security.interfaces.RSAKey, java.security.interfaces.RSAPublicKey, java.security.Key, java.security.PublicKey

public class RSAOaepPublicKey
extends RSAPublicKey

This class implements a RSAES-OAEP public key according to RFC 4055. This class is derived from iaik.x509.PublicKeyInfo for supporting RSA-OAEP public keys to be used within X.509 certificates. This class implements the java.security.interfaces.RSAPublicKey interface for providing the functionality of a public key, as used for encryption 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 public key differs from an ordinary PKCS#1 RSA public key only in that a RSAES-OAEP key may contain OAEP parameters; modulus and publicExponent fields are encoded in the same way as ASN.1 SEQUENCE according to PKCS#1:

 RSAPublicKey ::= SEQUENCE {
   modulus INTEGER, -- n
   publicExponent INTEGER -- e }
 

If a RSAES-OAEP key does not contain parameters it may be used for OAEP based encryption 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 RSAOaepPublicKey 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 RSAOaepPublicKey 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();
 

An RSAES-OAEP key must be only used for encryption 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 private key:

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

Version:

File Revision 5

See Also:

PublicKeyInfo, RSAPublicKey, RSAOaepPrivateKey, RSAOaepKeyPairGenerator, RSAOaepKeyFactory, RSAOaepParameterSpec, RSACipher, RSAPublicKey, KeyPairGenerator, KeyPair, Serialized Form

Field Summary

Fields inherited from class iaik.x509.PublicKeyInfo

public_key_algorithm

Fields inherited from interface java.security.interfaces.RSAPublicKey

serialVersionUID

Constructor Summary

Constructors

Constructor and Description
RSAOaepPublicKey(ASN1Object obj) Creates a new RSAOaepPublicKey from the given ASN.1 object.
RSAOaepPublicKey(java.math.BigInteger modulus, java.math.BigInteger publicExponent) Creates a new RSAOaepPublicKey with given values for modulus n and public exponent e.
RSAOaepPublicKey(java.math.BigInteger modulus, java.math.BigInteger publicExponent, java.security.spec.AlgorithmParameterSpec oaepParams) Creates a new RSAOaepPublicKey with given values for modulus n and public exponent e and given OAEP parameters.
RSAOaepPublicKey(byte[] pk) Creates a new RSAOaepPublicKey from the given DER encoded byte array.
RSAOaepPublicKey(java.io.InputStream is) Creates a new RSAOaepPublicKey from an InputStream.

Method Summary

Methods

Modifier and Type	Method and Description
protected void	decode(byte[] publicKey) Decodes a RSAOaepPublicKey, encoded in DER format.
boolean	equals(java.lang.Object obj) Compares this RSAOaepPublicKey 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).
int	hashCode() Returns a hash code for this object.
java.lang.String	toString() Returns a string that represents the contents of this RSA OAEP public key.
boolean	validateParameters(java.security.spec.AlgorithmParameterSpec rsaOaepParamSpec) Validates the given parameters for this OAEP key.

Methods inherited from class iaik.security.rsa.RSAPublicKey

crypt, encode, getFingerprint, getModulus, getPublicExponent, parse

Methods inherited from class iaik.x509.PublicKeyInfo

clone, createPublicKeyInfo, decode, getAlgorithmID, getEncoded, getFormat, getPublicKey, getPublicKey, getPublicKey, getPublicKey, 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

RSAOaepPublicKey

public RSAOaepPublicKey(java.math.BigInteger modulus,
                java.math.BigInteger publicExponent)

Creates a new RSAOaepPublicKey with given values for modulus n and public exponent e. 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 of the key

publicExponent - the public exponent of the key

RSAOaepPublicKey

public RSAOaepPublicKey(java.math.BigInteger modulus,
                java.math.BigInteger publicExponent,
                java.security.spec.AlgorithmParameterSpec oaepParams)
                 throws java.security.spec.InvalidParameterSpecException

Creates a new RSAOaepPublicKey with given values for modulus n and public exponent e and given 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 of the key

publicExponent - the public exponent of the key

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

RSAOaepPublicKey

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

Creates a new RSAOaepPublicKey from the given DER encoded byte array.

This constructor may be used for parsing an already existing RSA-OAEP public key, wrapped into a X.509 PublicKeyInfo that is supplied as DER encoded byte array.

Parameters:

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

Throws:

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

RSAOaepPublicKey

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

Creates a new RSAOaepPublicKey from the given ASN.1 object. The supplied ASN1Object represents a X.509 PublicKeyInfo holding the RSA-OAEP public key.

Parameters:

obj - the public key ASN.1 structure

Throws:

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

RSAOaepPublicKey

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

Creates a new RSAOaepPublicKey from an InputStream.

This constructor may be used for parsing an already existing RSA public key, wrapped into a X.509 PublicKeyInfo that is supplied as DER encoded byte array.

Parameters:

is - an input stream with the data to be read to initialize the public 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[] publicKey)
               throws java.security.InvalidKeyException

Decodes a RSAOaepPublicKey, encoded in DER format.

From the given DER encoded byte array an ASN.1 object is created and parsed for modulus n and public exponent e and OAEP parameters, if included.

This method is protected and typically will not be used by an application. Rather it is used by the parent X.509 PublicKeyInfo class for decoding the public key.

Overrides:

decode in class RSAPublicKey

Parameters:

publicKey - the public key as DER encoded ASN.1 object (PKCS#1)

Throws:

java.security.InvalidKeyException - if something is wrong with the encoding of the 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 RSAPublicKey

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 are (have been) used with RSA OAEP encryption against the OAEP parameters that are contained in the public encryption 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 RSAPublicKey

Returns:

the hash code

equals

public boolean equals(java.lang.Object obj)

Compares this RSAOaepPublicKey object with the supplied object.

Overrides:

equals in class RSAPublicKey

Parameters:

obj - the object to be compared

Returns:

true if the two objects are RSAOaepPublicKey objects with same modulus and exponent and parameters, false otherwise

toString

public java.lang.String toString()

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

Overrides:

toString in class RSAPublicKey

Returns:

the string representation