iaik.security.rsa

Class RSAPssKeyPairGeneratorFIPS

java.lang.Object

java.security.KeyPairGeneratorSpi

java.security.KeyPairGenerator

iaik.security.rsa.RSAKeyPairGenerator

iaik.security.rsa.RSAKeyPairGeneratorFIPS

iaik.security.rsa.RSAPssKeyPairGeneratorFIPS

All Implemented Interfaces:

PssKeyPairGenerator

public class RSAPssKeyPairGeneratorFIPS
extends RSAKeyPairGeneratorFIPS
implements PssKeyPairGenerator

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

The modulus of the generated KeyPair always has either 1024, 2048 or 3072 bits. If no initialize() method of this key pair generator is called, it defaults to initialize(2048).
The algorithm used for key generation was published in FIPS 186-3.

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 RSAPssKeyPairGeneratorFIPS for performing an algorithm-specific initialization with proper RSASSA-PSS parameters. If an algorithm-specific initialization is not required, the cast to RSAPssKeyPairGeneratorFIPS 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-FIPS-186-3" as algorithm name:

   KeyPairGenerator keyGen = KeyPairGenerator.getInstance("RSASSA-PSS-FIPS-186-3",
       "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 RSAPssKeyPairGeneratorFIPS to be initialized with the desired RSA-PSS parameters which have to be supplied as RSAPssParameterSpec object, e.g.:

 RSAPssKeyPairGeneratorFIPS rsaPsskeyGen = (RSAPssKeyPairGeneratorFIPS) 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-FIPS-186-3" has to be specified as algorithm name when instantiating the Signature object:

 Signature rsaPss = Signature.getInstance("RSASSA-PSS-FIPS-186-3", "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-FIPS-186-3", "IAIK");
 rsaPss.initVerify(publicKey); 
 // verify signature  
 rsaPss.update(data);
 System.out.println("Signature " + (rsaPss.verify(signature) ? "correct!" : "not correct!"));

Version:

File Revision 3

See Also:

RSAPssPublicKey, RSAPssPrivateKey, RSAPssKeyFactory, RSAPssParameterSpec, KeyPairGenerator, KeyPair

Field Summary

Fields inherited from class iaik.security.rsa.RSAKeyPairGeneratorFIPS

KEYLENGTH_1024, KEYLENGTH_2048, KEYLENGTH_3072, LOWER_PUBLIC_EXPONENT_BOUND, UPPER_PUBLIC_EXPONENT_BOUND

Fields inherited from class iaik.security.rsa.RSAKeyPairGenerator

initialized, keylen, public_exponent, random

Constructor Summary

Constructors

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

Method Summary

Methods

Modifier and Type	Method and Description
void	initialize(java.security.spec.AlgorithmParameterSpec params) Initializes this RSAPssKeyPairGeneratorFIPS with the given RSAPssParameterSpec.
void	initialize(java.security.spec.AlgorithmParameterSpec params, java.security.SecureRandom random) Initializes this RSAPssKeyPairGeneratorFIPS with given RSAPssParameterSpec and random number generator.
void	initialize(int strength, java.security.spec.AlgorithmParameterSpec params) Initializes the RSAKeyPairGenerator 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 RSAKeyPairGenerator 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

RSAPssKeyPairGeneratorFIPS

public RSAPssKeyPairGeneratorFIPS()

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

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

See Also:

KeyPairGenerator

Method Detail

initialize

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

Initializes this RSAPssKeyPairGeneratorFIPS with the given RSAPssParameterSpec. When using JDK 1.2 or later an application may use this method for initializing the KeyPairGenerator with PSS parameters without casting the KeyPairGenerator to RSAPssKeyPairGeneratorFIPS. If the KeyPairGenerator also shall be initialized with a specific strength, two initialize methods may be called during the initialization process, e.g.:

 int strength = ...;
 RSAPssParameterSpec pssParamSpec = ...;
 KeyPairGenerator keyGen = KeyPairGenerator.getInstance("RSASSA-PSS-FIPS-186-3", "IAIK");
 keyGen.initialize(strength);
 keyGen.initialize(pssParamSpec);
 ...
 

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

initialize

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

Initializes this RSAPssKeyPairGeneratorFIPS with given RSAPssParameterSpec and random number generator. When using JDK 1.2 or later an application may use this method for initializing the KeyPairGenerator with PSS parameters without casting the KeyPairGenerator to RSAPssKeyPairGeneratorFIPS. If the KeyPairGenerator also shall be initialized with a specific strength, two initialize methods may be called during the initialization process, e.g.:

 int strength = ...;
 RSAPssParameterSpec pssParamSpec = ...;
 SecureRandom secureRandom = ...;
 KeyPairGenerator keyGen = KeyPairGenerator.getInstance("RSASSA-PSS-FIPS-186-3", "IAIK");
 keyGen.initialize(strength);
 keyGen.initialize(pssParamSpec, secureRandom);
 ...
 

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

initialize

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

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

 RSAPssKeyPairGeneratorFIPS keyGen = (RSAPssKeyPairGeneratorFIPS)KeyPairGenerator.getInstance("RSASSA-PSS-FIPS-186-3", "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

initialize

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

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

 RSAPssKeyPairGeneratorFIPS keyGen = (RSAPssKeyPairGeneratorFIPS)KeyPairGenerator.getInstance("RSASSA-PSS-FIPS-186-3", "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

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. Typical values for the public exponent are the Fermat primes F4 and F0 (0x10001 and 0x11) and, less commonly, 17. When using this initialization method, an explicit cast from KeyPairGenerator to RSAPssKeyPairGeneratorFIPS is required:

 RSAPssKeyPairGeneratorFIPS keyGen = (RSAPssKeyPairGeneratorFIPS)KeyPairGenerator.getInstance("RSASSA-PSS-FIPS-186-3", "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