iaik.security.rsa

Class WHIRLPOOLwithRSAISO9796P2S2S3andMGF1Signature

java.lang.Object

java.security.SignatureSpi

iaik.iso.iso9796.ISO9796P2Signature

iaik.iso.iso9796.ISO9796P2S2S3Signature

iaik.security.rsa.RSAISO9796P2S2S3Signature

iaik.security.rsa.WHIRLPOOLwithRSAISO9796P2S2S3andMGF1Signature

public class WHIRLPOOLwithRSAISO9796P2S2S3andMGF1Signature
extends RSAISO9796P2S2S3Signature

ISO 9796-2 Signature engine (scheme S2, S3) that uses RSA as underlying public key system and WHIRLPOOL as message digest algorithm.

ISO 9796 (2002) Part 2 ("Digital Signature schemes giving message recovery, Part 2: Integer factorization based mechanisms") specifies three digital signature schemes S1, S2 and S3. S1 and S3 are deterministic, S2 is randomized by a random salt value. ISO 9796-2 recommends to use the randomized scheme (S2) where possible; and to prefer S3 to S1, which only shall be used if backwards compatibility to the 1997 version of the ISO 9796-2 standard is required.
This class implements the S2 and S3 schemes for the RSA public key system with WHIRLPOOL as hash algorithm and MGF1 as mask generation function. See WHIRLPOOLwithRSAISO9796P2Signature for the RSA based implementation of signature scheme S1.

Scheme S2 and S3 only differ in the usage of random or fixed salt value, respectively. By default this class uses a random salt value as required for signature scheme S2. For using signature scheme S3 an application may specify a fixed salt value as ISO9796P2S2S3ParameterSpec:

 // create parameter spec
 ISO9796P2S2S3ParameterSpec paramSpec = new ISO9796P2S2S3ParameterSpec();
 // set fixed salt value 
 byte[] salt = ...;
 paramSpec.setSalt(salt);
 // create Signature engine
 Signature signatureEngine = Signature.getInstance("WHIRLPOOLandMGF1/RSA-ISO9796-2-2-3", "IAIK");
 // set salt value as parameter
 signatureEngine.setParameter(paramSpec);
 

When specifying a fixed salt value as shown above the scheme that is actually used switches from S2 to S3.

The table below shows the default configuration for this RSA based ISO 9796-2-2-3 Signature engine. For each option, the column "changeable" tells you if you can change the corresponding setting with an alternative value, supplied as ISO9796P2S2S3ParameterSpec.

	Value	Changeable
Hash Algorithm	WHIRLPOOL	no
Hash ID	0x37	no
Hash Engine	iaik.security.md.Whirlpool	yes (but must be a MessageDigest engine for the WHIRLPOOL algorithm)
Explicit Trailer Field	false	yes
Alternative Signature Function	true	yes
SecureRandom	iaik.security.random.WhirlpoolRandom	yes
Salt length	64 (same as hash size of WHIRLPOOL)	yes
Salt value	randomly created	yes
Mask generation function	MGF1	no
MGF engine	iaik.pkcs.pksc1.MGF1	yes (but must be a MGF engine for the MGF1 algorithm)
cMinus value	0 (maximum recovery)	yes

When creating a RSA-ISO9796-2 Signature engine for signature scheme S2, S3 with WHIRLPOOL as hash and MGF1 as mask generation algorithm you have to specify "WHIRLPOOLandMGF1/RSA-ISO9796-2-2-3" as algorithm name (the first "2" in the name indicates the "Part 2" version of the ISO 9796 Signature standard). Subsequently init the Signature engine with the private signing or public verification RSA key and then specify the data to be signed/verified through one or -- if required -- more calls of method update. Finally create or verify the signature value by calling method sign or verify, respectively, e.g. (see also demo source of class demo.TestSignature):

 // create Signature engine
 Signature signatureEngine = Signature.getInstance("WHIRLPOOLandMGF1/RSA-ISO9796-2-2-3", "IAIK");
 // the private signing key
 PrivateKey privateKey = ...;
 signatureEngine.initSign(privateKey);
 // supply data to be signed by one or more update calls
 signatureEngine.update(...);
 ...
 // create signature
 byte[] signature = signatureEngine.sign();
 

And on the verification side:

 // create Signature engine
 Signature signatureEngine = Signature.getInstance("WHIRLPOOLandMGF1/RSA-ISO9796-2-2-3", "IAIK");
 // the public verification key
 PublicKey publicKey = ...;
 signatureEngine.initVerify(publicKey);
 // supply data to be verified by one or more update calls
 signatureEngine.update(...);
 ...
 // verify signature
 boolean ok = signatureEngine.verify(signature);
 

Since ISO 9796-2 represents a signature algorithm giving message recovery, you may get the recovered part of the message after having verified the signature, e.g.:

 
 // get the recovered message:
 AlgorithmParameters recoveredMessage = 
   (AlgorithmParameters)signatureEngine.getParameters();
 byte[] rm = recoveredMessage.getEncoded();
 

The recovered message will be equal to the original message if total recovery has been applied. In this case it is possible to verify the signature without calling method update of the Signature engine at all (see Javadoc of RecoveredMessage for more information).

This Signature engine also can operate in "raw" mode where the hash value is calulated outside the engine and specified when calling method update. However, when running this engine in raw mode, you have to specify the total message length and the recoverable part of the message as RawISO9796P2S2S3ParameterSpec.

Version:

File Revision 3

See Also:

Signature, ISO9796P2S2S3Signature, ISO9796P2S2S3ParameterSpec, RawISO9796P2S2S3ParameterSpec, RecoveredMessage, RSAISO9796P2S2S3Signature, RSAISO9796P2Signature

Field Summary

Fields

Modifier and Type	Field and Description
static byte	HASH_ID ID for WHIRLPOOL hash algorithm; implicitly specified in trailer field.

Fields inherited from class iaik.iso.iso9796.ISO9796P2S2S3Signature

mgfEngine_

Fields inherited from class iaik.iso.iso9796.ISO9796P2Signature

hashEngine_, secureRandom_

Fields inherited from class java.security.SignatureSpi

appRandom

Constructor Summary

Constructors

Constructor and Description
WHIRLPOOLwithRSAISO9796P2S2S3andMGF1Signature() Default Constructor.

Method Summary

Methods

Modifier and Type	Method and Description
protected boolean	checkHashEngineName(java.lang.String hashAlgName) Checks whether the given hash algorithm name is suitable for this Signature engine.
protected java.security.SecureRandom	getSecureRandom() Gets the SecureRandom used by this Signature engine.

Methods inherited from class iaik.security.rsa.RSAISO9796P2S2S3Signature

engineInitSign, engineInitSign, engineInitVerify, openSignature, produceSignature, setSecureRandom

Methods inherited from class iaik.iso.iso9796.ISO9796P2S2S3Signature

calculateCapacity, calculateCapacity, engineSetParameter, engineSign, engineUpdate, engineUpdate, engineVerify, reset

Methods inherited from class iaik.iso.iso9796.ISO9796P2Signature

engineGetParameter, engineGetParameters, engineSetParameter, registerHashEngine

Methods inherited from class java.security.SignatureSpi

clone, engineSign, engineUpdate, engineVerify

Methods inherited from class java.lang.Object

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

Field Detail

HASH_ID

public static final byte HASH_ID

ID for WHIRLPOOL hash algorithm; implicitly specified in trailer field.

See Also:

Constant Field Values

Constructor Detail

WHIRLPOOLwithRSAISO9796P2S2S3andMGF1Signature

public WHIRLPOOLwithRSAISO9796P2S2S3andMGF1Signature()

Default Constructor.

Applications do not call this constructor. They shall use one of the getInstance methods of the java.security.Signature class for instantiating a WHIRLPOOLandMGF1/RSA-ISO9796-2-2-3 Signature object:

 Signature signatureEngine = Signature.getInstance("WHIRLPOOLandMGF1/RSA-ISO9796-2-2-3", "IAIK");
 

See Also:

Signature.getInstance(java.lang.String)

Method Detail

checkHashEngineName

protected boolean checkHashEngineName(java.lang.String hashAlgName)

Checks whether the given hash algorithm name is suitable for this Signature engine. This method is used for checking if a MessageDigest engine that has been supplied as parameter can be used with this Signature engine.

Overrides:

checkHashEngineName in class ISO9796P2Signature

Parameters:

hashAlgName - the name of hash algorithm of the MessageDigest engine that has been supplied as parameter to this Signature engine

Returns:

true if the given hashAlgName is "WHIRLPOOL" or "WHIRLPOOL" (case insensitive), false otherwise

getSecureRandom

protected java.security.SecureRandom getSecureRandom()

Gets the SecureRandom used by this Signature engine. If no SecureRandom has been explicitly set as parameter, a default SecureRandom is created and returned.

Overrides:

getSecureRandom in class ISO9796P2Signature

Returns:

the SecureRandom used by this Signature engine