RawISO9796P2ParameterSpec (6.0 API Documentation)

java.lang.Object
- iaik.iso.iso9796.ISO9796P2ParameterSpec
- - iaik.iso.iso9796.RawISO9796P2ParameterSpec

All Implemented Interfaces:

java.security.spec.AlgorithmParameterSpec
```
public class RawISO9796P2ParameterSpec
extends ISO9796P2ParameterSpec
```
Raw ISO 9796-2 ParameterSpec for specifying message length and recoverable part of message if an ISO 9796-2 S1 Signature engine operates in "raw" mode (where the hash value is calculated outside the engine).
As accustomed from all other IAIK Signature engines, it is also possible to use ISO 9796-2 Signature engines in "raw" mode. "Raw" mode means that the hash value is calculated outside the Signature engine and then set by using an update method of the Signature engine. However, in contrast to the other IAIK Signature engines, there do not exist special "raw" engines for the ISO 9796-2 Signature schemes. In raw mode the hash value (but not the data to be signed) is specified by calling the update method of the engine. However, ISO 9796-2 also needs to know the length of the message and the recoverable part of the message. For an S1 Signature engine this information can be provided by using a RawISO9796P2ParameterSpec; for signature scheme S2 and S3 a RawISO9796P2S2S3ParameterSpec has to be used. When specifying a raw parameter spec the ISO 9796-2 Signature engine automatically switches into the raw mode.
To be able to specify the recoverable part of the message an application must know how many bytes of the message do belong to its recoverable part. The number of bytes that are required for the recoverable part are determined by the capacity of the signature scheme. Depending on if the length of the message is shorter than the capacity, the recovery may be either total or partial. The capacity specifies the maximum length of the recoverable part of the message. Thus an application first will have to calculate the capacity and then check if the length of the message is shorter than the capacity value. If yes (total recovery), the whole message can be supplied as recoverable part. If no, capacity bytes of the message can be supplied as RawISO9796P2ParameterSpec (note that in this case the actual length -- it is calculated during signature creation/verification -- of the recoverable part may be shorter than the capacity; however, it is more safe to supply the maximum number of required bytes than accidently supplying not enough bytes). For signature scheme S1 the capacity depends on the modulus length of the private/public key in use, the length of the underlying hash algorithm, and whether the hash id is (to be) included in the trailer field (two octets) or not (one octet). If you are (e.g. on the verification side) not sure if the trailer field consists of two or one octets, set explicit to true when calculating the capacity (so that the max number of two octets is assumed). Since the capacity has to be calculated in bits, you will have to specify the required modulus length and hash length as number of bits, e.g. (see also sample source of demo.TestSignature):
```
 // the private RSA signing key:
 RSAPrivateKey privateKey = ...;
 int modLen = privateKey.getModulus().bitLength();
 // hash algorithm is SHA-1 
 int hashLength = 160;
 // we do not include hash id (implicit trailer)
 boolean explicit = false;
 // calculate capacity
 int capacity = ISO9796P2Signature.calculateCapacity(modLen, 
                                                     hashLength,
                                                     explicit);
 // the message to be signed:
 byte[] message = ...;
 int msgLen = message.length;
 // create recoverable message part
 int len = Math.min(msgLen, capacity/8);
 byte[] mr = new byte[len];
 System.arraycopy(message, 0, mr, 0, len);
 // create raw parameters
 RawISO9796P2ParameterSpec rawParamSpec = new RawISO9796P2ParameterSpec("SHA-1", 
                                                                        hashLength/8, 
                                                                        mr, 
                                                                        msgLen);                                                    
 
```
When now setting the RawISO9796P2ParameterSpec as parameter for the ISO 9796-2 Signature engine, the engine automatically operates in raw mode. This makes it necessary to calculate the hash value from the message outside the Signature engine, and provide the hash value when calling the update method of the engine:
```
 // calculate hash value:
 MessageDigest hashEngine = MessageDigest.getInstance("SHA-1", "IAIK");
 byte[] rawHash = hashEngine.digest(message);
 // create the Signature engine:
 Signature signatureEngine = Signature.getInstance("SHA/RSA-ISO9796-2", "IAIK");
 // init Signature engine with private key for signing
 signatureEngine.initSign(privateKey);
 // set parameter
 signatureEngine.setParameter(rawParamSpec);
 // update engine with raw hash 
 signatureEngine.update(rawHash);      
 // finally calculate the signature
 byte[] signature = signatureEngine.sign(); 
 
```
On the verification side the proceeding for operating in raw mode is quite similar, except for that you have to use the public verification key and finally use method verify to verify the signature:
```
 // the public RSA verification key:
 RSAPublicKey publicKey = ...;
 int modLen = publicKey.getModulus().bitLength();
 // hash algorithm is SHA-1 
 int hashLength = 160;
 // implicit trailer
 boolean explicit = false;
 // calculate capacity
 int capacity = ISO9796P2Signature.calculateCapacity(modLen, 
                                                     hashLength,
                                                     explicit);
 // the message that has been signed:
 byte[] message = ...;
 int msgLen = message.length;
 // create recoverable message part
 int len = Math.min(msgLen, capacity/8);
 byte[] mr = new byte[len];
 System.arraycopy(message, 0, mr, 0, len);
 // create raw parameters
 RawISO9796P2ParameterSpec rawParamSpec = new RawISO9796P2ParameterSpec("SHA-1", 
                                                                        hashLength/8, 
                                                                        mr, 
                                                                        msgLen);   
 // calculate hash value:
 MessageDigest hashEngine = MessageDigest.getInstance("SHA-1", "IAIK");
 byte[] rawHash = hashEngine.digest(message);
 // create the Signature engine:
 Signature signatureEngine = Signature.getInstance("SHA/RSA-ISO9796-2", "IAIK");
 // init Signature engine with public key for verification
 signatureEngine.initVerify(publicKey);
 // set parameter
 signatureEngine.setParameter(rawParamSpec);
 // update engine with raw hash 
 signatureEngine.update(rawHash);      
 // finally verify the signature
 boolean ok = signatureEngine.verify(signature);                                                                                                                         
 
```
Version:

File Revision 1

See Also:
RawISO9796P2S2S3ParameterSpec, ISO9796P2Signature, RecoveredMessage, RSAISO9796P2Signature, SHAwithRSAISO9796P2Signature, SHA256withRSAISO9796P2Signature, SHA384withRSAISO9796P2Signature, SHA512withRSAISO9796P2Signature, RIPEMD128withRSAISO9796P2Signature, RIPEMD160withRSAISO9796P2Signature

Constructor Summary

Constructors
Constructor and Description
`RawISO9796P2ParameterSpec(java.lang.String hashAlgorithm, int hashLen, byte[] Mr, int msgLen)` Creates a RawISO9796P2ParameterSpec from given hash algorithm name, hash len, recoverable message bytes and message length.

Method Summary

Methods
Modifier and Type	Method and Description
`byte[]`	`getMr()` Gets the recoverable message bytes.
`int`	`getMsgLen()` Gets the total length of the message to be signed.
`java.lang.String`	`toString()` Returns a String representation of this ParameterSpec.

Methods inherited from class iaik.iso.iso9796.ISO9796P2ParameterSpec
getHashEngine, getHashID, getHashLen, getSecureRandom, getUseAlternativeSignatureFunction, getUseExplicitTrailer, setHashEngine, setHashID, setSecureRandom, setUseAlternativeSignatureFunction, setUseExplicitTrailer

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - RawISO9796P2ParameterSpec
```
public RawISO9796P2ParameterSpec(java.lang.String hashAlgorithm,
                         int hashLen,
                         byte[] Mr,
                         int msgLen)
```
    Creates a RawISO9796P2ParameterSpec from given hash algorithm name, hash len, recoverable message bytes and message length.
    
    Parameters:
    hashAlgorithm - the name of hash algorithm to be used (e.g. SHA-1)
    hashLen - the length (in bytes) of the output value of the hash algorithm in use (e.g. 20)
    Mr - any bytes that may contribute to the recoverable part of the message
    msgLen - the total length of the message to be signed
    
    Throws:
    
    java.lang.NullPointerException - if Mr is null
    
    java.lang.IllegalArgumentException - if the supplied hashLen value is negative
    
    java.lang.IllegalArgumentException - if the supplied msgLen value is negative
- Method Detail
  - getMr
```
public byte[] getMr()
```
    Gets the recoverable message bytes.
    
    Returns:
    the recoverable message bytes
  - getMsgLen
```
public int getMsgLen()
```
    Gets the total length of the message to be signed.
    
    Returns:
    the message length
  - toString
```
public java.lang.String toString()
```
    Returns a String representation of this ParameterSpec.
    
    Overrides:
    
    toString in class ISO9796P2ParameterSpec
    
    Returns:
    a String representation

Class RawISO9796P2ParameterSpec

Constructor Summary

Method Summary

Methods inherited from class iaik.iso.iso9796.ISO9796P2ParameterSpec

Methods inherited from class java.lang.Object

Constructor Detail

RawISO9796P2ParameterSpec

Method Detail

getMr

getMsgLen

toString