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:

• The application provides directly the 16-byte unlock value expected by the SAM in static mode (setUnlockData(String) and setUnlockData(String, LegacySam.ProductType)).
• The application implements a LegacySamStaticUnlockDataProviderSpi used to compute the 16-byte value expected byte the SAM in static mode (may diversified with the SAM serial number) (setStaticUnlockDataProvider(LegacySamStaticUnlockDataProviderSpi) and setStaticUnlockDataProvider(LegacySamStaticUnlockDataProviderSpi, CardReader)).
• The application implements a LegacySamDynamicUnlockDataProviderSpi used to have the 8-byte value expected by the SAM in dynamic mode computed by an origin SAM (setDynamicUnlockDataProvider(LegacySamDynamicUnlockDataProviderSpi) and setDynamicUnlockDataProvider(LegacySamDynamicUnlockDataProviderSpi, CardReader)).

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 Summary

Modifier and Type	Method	Description
LegacySamSelectionExtension	prepareReadAllCountersStatus()	Schedules the execution of a "Read Event Counter" and "Read Ceiling" commands to read the status of all counters.
LegacySamSelectionExtension	prepareReadCounterStatus(int counterNumber)	Schedules the execution of a "Read Event Counter" and "Read Ceiling" commands to read the status of a counter.
LegacySamSelectionExtension	prepareReadSystemKeyParameters(SystemKeyType systemKeyType)	Schedules the execution of a "Read Key Parameters" command for a system key.
LegacySamSelectionExtension	setDynamicUnlockDataProvider(LegacySamDynamicUnlockDataProviderSpi dynamicUnlockDataProvider)	Sets the unlock data provider to use for unlocking the SAM in dynamic mode.
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.
LegacySamSelectionExtension	setStaticUnlockDataProvider(LegacySamStaticUnlockDataProviderSpi staticUnlockDataProvider)	Sets the unlock data provider to use for unlocking the SAM in static mode.
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.
LegacySamSelectionExtension	setUnlockData(java.lang.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.
LegacySamSelectionExtension	setUnlockData(java.lang.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.

Method Detail

setUnlockData

LegacySamSelectionExtension setUnlockData(java.lang.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:

java.lang.IllegalArgumentException - If the provided unlock data is null, malformed or out of range.

java.lang.IllegalStateException - If an unlocking setting has already been set.

Since:

0.1.0

setUnlockData

LegacySamSelectionExtension setUnlockData(java.lang.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:

java.lang.IllegalArgumentException - If the provided unlock data or product type is null, malformed or out of range.

java.lang.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:

java.lang.IllegalArgumentException - If the provided argument is null.

java.lang.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:

java.lang.IllegalArgumentException - If one of the provided arguments is null.

java.lang.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:

java.lang.IllegalArgumentException - If the provided argument is null.

java.lang.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:

java.lang.IllegalArgumentException - If one of the provided arguments is null.

java.lang.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:

java.lang.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:

java.lang.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