SignatureMessageRecovery (Java Card API, Connected Edition)
Date: 2009-12-11

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javacard.security
Interface SignatureMessageRecovery

    @TransactionType(value=SUPPORTS)
    public 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 `Signature.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 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` | `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 the `Signature` object with the appropriate `Key`.
`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 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:
    `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 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 sequence prior to either the `update()` or the `verify()` methods during verification.
  - The trailing (`sigLength` - recovered message length) bytes of signature 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:
    `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 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:
    `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 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:
    `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 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 this `Signature` 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 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:
    `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:
    `sign(byte[], short, short, byte[], short, short[], short)`, `verify(byte[], short, short)`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (c) 2009 Sun Microsystems, Inc. All rights reserved.