iaik.security.rsa

Class RSAISO9796P2S2S3Signature

java.lang.Object

java.security.SignatureSpi

iaik.iso.iso9796.ISO9796P2Signature

iaik.iso.iso9796.ISO9796P2S2S3Signature

iaik.security.rsa.RSAISO9796P2S2S3Signature

Direct Known Subclasses:

RIPEMD128withRSAISO9796P2S2S3andMGF1Signature, RIPEMD160withRSAISO9796P2S2S3andMGF1Signature, SHA256withRSAISO9796P2S2S3andMGF1Signature, SHA384withRSAISO9796P2S2S3andMGF1Signature, SHA512withRSAISO9796P2S2S3andMGF1Signature, SHAwithRSAISO9796P2S2S3andMGF1Signature, WHIRLPOOLwithRSAISO9796P2S2S3andMGF1Signature

public class RSAISO9796P2S2S3Signature
extends ISO9796P2S2S3Signature

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

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. See RSAISO9796P2Signature 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("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.

By default this class uses the SHA-1 digest algorithm for hash calculation, but it can be used with any alternative hash algorithm for which a MessageDigest engine is available. If you want to use a different hash algorithm you will have to specify it by means of a ISO9796P2S2S3ParameterSpec object, e.g.:

 // create parameter spec
 ISO9796P2S2S3ParameterSpec paramSpec = new ISO9796P2S2S3ParameterSpec();
 // set hash engine
 MessageDigest hashEngine = MessageDigest.getInstance("SHA-224", "IAIK");
 int hashLen = 28;
 paramSpec.setHashEngine(hashEngine, hashLen);
 // set hash id
 int hashID = ...;
 paramSpec.setHashID(hashID);
 // create Signature engine
 Signature signatureEngine = Signature.getInstance("RSA-ISO9796-2-2-3", "IAIK");
 // set hash engine and id as parameter
 signatureEngine.setParameter(paramSpec);
 

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	SHA-1	yes
Hash ID	0x33	yes
Hash Engine	iaik.security.md.SHA	yes
Explicit Trailer Field	true	yes
Alternative Signature Function	true	yes
SecureRandom	iaik.security.random.SHA1Random	yes
Salt length	20 (same as hash size of SHA-1)	yes
Salt value	randomly created	yes
Mask generation function	MGF1	yes
MGF engine	iaik.pkcs.pksc1.MGF1	yes
cMinus value	0 (maximum recovery)	yes

When creating a RSA-ISO9796-2 Signature engine for signature scheme S2, S3, you have to specify "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("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("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 2

See Also:

Signature, ISO9796P2S2S3Signature, ISO9796P2S2S3ParameterSpec, RawISO9796P2S2S3ParameterSpec, RecoveredMessage, SHAwithRSAISO9796P2S2S3andMGF1Signature, SHA256withRSAISO9796P2S2S3andMGF1Signature, SHA384withRSAISO9796P2S2S3andMGF1Signature, SHA512withRSAISO9796P2S2S3andMGF1Signature, RIPEMD128withRSAISO9796P2S2S3andMGF1Signature, RIPEMD160withRSAISO9796P2S2S3andMGF1Signature, RSAISO9796P2Signature

Field Summary

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

Modifier	Constructor and Description
	RSAISO9796P2S2S3Signature() Default constructor.
protected	RSAISO9796P2S2S3Signature(java.lang.String name, int hLen, byte hashID) Creates a RSA ISO 9796-2-2-3 Signature object with the given name using the supplied hash ID and hash length.

Method Summary

Methods

Modifier and Type	Method and Description
protected void	engineInitSign(java.security.PrivateKey pk) SPI: Initializes this Signature object with the given RSA private key for going to sign some data.
protected void	engineInitSign(java.security.PrivateKey pk, java.security.SecureRandom random) SPI: Initializes this Signature object with the given RSA private key for going to sign some data.
protected void	engineInitVerify(java.security.PublicKey pk) SPI: Initializes this Signature object with the given RSA public key for performing a signature verification.
protected byte[]	openSignature(byte[] signature) Performs the initial signature opening operation (decryption with the RSA public verification key).
protected byte[]	produceSignature(byte[] toBeSigned) Performs the final signature production operation (encryption with the RSA private signing key).
protected void	setSecureRandom(java.security.SecureRandom random) Sets the SecureRandom to be used by this Signature engine.

Methods inherited from class iaik.iso.iso9796.ISO9796P2S2S3Signature

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

Methods inherited from class iaik.iso.iso9796.ISO9796P2Signature

checkHashEngineName, engineGetParameter, engineGetParameters, engineSetParameter, getSecureRandom, 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

Constructor Detail

RSAISO9796P2S2S3Signature

public RSAISO9796P2S2S3Signature()

Default constructor.
Required for dynamic object creation. An application shall use

 Signature.getInstance("RSA-ISO9796-2-2-3", "IAIK");
 

for instantiating an RSA-ISO9796-2-2-3 Signature engine.

See Also:

Signature.getInstance(java.lang.String)

RSAISO9796P2S2S3Signature

protected RSAISO9796P2S2S3Signature(java.lang.String name,
                         int hLen,
                         byte hashID)

Creates a RSA ISO 9796-2-2-3 Signature object with the given name using the supplied hash ID and hash length.

An application shall use

 Signature.getInstance("RSA-ISO9796-2-2-3", "IAIK");
 

for instantiating an RSA-ISO9796-2-2-3 Signature engine.

Parameters:

name - the name of the signature engine

hLen - the length of the output value of the hash algorithm that is used by this Signature engine

hashID - the identification byte of the hash algorithm in use

See Also:

Signature.getInstance(java.lang.String)

Method Detail

engineInitVerify

protected void engineInitVerify(java.security.PublicKey pk)
                         throws java.security.InvalidKeyException

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

Specified by:

engineInitVerify in class java.security.SignatureSpi

Parameters:

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

Throws:

java.security.InvalidKeyException - if the supplied key cannot be used for initializing this engine

engineInitSign

protected void engineInitSign(java.security.PrivateKey pk)
                       throws java.security.InvalidKeyException

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

Specified by:

engineInitSign in class java.security.SignatureSpi

Parameters:

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

Throws:

java.security.InvalidKeyException - if the supplied key cannot be used for initializing this engine

engineInitSign

protected void engineInitSign(java.security.PrivateKey pk,
                  java.security.SecureRandom random)
                       throws java.security.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. RSA blinding, random salt value creation for signature scheme S2).

If a SecureRandom never has been supplied by the application, the signature engine will use a default SecureRandom, if required.

Overrides:

engineInitSign in class java.security.SignatureSpi

Parameters:

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

random - the SecureRandom if random numbers are required by the signature engine

Throws:

java.security.InvalidKeyException - if the supplied key cannot be used for initializing this engine

produceSignature

protected byte[] produceSignature(byte[] toBeSigned)
                           throws java.security.SignatureException

Performs the final signature production operation (encryption with the RSA private signing key). This method is called at the end of the signature calculation procedure.

Specified by:

produceSignature in class ISO9796P2Signature

Parameters:

toBeSigned - the ISO 9796-2 (S2, S3) prepared message representative to be signed

Returns:

the signature value

Throws:

java.security.SignatureException - if an error occurs when producing the signature value

openSignature

protected byte[] openSignature(byte[] signature)
                        throws java.security.SignatureException

Performs the initial signature opening operation (decryption with the RSA public verification key). This method is called at the begin of the signature verification procedure.

Specified by:

openSignature in class ISO9796P2Signature

Parameters:

signature - the signature value to be opened

Returns:

the opened signature value to be further processed according to ISO 9796-2 (S2, S3)

Throws:

java.security.SignatureException - if an error occurs when opening the signature

setSecureRandom

protected void setSecureRandom(java.security.SecureRandom random)

Sets the SecureRandom to be used by this Signature engine. Subclasses only may use this method to set the SecureRandom object, if required.

Overrides:

setSecureRandom in class ISO9796P2Signature

Parameters:

random - the SecureRandom to be used by this signature engine