Package org.eclipse.keypop.calypso.crypto.legacysam.sam

Interface LegacySamSelectionExtension

All Superinterfaces:
org.eclipse.keypop.reader.selection.spi.CardSelectionExtension
public interface LegacySamSelectionExtension extends org.eclipse.keypop.reader.selection.spi.CardSelectionExtension
Extends the CardSelectionExtension interface of the "Keypop Reader API" to provide means to define optional commands to be executed during the selection phase such as the "Unlock" command.

An instance of this interface can be obtained via the method LegacySamApiFactory.createLegacySamSelectionExtension().

In the case where the SAM is locked, three options are proposed:

All three methods are exclusive.

When the unlocking data is supplied by a provider, a CardReader is needed to perform additional exchanges after the initial selection process. The reader can be provided either at the time of the creation of the selection extension or later depending on the implementation (in the case of dynamic SAM reader allocation for example).

Since:
0.3.0

  • Method Details

    • setUnlockData

      LegacySamSelectionExtension setUnlockData(String unlockData)
      Sets the unlock data to be used to unlock a SAM C1 (8 or 16 bytes) and schedules the execution of the "Unlock data" command in the first position.

      The "Unlock" command will be executed only after a successful filtering.

      Parameters:
      unlockData - Unlock data as a 32-character hexadecimal string.
      Returns:
      The current instance.
      Throws:
      IllegalArgumentException - If the provided unlock data is null, malformed or out of range.
      IllegalStateException - If an unlocking setting has already been set.
      Since:
      0.1.0

    • setUnlockData

      LegacySamSelectionExtension setUnlockData(String unlockData, LegacySam.ProductType productType)
      Sets the unlock data to be used to unlock a SAM (8 or 16 bytes) and schedules the execution of the "Unlock data" command in the first position.

      The "Unlock" command will be executed only after a successful filtering.

      Parameters:
      unlockData - Unlock data as a 32-character hexadecimal string.
      productType - The targeted product type.
      Returns:
      The current instance.
      Throws:
      IllegalArgumentException - If the provided unlock data or product type is null, malformed or out of range.
      IllegalStateException - If an unlocking setting has already been set.
      Since:
      0.3.0

    • setStaticUnlockDataProvider

      LegacySamSelectionExtension setStaticUnlockDataProvider(LegacySamStaticUnlockDataProviderSpi staticUnlockDataProvider)
      Sets the unlock data provider to use for unlocking the SAM in static mode.

      This method must be used when the card reader needed to communicate with the target SAM is provided at a later point within the interface's implementation process.

      The "Unlock" command is initiated once the filtering is successfully completed, followed by a request to the provider to obtain the needed unlocking data.

      Parameters:
      staticUnlockDataProvider - An implementation of LegacySamStaticUnlockDataProviderSpi.
      Returns:
      The current instance.
      Throws:
      IllegalArgumentException - If the provided argument is null.
      IllegalStateException - If an unlocking setting has already been set.
      Since:
      0.4.0

    • setStaticUnlockDataProvider

      LegacySamSelectionExtension setStaticUnlockDataProvider(LegacySamStaticUnlockDataProviderSpi staticUnlockDataProvider, org.eclipse.keypop.reader.CardReader targetSamReader)
      Sets the unlock data provider and the card reader to use for unlocking the SAM in static mode.

      This method must be used when the card reader is known at the time of creating the SAM selection extension.

      The "Unlock" command is initiated once the filtering is successfully completed, followed by a request to the provider to obtain the needed unlocking data.

      Parameters:
      staticUnlockDataProvider - An implementation of LegacySamStaticUnlockDataProviderSpi.
      targetSamReader - The card reader used to communicate with the target SAM.
      Returns:
      The current instance.
      Throws:
      IllegalArgumentException - If one of the provided arguments is null.
      IllegalStateException - If an unlocking setting has already been set.
      Since:
      0.4.0

    • setDynamicUnlockDataProvider

      LegacySamSelectionExtension setDynamicUnlockDataProvider(LegacySamDynamicUnlockDataProviderSpi dynamicUnlockDataProvider)
      Sets the unlock data provider to use for unlocking the SAM in dynamic mode.

      This method must be used when the card reader needed to communicate with the target SAM is provided at a later point within the interface's implementation process.

      The "Unlock" command is initiated once the filtering is successfully completed, followed by a request to the provider to obtain the needed unlocking data.

      Parameters:
      dynamicUnlockDataProvider - An implementation of LegacySamDynamicUnlockDataProviderSpi.
      Returns:
      The current instance.
      Throws:
      IllegalArgumentException - If the provided argument is null.
      IllegalStateException - If an unlocking setting has already been set.
      Since:
      0.4.0

    • setDynamicUnlockDataProvider

      LegacySamSelectionExtension setDynamicUnlockDataProvider(LegacySamDynamicUnlockDataProviderSpi dynamicUnlockDataProvider, org.eclipse.keypop.reader.CardReader targetSamReader)
      Sets the unlock data provider and the card reader to use for unlocking the SAM in dynamic mode.

      This method must be used when the card reader is known at the time of creating the SAM selection extension.

      The "Unlock" command is initiated once the filtering is successfully completed, followed by a request to the provider to obtain the needed unlocking data.

      Parameters:
      dynamicUnlockDataProvider - An implementation of LegacySamDynamicUnlockDataProviderSpi.
      targetSamReader - The card reader used to communicate with the target SAM.
      Returns:
      The current instance.
      Throws:
      IllegalArgumentException - If one of the provided arguments is null.
      IllegalStateException - If an unlocking setting has already been set.
      Since:
      0.4.0

    • prepareReadSystemKeyParameters

      LegacySamSelectionExtension prepareReadSystemKeyParameters(SystemKeyType systemKeyType)
      Schedules the execution of a "Read Key Parameters" command for a system key.

      Once this command is processed, the result is accessible with LegacySam.getSystemKeyParameter(SystemKeyType).

      Parameters:
      systemKeyType - The type of system key.
      Returns:
      The current instance.
      Throws:
      IllegalArgumentException - If the provided argument is null.
      Since:
      0.3.0

    • prepareReadCounterStatus

      LegacySamSelectionExtension prepareReadCounterStatus(int counterNumber)
      Schedules the execution of a "Read Event Counter" and "Read Ceiling" commands to read the status of a counter.

      Note: the status of each counter of the record to which the targeted counter belongs will be read. The number of commands actually transmitted to the SAM will be optimized before to be transmitted.

      Parameters:
      counterNumber - The number of the counter whose status is to be read (in range [0..26]).
      Returns:
      The current instance.
      Throws:
      IllegalArgumentException - If the provided argument is out of range.
      Since:
      0.3.0

    • prepareReadAllCountersStatus

      LegacySamSelectionExtension prepareReadAllCountersStatus()
      Schedules the execution of a "Read Event Counter" and "Read Ceiling" commands to read the status of all counters.
      Returns:
      The current instance.
      Since:
      0.3.0

    • prepareGetData

      LegacySamSelectionExtension prepareGetData(GetDataTag tag)
      Schedules the execution of a "Get Data" command for the specified tag.

      Once this command is processed, data is accessible using dedicated getter methods, like LegacySam.getCaCertificate().

      Parameters:
      tag - The tag to retrieve the data for.
      Returns:
      The current instance.
      Throws:
      IllegalArgumentException - If tag is null.
      Since:
      0.6.0