iaik.security.rsa

Class RSAPssPublicKey

java.lang.Object

iaik.x509.PublicKeyInfo

iaik.security.rsa.RSAPublicKey

iaik.security.rsa.RSAPssPublicKey

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 RSAPssPublicKey
extends RSAPublicKey

This class implements a RSASSA-PSS public key according to RFC 4055. This class is derived from iaik.x509.PublicKeyInfo for supporting RSA-PSS 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 signature verification 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 public key differs from an ordinary PKCS#1 RSA public key only in that a RSASSA-PSS key may contain PSS 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 RSASSA-PSS key does not contain parameters it may be used for PSS based signatures 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 RSAPssPublicKey to be used for PSS based signature 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 RSAPssPublicKey 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 6

See Also:

PublicKeyInfo, RSAPublicKey, RSAPssPrivateKey, RSAPssKeyPairGenerator, RSAPssKeyFactory, RSAPssSignature, RSAPssParameterSpec, RSAPublicKey, KeyPairGenerator, KeyPair, Serialized Form

Field Summary

Fields inherited from class iaik.x509.PublicKeyInfo

public_key_algorithm

Constructor Summary

Constructors

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

Method Summary

Methods

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

Methods inherited from class iaik.security.rsa.RSAPublicKey

crypt, encode, getFingerprint, getModulus, getPublicExponent, isValidSP80089SignatureVerificationKey, isValidSP80089SignatureVerificationKey, parse

Methods inherited from class iaik.x509.PublicKeyInfo

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

RSAPssPublicKey

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

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

publicExponent - the public exponent of the key

RSAPssPublicKey

public RSAPssPublicKey(java.math.BigInteger modulus,
               java.math.BigInteger publicExponent,
               java.security.spec.AlgorithmParameterSpec pssParams)
                throws java.security.spec.InvalidParameterSpecException

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

publicExponent - the public exponent of the key

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

RSAPssPublicKey

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

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

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

RSAPssPublicKey

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

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

Parameters:

obj - the public key ASN.1 structure

Throws:

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

RSAPssPublicKey

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

Creates a new RSAPssPublicKey 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 encoded 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 RSAPssPublicKey, 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 PSS 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:

"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 (have been) used with RSA PSS signature calculation against the PSS parameters that are contained in the public verification 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 RSAPublicKey

Returns:

the hash code

equals

public boolean equals(java.lang.Object obj)

Compares this RSAPssPublicKey object with the supplied object.

Overrides:

equals in class RSAPublicKey

Parameters:

obj - the object to be compared

Returns:

true if the two objects are RSAPssPublicKey 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 PSS public key.

Overrides:

toString in class RSAPublicKey

Returns:

the string representation