RecoveredMessage (6.0 API Documentation)

java.lang.Object
- java.security.AlgorithmParametersSpi
- - iaik.iso.iso9796.RecoveredMessage

```
public final class RecoveredMessage
extends java.security.AlgorithmParametersSpi
```
Represents the recovered part of the message for which a signature is verified according to ISO9796-2.
ISO 9796-2 specifies three signature schemes (S1, S2, S3) that are based on message recovery. In contrast to signature schemes with appendix (as for instance used by the signature schemes defined in PKCS#1) where the whole data has to be transmitted with the signature, message recovery means that the input data -- or parts of the input data -- can be recovered from the signature. Depending on if the length of the message is shorter than the capacity of the signature scheme, the recovery may be either total or partial. For digital signature scheme S1 the capacity is calculated from the modulus length of the private/public key in use and the length of the underlying hash algorithm. Signature schemes S2, S3 calculate the capacity from modulus length, hash length and length of the salt value that is used.
In general JCA Signature engines are not designed for signature schemes giving message recovery. A JCA Signature engine requires that the data to be signed or verified is supplied by one or more calls of its update methods, and the verify method only returns whether the signature has been verified successfully or signature verification has failed. There is no general means for fetching the recovered part of the message from the Signature engine. For that reason we have implemented this RecoveredMessage class. It allows to get the recovered part of the message as parameter from the engine after the signature has been verified (by having called method verify), e.g.:
```
 // create Signature engine
 Signature signatureEngine = Signature.getInstance("SHA1/RSA-ISO9796-2", "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);
 // get the recovered part of the message:
 AlgorithmParameters recoveredMessage = 
   (AlgorithmParameters)signatureEngine.getParameters();
 byte[] rm = recoveredMessage.getEncoded();
 
```
When total recovery has been applied the recovered part of the message got from the Signature engine will be equal to the original message. In this case it is also possible to verify the signature without supplying the data (i.e. method update may not be called at all) and then get the recovered message from the Signature engine as RecoveredMessage parameter:
```
 // create Signature engine
 Signature signatureEngine = Signature.getInstance("SHA1/RSA-ISO9796-2", "IAIK");
 // the public verification key
 PublicKey publicKey = ...;
 signatureEngine.initVerify(publicKey);
 // verify signature
 boolean ok = signatureEngine.verify(signature);
 // get the recovered message:
 AlgorithmParameters recoveredMessage = 
   (AlgorithmParameters)signatureEngine.getParameters();
 byte[] message = recoveredMessage.getEncoded();
 
```
Note that you also can get the recovered part of the message when partial recovery has been applied. However, this may not be necessary since in the case of partial recovery you will have to supply the full message via update calls anyway as required by the JCA Signature API. This may be no disadvantage since in practice the document usually may be transmitted along with the signature (and not splitted into a recoverable and not-recoverable part to then be put together again at the receiving side).
Method getParameters only will return the recovered part of the message if it is called after method verify has been called. In any other case you will get null indicating that the Signature engine is in a state where no recovered message is available. It also is not possible to set the recovered message as algorithm parameter for the Signature engine. The recovered part of the message is gained from the signature during the verification process and therefore only can be get from the engine but not set.
Version:

File Revision 2

See Also:
ISO9796P2S2S3Signature, ISO9796P2ParameterSpec, ISO9796P2S2S3ParameterSpec, RawISO9796P2ParameterSpec, RawISO9796P2S2S3ParameterSpec, RSAISO9796P2Signature, RSAISO9796P2S2S3Signature, SHAwithRSAISO9796P2Signature, SHA256withRSAISO9796P2Signature, SHA384withRSAISO9796P2Signature, SHA512withRSAISO9796P2Signature, RIPEMD128withRSAISO9796P2Signature, RIPEMD160withRSAISO9796P2Signature, SHAwithRSAISO9796P2S2S3andMGF1Signature, SHA256withRSAISO9796P2S2S3andMGF1Signature, SHA384withRSAISO9796P2S2S3andMGF1Signature, SHA512withRSAISO9796P2S2S3andMGF1Signature, RIPEMD128withRSAISO9796P2S2S3andMGF1Signature, RIPEMD160withRSAISO9796P2S2S3andMGF1Signature

Constructor Summary

Constructors
Constructor and Description

RecoveredMessage()
Empty default constructor.

Constructors
Constructor and Description
`RecoveredMessage()` Empty default constructor.

Method Summary

Methods
Modifier and Type	Method and Description
`protected byte[]`	`engineGetEncoded()` Returns the recovered part of the message.
`protected byte[]`	`engineGetEncoded(java.lang.String format)` Returns the recovered part of the message.
`protected java.security.spec.AlgorithmParameterSpec`	`engineGetParameterSpec(java.lang.Class paramSpec)` Returns null in any case since not required.
`protected void`	`engineInit(java.security.spec.AlgorithmParameterSpec paramSpec)` Not required.
`protected void`	`engineInit(byte[] params)` Inits this RecoveredMessage object with the recovered message bytes.
`protected void`	`engineInit(byte[] params, java.lang.String format)` Inits this RecoveredMessage object with the recovered message bytes.
`protected java.lang.String`	`engineToString()` Returns a String representation of this object.

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

- Constructor Detail
  - RecoveredMessage
```
public RecoveredMessage()
```
    Empty default constructor. Required for dynamic object creation. May not be used by an application.
- Method Detail
  - engineInit
```
protected void engineInit(java.security.spec.AlgorithmParameterSpec paramSpec)
                   throws java.security.spec.InvalidParameterSpecException
```
    Not required. Does nothing.
    
    Specified by:
    
    engineInit in class java.security.AlgorithmParametersSpi
    
    Throws:
    
    java.security.spec.InvalidParameterSpecException
  - engineInit
```
protected void engineInit(byte[] params)
                   throws java.io.IOException
```
    Inits this RecoveredMessage object with the recovered message bytes.
    
    Specified by:
    
    engineInit in class java.security.AlgorithmParametersSpi
    
    Parameters:
    params - the bytes representing the recovered part of the message
    
    Throws:
    
    java.io.IOException - if an error occurs during initialization
  - engineInit
```
protected void engineInit(byte[] params,
              java.lang.String format)
                   throws java.io.IOException
```
    Inits this RecoveredMessage object with the recovered message bytes.
    
    Specified by:
    
    engineInit in class java.security.AlgorithmParametersSpi
    
    Parameters:
    params - the bytes representing the recovered part of the message
    format - ignored
    
    Throws:
    
    java.io.IOException - if an error occurs during initialization
  - engineGetParameterSpec
```
protected java.security.spec.AlgorithmParameterSpec engineGetParameterSpec(java.lang.Class paramSpec)
```
    Returns null in any case since not required.
    
    Specified by:
    
    engineGetParameterSpec in class java.security.AlgorithmParametersSpi
    
    Returns:
    null
  - engineGetEncoded
```
protected byte[] engineGetEncoded()
                           throws java.io.IOException
```
    Returns the recovered part of the message.
    
    Specified by:
    
    engineGetEncoded in class java.security.AlgorithmParametersSpi
    
    Returns:
    a byte array holding the recovered part of the message
    
    Throws:
    
    java.io.IOException - if an error occurs during message recovery
  - engineGetEncoded
```
protected byte[] engineGetEncoded(java.lang.String format)
                           throws java.io.IOException
```
    Returns the recovered part of the message.
    
    Specified by:
    
    engineGetEncoded in class java.security.AlgorithmParametersSpi
    
    Parameters:
    format - ignored
    
    Returns:
    a byte array holding the recovered part of the message
    
    Throws:
    
    java.io.IOException - if an error occurs during message recovery
  - engineToString
```
protected java.lang.String engineToString()
```
    Returns a String representation of this object.
    
    Specified by:
    
    engineToString in class java.security.AlgorithmParametersSpi
    
    Returns:
    a String representation of the recovered message bytes

Class RecoveredMessage

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

RecoveredMessage

Method Detail

engineInit

engineInit

engineInit

engineGetParameterSpec

engineGetEncoded

engineGetEncoded

engineToString