iaik.security.rsa
Class RSAPssSignature

java.lang.Object
  |
  +--java.security.SignatureSpi
        |
        +--java.security.Signature
              |
              +--iaik.security.rsa.RSAPkcs1Signature
                    |
                    +--iaik.security.rsa.RSAPssSignature

Direct Known Subclasses:

iaik.security.rsa.HASHwithRSAandMGFSignature, RawRSAPssSignature

public class RSAPssSignature

extends iaik.security.rsa.RSAPkcs1Signature

This class implements the sign and verify methods of the PKCS#1v2.1 PSS signature scheme (RSASSA-PSS).

This class follows the guidelines presented in PKCS#1 (v.2.1)) for implementing the RSASSA-PSS signature algorithm based on the RSA encryption method.

This class may be used to create/verify PSS based signatures according the specification where all parameters (hash algorithm, mask generation function, salt length, and trailer field) maybe supplied by the calling application. The trailer field is fixed to the 0xBC which is the only trailer field supported by PSS. Generally the following steps have to be performed for calculating/verifying a PSS signature:

• First an instance of the RSASSA-PSS signature engine has to be created using a proper getInstance method, e.g.:

   Signature pss = Signature.getInstance("RSASSA-PSS");
   

• Second, the Signature object just created has to be properly initialized for signing a message respectively verifying a signature using a RSA private respectively RSA public key, e.g.:
  • Initialize for Signing: pss.initSign(rsaPrivateKey);
  • Initialize for Verifying: pss.initVerify(rsaPublicKey);

• Third, supply the required parameters (hash algorithm, mask generation function, salt length -- trailer field is fixed) as RSAPssParameterSpec, e.g.:

   // hash algorithm
   AlgorithmID hashID = (AlgorithmID)AlgorithmID.ripeMd160.clone();
   // mask generation function ID
   AlgorithmID mgfID = (AlgorithmID)AlgorithmID.mgf1.clone();
   mgfID.setParameter(hashID.toASN1Object());
   // salt length
   int saltLength = 20;
   // create a RSAPssParameterSpec
   RSAPssParameterSpec pssParamSpec = new RSAPssParameterSpec(hashID, mgfID, saltLength);
   // optionally set hash and mgf engines
   MessageDigest hashEngine = MessageDigest.getInstance(“SHA-1”);
   pssParamSpec.setHashEngine(hashEngine);
   MaskGenerationAlgorithm mgfEngine = MaskGenerationAlgorithm.getInstance(“MGF1”);
   MGF1ParameterSpec mgf1Spec = new MGF1ParameterSpec(hashID);
   mgf1Spec.setHashEngine(hashEngine);
   mgfEngine.setParameters(mgf1Spec);
   pssParamSpec.setMGFEngine(mgfEngine);
   // set parameters (for JDK 1.1.8 use pss.setParameter(null, pssParamSpec);)
   pss.setParameter(pssParamSpec); 
   

• Finally, if the Signature object has been initialized for signing, the data to be signed is supplied to it and subsequently the signature is created by calling the sign method returning the signature as byte array. Otherwise, if the Signature object has been initialized for verifying, first the data to be verified is supplied to the Signature object, and subsequently the signature is verified by calling the verify method, supplied with the byte array holding the corresponding signature value:
  • Supply the data to be signed, and subsequently sign it:

     pss.update(data);
     byte[] signature = pss.sign();
     

  • Supply the data to be verified, and verify the signature:

     pss.update(data);
     System.out.println("Signature " + (pss.verify(signature) ? "correct!" : "not correct!"));
     

Please note that the Java Cryptography Architecture only allows to set the salt length as parameter and specifies all the other parameters by the algorithm standard name to be implemented by a corresponding PSS signature engine: A signature engine that implements the, for instance, "SHA1withRSAandMGF1" (in general: <digest>with<encryption>and<mgf>) PSS signature algorithm has to use SHA-1 as hash- and MGF1 as mask generation algorithm. The trailer field (0xBC) is fixed by the PKCS#1v2.1 standard and the salt length may be supplied as parameter; if not, a default salt length (20 for the SHA-1 hash algorithm) will be used. IAIK-JCE implements JCA PSS based signature engine for all hash algorithms supported by the IAIK provider. The only mask generation in use is MGF1 as specified by PKCS#1 (v.2.1). For creating an instance of the PSS based signature engine call Signature.getInstance thereby using the JCA PSS naming convention (<digest>with<encryption>and<mgf>), e.g.:

 Signature shaRsaMgf1 = Signature.getInstance("SHA1withRSAandMGF1", "IAIK");
 

The only parameter allowed to be set for such an JCA engine is the salt length. Because of the JDK1.1.x compatibility of IAIK-JCE there is no proper way to use the java.security.spec.PSSParameterSpec class for modelling the saltLength parameter. The same functionality is provided by class RSAPssSaltParameterSpec which may be used to supply the saltLength to this PSS based signature engine; if no salt length is explicitly supplied, the defined default salt length for the underlying signature engine will be used.

Please note that in contrast to PKCS1v1.5 -- where attacks that are based on hash algorithm compromise ("hash function substitution") are caught by including the hash algorithm id in the DigestInfo encoding -- no such mechanism is used by the PSS signature scheme. So hash function substitution has to be addressed by other means when using PSS. One possible solution is to use the same hash function for message hashing and any hash operations done by the mask generation function (if based on a hash algorithm). This is ensured for all JCA based hash engines where the hash algorithm(s) to be used are already given by the implementing class: SHA1withRSAandMGF1, for instance, uses the SHA-1 algorithm for both message hashing and MGF1 hash operations. When using this general RSASSA-PSS signature engine, hash algorithm and mask generation function have to be supplied by the calling application. In this case it is the responsibility of the application to take care of hash function substitution issues - if desired. This may be done by, for instance, setting the same hash algorithm parameter for message hashing and MGF hashing, or, for instance, using one and only hash algorithm in any case, or following any other suitable strategy.

Version:

File Revision 27

See Also:

SHAwithRSAandMGF1Signature

Field Summary

protected MessageDigest

hash The MessageDigest engine used to hash the data; supplied with an instance of the desired MessageDigest algorithm by any extending subclass.

Fields inherited from class java.security.Signature

SIGN, state, UNINITIALIZED, VERIFY

Fields inherited from class java.security.SignatureSpi

appRandom

Constructor Summary

	RSAPssSignature() Default constructor.
protected	RSAPssSignature(String name) Creates a RSAPssSignature engine with the given name.

Method Summary

protected Object	engineGetParameter(String param) Returns the PSS parameters (hashAlgorithm, mask generation algorithm, salt length, trailer field) as RSAPssParameterSpec.
protected AlgorithmParameters	engineGetParameters() Returns the PSS parameters (hashAlgorithm, mask generation algorithm, salt length, trailer field) as RSAPssParameterSpec.
protected void	engineInitSign(PrivateKey pk) SPI: Initializes this Signature object with the given RSA private key for going to sign some data.
protected void	engineInitSign(PrivateKey pk, SecureRandom random) SPI: Initializes this Signature object with the given RSA private key for going to sign some data.
protected void	engineInitVerify(PublicKey pk) SPI: Initializes this Signature object with the given RSA public key for performing a signature verification.
protected void	engineSetParameter(AlgorithmParameterSpec params) Sets the parameters (hashAlgorithm, mask generation algorithm, salt length, trailer field) for this RSA PSS signature engine.
protected void	engineSetParameter(String param, Object value) Allows to supply a SecureRandom object if required by the underlying signature scheme (e.g.
protected byte[]	engineSign() SPI: Calculates the signature.
protected void	engineUpdate(byte b) SPI: Updates the data to be signed or verified with the specified byte.
protected void	engineUpdate(byte[] b, int off, int len) SPI: Updates the data to be signed or verified with the specified number of bytes, beginning at the specified offset within the given byte array.
protected boolean	engineVerify(byte[] sigBytes) Verifies the given signature.

Methods inherited from class java.security.Signature

clone, getAlgorithm, getInstance, getInstance, getParameter, getProvider, initSign, initSign, initVerify, initVerify, setParameter, setParameter, sign, sign, toString, update, update, update, verify

Methods inherited from class java.security.SignatureSpi

engineSign

Methods inherited from class java.lang.Object

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

Field Detail

hash

protected MessageDigest hash

The MessageDigest engine used to hash the data; supplied with an instance of the desired MessageDigest algorithm by any extending subclass.

Constructor Detail

RSAPssSignature

public RSAPssSignature()

Default constructor. Only used for dynamic object creation. An application shall use

 Signature.getInstance("RSASSA-PSS");
 
 to create a JCA Signature engine for the RSASSA-PSS signature scheme.
 

 Default salt length is set to -1.

RSAPssSignature

protected RSAPssSignature(String name)

Creates a RSAPssSignature engine with the given name. This constructor may be used by extending classes to implement PPS signature engines according the JCA convention where only the salt length maybe supplied as parameter whereas hash algorithm and mask generation function are fixed by the engine (e.g.

SHAwithRSAandMGF1

.

Default salt length is set to -1.

Parameters:

name - the name of the engine

Method Detail

engineInitSign

protected void engineInitSign(PrivateKey pk)
                       throws InvalidKeyException

SPI: Initializes this Signature object with the given RSA private key for going to sign some data.

Overrides:

engineInitSign in class iaik.security.rsa.RSAPkcs1Signature

Parameters:

privateKey - the RSA private key to be used for signing.

Throws:

InvalidKeyException - if a key encoding error occurs

engineInitVerify

protected void engineInitVerify(PublicKey pk)
                         throws InvalidKeyException

SPI: Initializes this Signature object with the given RSA public key for performing a signature verification.

Overrides:

engineInitVerify in class iaik.security.rsa.RSAPkcs1Signature

Parameters:

publicKey - the RSA public key belonging to the RSA private key that has been used for signing.

Throws:

InvalidKeyException - if a key encoding error occurs

engineSetParameter

protected void engineSetParameter(AlgorithmParameterSpec params)
                           throws InvalidAlgorithmParameterException

Sets the parameters (hashAlgorithm, mask generation algorithm, salt length, trailer field) for this RSA PSS signature engine.

PKCS#1 (v.2.1) requires the following parameters for the RSA PSS signature scheme:

 RSASSA-PSS-params :: = SEQUENCE {
      hashAlgorithm            [0] HashAlgorithm     DEFAULT sha1,
      maskGenerationAlgorithm  [1] MaskGenAlgorithm  DEFAULT mgf1SHA1,
      saltLength               [2] INTEGER           DEFAULT 20,
      trailerField             [3] TrailerField      DEFAULT trailerFieldBC
 }

 HashAlgorithm ::= AlgorithmIdentifer { {OAEP-PSSDigestAlgorithms} }

 MaskGenAlgorithm ::= AlgorithmIdentifier { {PKCS1MGFAlgorithms} }

 TrailerField ::= INTEGER { trailerFieldBC(1) }
 

This class does not use any default parameters. All parameters have to be supplied as RSAPssParameterSpec; the trailer field has to be set to 1 which corresponds to the trailer field byte 0xBC, which is the only trailer field supported by the RSA-PSS signature scheme.

An application also may use the RSAPssParameterSpec to provide a SecureRandom object for supplying any random numbers as required by the PSS signature algorithm. JDK 1.2 (or later) based applications may prefer to use method initSign(PrivateKey, SecureRandom) to supply a SecureRandom object if required. If a SecureRandom never has been supplied by the application, the signature engine will use a default SecureRandom for generating random numbers.

Overrides:

engineSetParameter in class iaik.security.rsa.RSAPkcs1Signature

Parameters:

params - the PSS parameters supplied as RSAPssParameterSpec

Throws:

InvalidParameterException - if the parameters are not supplied as RSAPssParameterSpec, the trailer field is invalid (not 1), or any of the required hash or mgf engines is not available

engineGetParameter

protected Object engineGetParameter(String param)
                             throws InvalidParameterException

Returns the PSS parameters (hashAlgorithm, mask generation algorithm, salt length, trailer field) as RSAPssParameterSpec.

Overrides:

engineGetParameter in class iaik.security.rsa.RSAPkcs1Signature

Returns:

the PSS parameters as RSAPssParameterSpec.

Throws:

InvalidParameterException - should not occur

engineGetParameters

protected AlgorithmParameters engineGetParameters()

Returns the PSS parameters (hashAlgorithm, mask generation algorithm, salt length, trailer field) as RSAPssParameterSpec.

Returns:

the PSS parameters as RSAPssParameterSpec.

engineSign

protected byte[] engineSign()
                     throws SignatureException

SPI: Calculates the signature.

Overrides:

engineSign in class SignatureSpi

Returns:

a byte array holding the signature value calculated on the data that has been supplied when updating this engine

Throws:

SignatureException - if an error occurs when creating the signature

engineVerify

protected boolean engineVerify(byte[] sigBytes)
                        throws SignatureException

Verifies the given signature.

Overrides:

engineVerify in class SignatureSpi

Parameters:

sigBytes - the signature bytes to be verified

Returns:

true if signature is OK, false otherwise

Throws:

SignatureException - if an error occurs when verifying the signature

engineInitSign

protected void engineInitSign(PrivateKey pk,
                              SecureRandom random)
                       throws InvalidKeyException

SPI: Initializes this Signature object with the given RSA private key for going to sign some data. The supplied SecureRandom may be used by the signature engine if random numbers are required (e.g. PSS).

Note that this method is not available for JDK versions prior JDK 1.2. When using JDK 1.1 a SecureRandom object may be supplied as parameter by calling method setParameter. If a SecureRandom never has been supplied by the application, the signature engine will use a default SecureRandom, if required.

Overrides:

engineInitSign in class SignatureSpi

Parameters:

privateKey - the RSA private key to be used for signing.

SecureRandom - the SecureRandom if random numbers are required by the signature engine (e.g. PSS)

Throws:

InvalidKeyException - if a key encoding error occurs

engineUpdate

protected void engineUpdate(byte b)

SPI: Updates the data to be signed or verified with the specified byte.

Overrides:

engineUpdate in class SignatureSpi

Parameters:

b - the byte to be used for updating.

engineUpdate

protected void engineUpdate(byte[] b,
                            int off,
                            int len)

SPI: Updates the data to be signed or verified with the specified number of bytes, beginning at the specified offset within the given byte array.

Overrides:

engineUpdate in class SignatureSpi

Parameters:

b - the byte array holding the data to be used for this update operation.

off - the offset, indicating the start position within the given byte array.

len - the number of bytes to be obtained from the given byte array, starting at the given position.

engineSetParameter

protected void engineSetParameter(String param,
                                  Object value)
                           throws InvalidParameterException

Allows to supply a SecureRandom object if required by the underlying signature scheme (e.g. PSS). When using JDK versions prior JDK 1.2 method initSign(PrivateKey, SecureRandom) is not available. If required by the underlying signature scheme (e.g. PSS) an application may supply a SecureRandom object as parameter. If a SecureRandom never has been supplied by the application, the signature engine will use a default SecureRandom, if required.

Overrides:

engineSetParameter in class SignatureSpi

Parameters:

param - ignored

value - the SecureRandom supplied as PKCS1AlgorithmParameterSpec

Throws:

InvalidParameterException - if the SecureRandom is not supplied as PKCS1AlgorithmParameterSpec