#include <PoTransaction.h>
|
| 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 () |
|
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
◆ PinTransmissionMode
◆ 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.
|
◆ PoTransaction() [1/2]
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
-
◆ 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
-
◆ 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
-
sfi | the sfi to select |
recordData | the 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
-
CalypsoPoTransactionIllegalStateException | if 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. |
sfi | SFI of the file to select or 00h for current EF |
decValue | Value 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. |
sfi | SFI of the file to select or 00h for current EF |
incValue | Value 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
-
CalypsoPoTransactionIllegalStateException | if 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
-
sfi | the SFI of the EF |
countersNumber | the number of the last counter to be read |
- Exceptions
-
IllegalArgumentException | if 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
-
sfi | the SFI of the EF |
firstRecordNumber | the record number to read (or first record to read in case of several records) |
numberOfRecords | the number of records expected |
recordSize | the record length |
- Exceptions
-
IllegalArgumentException | if 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
-
sfi | the SFI of the EF to read |
recordNumber | the record number to read |
- Exceptions
-
IllegalArgumentException | if 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
-
CalypsoPoTransactionIllegalStateException | if 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
-
control | provides 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
-
lid | the 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
-
amount | the 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
-
amount | the amount to be subtracted or added, positive integer in the range 0..32767 when subtracted and 0..32768 when added. |
date | 2-byte free value |
time | 2-byte free value |
◆ prepareSvGet()
Prepares an SV operation or simply retrieves the current SV status
- Parameters
-
svOperation | informs about the nature of the intended operation: debit or reload |
svAction | the type of action: DO a debit or a positive reload, UNDO an undebit or a negative reload |
- Exceptions
-
CalypsoPoTransactionIllegalStateException | if 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
-
amount | the 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
-
CalypsoPoTransactionIllegalStateException | if 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
-
amount | the value to be reloaded, positive or negative integer in the range -8388608..8388607 |
date | 2-byte free value |
time | 2-byte free value |
free | 2-byte free value |
- Exceptions
-
CalypsoPoTransactionIllegalStateException | if 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
-
sfi | the sfi to select |
recordNumber | the record number to update |
recordData | the 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
-
sfi | the sfi to select |
recordNumber | the record number to write |
recordData | the 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
-
CalypsoPoTransactionException | if a functional error occurs (including PO and SAM IO errors) |
CalypsoPoCommandException | if 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
-
CalypsoPoTransactionException | if a functional error occurs (including PO and SAM IO errors) |
CalypsoPoCommandException | if a response from the PO was unexpected |
CalypsoSamCommandException | if a response from the SAM was unexpected |
◆ processOpening()
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
-
accessLevel | access level of the session (personalization, load or debit). |
- Exceptions
-
CalypsoPoTransactionException | if a functional error occurs (including PO and SAM IO errors) |
CalypsoPoCommandException | if a response from the PO was unexpected |
CalypsoSamCommandException | if 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
-
CalypsoPoTransactionException | if a functional error occurs (including PO and SAM IO errors) |
CalypsoPoCommandException | if a response from the PO was unexpected |
CalypsoSamCommandException | if 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
-
pin | an 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
-
pin | the PIN code value (4-byte long byte array) |
- Exceptions
-
CalypsoPoTransactionException | if a functional error occurs (including PO and SAM IO errors) |
CalypsoPoCommandException | if a response from the PO was unexpected |
CalypsoPoPinException | if the PIN presentation failed (the remaining attempt counter is update in Calypso). See CalypsoPo#isPinBlocked and CalypsoPo#getPinAttemptRemaining methods |
CalypsoPoTransactionIllegalStateException | if the PIN feature is not available for this PO or if commands have been prepared before calling this process method. |
◆ operator<<
std::ostream& operator<< |
( |
std::ostream & |
os, |
|
|
const SessionState & |
ss |
|
) |
| |
|
friend |
The documentation for this class was generated from the following files: