Interface CalypsoCardSelectionExtension

All Superinterfaces:
org.eclipse.keypop.reader.selection.spi.CardSelectionExtension

public interface CalypsoCardSelectionExtension 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.

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 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

      CalypsoCardSelectionExtension prepareSelectFile(short lid)
      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

      CalypsoCardSelectionExtension prepareSelectFile(SelectFileControl selectControl)
      Adds a "Select File" command to select file according to the provided SelectFileControl 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 - A SelectFileControl 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

      CalypsoCardSelectionExtension prepareReadRecord(byte sfi, int recordNumber)
      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 read
      recordNumber - 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

      CalypsoCardSelectionExtension prepareReadBinary(byte sfi, int offset, int nbBytesToRead)
      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

      CalypsoCardSelectionExtension 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.

      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

      CalypsoCardSelectionExtension preparePreOpenSecureSession(WriteAccessLevel writeAccessLevel)
      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:

      
       transaction
         .prepareOpenSecureSession(...)
         .prepare...
         [...]
         .prepare...
         .prepareCloseSecureSession()
         .processCommands(...);
       
      Caution: this feature will be ineffective in the following cases:
      • 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