Package org.eclipse.keyple.core.plugin.storagecard.internal

Interface CommandProcessorApi

public interface CommandProcessorApi
Interface defining a command processor for interacting with a storage card.

To be implemented by the plugin.

Exception Handling

All methods may throw exceptions to indicate error conditions. Implementations should distinguish between:

  • IllegalArgumentException - For invalid parameters that can be validated before hardware access
  • Exception - For technical errors during hardware operations (communication failures, authentication failures, etc.)

The exception message should provide clear diagnostic information about the failure cause.

Since:
1.0.0

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    generalAuthenticate(int blockAddress, int keyType, int keyNumber)
    Performs authentication to a contactless card using a previously loaded key.
    byte[]
    getUID()
    Retrieves the Unique Identifier (UID) of the card.
    void
    loadKey(KeyStorageType keyStorageType, int keyNumber, byte[] key)
    Loads a card-specific authentication key into the reader's memory.
    byte[]
    readBlock(int blockAddress, int length)
    Reads data starting from a specified block address.
    byte[]
    transmitIsoApdu(byte[] apdu)
    Transmits a standard APDU command to the card.
    void
    writeBlock(int blockAddress, byte[] data)
    Writes data to a specified memory block on the card.

  • Method Details

    • transmitIsoApdu

      byte[] transmitIsoApdu(byte[] apdu) throws Exception
      Transmits a standard APDU command to the card.
      Parameters:
      apdu - The APDU ISO 7816-4 command.
      Returns:
      The response from the card including both data and status words.
      Throws:
      IllegalArgumentException - if apdu is null or invalid
      Exception - if transmission fails or communication error occurs
      Since:
      1.0.0

    • getUID

      byte[] getUID() throws Exception
      Retrieves the Unique Identifier (UID) of the card.

      This method obtains the UID which uniquely identifies the card. The UID length varies depending on the card type.

      If the UID is not available for the current card type, an empty byte array will be returned.

      Returns:
      A byte array containing the card's UID, or an empty array if the UID is not available.
      Throws:
      Exception - if the retrieval operation fails or communication error occurs
      Since:
      1.0.0

    • readBlock

      byte[] readBlock(int blockAddress, int length) throws Exception
      Reads data starting from a specified block address.

      This method handles reading memory blocks according to the card's memory page structure. The requested length should be a multiple of the card's page size and must not exceed the maximum readable size in a single exchange with the specific card type.

      For example, Mifare Ultralight cards have 4-byte pages, but each read command returns 4 pages (16 bytes) at once. ST25/SRT512 cards read one page at a time.

      If the requested length is shorter than the actual exchange size with the card, the response will be truncated accordingly.

      Parameters:
      blockAddress - The address of the first block to be read.
      length - The address of bytes to read, should be a multiple of the card's page size and must not exceed the maximum readable size for the specific card type.
      Returns:
      A byte array containing the block data.
      Throws:
      IllegalArgumentException - if blockAddress is out of range or length is negative, not compatible with the card's page structure, or exceeds the maximum readable size.
      Exception - if the read operation fails or communication error occurs
      Since:
      1.0.0

    • writeBlock

      void writeBlock(int blockAddress, byte[] data) throws Exception
      Writes data to a specified memory block on the card.

      This method handles writing memory blocks according to the card's memory page structure. The data length must exactly match the exchange size for the specific card type.

      Parameters:
      blockAddress - The address of the first block to be written.
      data - The byte array containing the data to write. The length must match exactly the card's page size or exchange size.
      Throws:
      IllegalArgumentException - if blockAddress is out of range or if data length does not match the required exchange size for the card type.
      Exception - if the write operation fails or communication error occurs
      Since:
      1.0.0

    • loadKey

      void loadKey(KeyStorageType keyStorageType, int keyNumber, byte[] key) throws Exception
      Loads a card-specific authentication key into the reader's memory.

      This method stores a card key in either volatile (RAM) or non-volatile (EEPROM) memory of the card reader. The key can be subsequently used by the generalAuthenticate(int, int, int) method to authenticate to the card. This command can be used for all kinds of contactless cards.

      Volatile memory provides temporary storage that is cleared when the reader loses power, while non-volatile memory persists across power cycles. The availability of non-volatile memory depends on the specific reader hardware.

      The key structure and length depend on the card type. For example:

      • Mifare cards: 6-byte keys (Type A or Type B)
      • Other contactless cards: card-specific key formats

      The key number parameter identifies the storage location in the reader's memory. The valid range and meaning of key numbers depend on the reader implementation and whether volatile or non-volatile memory is used. Consult the reader documentation for specific key number assignments.

      Note that keys stored in memory cannot be read back for security reasons. Once loaded, they can only be used for authentication operations.

      Parameters:
      keyStorageType - The type of memory to store the key in (VOLATILE or NON_VOLATILE).
      keyNumber - The key index identifying the storage location. Valid ranges depend on the reader implementation and memory type.
      key - A byte array containing the card-specific key value. Must not be null. The required length depends on the card type and authentication algorithm.
      Throws:
      IllegalArgumentException - if keyStorageType or key is null, if the key length is not valid for the card type, or if keyNumber is not in the valid range for the reader and memory type.
      Exception - if the load operation fails, if the specified memory type is not available on the reader hardware, or if a communication error occurs.
      Since:
      1.1.0
      See Also:

    • generalAuthenticate

      boolean generalAuthenticate(int blockAddress, int keyType, int keyNumber) throws Exception
      Performs authentication to a contactless card using a previously loaded key.

      This method authenticates to a specific memory location on the card using a key that was previously loaded into the reader's memory via the loadKey(KeyStorageType, int, byte[]) method. Successful authentication is typically required before performing read or write operations on protected memory areas.

      The authentication process establishes a secure session between the reader and the card. The block address represents the block number or starting byte number of the card to be authenticated, depending on the card type.

      The key type parameter is card-specific and indicates which type of key to use for authentication. Examples:

      • Mifare cards: 0x60 (KEY_A) or 0x61 (KEY_B)
      • Other contactless cards: card-specific key type values

      The key number parameter references a key previously loaded via loadKey(KeyStorageType, int, byte[]) and identifies which stored key to use for this authentication operation.

      Parameters:
      blockAddress - The block number or starting byte number on the card where authentication is to be performed. Valid range depends on the card type and memory structure.
      keyType - The type of key to use for authentication. The valid values are card-specific (e.g., 0x60 or 0x61 for Mifare cards).
      keyNumber - The index of the previously loaded key to use for authentication. Must reference a key that was loaded via loadKey(KeyStorageType, int, byte[]).
      Returns:
      true if authentication succeeded, false if authentication failed (e.g., incorrect key).
      Throws:
      IllegalArgumentException - if blockAddress is out of valid range for the card type, if keyType is not supported by the card, or if keyNumber does not reference a valid loaded key.
      Exception - if the referenced key was not previously loaded, if the card does not support authentication, or if a communication error occurs.
      Since:
      1.1.0
      See Also: