iaik.iso.iso9796

Class ISO9796P2ParameterSpec

java.lang.Object

iaik.iso.iso9796.ISO9796P2ParameterSpec

All Implemented Interfaces:

java.security.spec.AlgorithmParameterSpec

Direct Known Subclasses:

ISO9796P2S2S3ParameterSpec, RawISO9796P2ParameterSpec

public class ISO9796P2ParameterSpec
extends java.lang.Object
implements java.security.spec.AlgorithmParameterSpec

ParameterSpec for the ISO9796-2 signature engines.

ISO 9796-2 specifies three signature schemes (S1, S2, S3) that are based on message recovery. This class represents a parameter specification to maybe used for setting parameters for all three schemes.

Generally the ISO 9796-2 Signature schemes do not use parameters in that sense that they are transmitted with the signature to tell the verifier some information that is required for verifying the signature. Any information that is not included in the signature itself (like, for instance, which of the schemes S1, S2, S3, or which of the underlying signature production functions have been used, or what is the length of salt value used by signature scheme S2 or S3) has to be agreed by other means. This ISO9796P2ParameterSpec class can be used to specify any of the following parameters to any of the ISO 9796-2 Signature engines (S1, S2 or S3) (note that these parameters only can be set to the engine, but not get from it; parameters that are got from the engine represent the recovered part of the message):

• hash engine and hash id: the hash algorithm that is used by an ISO 9796-2 signature scheme may be indicated by using a single hash identifier octet in the range of (hexadecimal) 0x00 to 0xFF. This library contains concrete RSA based ISO 9796-2 Signature engines for the following dedicated hash functions for which hash identifiers are defined by ISO/IEC 10118-3: SHA-1 (S1, S2S3), SHA-256 (S1, S2S3), SHA-384 (S1, S2S3), SHA-512 (S1, S2S3), RIPEMD128 (S1, S2S3) and RIPEMD160 (S1, S2S3). Since ISO/IEC 10118-3 does not define hash ids for, e.g., MD5 and SHA-224, we cannot provide concrete implementations for "MD5/RSA-ISO9796-2" or "SHA224/RSA-ISO9796-2" Signature engines. However, MD5 or SHA-224 may be used with a general (S1, S2S3) RSA based ISO 9796-2 Signature engine and parameterizing it by specifying the hash engine and -- if available -- hash id to be used, e.g.:

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

  You also can set hash engine and/or hash id for any of the concrete ISO 9796-2 Signature engines stated above. However, since these engines are allowed to operate with one specific hash algorithm only, the supplied parameters are checked for compliance and an exception will be thrown if, for instance, trying to set a MD5 MessageDigest engine for a "SHA1/RSA-ISO9796-2" Signature engine.

• Whether to use explicit or implicit trailer field. When signing a message according to ISO 9796-2 at first a message representative is created which then is "signed" (i.e. encrypted for RSA) with the private key of the underlying signature production function (e.g. RSA). The last one or two octets of the message representative represent the so-called trailer field. Depending on if the hash id octet is included in the trailer field (explicit) or if it is not included (implicit) the trailer field consists of two or one octets, respectively. Each of the concrete RSA based ISO 9796-2 implementations listed above uses an implicit trailer field trailer field by default (since it already "knows" the hash algorithms it is using). This means that by default the hash identifier is not included in the trailer field. However, the general (S1, S2S3) RSA based ISO 9796-2 Signature engines use an explicit trailer by default expecting that the hash id is provided as parameter. To change the explicit/implicit trailer field usage set/unset the corresponding boolean useExplicitTrailer flag of the ISO9796P2ParameterSpec object, e.g.:

          // create parameter spec
          ISO9796P2ParameterSpec paramSpec = new ISO9796P2ParameterSpec();
          // set hash engine
          MessageDigest hashEngine = ...;
          int hashLen = ...;
          paramSpec.setHashEngine(hashEngine, hashLen);
          // set hash id
          int hashID = ...;
          paramSpec.setHashID(hashID);
          // switch explicit/implicit trailer field usage if desired
          boolean explicit = ...;
          paramSpecset.setUseExplicitTrailer(explicit);
          // create Signature engine
          Signature signatureEngine = Signature.getInstance("RSA-ISO9796-2", "IAIK");
          // set hash engine and id as parameter
          signatureEngine.setParameter(paramSpec);
          

• Whether to use the alternative signature production function specified in ISO 9796-2 or not. ISO 9796-2 (2002), appendix A specifies two signature production functions to may be used with the underlying public key system (e.g. RSA). The first variant subtract the result of the modulus exponentiation from the modulus and sets it as signature value, if it is shorter than the result of the modulus exponentiation. The second (alternative) method omits this step so that the signature value is always the result of the modulus exponentiation. This ISO 9796-2 implementation uses the second (alternative) variant by default. To enforce the first variant unset the corresponding boolean UseAlternativeSignatureFunction flag of the ISO9796P2ParameterSpec object, e.g.:

          // create parameter spec
          ISO9796P2ParameterSpec paramSpec = new ISO9796P2ParameterSpec();
          // do not use the alternative signature production function:
          paramSpec.setUseAlternativeSignatureFunction(false);
          // create Signature engine
          Signature signatureEngine = Signature.getInstance("SHA1/RSA-ISO9796-2", "IAIK");
          // set hash engine and id as parameter
          signatureEngine.setParameter(paramSpec);
          

• Secure Random Number generator for supplying random numbers if required (e.g. for RSA blinding, or generating a random salt value for ISO 9796-2 signature scheme S2), e.g.:

          // create parameter spec
          ISO9796P2ParameterSpec paramSpec = new ISO9796P2ParameterSpec();
          // create and set SecureRandom:
          SecureRandom secRandom = ...;
          paramSpec.setSecureRandom(secRandom);
          // create Signature engine
          Signature signatureEngine = Signature.getInstance("SHA1/RSA-ISO9796-2", "IAIK");
          // set parameter
          signatureEngine.setParameter(paramSpec);
          

  If no SecureRandom has been explicitly specified via parameterSpec, a default SecureRandom is used for creating random numbers when required by the Signature engine.

For ISO 9796-2 Signature schemes S2, S3 additional parameters (salt value, salt length, mask generation function, cMinus value) maybe specified by using a ISO9796P2S2S3ParameterSpec object.

Version:

File Revision 2

See Also:

ISO9796P2Signature, ISO9796P2S2S3Signature, ISO9796P2S2S3ParameterSpec, RawISO9796P2ParameterSpec, RecoveredMessage, RSAISO9796P2Signature, RSAISO9796P2S2S3Signature, SHAwithRSAISO9796P2Signature, SHA256withRSAISO9796P2Signature, SHA384withRSAISO9796P2Signature, SHA512withRSAISO9796P2Signature, RIPEMD128withRSAISO9796P2Signature, RIPEMD160withRSAISO9796P2Signature, SHAwithRSAISO9796P2S2S3andMGF1Signature, SHA256withRSAISO9796P2S2S3andMGF1Signature, SHA384withRSAISO9796P2S2S3andMGF1Signature, SHA512withRSAISO9796P2S2S3andMGF1Signature, RIPEMD128withRSAISO9796P2S2S3andMGF1Signature, RIPEMD160withRSAISO9796P2S2S3andMGF1Signature

Constructor Summary

Constructors

Constructor and Description
ISO9796P2ParameterSpec() Default constructor.

Method Summary

Methods

Modifier and Type	Method and Description
java.security.MessageDigest	getHashEngine() Gets the JCA MessageDigest engine used for data hashing.
int	getHashID() Gets the hash id.
int	getHashLen() Gets the length of the output of the hash engine that is used by this parameter object.
java.security.SecureRandom	getSecureRandom() Gets the SecureRandom.
boolean	getUseAlternativeSignatureFunction() Checks whether the alternative signature function (ISO 9796-2 Appendix A.6, A.7) is used or not.
boolean	getUseExplicitTrailer() Asks whether an explicit or implicit trailer field shall be used by the ISO 9796-2 Signature engine to which this ParameterSpec shall be supplied.
void	setHashEngine(java.security.MessageDigest hashEngine, int hashLen) Sets the JCA MessageDigest engine to be used by the ISO 9796-2 Signature engine to which this ParameterSpec shall be supplied.
void	setHashID(int hashID) Sets the hash id.
void	setSecureRandom(java.security.SecureRandom random) Sets the SecureRandom to be used by the ISO 9796-2 Signature engine (random salt value creation for signature scheme 2 or for inherent RSA Cipher (blinding)) to which this ParameterSpec shall be supplied.
void	setUseAlternativeSignatureFunction(boolean useAlternativeSignatureFunction) Decides whether to use alternative signature function (ISO 9796-2 Appendix A.6, A.7).
void	setUseExplicitTrailer(boolean useExplicitTrailer) Decides whether an explicit or implicit trailer field shall be used by the ISO 9796-2 Signature engine to which this ParameterSpec shall be supplied.
java.lang.String	toString() Returns a String representation of this ParameterSpec.

Methods inherited from class java.lang.Object

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

Constructor Detail

ISO9796P2ParameterSpec

public ISO9796P2ParameterSpec()

Default constructor. Use any of the set* methods to fill this ParameterSpec object with values.

Method Detail

setHashEngine

public void setHashEngine(java.security.MessageDigest hashEngine,
                 int hashLen)

Sets the JCA MessageDigest engine to be used by the ISO 9796-2 Signature engine to which this ParameterSpec shall be supplied.

Parameters:

hashEngine - the hash engine to be used

hashLen - the length of the hash output value produced by the given hash engine

Throws:

java.lang.NullPointerException - if null is supplied as hash engine

java.lang.IllegalArgumentException - if the supplied hashLen value is negative

getHashEngine

public java.security.MessageDigest getHashEngine()

Gets the JCA MessageDigest engine used for data hashing.

Returns:

the MessageDigest engine to be used, or null if not set by the application

getHashLen

public int getHashLen()

Gets the length of the output of the hash engine that is used by this parameter object.

Returns:

the length of the hash value produced by the hash engine that is used by this ParameterSpec

setHashID

public void setHashID(int hashID)

Sets the hash id.

The hash algorithm that is used by an ISO 9796-2 signature scheme may be indicated by using a single hash identifier octet in the range of (hexadecimal) 0x00 to 0xFF.

Parameters:

hashID - the hash id identifying the hash algorithm in use

Throws:

java.lang.IllegalArgumentException - if the hashID is not in the range from 0 to 255 (0x00 to 0xFF)

getHashID

public int getHashID()

Gets the hash id.

The hash algorithm that is used by an ISO 9796-2 signature scheme may be indicated by using a single hash identifier octet in the range of (hexadecimal) 0x00 to 0xFF.

Returns:

the hash id identifying the hash algorithm in use

setUseExplicitTrailer

public void setUseExplicitTrailer(boolean useExplicitTrailer)

Decides whether an explicit or implicit trailer field shall be used by the ISO 9796-2 Signature engine to which this ParameterSpec shall be supplied. An explicit trailer field encodes the hash id into the signature ({0xCC, hash id}), an implicit trailer field consists of the single byte 0xBC only and omits the hash id (in this case the hash algorithm in use must be known by the verification party).

Parameters:

useExplicitTrailer - whether to use an explicit or implicit trailer field

getUseExplicitTrailer

public boolean getUseExplicitTrailer()

Asks whether an explicit or implicit trailer field shall be used by the ISO 9796-2 Signature engine to which this ParameterSpec shall be supplied. An explicit trailer field encodes the hash id into the signature ({0xCC, hash id}), an implicit trailer field consists of the single byte 0xBC only and omits the hash id (in this case the hash algorithm in use must be known by the verification party).

Returns:

whether to use an explicit or implicit trailer field

setUseAlternativeSignatureFunction

public void setUseAlternativeSignatureFunction(boolean useAlternativeSignatureFunction)

Decides whether to use alternative signature function (ISO 9796-2 Appendix A.6, A.7).
ISO 9796-2, appendix A specifies two possible functions for public key systems used with ISO 9796-2. The first variant subtract the result of the modulus exponentiation from the modulus and sets it as signature value, if it is shorter than the result of the modulus exponentiation. The second (alternative) method omits this step so that the signature value is always the result of the modulus exponentiation. This ISO 9796-2 implementation uses the second (alternative) variant by default. An application may enforce the first variant by setting useAlternativeSignatureFunction to false.

Parameters:

useAlternativeSignatureFunction - whether to use the alternative signature function (true) or not (false)

getUseAlternativeSignatureFunction

public boolean getUseAlternativeSignatureFunction()

Checks whether the alternative signature function (ISO 9796-2 Appendix A.6, A.7) is used or not. ISO 9796-2, appendix A specifies two possible functions for public key systems used with ISO 9796-2. The first variant subtract the result of the modulus exponentiation from the modulus and sets it as signature value, if it is shorter than the result of the modulus exponentiation. The second (alternative) method omits this step so that the signature value is always the result of the modulus exponentiation. This ISO 9796-2 implementation use the second (alternative) variant by the default. An application may enforce the first variant by calling setUseAlternativeSignatureFunction(false). return whether the alternative signature function (true) is used or not (false)

setSecureRandom

public void setSecureRandom(java.security.SecureRandom random)

Sets the SecureRandom to be used by the ISO 9796-2 Signature engine (random salt value creation for signature scheme 2 or for inherent RSA Cipher (blinding)) to which this ParameterSpec shall be supplied.

Parameters:

random - the SecureRandom to be used

getSecureRandom

public java.security.SecureRandom getSecureRandom()

Gets the SecureRandom.

Returns:

the SecureRandom

toString

public java.lang.String toString()

Returns a String representation of this ParameterSpec.

Overrides:

toString in class java.lang.Object

Returns:

a String representation