Interface CalypsoCardSelectionExtension
- All Superinterfaces:
org.eclipse.keypop.reader.selection.spi.CardSelectionExtension
CardSelectionExtension
interface of the "Keypop Reader API" to provide means
to define optional commands to be executed during the selection phase.
An instance of this interface can be obtained via the method CalypsoCardApiFactory.createCalypsoCardSelectionExtension()
.
Note 1: by default, the selection process ignores PRIME revision 3 cards that have been
invalidated. The acceptInvalidatedCard()
method must be
called to stop ignoring them.
This feature does not apply to earlier revisions for which it is necessary to run a Select File
(DF) command to determine the invalidation status. In this case, the rejection or acceptance of
invalidated cards will have to be handled by the application.
Note 2: the APDU commands resulting from the invocation of the "prepare" methods shall be compliant with the PRIME revision 3 cards.
For all "prepare" type commands, unless otherwise specified, here are the ranges of values checked for the various parameters:
- SFI: [0..30] (0 indicates the current EF)
- Record number: [1..250]
- Counter number: [1..83]
- Counter value: [0..16777215]
- Offset: [0..249] or [0..32767] for binary files (0 indicates the first byte)
- Input data length: [1..250] or [1..32767] for binary files
- Since:
- 2.0.0
-
Method Summary
Modifier and TypeMethodDescriptionRequest to accept invalidated cards during the selection stage.prepareGetData
(GetDataTag tag) Adds a "Get Data" command to retrieve the data indicated by the provided tag.preparePreOpenSecureSession
(WriteAccessLevel writeAccessLevel) Adds a specific "Open Secure Session" command to attempt a secure session pre-opening.prepareReadBinary
(byte sfi, int offset, int nbBytesToRead) Adds one or multiple "Read Binary" commands to read all or part of the indicated "binary" EF.prepareReadCounter
(byte sfi, int nbCountersToRead) Adds a "Read Records" command to read a part of a record of the indicated EF, which should be a counter file.prepareReadRecord
(byte sfi, int recordNumber) Adds a "Read Records" command to read a single record from the indicated "linear" or "cyclic" EF.prepareSelectFile
(short lid) Adds a "Select File" command to select an EF by its LID in the current DF.prepareSelectFile
(SelectFileControl selectControl) Adds a "Select File" command to select file according to the providedSelectFileControl
enum entry indicating the navigation case: FIRST, NEXT or CURRENT.
-
Method Details
-
acceptInvalidatedCard
CalypsoCardSelectionExtension acceptInvalidatedCard()Request to accept invalidated cards during the selection stage.Caution: this functionality is operational only from PRIME revision 3 cards. Invalidated cards are rejected by default.
- Returns:
- The current instance.
- Since:
- 1.0.0
-
prepareSelectFile
Adds a "Select File" command to select an EF by its LID in the current DF.Caution 1: the resulting APDU command must be compliant with PRIME revision 3 cards. Therefore, the command may be rejected by some earlier revision cards.
Caution 2: the command will fail if the selected file is not an EF.
- Parameters:
lid
- The LID of the EF to select.- Returns:
- The current instance.
- Since:
- 1.0.0
-
prepareSelectFile
Adds a "Select File" command to select file according to the providedSelectFileControl
enum entry indicating the navigation case: FIRST, NEXT or CURRENT.Caution: the resulting APDU command must be compliant with PRIME revision 3 cards. Therefore, the command may be rejected by some earlier revision cards.
- Parameters:
selectControl
- ASelectFileControl
enum entry.- Returns:
- The current instance.
- Throws:
IllegalArgumentException
- If the argument is null.- Since:
- 1.0.0
-
prepareGetData
Adds a "Get Data" command to retrieve the data indicated by the provided tag.This method can be used to obtain FCI information when it is not provided directly by the select application (e.g. OMAPI case).
Caution: the resulting APDU command must be compliant with PRIME revision 3 cards. Therefore, the command may be rejected by some earlier revision cards.
- Parameters:
tag
- The tag to use.- Returns:
- The current instance.
- Throws:
IllegalArgumentException
- If tag is null.- Since:
- 1.0.0
-
prepareReadRecord
Adds a "Read Records" command to read a single record from the indicated "linear" or "cyclic" EF.Once this command is processed, the result is available in
CalypsoCard
if the requested file and record exist in the file structure of the card (best-effort mode).Caution: the resulting APDU command is compliant with PRIME revision 3 cards. Therefore, the command may be rejected by some earlier revision cards.
- Parameters:
sfi
- The SFI of the EF to readrecordNumber
- The record number to read.- Returns:
- The current instance.
- Throws:
IllegalArgumentException
- If one of the provided argument is out of range.- Since:
- 1.1.0
-
prepareReadBinary
Adds one or multiple "Read Binary" commands to read all or part of the indicated "binary" EF.Once this command is processed, the result is available in
CalypsoCard
if the requested file exist in the file structure of the card and if the offset and number of bytes to read are valid (best-effort mode).Caution: the resulting APDU command is compliant with PRIME revision 3 cards. Therefore, the command may be rejected by some earlier revision cards.
- Parameters:
sfi
- The SFI of the EF.offset
- The offset (0 indicates the first byte).nbBytesToRead
- The number of bytes to read.- Returns:
- The current instance.
- Throws:
IllegalArgumentException
- If one of the provided argument is out of range.- Since:
- 1.7.0
-
prepareReadCounter
Adds a "Read Records" command to read a part of a record of the indicated EF, which should be a counter file.The record will be read up to the counter location indicated in parameter.
Thus, all previous counters will also be read.Once this command is processed, the result is available in
CalypsoCard
if the requested file and the counter number exist in the file structure of the card (best-effort mode).Caution: the resulting APDU command is compliant with PRIME revision 3 cards. Therefore, the command may be rejected by some earlier revision cards.
- Parameters:
sfi
- The SFI of the EF.nbCountersToRead
- The number of counters to read.- Returns:
- The current instance.
- Throws:
IllegalArgumentException
- If one of the provided argument is out of range.- Since:
- 1.7.0
-
preparePreOpenSecureSession
Adds a specific "Open Secure Session" command to attempt a secure session pre-opening. For cards that support this feature, this optimizes future exchanges with the card in the case of secure sessions intended to be executed in a single step.The objective of the pre-opening is to allow the grouping of all the commands of a secure session. This functionality is only relevant in the case of a distributed system where the ticketing processing is done remotely in order to allow a complete secure session to be carried out in a single exchange between the server and the terminal.
This mechanism is based on the anticipation of the APDU responses of the card.
In order to achieve the objective of a single exchange, it is essential to read locally beforehand (out of session) all the data that will have to be read in session. If not, additional exchanges will be made.
Then, the remote ticketing processing must prepare all the commands of the session (from opening to closing) before executing it.
Example:
Caution: this feature will be ineffective in the following cases:transaction .prepareOpenSecureSession(...) .prepare... [...] .prepare... .prepareCloseSecureSession() .processCommands(...);
- the card or the cryptographic module does not support the extended mode
- the session contains commands that necessarily require exchanges with the card during the session (e.g. PIN, Stored Value, encryption, early mutual authentication, data not previously read outside the session)
- the session is opened with an access level different from the pre-opening one
- an intermediate "processCommand(...)" call has been made
- the session uses asymmetric cryptography
- Parameters:
writeAccessLevel
- The write access level.- Returns:
- The current instance.
- Throws:
IllegalArgumentException
- If writeAccessLevel is null.IllegalStateException
- If "Pre-Open" command is already prepared.- Since:
- 1.7.0
-