Package org.eclipse.keypop.storagecard.transaction

Interface StorageCardTransactionManager

All Superinterfaces:
org.eclipse.keypop.reader.transaction.spi.CardTransactionManager<StorageCardTransactionManager>
public interface StorageCardTransactionManager extends org.eclipse.keypop.reader.transaction.spi.CardTransactionManager<StorageCardTransactionManager>
Provides methods to manage APDU exchanges with a storage card.

This interface allows to:

  • Prepare read and write operations to the card
  • Process prepared commands in a single transaction
  • Manage the communication channel with the card

Note about processing commands

The inherited CardTransactionManager.processCommands(ChannelControl) method processes all previously prepared commands and closes the physical channel if requested.

All APDUs corresponding to the prepared commands are sent to the card, their responses are retrieved and used to update the StorageCard associated with the transaction.

For read commands: The StorageCard memory image is updated with the data retrieved from the card.

For write commands: The StorageCard memory image is not updated even when the command appears successful, as some storage card technologies do not provide reliable confirmation of write completion. Applications should perform explicit read operations after writes to verify the actual card content and update the memory image.

The process is interrupted at the first failed command.

Since:
1.0.0

  • Method Details

    • prepareReadSystemBlock

      @Deprecated StorageCardTransactionManager prepareReadSystemBlock()
      Deprecated.
      Use prepareSt25ReadSystemBlock() instead. This method will be removed in a future version.
      Prepares the reading of the system block from the storage card when present.

      Not all storage card types include a system block. This method should only be called for card types that support system block access.

      Once this command is processed, the result is available in StorageCard.

      Returns:
      The current instance.
      Throws:
      UnsupportedOperationException - If the current card type does not support system block access.
      Since:
      1.0.0

    • prepareWriteSystemBlock

      @Deprecated StorageCardTransactionManager prepareWriteSystemBlock(byte[] data)
      Deprecated.
      Use prepareSt25WriteSystemBlock(byte[]) instead. This method will be removed in a future version.
      Prepares the writing of data to the system block of the storage card when present.

      System blocks contain card-specific metadata and configuration data. Not all storage card types include a system block that can be written to. This method should only be called for card types that support system block write access.

      The data length must match the block size defined by the card's ProductType.

      Important: After execution of this write command, the StorageCard memory image is not automatically updated. Some storage card technologies do not provide reliable status codes to confirm successful write operations. To ensure data consistency, an explicit read operation must be performed after the write to refresh the memory image and verify the actual content stored on the card.

      Parameters:
      data - The data to be written to the system block. The length must match the card's block size.
      Returns:
      The current instance.
      Throws:
      IllegalArgumentException - If data is null or its length does not match the block size.
      UnsupportedOperationException - If the current card type does not support system block write access.
      Since:
      1.0.0
      See Also:

    • prepareSt25ReadSystemBlock

      StorageCardTransactionManager prepareSt25ReadSystemBlock()
      Prepares the reading of the system block from an ST25/SRT512 storage card.

      This method is specific to ST25 and SRT512 card types which provide access to a system block at address 255 containing card-specific metadata and configuration data.

      Once this command is processed, the result is available in StorageCard.

      Returns:
      The current instance.
      Throws:
      UnsupportedOperationException - If the current card type is not ST25/SRT512.
      Since:
      1.1.0

    • prepareSt25WriteSystemBlock

      StorageCardTransactionManager prepareSt25WriteSystemBlock(byte[] data)
      Prepares the writing of data to the system block of an ST25/SRT512 storage card.

      This method is specific to ST25 and SRT512 card types which provide access to a system block at address 255 containing card-specific metadata and configuration data.

      The data length must match the block size defined by the card's ProductType.

      Important: After execution of this write command, the StorageCard memory image is not automatically updated. ST25/SRT512 cards do not provide reliable status codes to confirm successful write operations. To ensure data consistency, an explicit read operation must be performed after the write to refresh the memory image and verify the actual content stored on the card.

      Parameters:
      data - The data to be written to the system block. The length must match the card's block size.
      Returns:
      The current instance.
      Throws:
      IllegalArgumentException - If data is null or its length does not match the block size.
      UnsupportedOperationException - If the current card type is not ST25/SRT512.
      Since:
      1.1.0
      See Also:

    • prepareReadBlock

      StorageCardTransactionManager prepareReadBlock(int blockAddress)
      Prepares the reading of a specific block from the storage card.

      Block addresses start at 0 and the maximum value is equal to ProductType.getBlockCount() - 1.

      Once this command is processed, the result is available in StorageCard.

      Parameters:
      blockAddress - The address of the block to be read.
      Returns:
      The current instance.
      Throws:
      IllegalArgumentException - If the block address is out of range.
      Since:
      1.0.0
      See Also:

    • prepareReadBlocks

      StorageCardTransactionManager prepareReadBlocks(int fromBlockAddress, int toBlockAddress)
      Prepares the reading of a range of blocks from the storage card.

      Block addresses start at 0 and the maximum value is equal to ProductType.getBlockCount() - 1.

      Once this command is processed, the result is available in StorageCard.

      Parameters:
      fromBlockAddress - The starting block address (inclusive).
      toBlockAddress - The ending block address (inclusive).
      Returns:
      The current instance.
      Throws:
      IllegalArgumentException - If one of the arguments is out of range.
      Since:
      1.0.0
      See Also:

    • prepareWriteBlocks

      StorageCardTransactionManager prepareWriteBlocks(int fromBlockAddress, byte[] data)
      Prepares the writing of blocks of data to the storage card starting from a specific block number offset.

      The provided data should be a byte array representing the content of the blocks to be written. The number of blocks that will be written is determined by the length of the data array divided by the block size of the storage card. The block size is provided by ProductType.getBlockSize().

      Important: Some storage card technologies do not provide reliable status codes to confirm successful write operations. For such cards (e.g., SRT512/ST25), the library automatically performs a verification read after each write to ensure that the data has been correctly stored. For cards that provide a reliable write acknowledgment, no additional read is performed. In all cases, the library guarantees the integrity of the written data, and the application does not need to explicitly perform verification reads.

      Parameters:
      fromBlockAddress - The offset from which the blocks will be written.
      data - The data to be written to the storage card.
      Returns:
      The current instance of the StorageCardTransactionManager.
      Throws:
      IllegalArgumentException - If data is null or its length is not a multiple of the block size.
      Since:
      1.0.0
      See Also:

    • prepareMifareClassicAuthenticate

      StorageCardTransactionManager prepareMifareClassicAuthenticate(int blockAddress, MifareClassicKeyType mifareClassicKeyType, byte[] key)
      Prepares a Mifare Classic authentication command using a provided key.

      This method is specific to Mifare Classic cards and must be called before reading from or writing to protected sectors. The authentication applies to the entire sector containing the specified block address.

      The key must be a 6-byte array representing the Mifare Classic key value.

      When the key value is provided this way, it will be sent to the reader to be stored as a volatile key at index 0 (see Load Key command of the PC/SC standard). This volatile key is temporary and will be erased after usage, when the reader is powered off.

      Security Note: This method transmits the key value over the communication channel between the application and the reader. For production environments and security-sensitive applications, it is recommended to use prepareMifareClassicAuthenticate(int, MifareClassicKeyType, int) instead, which references a pre-stored key in the reader without transmitting the key value.

      Once authenticated, subsequent read and write operations within the same sector can be performed without re-authentication, until the card is removed from the field or another sector is accessed.

      Parameters:
      blockAddress - The address of any block within the sector to authenticate.
      mifareClassicKeyType - The type of key to use (Key A or Key B).
      key - The 6-byte key data for authentication.
      Returns:
      The current instance.
      Throws:
      IllegalArgumentException - If the block address is out of range, or if the key is null or not exactly 6 bytes long.
      UnsupportedOperationException - If the current card type does not support authentication.
      Since:
      1.1.0

    • prepareMifareClassicAuthenticate

      StorageCardTransactionManager prepareMifareClassicAuthenticate(int blockAddress, MifareClassicKeyType mifareClassicKeyType, int keyNumber)
      Prepares a Mifare Classic authentication command using a key stored in the reader.

      This method is specific to Mifare Classic cards and must be called before reading from or writing to protected sectors. The authentication applies to the entire sector containing the specified block address.

      The key is referenced by its storage index in the reader's key storage. This allows using pre-configured keys without transmitting them over the communication channel, providing enhanced security.

      Once authenticated, subsequent read and write operations within the same sector can be performed without re-authentication, until the card is removed from the field or another sector is accessed.

      Parameters:
      blockAddress - The address of any block within the sector to authenticate.
      mifareClassicKeyType - The type of key to use (Key A or Key B).
      keyNumber - The index of the key in the reader's key storage.
      Returns:
      The current instance.
      Throws:
      IllegalArgumentException - If the block address is out of range, or if the key number is invalid.
      UnsupportedOperationException - If the current card type does not support authentication.
      Since:
      1.1.0