#include <CalypsoCardSelectionExtension.hpp>

Inheritance diagram for keypop::calypso::card::card::CalypsoCardSelectionExtension:

Collaboration diagram for keypop::calypso::card::card::CalypsoCardSelectionExtension:

Public Member Functions
virtual CalypsoCardSelectionExtension &	acceptInvalidatedCard ()=0

virtual CalypsoCardSelectionExtension &	prepareSelectFile (const uint16_t lid)=0

virtual CalypsoCardSelectionExtension &	prepareSelectFile (const SelectFileControl selectControl)=0

virtual CalypsoCardSelectionExtension &	prepareGetData (const GetDataTag tag)=0

virtual CalypsoCardSelectionExtension &	prepareReadRecord (const uint8_t sfi, const int recordNumber)=0

virtual CalypsoCardSelectionExtension &	prepareReadBinary (const uint8_t sfi, const int offset, const int nbBytesToRead)=0

virtual CalypsoCardSelectionExtension &	prepareReadCounter (const uint8_t sfi, const int nbCountersToRead)=0

virtual CalypsoCardSelectionExtension &	preparePreOpenSecureSession (const WriteAccessLevel writeAccessLevel)=0

Detailed Description

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

Definition at line 56 of file CalypsoCardSelectionExtension.hpp.

Member Function Documentation

◆ acceptInvalidatedCard()

virtual CalypsoCardSelectionExtension & keypop::calypso::card::card::CalypsoCardSelectionExtension::acceptInvalidatedCard ( )

pure virtual

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 object instance.

Since: 1.0.0

◆ prepareGetData()

virtual CalypsoCardSelectionExtension & keypop::calypso::card::card::CalypsoCardSelectionExtension::prepareGetData ( const GetDataTag tag )

pure virtual

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.

Exceptions

IllegalArgumentException If tag is null.

Since: 1.0.0

◆ preparePreOpenSecureSession()

virtual CalypsoCardSelectionExtension & keypop::calypso::card::card::CalypsoCardSelectionExtension::preparePreOpenSecureSession ( const WriteAccessLevel writeAccessLevel )

pure virtual

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.

Exceptions

IllegalArgumentException	If writeAccessLevel is null.
IllegalStateException	If "Pre-Open" command is already prepared.

Since: 1.7.0

◆ prepareReadBinary()

virtual CalypsoCardSelectionExtension & keypop::calypso::card::card::CalypsoCardSelectionExtension::prepareReadBinary	(	const uint8_t	sfi,
		const int	offset,
		const int	nbBytesToRead
	)

pure virtual

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.

Exceptions

IllegalArgumentException If one of the provided argument is out of range.

Since: 1.7.0

◆ prepareReadCounter()

virtual CalypsoCardSelectionExtension & keypop::calypso::card::card::CalypsoCardSelectionExtension::prepareReadCounter	(	const uint8_t	sfi,
		const int	nbCountersToRead
	)

pure virtual

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.

Exceptions

IllegalArgumentException If one of the provided argument is out of range.

Since: 1.7.0

◆ prepareReadRecord()

virtual CalypsoCardSelectionExtension & keypop::calypso::card::card::CalypsoCardSelectionExtension::prepareReadRecord	(	const uint8_t	sfi,
		const int	recordNumber
	)

pure virtual

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.

Exceptions

IllegalArgumentException If one of the provided argument is out of range.

Since: 1.1.0

◆ prepareSelectFile() [1/2]

virtual CalypsoCardSelectionExtension & keypop::calypso::card::card::CalypsoCardSelectionExtension::prepareSelectFile ( const SelectFileControl selectControl )

pure virtual

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.

Exceptions

IllegalArgumentException If the argument is null.

Since: 1.0.0

◆ prepareSelectFile() [2/2]

virtual CalypsoCardSelectionExtension & keypop::calypso::card::card::CalypsoCardSelectionExtension::prepareSelectFile ( const uint16_t lid )

pure virtual

Adds a command APDU 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 A short.

Returns: The object instance.

Since: 1.0.0

The documentation for this class was generated from the following file:

/github/workspace/include/keypop/calypso/card/card/CalypsoCardSelectionExtension.hpp

Public Member Functions

Detailed Description

Member Function Documentation

◆ acceptInvalidatedCard()

◆ prepareGetData()

◆ preparePreOpenSecureSession()

◆ prepareReadBinary()

◆ prepareReadCounter()

◆ prepareReadRecord()

◆ prepareSelectFile() [1/2]

◆ prepareSelectFile() [2/2]