iaik.security.rsa
Class SHA256withRSAandMGF1Signature

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

public class SHA256withRSAandMGF1Signature

extends iaik.security.rsa.HASHwithRSAandMGFSignature

This class implements PKCS#1v2.1 RSASSA-PSS signature scheme using SHA256 as hash algorithm, MGF1 (with SHA256) as mask generation function, 32 as salt length, and 1 as trailer field (which corresponds to the only trailer field byte -- 0xBC -- supported by PSS).

Although PKCS#1 (v.2.1) requires hash algorithm, mask generation algorithm, salt length and trailer field as 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) }
 

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 "SHA256withRSAandMGF1" (in general: <digest>with<encryption>and<mgf>) PSS signature algorithm has to use SHA256 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 (32 for the SHA256 hash algorithm) will be used.

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.
An application also may use a RSAPssSaltParameterSpec or PKCS1AlgorithmParameterSpec 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.

Generally the following steps have to be performed for calculating/verifying a SHA256withRSAandMGF1 signature:

• First an instance of the SHA256withRSAandMGF1 signature engine has to be created using a proper getInstance method:

   Signature pss = Signature.getInstance("SHA256withRSAandMGF1");
   

• 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, optionally the saltLength maybe supplied as RSAPssSaltParameterSpec:

   int saltLength = ...;
   RSAPssSaltParameterSpec saltParamSpec = new RSAPssSaltParameterSpec(hashID, mgfID, saltLength);
   // set the paramters (for JDK 1.1 use pss.setParameter(null, saltParamSpec);)
   pss.setParameter(saltParamSpec); 
   

• 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!"));
     

Version:

File Revision 12

See Also:

Signature

Fields inherited from class iaik.security.rsa.RSAPssSignature

hash

Fields inherited from class java.security.Signature

SIGN, state, UNINITIALIZED, VERIFY

Fields inherited from class java.security.SignatureSpi

appRandom

Constructor Summary

SHA256withRSAandMGF1Signature()
Default constructor.

Method Summary

protected void

engineSetParameter(AlgorithmParameterSpec params) Sets the saltLength parameter for this RSA PSS signature engine.

Methods inherited from class iaik.security.rsa.RSAPssSignature

engineGetParameter, engineGetParameters, engineInitSign, engineInitSign, engineInitVerify, engineSetParameter, engineSign, engineUpdate, engineUpdate, engineVerify

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

Constructor Detail

SHA256withRSAandMGF1Signature

public SHA256withRSAandMGF1Signature()

Default constructor. Shall not be used by an application.

Applications use

 Signature signature = Signature.getInstance("SHA256withRSAandMGF1");
 

to get an instance of this PSS signature engine using SHA256 as hash- and MGF1 (with SHA256) as mask generation algorithm.

Method Detail

engineSetParameter

protected void engineSetParameter(AlgorithmParameterSpec params)
                           throws InvalidAlgorithmParameterException

Sets the saltLength parameter for this RSA PSS signature engine.

Although PKCS#1 (v.2.1) requires hash algorithm, mask generation algorithm, salt length and trailer field as 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) }
 

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.

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.
An application also may use a RSAPssSaltParameterSpec or PKCS1AlgorithmParameterSpec 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 RSAPssSignature

Parameters:

params - the saltLength parameter supplied as RSAPssSaltParameterSpec

Throws:

InvalidParameterException - if the parameters are not supplied as RSAPssSaltParameterSpec or PKCS1AlgorithmParameterSpec