iaik.security.rsa

Class RSAPssKeyPairGenerator

java.lang.Object

java.security.KeyPairGeneratorSpi

java.security.KeyPairGenerator

iaik.security.rsa.RSAKeyPairGenerator

iaik.security.rsa.RSAPssKeyPairGenerator

All Implemented Interfaces:

PssKeyPairGenerator

public class RSAPssKeyPairGenerator
extends RSAKeyPairGenerator
implements PssKeyPairGenerator

KeyPairGenerator for generating RSASSA-PSS keys according to RFC 4055.

If no initialize() method of this key pair generator is called, it defaults to initialize(2048).
The algorithm used for key generation is according IEEE P1363.

RSASSA-PSS keys (RSAPssPublicKey, RSAPssPrivateKey) differ from an ordinary PKCS#1 RSA keys (RSAPublicKey, RSAPrivateKey) only in that RSASSA-PSS keys may contain PSS parameters. If RSASSA-PSS keys do not contain parameters they may be used for PSS based siganture calcualtion/verification with any PSS parameters. However, if RSASSA-PSS keys contain PSS parameters they must be only used with the hash algorithm, mask generation function and trailer field that are specified by their parameters (see RFC 4055):

 RSASSA-PSS-params  ::=  SEQUENCE  {
   hashFunc            [0] AlgorithmIdentifier DEFAULT
                            sha1Identifier,
   maskGenFunc         [1] AlgorithmIdentifier DEFAULT
                            mgf1SHA1Identifier,
   saltLength          [2] INTEGER DEFAULT 20,
   trailerField        [3] INTEGER DEFAULT 1  }
 

An application wishing to create a RSASSA-PSS key pair to be used for PSS based signature calcualtion/verification with the RSA algorithm, uses a proper getInstance method of the java.security.KeyPairGenerator class, which subsequently maybe casted to RSAPssKeyPairGenerator for performing an algorithm-specific initialization with proper RSASSA-PSS parameters. If an algorithm-specific initialization is not required, the cast to RSAPssKeyPairGenerator can be omitted (in this case no parameters will be included in the RSA-PSS generated keys and they maybe used with any PSS parameters).

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

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

   KeyPairGenerator keyGen = KeyPairGenerator.getInstance("RSASSA-PSS", "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 2048 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:

   RSAPssPrivateKey privateKey = (RSAPssPrivateKey) keyPair.getPrivate();
   RSAPssPublicKey publicKey = (RSAPssPublicKey) keyPair.getPublic();
   

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

 RSAPssKeyPairGenerator rsaPsskeyGen = (RSAPssKeyPairGenerator) keyGen;
 // create PSS parameters for specifying hash, mgf algorithms and salt length:
 // hash and mgf algorithm ids
 AlgorithmID hashID = (AlgorithmID) AlgorithmID.sha512.clone();
 AlgorithmID mgfID = (AlgorithmID) AlgorithmID.mgf1.clone();
 mgfID.setParameter(hashID.toASN1Object());
 int saltLength = 64;
 // 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 RSAPssParameterSpec
 RSAPssParameterSpec pssParamSpec = new RSAPssParameterSpec(hashID, mgfID,
     saltLength);
 // set engines
 pssParamSpec.setHashEngine(hashEngine);
 pssParamSpec.setMGFEngine(mgfEngine);
 // initialize key pair generator
 rsaPsskeyGen.initialize(2048, pssParamSpec);
 KeyPair keyPair = rsaPsskeyGen.generateKeyPair();
 RSAPssPublicKey publicKey = (RSAPssPublicKey) keyPair.getPublic();
 RSAPssPrivateKey privateKey = (RSAPssPrivateKey) keyPair.getPrivate();
 

RSASSA-PSS keys must be only used for signature purposes with the RSASSA-PSS signature scheme. For using RSASSA-PSS keys with a Signature engine, "RSASSA-PSS" has to be specified as algorithm name when instantiating the Signature object:

 Signature rsaPss = Signature.getInstance("RSASSA-PSS", "IAIK");
 

When now initializing the Signature engine with an RSASSA-PSS key that contains PSS parameters, the hash algorithm, mask generation function, trailer field and salt (length) parameters are taken from the key parameters:

 rsaPss.initSign(privateKey); 
 // the data to be signed:
 byte[] data = ...;
 // sign data
 rsaPss.update(data);  
 byte[] signature = rsaPss.sign();
 

For verifying the signature you will have to use the right RSASSA-PSS public key}:

 Signature rsaPss = Signature.getInstance("RSASSA-PSS", "IAIK");
 rsaPss.initVerify(publicKey); 
 // verify signature  
 rsaPss.update(data);
 System.out.println("Signature " + (rsaPss.verify(signature) ? "correct!" : "not correct!"));

Version:

File Revision 7

See Also:

RSAPssPublicKey, RSAPssPrivateKey, RSAPssKeyFactory, RSAPssParameterSpec, KeyPairGenerator, KeyPair

Field Summary

Fields inherited from class iaik.security.rsa.RSAKeyPairGenerator

initialized, keylen, public_exponent, random

Constructor Summary

Constructors

Constructor and Description
RSAPssKeyPairGenerator() Default constructor for creating a RSAPssKeyPairGenerator object.

Method Summary

Methods

Modifier and Type	Method and Description
void	initialize(java.security.spec.AlgorithmParameterSpec params) Initializes this RSAPssKeyPairGenerator with the given AlgorithmParameterSpec.
void	initialize(java.security.spec.AlgorithmParameterSpec params, java.security.SecureRandom random) Initializes this RSAPssKeyPairGenerator with given RSAPssParameterSpec and random number generator.
void	initialize(int strength, java.security.spec.AlgorithmParameterSpec params) Initializes the RSAPssKeyPairGenerator for generating keys with the given length and PSS parameters.
void	initialize(int strength, java.security.spec.AlgorithmParameterSpec params, java.security.SecureRandom secureRandom) Initializes the RSAPssKeyPairGenerator for a certain key length with the given random number generator and PSS parameters.
void	initialize(int strength, java.math.BigInteger publicExponent, java.security.spec.AlgorithmParameterSpec params, java.security.SecureRandom secureRandom) Initializes the key pair generator using the specified "strength" (desired key length in bits), public exponent, source of random bits, and PSS parameters.

Methods inherited from class iaik.security.rsa.RSAKeyPairGenerator

generateKeyPair, initialize, initialize, initialize

Methods inherited from class java.security.KeyPairGenerator

genKeyPair, getAlgorithm, getInstance, getInstance, getInstance, getProvider

Methods inherited from class java.lang.Object

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

Constructor Detail

RSAPssKeyPairGenerator

public RSAPssKeyPairGenerator()

Default constructor for creating a RSAPssKeyPairGenerator object. Required for dynamic object creation. An application typically will not use this constructor for creating a RSAPssKeyPairGenerator. Rather it will use a proper KeyPairGenerator.getInstance method:

 KeyPairGenerator keyGen = KeyPairGenerator.getInstance("RSASSA-PSS", "IAIK");
 

See Also:

KeyPairGenerator

Method Detail

initialize

public void initialize(java.security.spec.AlgorithmParameterSpec params)
                throws java.security.InvalidAlgorithmParameterException

Initializes this RSAPssKeyPairGenerator with the given AlgorithmParameterSpec.

Specified by:

initialize in interface PssKeyPairGenerator

Overrides:

initialize in class RSAKeyPairGenerator

Parameters:

params - the RSAPssParameterSpec for initializing this generator

Throws:

java.security.InvalidAlgorithmParameterException - if the given parameter specification is not a RSAPssParameterSpec or java.security.spec.RSAKeyGenParameterSpec or the KeyPairGenerator cannot be initialized from the parameters

initialize

public void initialize(java.security.spec.AlgorithmParameterSpec params,
              java.security.SecureRandom random)
                throws java.security.InvalidAlgorithmParameterException

Initializes this RSAPssKeyPairGenerator with given RSAPssParameterSpec and random number generator.

Specified by:

initialize in interface PssKeyPairGenerator

Overrides:

initialize in class RSAKeyPairGenerator

Parameters:

params - the RSAPssParameterSpec for initializing this generator

random - the SecureRandom for generating random numbers

Throws:

java.security.InvalidAlgorithmParameterException - if the given parameter specification is not a RSAPssParameterSpec or java.security.spec.RSAKeyGenParameterSpec or the KeyPairGenerator cannot be initialized from the parameters

initialize

public void initialize(int strength,
              java.security.spec.AlgorithmParameterSpec params)
                throws java.security.InvalidParameterException

Initializes the RSAPssKeyPairGenerator for generating keys with the given length and PSS parameters. When using this initialization method, an explicit cast to RSAPssKeyPairGenerator is required:

 RSAPssKeyPairGenerator keyGen = (RSAPssKeyPairGenerator)KeyPairGenerator.getInstance("RSASSA-PSS", "IAIK");
 keyGen.initialize(strength, pssParamSpec);
 ...
 

Specified by:

initialize in interface PssKeyPairGenerator

Parameters:

strength - the length of the key in bits.

params - the PSS parameters to be set for the RSASSA-PSS keys

Throws:

java.security.InvalidParameterException - if the supplied parameters do not represent PSS parameters or java.security.spec.RSAKeyGenParameterSpec or the KeyPairGenerator cannot be initialized from the parameters

initialize

public void initialize(int strength,
              java.security.spec.AlgorithmParameterSpec params,
              java.security.SecureRandom secureRandom)
                throws java.security.InvalidParameterException

Initializes the RSAPssKeyPairGenerator for a certain key length with the given random number generator and PSS parameters. When using this initialization method, an explicit cast to RSAPssKeyPairGenerator is required:

 RSAPssKeyPairGenerator keyGen = (RSAPssKeyPairGenerator)KeyPairGenerator.getInstance("RSASSA-PSS", "IAIK");
 keyGen.initialize(strength, pssParamSpec, secureRandom);
 ...
 

Specified by:

initialize in interface PssKeyPairGenerator

Parameters:

strength - the length of the key in bits.

params - the PSS parameters to be set for the RSASSA-PSS keys

secureRandom - the random number generator

Throws:

java.security.InvalidParameterException - if the supplied parameters do not represent PSS parameters or java.security.spec.RSAKeyGenParameterSpec or the KeyPairGenerator cannot be initialized from the parameters

initialize

public void initialize(int strength,
              java.math.BigInteger publicExponent,
              java.security.spec.AlgorithmParameterSpec params,
              java.security.SecureRandom secureRandom)
                throws java.security.InvalidParameterException

Initializes the key pair generator using the specified "strength" (desired key length in bits), public exponent, source of random bits, and PSS parameters. When using this initialization method, an explicit cast to RSAPssKeyPairGenerator is required:

 RSAPssKeyPairGenerator keyGen = (RSAPssKeyPairGenerator)KeyPairGenerator.getInstance("RSASSA-PSS", "IAIK");
 keyGen.initialize(strength, publicExponent, pssParamSpec, secureRandom);
 ...
 

Specified by:

initialize in interface PssKeyPairGenerator

Parameters:

strength - keyLength the length of the key in bits.

publicExponent - the public exponent

params - the PSS parameters to be set for the RSASSA-PSS keys

secureRandom - the random seed

Throws:

java.security.InvalidParameterException - if the supplied parameters do not represent PSS parameters or java.security.spec.RSAKeyGenParameterSpec or the KeyPairGenerator cannot be initialized from the parameters