Keyple C++  0.9.0
Keyple, an Open Source SDK for Ticketing
Classes | Public Types | Public Member Functions | Friends | List of all members
keyple::calypso::transaction::PoTransaction Class Referencefinal

#include <PoTransaction.h>

Classes

class  SessionSetting
 
class  SvSettings
 

Public Types

enum  SessionState { SessionState::SESSION_UNINITIALIZED, SessionState::SESSION_OPEN, SessionState::SESSION_CLOSED }
 
enum  PinTransmissionMode { PinTransmissionMode::PLAIN, PinTransmissionMode::ENCRYPTED }
 

Public Member Functions

 PoTransaction (std::shared_ptr< SeResource< CalypsoPo >> poResource, std::shared_ptr< PoSecuritySettings > poSecuritySettings)
 
 PoTransaction (std::shared_ptr< SeResource< CalypsoPo >> poResource)
 
void processOpening (const SessionSetting::AccessLevel &accessLevel)
 
void processClosing ()
 
void processPoCommands ()
 
void processCancel ()
 
void processVerifyPin (const std::vector< uint8_t > &pin)
 
void processVerifyPin (const std::string &pin)
 
void prepareSelectFile (const std::vector< uint8_t > &lid)
 
void prepareSelectFile (const SelectFileControl control)
 
void prepareReadRecordFile (const uint8_t sfi, const uint8_t recordNumber)
 
void prepareReadRecordFile (const uint8_t sfi, const uint8_t firstRecordNumber, const uint8_t numberOfRecords, const uint8_t recordSize)
 
void prepareReadCounterFile (const uint8_t sfi, const uint8_t countersNumber)
 
void prepareAppendRecord (const uint8_t sfi, const std::vector< uint8_t > &recordData)
 
void prepareUpdateRecord (const uint8_t sfi, const uint8_t recordNumber, const std::vector< uint8_t > &recordData)
 
void prepareWriteRecord (const uint8_t sfi, const uint8_t recordNumber, const std::vector< uint8_t > &recordData)
 
void prepareIncreaseCounter (const uint8_t sfi, const uint8_t counterNumber, const int incValue)
 
void prepareDecreaseCounter (const uint8_t sfi, const uint8_t counterNumber, const int decValue)
 
void prepareCheckPinStatus ()
 
void prepareSvGet (const SvSettings::Operation &svOperation, const SvSettings::Action &svAction)
 
void prepareSvReload (const int amount, const std::vector< uint8_t > &date, const std::vector< uint8_t > &time, const std::vector< uint8_t > &free)
 
void prepareSvReload (const int amount)
 
void prepareSvDebit (const int amount, const std::vector< uint8_t > &date, const std::vector< uint8_t > &time)
 
void prepareSvDebit (const int amount)
 
void prepareSvReadAllLogs ()
 
void prepareInvalidate ()
 
void prepareRehabilitate ()
 
void prepareReleasePoChannel ()
 

Friends

std::ostream & operator<< (std::ostream &os, const SessionState &ss)
 

Detailed Description

Portable Object Secure Session.

A non-encrypted secure session with a Calypso PO requires the management of two keyple::core::seproxy::message::ProxyReader in order to communicate with both a Calypso PO and a SAM

Author
Calypso Networks Association

Member Enumeration Documentation

◆ PinTransmissionMode

The keyple::calypso::transaction::PoTransaction::PinTransmissionMode indicates whether the PIN transmission is encrypted or not.

Enumerator
PLAIN 
ENCRYPTED 

◆ SessionState

The PO Transaction State defined with the elements: ‘IOError’, ‘SEInserted’ and ‘SERemoval’.

Enumerator
SESSION_UNINITIALIZED 

Initial state of a PO transaction. The PO must have been previously selected.

SESSION_OPEN 

The secure session is active.

SESSION_CLOSED 

The secure session is closed.

Constructor & Destructor Documentation

◆ PoTransaction() [1/2]

keyple::calypso::transaction::PoTransaction::PoTransaction ( std::shared_ptr< SeResource< CalypsoPo >>  poResource,
std::shared_ptr< PoSecuritySettings poSecuritySettings 
)

PoTransaction with PO and SAM readers.

  • Logical channels with PO & SAM could already be established or not.
  • A list of SAM parameters is provided as en EnumMap.
Parameters
poResourcethe PO resource (combination of keyple::core::seproxy::SeReader and keyple::calypso::transaction::CalypsoPo)
poSecuritySettingsa list of security settings (keyple::calypso::transaction::PoSecuritySettings) used in

◆ PoTransaction() [2/2]

keyple::calypso::transaction::PoTransaction::PoTransaction ( std::shared_ptr< SeResource< CalypsoPo >>  poResource)

PoTransaction with PO reader and without SAM reader.

  • Logical channels with PO could already be established or not.
Parameters
poResourcethe PO resource (combination of keyple::core::seproxy::SeReader and keyple::calypso::transaction::CalypsoPo)

Member Function Documentation

◆ prepareAppendRecord()

void keyple::calypso::transaction::PoTransaction::prepareAppendRecord ( const uint8_t  sfi,
const std::vector< uint8_t > &  recordData 
)

Builds an AppendRecord command and add it to the list of commands to be sent with the next process command.

Parameters
sfithe sfi to select
recordDatathe new record data to write
Exceptions
IllegalArgumentException- if the command is inconsistent

◆ prepareCheckPinStatus()

void keyple::calypso::transaction::PoTransaction::prepareCheckPinStatus ( )

Builds a VerifyPin command without PIN presentation in order to get the attempt counter.
The PIN status will made available in CalypsoPo after the execution of process command.
Adds it to the list of commands to be sent with the next process command.

See CalypsoPo#isPinBlocked and CalypsoPo#getPinAttemptRemaining methods.

Exceptions
CalypsoPoTransactionIllegalStateExceptionif the PIN feature is not available for this PO.

◆ prepareDecreaseCounter()

void keyple::calypso::transaction::PoTransaction::prepareDecreaseCounter ( const uint8_t  sfi,
const uint8_t  counterNumber,
const int  decValue 
)

Builds a Decrease command and add it to the list of commands to be sent with the next process command

Parameters
counterNumber>= 01h: Counters file, number of the counter. 00h: Simulated Counter file.
sfiSFI of the file to select or 00h for current EF
decValueValue to subtract to the counter (defined as a positive int <= 16777215 [FFFFFFh])
Exceptions
IllegalArgumentException- if the decrement value is out of range
IllegalArgumentException- if the command is inconsistent

◆ prepareIncreaseCounter()

void keyple::calypso::transaction::PoTransaction::prepareIncreaseCounter ( const uint8_t  sfi,
const uint8_t  counterNumber,
const int  incValue 
)

Builds a Increase command and add it to the list of commands to be sent with the next process command

Parameters
counterNumber>= 01h: Counters file, number of the counter. 00h: Simulated Counter file.
sfiSFI of the file to select or 00h for current EF
incValueValue to add to the counter (defined as a positive int <= 16777215 [FFFFFFh])
Exceptions
IllegalArgumentException- if the decrement value is out of range
IllegalArgumentException- if the command is inconsistent

◆ prepareInvalidate()

void keyple::calypso::transaction::PoTransaction::prepareInvalidate ( )

Prepare the invalidation of the PO
This command is usually executed within a secure session with the SESSION_LVL_DEBIT key (depends on the access rights given to this command in the file structure of the PO).

Exceptions
CalypsoPoTransactionIllegalStateExceptionif the PO is already invalidated

◆ prepareReadCounterFile()

void keyple::calypso::transaction::PoTransaction::prepareReadCounterFile ( const uint8_t  sfi,
const uint8_t  countersNumber 
)

Read a record of the indicated EF, which should be a count file.

The record will be read up to the counter location indicated in parameter.
Thus all previous counters will also be read.

Parameters
sfithe SFI of the EF
countersNumberthe number of the last counter to be read
Exceptions
IllegalArgumentExceptionif one of the provided argument is out of range

◆ prepareReadRecordFile() [1/2]

void keyple::calypso::transaction::PoTransaction::prepareReadRecordFile ( const uint8_t  sfi,
const uint8_t  firstRecordNumber,
const uint8_t  numberOfRecords,
const uint8_t  recordSize 
)

Read one or more records from the indicated EF

Parameters
sfithe SFI of the EF
firstRecordNumberthe record number to read (or first record to read in case of several records)
numberOfRecordsthe number of records expected
recordSizethe record length
Exceptions
IllegalArgumentExceptionif one of the provided argument is out of range

◆ prepareReadRecordFile() [2/2]

void keyple::calypso::transaction::PoTransaction::prepareReadRecordFile ( const uint8_t  sfi,
const uint8_t  recordNumber 
)

Read a single record from the indicated EF

Parameters
sfithe SFI of the EF to read
recordNumberthe record number to read
Exceptions
IllegalArgumentExceptionif one of the provided argument is out of range

◆ prepareRehabilitate()

void keyple::calypso::transaction::PoTransaction::prepareRehabilitate ( )

Prepare the rehabilitation of the PO
This command is usually executed within a secure session with the SESSION_LVL_PERSO key (depends on the access rights given to this command in the file structure of the PO).

Exceptions
CalypsoPoTransactionIllegalStateExceptionif the PO is not invalidated

◆ prepareReleasePoChannel()

void keyple::calypso::transaction::PoTransaction::prepareReleasePoChannel ( )

Prepare to close the PO channel.
If this command is called before a "process" command (except for processOpening) then the last transmission to the PO will be associated with the indication CLOSE_AFTER in order to close the PO channel.
Important: this command must imperatively be called at the end of any transaction, whether it ended normally or not.
In case the transaction was interrupted (exception), an additional call to processPoCommands must be made to effectively close the channel.

C++ vs. Java: private in Java

◆ prepareSelectFile() [1/2]

void keyple::calypso::transaction::PoTransaction::prepareSelectFile ( const SelectFileControl  control)

Prepare a select file ApduRequest to be executed following the selection.

Parameters
controlprovides the navigation case: FIRST, NEXT or CURRENT

◆ prepareSelectFile() [2/2]

void keyple::calypso::transaction::PoTransaction::prepareSelectFile ( const std::vector< uint8_t > &  lid)

Prepare a select file ApduRequest to be executed following the selection.

Parameters
lidthe LID of the EF to select

◆ prepareSvDebit() [1/2]

void keyple::calypso::transaction::PoTransaction::prepareSvDebit ( const int  amount)

Prepares an SV debit or Undebit (partially or totally cancels the last SV debit command).

It consists in decreasing the current balance of the SV by a certain amount or canceling a previous debit.
The information fields such as date and time are set to 0. The extraInfo field propagated in Logs are automatically generated with the type of transaction and amount.
Operations that would result in a negative balance are forbidden (SV Exception raised).
Note: the key used is the debit key

Parameters
amountthe amount to be subtracted or added, positive integer in the range 0..32767 when subtracted and 0..32768 when added.

◆ prepareSvDebit() [2/2]

void keyple::calypso::transaction::PoTransaction::prepareSvDebit ( const int  amount,
const std::vector< uint8_t > &  date,
const std::vector< uint8_t > &  time 
)

Prepares an SV debit or Undebit (partially or totally cancels the last SV debit command).

It consists in decreasing the current balance of the SV by a certain amount or canceling a previous debit.
Note: the key used is the debit key

Parameters
amountthe amount to be subtracted or added, positive integer in the range 0..32767 when subtracted and 0..32768 when added.
date2-byte free value
time2-byte free value

◆ prepareSvGet()

void keyple::calypso::transaction::PoTransaction::prepareSvGet ( const SvSettings::Operation svOperation,
const SvSettings::Action svAction 
)

Prepares an SV operation or simply retrieves the current SV status

Parameters
svOperationinforms about the nature of the intended operation: debit or reload
svActionthe type of action: DO a debit or a positive reload, UNDO an undebit or a negative reload
Exceptions
CalypsoPoTransactionIllegalStateExceptionif the SV feature is not available for this PO.

◆ prepareSvReadAllLogs()

void keyple::calypso::transaction::PoTransaction::prepareSvReadAllLogs ( )

Prepare the reading of all SV log records

The SV transaction logs are contained in two files with fixed identifiers.
The file whose SFI is 0x14 contains 1 record containing the unique reload log.
The file whose SFI is 0x15 contains 3 records containing the last three debit logs.
At the end of this reading operation, the data will be accessible in CalypsoPo in raw format via the standard commands for accessing read files or in the form of dedicated objects (see CalypsoPo#getSvLoadLogRecord() and CalypsoPo#getSvDebitLogAllRecords())

◆ prepareSvReload() [1/2]

void keyple::calypso::transaction::PoTransaction::prepareSvReload ( const int  amount)

Prepares an SV reload (increasing the current SV balance)

Note: the key used is the reload key

Parameters
amountthe value to be reloaded, positive integer in the range 0..8388607 for a DO action, in the range 0..8388608 for an UNDO action.
Exceptions
CalypsoPoTransactionIllegalStateExceptionif the SV feature is not available for this PO.

◆ prepareSvReload() [2/2]

void keyple::calypso::transaction::PoTransaction::prepareSvReload ( const int  amount,
const std::vector< uint8_t > &  date,
const std::vector< uint8_t > &  time,
const std::vector< uint8_t > &  free 
)

Prepares an SV reload (increasing the current SV balance)

Note: the key used is the reload key

Parameters
amountthe value to be reloaded, positive or negative integer in the range -8388608..8388607
date2-byte free value
time2-byte free value
free2-byte free value
Exceptions
CalypsoPoTransactionIllegalStateExceptionif the SV feature is not available for this PO.

◆ prepareUpdateRecord()

void keyple::calypso::transaction::PoTransaction::prepareUpdateRecord ( const uint8_t  sfi,
const uint8_t  recordNumber,
const std::vector< uint8_t > &  recordData 
)

Builds an UpdateRecord command and add it to the list of commands to be sent with the next process command

Parameters
sfithe sfi to select
recordNumberthe record number to update
recordDatathe new record data. If length < RecSize, bytes beyond length are left unchanged.
Exceptions
IllegalArgumentException- if record number is < 1
IllegalArgumentException- if the request is inconsistent

◆ prepareWriteRecord()

void keyple::calypso::transaction::PoTransaction::prepareWriteRecord ( const uint8_t  sfi,
const uint8_t  recordNumber,
const std::vector< uint8_t > &  recordData 
)

Builds an WriteRecord command and add it to the list of commands to be sent with the next process command

Parameters
sfithe sfi to select
recordNumberthe record number to write
recordDatathe data to overwrite in the record. If length < RecSize, bytes beyond length are left unchanged.
Exceptions
IllegalArgumentException- if record number is < 1
IllegalArgumentException- if the request is inconsistent

◆ processCancel()

void keyple::calypso::transaction::PoTransaction::processCancel ( )

Abort a Secure Session.

Send the appropriate command to the PO

Clean up internal data and status.

Exceptions
CalypsoPoTransactionExceptionif a functional error occurs (including PO and SAM IO errors)
CalypsoPoCommandExceptionif a response from the PO was unexpected

◆ processClosing()

void keyple::calypso::transaction::PoTransaction::processClosing ( )

Sends the currently prepared commands list (may be empty) and closes the Secure Session.

  • The ratification is handled according to the communication mode.
  • The logical channel can be left open or closed.
  • The result of the commands is placed in CalypsoPo.

The communication mode is retrieved from CalypsoPO to manage the ratification process. If the communication mode is CONTACTLESS, a ratification command will be generated and sent to the PO after the Close Session command; the ratification will not be requested in the Close Session command. On the contrary, if the communication mode is CONTACTS, no ratification command will be sent to the PO and ratification will be requested in the Close Session command

Exceptions
CalypsoPoTransactionExceptionif a functional error occurs (including PO and SAM IO errors)
CalypsoPoCommandExceptionif a response from the PO was unexpected
CalypsoSamCommandExceptionif a response from the SAM was unexpected

◆ processOpening()

void keyple::calypso::transaction::PoTransaction::processOpening ( const SessionSetting::AccessLevel accessLevel)

Open a Secure Session.

  • The PO must have been previously selected, so a logical channel with the PO application must be already active.
  • The PO serial & revision are identified from FCI data.
  • A first request is sent to the SAM session reader.
    • In case not logical channel is active with the SAM, a channel is open.
    • Then a Select Diversifier (with the PO serial) & a Get Challenge are automatically operated. The SAM challenge is recovered.
  • The PO Open Session command is built according to the PO revision, the SAM challenge, the keyIndex, and openingSfiToSelect / openingRecordNumberToRead.
  • Next the PO reader is requested:
    • for the currently selected PO, with channelControl set to KEEP_OPEN,
    • and some PO Apdu Requests including at least the Open Session command and all prepared PO command to operate inside the session.
  • The session PO keyset reference is identified from the PO Open Session response, the PO challenge is recovered too.
  • According to the PO responses of Open Session and the PO commands sent inside the session, a "cache" of SAM commands is filled with the corresponding Digest Init & Digest Update commands.
  • The result of the commands is placed in CalypsoPo.
  • Any call to prepareReleasePoChannel before this command will be ignored but will remain active for the next process command.
Parameters
accessLevelaccess level of the session (personalization, load or debit).
Exceptions
CalypsoPoTransactionExceptionif a functional error occurs (including PO and SAM IO errors)
CalypsoPoCommandExceptionif a response from the PO was unexpected
CalypsoSamCommandExceptionif a response from the SAM was unexpected

◆ processPoCommands()

void keyple::calypso::transaction::PoTransaction::processPoCommands ( )

Process all prepared PO commands outside or in a Secure Session.

  • In case the secure session is active, the "cache" of SAM commands is completed with the corresponding Digest Update commands. Also, the PO channel is kept open.
  • Outside of a secure session, the PO channel is closed depending on whether or not prepareReleasePoChannel has been called.
  • The result of the commands is placed in CalypsoPo.
Exceptions
CalypsoPoTransactionExceptionif a functional error occurs (including PO and SAM IO errors)
CalypsoPoCommandExceptionif a response from the PO was unexpected
CalypsoSamCommandExceptionif a response from the SAM was unexpected

◆ processVerifyPin() [1/2]

void keyple::calypso::transaction::PoTransaction::processVerifyPin ( const std::string &  pin)

ProcessVerifyPin variant with the PIN supplied as an ASCII string.
E.g. "1234" will be transmited as { 0x31,032,0x33,0x34 }

Parameters
pinan ASCII string (4-character long)

◆ processVerifyPin() [2/2]

void keyple::calypso::transaction::PoTransaction::processVerifyPin ( const std::vector< uint8_t > &  pin)

Performs a PIN verification, in order to authenticate the cardholder and/or unlock access to certain PO files.
This command can be performed both in and out of a secure session.
The PIN code can be transmitted in plain text or encrypted according to the parameter set in PoSecuritySettings (by default the transmission is encrypted).
If the execution is done out of session but an encrypted transmission is requested, then PoTransaction must be constructed with PoSecuritySettings
If PoTransaction is constructed without PoSecuritySettings the transmission in done in plain.
The PO channel is closed if prepareReleasePoChannel is called before this command.

Parameters
pinthe PIN code value (4-byte long byte array)
Exceptions
CalypsoPoTransactionExceptionif a functional error occurs (including PO and SAM IO errors)
CalypsoPoCommandExceptionif a response from the PO was unexpected
CalypsoPoPinExceptionif the PIN presentation failed (the remaining attempt counter is update in Calypso). See CalypsoPo#isPinBlocked and CalypsoPo#getPinAttemptRemaining methods
CalypsoPoTransactionIllegalStateExceptionif the PIN feature is not available for this PO or if commands have been prepared before calling this process method.

Friends And Related Function Documentation

◆ operator<<

std::ostream& operator<< ( std::ostream &  os,
const SessionState ss 
)
friend

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