iaik.security.rsa

Class RSAPssPrivateKey

java.lang.Object

iaik.pkcs.pkcs8.PrivateKeyInfo

iaik.security.rsa.RSAPrivateKey

iaik.security.rsa.RSAPssPrivateKey

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 RSAPssPrivateKey
extends RSAPrivateKey

This class implements a RSASSA-PSS 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-PSS private keys. This class implements the java.security.interfaces.RSAPrivateKey interface for providing the functionality of a private key, as used for signature calculation based on the RSASSA-PSS signature scheme as specified by PKCS#1v2.1.

The ASN.1 object identifier for RSASSA-PSS key derived from PKCS-1:

 pkcs-1  OBJECT IDENTIFIER  ::=  { iso(1) member-body(2)
                         us(840) rsadsi(113549) pkcs(1) 1 }
                         
 id-RSASSA-PSS  OBJECT IDENTIFIER  ::=  { pkcs-1 10 }                        
 

This corresponds to the OID string "1.2.840.113549.1.1.10".

A RSASSA-PSS private key differs from an ordinary PKCS#1 RSA private key only in that a RSASSA-PSS key may contain PSS 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 RSASSA-PSS key does not contain parameters it may be used for PSS based signature calculation with any PSS parameters. However, if a RSASSA-PSS key contains PSS parameters it must be only used with the hash algorithm, mask generation function and trailer field that are specified by its 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 RSAPssPrivateKey to be used for PSS based signature calculation 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 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:

   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 5

See Also:

PrivateKeyInfo, RSAPublicKey, RSAPssPublicKey, RSAPssKeyPairGenerator, RSAPssKeyFactory, RSAPssSignature, RSAPssParameterSpec, RSAPublicKey, 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
RSAPssPrivateKey(ASN1Object obj) Creates a new RSAPssPrivateKey key from an ASN1Object.
RSAPssPrivateKey(java.math.BigInteger modulus, java.math.BigInteger privateExponent) Creates a new RSAPssPrivate key from given modulus and private exponent.
RSAPssPrivateKey(java.math.BigInteger modulus, java.math.BigInteger privateExponent, java.security.spec.AlgorithmParameterSpec pssParams) Creates a new RSAPssPrivate key from given modulus and private exponent and PSS parameters.
RSAPssPrivateKey(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 RSAPssPrivateKey from the given values.
RSAPssPrivateKey(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 pssParams) Creates a RSAPssPrivateKey from the given values and PSS parameters.
RSAPssPrivateKey(byte[] pk) Creates a new RSAPssPrivateKey from a DER encoded ASN.1 data structure.
RSAPssPrivateKey(java.io.InputStream is) Creates a new RSAPssPrivateKey from an InputStream.

Method Summary

Methods

Modifier and Type	Method and Description
protected void	decode(byte[] privateKey) Decodes a DER encoded RSAPssPrivateKey (PKCS#1).
boolean	equals(java.lang.Object obj) Compares this RSAPssPrivateKey object with the supplied object.
java.lang.String	getAlgorithm() Returns the name of the key algorithm.
java.security.spec.AlgorithmParameterSpec	getParams() Gets the PSS parameters from this RSA-PSS 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 PSS private key.
boolean	validateParameters(java.security.spec.AlgorithmParameterSpec rsaPssParamSpec) Validates the given parameters for this PSS 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

RSAPssPrivateKey

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

Creates a new RSAPssPrivate 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 PSS key, no parameters are explicitly specified. This means that no parameters will be encoded with the algorithm id of this PSS key and the key may be used with any PSS parameters.

Parameters:

privateExponent - the private exponent d

modulus - the modulus n

RSAPssPrivateKey

public RSAPssPrivateKey(java.math.BigInteger modulus,
                java.math.BigInteger privateExponent,
                java.security.spec.AlgorithmParameterSpec pssParams)
                 throws java.security.spec.InvalidParameterSpecException

Creates a new RSAPssPrivate key from given modulus and private exponent and PSS 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 PSS key and the key may be used with any PSS parameters.

Parameters:

privateExponent - the private exponent d

modulus - the modulus n

pssParams - the PSS parameters (hash-, mgf-algorithm, trailer field, salt length)

Throws:

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

RSAPssPrivateKey

public RSAPssPrivateKey(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 RSAPssPrivateKey from the given values.
When using this constructor for creating an PSS key, no parameters are explicitly specified. This means that no parameters will be encoded with the algorithm id of this PSS key and the key may be used with any PSS 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)

RSAPssPrivateKey

public RSAPssPrivateKey(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 pssParams)
                 throws java.security.spec.InvalidParameterSpecException

Creates a RSAPssPrivateKey from the given values and PSS parameters. If no parameters are specified no parameters will be encoded with the algorithm id of this PSS key and the key may be used with any PSS 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)

pssParams - the PSS parameters (hash-, mgf-algorithm, trailer field, salt length)

Throws:

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

RSAPssPrivateKey

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

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

This constructor may be used for parsing an already existing RSASSA-PSS 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

RSAPssPrivateKey

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

Creates a new RSAPssPrivateKey key from an ASN1Object. The supplied ASN1Object represents a PKCS#8 PrivateKeyInfo holding the RSASSA-PSS private key.

Parameters:

obj - the private key as ASN1Object

Throws:

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

RSAPssPrivateKey

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

Creates a new RSAPssPrivateKey from an InputStream.

This constructor may be used for parsing an already existing RSASSA-PSS private key, wrapped into a PKCS#8 PrivateKeyInfo that is supplied as DER encoded byte data from an imput stream.

Parameters:

is - the input stream with the encoded 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 RSAPssPrivateKey (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 PSS 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 RSASSA-PSS private key.

Overrides:

decode in class RSAPrivateKey

Parameters:

privateKey - the RSASSA-PSS 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:

"RSASSA-PSS"

getParams

public java.security.spec.AlgorithmParameterSpec getParams()

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

Returns:

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

validateParameters

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

Validates the given parameters for this PSS key.
This method may be used for validating the parameters that are used with RSA PSS signature calculation against the PSS parameters that are contained in the private key. RFC 4055 requires that a RSASSA-PSS key, if it contains PSS parameters, only must be used with the hash algorithm, mask generation function and trailer field that are specified by the key parameters. If there are no parameters included in the key, the key may be used with any PSS parameters.

Parameters:

rsaPssParamSpec - the PSS 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 mask generation function and trailer field 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 RSAPssPrivateKey object with the supplied object.

Overrides:

equals in class PrivateKeyInfo

Parameters:

obj - the object to be compared

Returns:

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

toString

public java.lang.String toString()

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

Overrides:

toString in class RSAPrivateKey

Returns:

the string representation