**javacard.security** 
 ====Interface SignatureMessageRecovery  ====

 ----





A subclass of the abstract Signature class must implement this
 SignatureMessageRecovery interface to provide message recovery
 functionality. An instance implementing this interface is returned by the
 [[javacard:java-card-api:Signature#getInstance(byte, boolean)|Signature.getInstance(byte, boolean)]]  method when algorithm type with suffix *_MR
 is specified. e.g.[[javacard:java-card-api:Signature#ALG_RSA_SHA_ISO9796_MR|Signature.ALG_RSA_SHA_ISO9796_MR]] .
 This interface provides specialized versions of some of the methods defined
 in the Signature class to provide message recovery functions. An alternate
 version of the sign() and verify() methods is supported here
 along with a new beginVerify method to allow the message encoded
 in the signature to be recovered.
 For signing a message with message recovery functionality, the user must
 cast the Signature object to this interface, initialize the object for signing
 with a private key using the init() method, and issue 0 or more update() method
 calls and then finally call the sign() method to obtain the signature.
 For recovering the encoded message and verifying functionality, the user must
 cast the Signature object to this interface, initialize the object for verifying
 with a public key using the init() method, first recover the message
 using the beginVerify() method and then issue 0 or more update() method
 calls and then finally call the verify() method to verify the signature.
 Note:A Signature object implementing this interface must throw CryptoException
 with CryptoException.ILLEGAL_USE reason code
 when one of the following methods applicable only to a Signature object which
 does not include message recovery functionality, is called:
 \\ 
 
  *//init(Key, byte, byte[], short, short)// 
 \\ 
  *//sign(byte[], short, short, byte[], short)// 
 \\ 
  *//verify(byte[], short, short, byte[], short, short)// 
 \\  




**Since:**
  2.2.2 
 



 ----







^ Method Summary ^^ 
| ** short** | **[[javacard:java-card-api:SignatureMessageRecovery#beginVerify(byte[], short, short)|beginVerify]] **(byte[] sigAndRecDataBuff,short buffOffset,short sigLength)          This method begins the verification sequence by recovering the message encoded within the signature itself and initializing the internal hash function. |
| ** byte** | **[[javacard:java-card-api:SignatureMessageRecovery#getAlgorithm()|getAlgorithm]] **()          Gets the Signature algorithm. |
| ** short** | **[[javacard:java-card-api:SignatureMessageRecovery#getLength()|getLength]] **()          Returns the byte length of the signature data. |
| ** void** | **[[javacard:java-card-api:SignatureMessageRecovery#init(javacard.security.Key, byte)|init]] **([[javacard:java-card-api:Key|Key]]  theKey,byte theMode)          Initializes the Signature object with the appropriate Key. |
| ** short** | **[[javacard:java-card-api:SignatureMessageRecovery#sign(byte[], short, short, byte[], short, short[], short)|sign]] **(byte[] inBuff,short inOffset,short inLength,byte[] sigBuff,short sigOffset,short[] recMsgLen,short recMsgLenOffset)          Generates the signature of all/last input data. |
| ** void** | **[[javacard:java-card-api:SignatureMessageRecovery#update(byte[], short, short)|update]] **(byte[] inBuff,short inOffset,short inLength)          Accumulates a signature of the input data. |
| ** boolean** | **[[javacard:java-card-api:SignatureMessageRecovery#verify(byte[], short, short)|verify]] **(byte[] inBuff,short inOffset,short inLength)          Verifies the signature of all/last input data against the passed in signature. |

 






^ Method Detail ^ 



 === init === 
void **init**([[javacard:java-card-api:Key|Key]]  theKey,
byte theMode)
throws [[javacard:java-card-api:CryptoException|CryptoException]] 

Initializes the Signature object with the appropriate Key.
 This method should be used for algorithms which do not need initialization parameters
 or use default parameter values.
 init() must be used to update the Signature object with a new key.
 If the Key object is modified after invoking the init() method,
 the behavior of the update(), sign(), and verify()
 methods is unspecified.

 
 

**Parameters:**theKey - the key object to use for signing or verifying 
 
theMode - one of MODE_SIGN or MODE_VERIFY
 
 
**Throws:**
[[javacard:java-card-api:CryptoException|CryptoException]]  - with the following reason codes:
 \\ 
 
  *CryptoException.ILLEGAL_VALUE if theMode option is an undefined value or if the Key is inconsistent with theMode or with the Signature implementation. 
 \\ 
  *CryptoException.UNINITIALIZED_KEY if theKey instance is uninitialized. 
 \\   
 

 
 



 ----


 === beginVerify === 
short **beginVerify**(byte[] sigAndRecDataBuff,
short buffOffset,
short sigLength)
throws [[javacard:java-card-api:CryptoException|CryptoException]] 

This method begins the verification sequence by recovering the message
 encoded within the signature itself and initializing the internal hash
 function. The recovered message data overwrites the signature data in the
 sigAndRecDataBuff input byte array.
 Notes:
 \\ 
 
  *//This method must be called during the verification sequenceprior to either the //update()// or the //verify()// methods during verification.// 
 \\ 
  *// The trailing (//sigLength// - recovered message length) bytes ofsignature data in //sigAndRecDataBuff// may also be overwritten by this method.//
 \\  

 
 

**Parameters:**sigAndRecDataBuff - contains the signature data as input and also
  contains the recoverable part of the message as output. 
 
buffOffset - offset into the sigAndRecDataBuff array where data begins
  for signature and where this method will start writing recovered message data. 
 
sigLength - the length of signature data
 
 
**Returns:**byte length of recovered message data written to sigAndRecDataBuff
 
 
**Throws:**
[[javacard:java-card-api:CryptoException|CryptoException]]  - with the following reason codes:
 \\ 
 
  *CryptoException.ILLEGAL_USE for the following conditions:
 \\  
  *if this object is initialized for signature sign mode 
 \\ 
  *if sigLength is inconsistent with this Signature algorithm 
 \\ 
  *if the decrypted message representative does not meet the algorithm specifications 
 \\ 
  *if the bit length of the decrypted message representative is not a multiple of 8. 
 \\   
 \\ 
  *CryptoException.UNINITIALIZED_KEY if key not initialized. 
 \\ 
  *CryptoException.INVALID_INIT if this Signature object is not initialized. 
 \\   
 

 
 



 ----


 === sign === 
short **sign**(byte[] inBuff,
short inOffset,
short inLength,
byte[] sigBuff,
short sigOffset,
short[] recMsgLen,
short recMsgLenOffset)
throws [[javacard:java-card-api:CryptoException|CryptoException]] 

Generates the signature of all/last input data. In addition, this method
 returns the number of bytes beginning with the first byte of the message
 that was encoded into the signature itself.  The encoded message is called
 the recoverable message and its length is called
 the recoverable message length. This recoverable message 
 need not be transmitted and can be recovered during verification.
 A call to this method also resets this Signature object to the state it was in
 when previously initialized via a call to init().
 That is, the object is reset and available to sign another message.
 The input and output buffer data may overlap.

 
 

**Parameters:**inBuff - the input buffer of data to be signed 
 
inOffset - the offset into the input buffer at which to begin signature generation 
 
inLength - the byte length to sign 
 
sigBuff - the output buffer to store signature data 
 
sigOffset - the offset into sigBuff at which to begin signature data 
 
recMsgLen - the output buffer containing the number of bytes of the recoverable message
 beginning with the first byte of the message that was encoded into the signature itself 
 
recMsgLenOffset - offset into the recMsgLen output buffer where
 the byte length of the recoverable message is stored. Note that a single short value is
 stored at recMsgLenOffset offset.
 
 
**Returns:**number of bytes of signature output in sigBuff
 
 
**Throws:**
[[javacard:java-card-api:CryptoException|CryptoException]]  - with the following reason codes:
 \\ 
 
  *CryptoException.UNINITIALIZED_KEY if key not initialized. 
 \\ 
  *CryptoException.INVALID_INIT if this Signature object is not initialized or initialized for signature verify mode. 
 \\   
 

 
 



 ----


 === verify === 
boolean **verify**(byte[] inBuff,
short inOffset,
short inLength)
throws [[javacard:java-card-api:CryptoException|CryptoException]] 

Verifies the signature of all/last input data against the passed in signature.
 A call to this method also resets this Signature object to the state it was in
 when previously initialized via a call to init().
 That is, the object is reset and available to verify another message.

 
 

**Parameters:**inBuff - the input buffer of data to be verified 
 
inOffset - the offset into the input buffer at which to begin signature generation 
 
inLength - the byte length to sign
 
 
**Returns:**true if the signature verifies, false otherwise
 
 
**Throws:**
[[javacard:java-card-api:CryptoException|CryptoException]]  - with the following reason codes:
 \\ 
 
  *CryptoException.UNINITIALIZED_KEY if key not initialized. 
 \\ 
  *CryptoException.INVALID_INIT if this Signature object is not initialized or initialized for signature sign mode. 
 \\ 
  *CryptoException.ILLEGAL_USE if one of the following conditions is met:
 \\  
  * if beginVerify method has not been called. 
 \\  
 \\   
 

 
 



 ----


 === getAlgorithm === 
byte **getAlgorithm**()

Gets the Signature algorithm.

 
 


**Returns:**the algorithm code implemented by this Signature instance. 
 

 
 



 ----


 === getLength === 
short **getLength**()
throws [[javacard:java-card-api:CryptoException|CryptoException]] 

Returns the byte length of the signature data.

 
 


**Returns:**the byte length of the signature data
 
 
**Throws:**
[[javacard:java-card-api:CryptoException|CryptoException]]  - with the following reason codes:
 \\ 
 
  *CryptoException.INVALID_INIT if this Signature object is not initialized. 
 \\ 
  *CryptoException.UNINITIALIZED_KEY if key not initialized. 
 \\   
 

 
 



 ----


 === update === 
void **update**(byte[] inBuff,
short inOffset,
short inLength)
throws [[javacard:java-card-api:CryptoException|CryptoException]] 

Accumulates a signature of the input data. This method requires temporary storage of 
 intermediate results. In addition, if the input data length is not block aligned
 (multiple of block size)
 then additional internal storage may be allocated at this time to store a partial
 input data block.
 This may result in additional resource consumption and/or slow performance.
 This method should only be used if all the input data required for signing/verifying
 is not available in one byte array. If all of the input data required for 
 signing/verifying is located in a single byte array, use of the sign()
 or beginVerify method and verify() method is recommended.
 The sign() or verify()
 method must be called to complete processing of input data accumulated by one or more
 calls to the update() method.
 Note:
 \\ 
 
  *//If inLength is 0 this method does nothing.// 
 \\  

 
 

**Parameters:**inBuff - the input buffer of data to be signed/verified 
 
inOffset - the offset into the input buffer where input data begins 
 
inLength - the byte length to sign/verify
 
 
**Throws:**
[[javacard:java-card-api:CryptoException|CryptoException]]  - with the following reason codes:
 \\ 
 
  *CryptoException.UNINITIALIZED_KEY if key not initialized. 
 \\ 
  *CryptoException.INVALID_INIT if this Signature object is not initialized. 
 \\ 
  *CryptoException.ILLEGAL_USE if the mode set in the init() method is MODE_VERIFY and the beginVerify() method is not yet called.
 \\   
 
**See Also:**[[javacard:java-card-api:SignatureMessageRecovery#sign(byte[], short, short, byte[], short, short[], short)|sign(byte[], short, short, byte[], short, short[], short)]] , 
[[javacard:java-card-api:SignatureMessageRecovery#verify(byte[], short, short)|verify(byte[], short, short)]]