iaik.security.rsa

Class RSAPssSignature

java.lang.Object

java.security.SignatureSpi

iaik.security.rsa.RSAPssSignature

Direct Known Subclasses:

MD2withRSAandMGF1Signature, MD5withRSAandMGF1Signature, RawRSAPssSignature, RIPEMD128withRSAandMGF1Signature, RIPEMD160withRSAandMGF1Signature, SHA224withRSAandMGF1Signature, SHA256withRSAandMGF1Signature, SHA3_224withRSAandMGF1Signature, SHA3_256withRSAandMGF1Signature, SHA3_384withRSAandMGF1Signature, SHA3_512withRSAandMGF1Signature, SHA384withRSAandMGF1Signature, SHA512_224withRSAandMGF1Signature, SHA512_256withRSAandMGF1Signature, SHA512withRSAandMGF1Signature, SHAwithRSAandMGF1Signature, WHIRLPOOLwithRSAandMGF1Signature

public class RSAPssSignature
extends java.security.SignatureSpi

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 (default: SHA-1, MGF1, 20), 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); 
   

  If RSASSA-PSS keys (RSAPssPrivateKey, RSAPssPublicKey) are used for initializing this Signature engine, they may contain PSS parameters. In this case the parameters are taken from the keys, except for the application explicitly specifies parameters by calling method setParameter. If parameters are specified by calling method setParameter they may have to be validated against the parameters contained in the key (according to RFC 4055, the Signature engine must be only used with the hash algorithm, mask generation function and trailer field parameters that are specified in the key). By default no such validation is performed since it may be the responsibility of the application to take care for proper parameters (or the application may wish to verify a signature even if parameters are used that differ from the key parameters). Parameter validation can be turned on/off by calling static method setValidateAgainstPssKeyParameters.

• 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 modeling 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 42

See Also:

SHAwithRSAandMGF1Signature