Interface SignatureMessageRecovery
-
public interface SignatureMessageRecovery
A subclass of the abstractSignature
class must implement thisSignatureMessageRecovery
interface to provide message recovery functionality. An instance implementing this interface is returned by theSignature.getInstance(byte, boolean)
method when algorithm type with suffix*_MR
is specified. e.g.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 thesign()
andverify()
methods is supported here along with a newbeginVerify
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 theinit()
method, and issue 0 or moreupdate()
method calls and then finally call thesign()
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 theinit()
method, first recover the message using thebeginVerify()
method and then issue 0 or moreupdate()
method calls and then finally call theverify()
method to verify the signature.Note:
ASignature
object implementing this interface must throwCryptoException
withCryptoException.ILLEGAL_USE
reason code when one of the following methods applicable only to aSignature
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)
- setInitialDigest(byte[], short, short, byte[], short, short)
- signPreComputedHash(byte[], short, short, byte[], short)
- Since:
- 2.2.2
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description 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
getAlgorithm()
Gets the Signature algorithm.short
getLength()
Returns the byte length of the signature data.void
init(Key theKey, byte theMode)
Initializes theSignature
object with the appropriateKey
.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
update(byte[] inBuff, short inOffset, short inLength)
Accumulates a signature of the input data.boolean
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(Key theKey, byte theMode) throws CryptoException
Initializes theSignature
object with the appropriateKey
. This method should be used for algorithms which do not need initialization parameters or use default parameter values.init()
must be used to update theSignature
object with a new key. If theKey
object is modified after invoking theinit()
method, the behavior of theupdate()
,sign()
, andverify()
methods is unspecified.- Parameters:
theKey
- the key object to use for signing or verifyingtheMode
- one ofMODE_SIGN
orMODE_VERIFY
- Throws:
CryptoException
- with the following reason codes:CryptoException.ILLEGAL_VALUE
iftheMode
option is an undefined value or if theKey
is inconsistent withtheMode
or with theSignature
implementation.CryptoException.UNINITIALIZED_KEY
iftheKey
instance is uninitialized.
-
beginVerify
short beginVerify(byte[] sigAndRecDataBuff, short buffOffset, short sigLength) throws 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 thesigAndRecDataBuff
input byte array.Notes:
- This method must be called during the verification sequence
prior to either the
update()
or theverify()
methods during verification. - The trailing (
sigLength
- recovered message length) bytes of signature data insigAndRecDataBuff
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:
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 thisSignature
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 thisSignature
object is not initialized.
- This method must be called during the verification sequence
prior to either the
-
sign
short sign(byte[] inBuff, short inOffset, short inLength, byte[] sigBuff, short sigOffset, short[] recMsgLen, short recMsgLenOffset) throws 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 toinit()
. 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 signedinOffset
- the offset into the input buffer at which to begin signature generationinLength
- the byte length to signsigBuff
- the output buffer to store signature datasigOffset
- the offset into sigBuff at which to begin signature datarecMsgLen
- 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 itselfrecMsgLenOffset
- offset into therecMsgLen
output buffer where the byte length of the recoverable message is stored. Note that a single short value is stored atrecMsgLenOffset
offset.- Returns:
- number of bytes of signature output in sigBuff
- Throws:
CryptoException
- with the following reason codes:CryptoException.UNINITIALIZED_KEY
if key not initialized.CryptoException.INVALID_INIT
if thisSignature
object is not initialized or initialized for signature verify mode.
-
verify
boolean verify(byte[] inBuff, short inOffset, short inLength) throws 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 toinit()
. That is, the object is reset and available to verify another message.- Parameters:
inBuff
- the input buffer of data to be verifiedinOffset
- the offset into the input buffer at which to begin signature generationinLength
- the byte length to sign- Returns:
true
if the signature verifies,false
otherwise- Throws:
CryptoException
- with the following reason codes:CryptoException.UNINITIALIZED_KEY
if key not initialized.CryptoException.INVALID_INIT
if thisSignature
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.
- if
-
getAlgorithm
byte getAlgorithm()
Gets the Signature algorithm.- Returns:
- the algorithm code implemented by this
Signature
instance.
-
getLength
short getLength() throws CryptoException
Returns the byte length of the signature data.- Returns:
- the byte length of the signature data
- Throws:
CryptoException
- with the following reason codes:CryptoException.INVALID_INIT
if thisSignature
object is not initialized.CryptoException.UNINITIALIZED_KEY
if key not initialized.
-
update
void update(byte[] inBuff, short inOffset, short inLength) throws 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 thesign()
orbeginVerify
method andverify()
method is recommended. Thesign()
orverify()
method must be called to complete processing of input data accumulated by one or more calls to theupdate()
method.Note:
- If
inLength
is 0 this method does nothing.
- Parameters:
inBuff
- the input buffer of data to be signed/verifiedinOffset
- the offset into the input buffer where input data beginsinLength
- the byte length to sign/verify- Throws:
CryptoException
- with the following reason codes:CryptoException.UNINITIALIZED_KEY
if key not initialized.CryptoException.INVALID_INIT
if thisSignature
object is not initialized.CryptoException.ILLEGAL_USE
if the mode set in theinit()
method is MODE_VERIFY and thebeginVerify()
method is not yet called.
- See Also:
sign(byte[], short, short, byte[], short, short[], short)
,verify(byte[], short, short)
- If
-
-