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

#include <CalypsoPo.h>

Inherits keyple::core::selection::AbstractMatchingSe.

Public Member Functions

 CalypsoPo (std::shared_ptr< SeResponse > selectionResponse, const TransmissionMode &transmissionMode)
 
PoRevision getRevision () const
 
const std::vector< uint8_t > & getDfNameBytes () const
 
const std::string getDfName () const
 
const std::vector< uint8_t > getApplicationSerialNumberBytes () const
 
const std::string getAtr () const
 
uint8_t getPlatform () const
 
uint8_t getApplicationType () const
 
bool isConfidentialSessionModeSupported () const
 
bool isDeselectRatificationSupported () const
 
bool isSvFeatureAvailable () const
 
bool isPinFeatureAvailable () const
 
bool isPublicAuthenticationSupported () const
 
uint8_t getApplicationSubtype () const
 
uint8_t getSoftwareIssuer () const
 
uint8_t getSoftwareVersion () const
 
uint8_t getSoftwareRevision () const
 
uint8_t getSessionModification () const
 
bool isDfInvalidated () const
 
bool isDfRatified () const
 
void setSvData (const int svBalance, const int svLastTNum, const std::shared_ptr< SvLoadLogRecord > svLoadLogRecord, const std::shared_ptr< SvDebitLogRecord > svDebitLogRecord)
 
int getSvBalance () const
 
int getSvLastTNum () const
 
const std::shared_ptr< SvLoadLogRecordgetSvLoadLogRecord ()
 
const std::shared_ptr< SvDebitLogRecordgetSvDebitLogLastRecord ()
 
const std::vector< std::shared_ptr< SvDebitLogRecord > > getSvDebitLogAllRecords () const
 
void setDfRatified (const bool dfRatified)
 
const std::string getApplicationSerialNumber () const
 
const std::string getStartupInfo () const
 
const std::shared_ptr< DirectoryHeadergetDirectoryHeader () const
 
CalypsoPosetDirectoryHeader (const std::shared_ptr< DirectoryHeader > directoryHeader)
 
const std::shared_ptr< ElementaryFilegetFileBySfi (const uint8_t sfi) const
 
const std::shared_ptr< ElementaryFilegetFileByLid (const uint16_t lid)
 
const std::map< uint8_t, std::shared_ptr< ElementaryFile > > & getAllFiles () const
 
void setFileHeader (const uint8_t sfi, const std::shared_ptr< FileHeader > header)
 
void setContent (const uint8_t sfi, const int numRecord, const std::vector< uint8_t > &content)
 
void setCounter (const uint8_t sfi, const int numCounter, const std::vector< uint8_t > &content)
 
void setContent (const uint8_t sfi, const int numRecord, const std::vector< uint8_t > &content, const int offset)
 
void fillContent (const uint8_t sfi, const int numRecord, std::vector< uint8_t > &content)
 
void addCyclicContent (const uint8_t sfi, const std::vector< uint8_t > &content)
 
void backupFiles ()
 
void restoreFiles ()
 
int getModificationsCounter () const
 
const PoClassgetPoClass () const
 
bool isModificationsCounterInBytes () const
 
uint8_t getPayloadCapacity () const
 
bool isPinBlocked () const
 
int getPinAttemptRemaining () const
 
void setPinAttemptRemaining (const int pinAttemptCounter)
 
- Public Member Functions inherited from keyple::core::selection::AbstractMatchingSe
virtual ~AbstractMatchingSe ()
 
virtual const TransmissionModegetTransmissionMode () const
 
bool hasFci () const
 
bool hasAtr () const
 
const std::vector< uint8_t > & getFciBytes () const
 
const std::vector< uint8_t > & getAtrBytes () const
 
 AbstractMatchingSe (const std::shared_ptr< SeResponse > selectionResponse, const TransmissionMode &transmissionMode)
 

Protected Member Functions

const std::vector< uint8_t > & getCalypsoSerialNumber () const
 
bool isSerialNumberExpiring () const
 
const std::vector< uint8_t > & getSerialNumberExpirationBytes () const
 

Detailed Description

The CalypsoPo class gathers all the information about the current PO retrieved from the response to the select application command.

An instance of CalypsoPo can be obtained by casting the AbstractMatchingSe object from the selection process (e.g. (CalypsoPo) matchingSelection.getMatchingSe())

The various information contained in CalypsoPo is accessible by getters and includes:

Constructor & Destructor Documentation

◆ CalypsoPo()

keyple::calypso::transaction::CalypsoPo::CalypsoPo ( std::shared_ptr< SeResponse selectionResponse,
const TransmissionMode transmissionMode 
)

Constructor.

Parameters
selectionResponsethe response to the selection application command
transmissionModethe current keyple::core::seproxy::protocol::TransmissionMode (contacts or contactless)

Member Function Documentation

◆ addCyclicContent()

void keyple::calypso::transaction::CalypsoPo::addCyclicContent ( const uint8_t  sfi,
const std::vector< uint8_t > &  content 
)

(package-private)
Add cyclic content at record #1 by rolling previously all actual records contents (record #1 -> record #2, record #2 -> record #3,...) of the provided SFI.
This is useful for cyclic files. Note that records are infinitely shifted.

If EF does not exist, then it is created.

Parameters
sfithe SFI
contentthe content (should be not empty)

◆ backupFiles()

void keyple::calypso::transaction::CalypsoPo::backupFiles ( )

(package-private)
Make a backup of the Elementary Files.
This method should be used before starting a PO secure session.

◆ fillContent()

void keyple::calypso::transaction::CalypsoPo::fillContent ( const uint8_t  sfi,
const int  numRecord,
std::vector< uint8_t > &  content 
)

(package-private)
Fill the content of the specified numRecord of the provided SFI using a binary OR operation with the provided content.
If EF does not exist, then it is created.
If actual record content is not set or has a size

<

content size, then missing data will be completed by the provided content.

Parameters
sfithe SFI
numRecordthe record number (should be
>=
1)
contentthe content (should be not empty)

◆ getAllFiles()

const std::map< uint8_t, std::shared_ptr< ElementaryFile > > & keyple::calypso::transaction::CalypsoPo::getAllFiles ( ) const

Gets a reference to a map of all known Elementary Files by their associated SFI.
Note that if a secure session is actually running, then the map contains all session modifications, which can be canceled if the secure session fails.

Returns
a not null reference (may be empty if no one EF is set).
Since
0.9

◆ getApplicationSerialNumber()

const std::string keyple::calypso::transaction::CalypsoPo::getApplicationSerialNumber ( ) const

The serial number for the application, is unique ID for the PO.

Returns
a String representing the Application Serial Number (8 hex bytes)

◆ getApplicationSerialNumberBytes()

const std::vector< uint8_t > keyple::calypso::transaction::CalypsoPo::getApplicationSerialNumberBytes ( ) const

The serial number for the application, is unique ID for the PO.

Returns
a byte array containing the Application Serial Number (8 bytes)

◆ getApplicationSubtype()

uint8_t keyple::calypso::transaction::CalypsoPo::getApplicationSubtype ( ) const

The Application Subtype indicates to the terminal a reference to the file structure of the Calypso DF.

Returns
the Application Subtype byte

◆ getApplicationType()

uint8_t keyple::calypso::transaction::CalypsoPo::getApplicationType ( ) const

The Application Type byte determines the Calypso Revision and various options

Returns
the Application Type byte

◆ getAtr()

const std::string keyple::calypso::transaction::CalypsoPo::getAtr ( ) const

The Answer To Reset is sent by the PO is ISO7816-3 mode and in contactless mode for PC/SC readers.

When the ATR is obtained in contactless mode, it is in fact reconstructed by the reader from information obtained from the lower communication layers. Therefore, it may differ from one reader to another depending on the interpretation that has been made by the manufacturer of the PC/SC standard.

This field is not interpreted in the Calypso module.

Returns
an HEX chain representing the ATR
Exceptions
IllegalStateExceptionif the ATR is not available (see method)
Since
0.9

◆ getCalypsoSerialNumber()

const std::vector< uint8_t > & keyple::calypso::transaction::CalypsoPo::getCalypsoSerialNumber ( ) const
protected

The serial number to be used as diversifier for key derivation.
This is the complete number returned by the PO in its response to the Select command.

Returns
a byte array containing the Calypso Serial Number (8 bytes)

◆ getDfName()

const std::string keyple::calypso::transaction::CalypsoPo::getDfName ( ) const
Returns
the DF name as an HEX string (see getDfNameBytes)

◆ getDfNameBytes()

const std::vector< uint8_t > & keyple::calypso::transaction::CalypsoPo::getDfNameBytes ( ) const

The DF name is the name of the application DF as defined in ISO/IEC 7816-4.

It also corresponds to the complete representation of the target covered by the AID value provided in the selection command.

The AID selects the application by specifying all or part of the targeted DF Name (5 bytes minimum).

Returns
a byte array containing the DF Name bytes (5 to 16 bytes)

◆ getDirectoryHeader()

const std::shared_ptr< DirectoryHeader > keyple::calypso::transaction::CalypsoPo::getDirectoryHeader ( ) const

Gets the DF metadata.

Returns
null if is not set.
Since
0.9

◆ getFileByLid()

const std::shared_ptr< ElementaryFile > keyple::calypso::transaction::CalypsoPo::getFileByLid ( const uint16_t  lid)

Gets a reference to the keyple::calypso::transaction::ElementaryFile that has the provided LID value.
Note that if a secure session is actually running, then the object contains all session modifications, which can be canceled if the secure session fails.

Parameters
lidthe LID to search
Returns
a not null reference.
Exceptions
NoSuchElementExceptionif requested EF is not found.
Since
0.9

◆ getFileBySfi()

const std::shared_ptr< ElementaryFile > keyple::calypso::transaction::CalypsoPo::getFileBySfi ( const uint8_t  sfi) const

Gets a reference to the keyple::calypso::transaction::ElementaryFile that has the provided SFI value.
Note that if a secure session is actually running, then the object contains all session modifications, which can be canceled if the secure session fails.

Parameters
sfithe SFI to search
Returns
a not null reference.
Exceptions
NoSuchElementExceptionif requested EF is not found.
Since
0.9

◆ getModificationsCounter()

int keyple::calypso::transaction::CalypsoPo::getModificationsCounter ( ) const

Indicates the maximum number of changes allowed in session.

This number can be a number of operations or a number of commands (see isModificationsCounterInBytes())

Returns
the maximum number of modifications allowed

◆ getPayloadCapacity()

uint8_t keyple::calypso::transaction::CalypsoPo::getPayloadCapacity ( ) const
Returns
the maximum length of data that an APDU in this PO can carry
Since
0.9

◆ getPinAttemptRemaining()

int keyple::calypso::transaction::CalypsoPo::getPinAttemptRemaining ( ) const

Gives the number of erroneous PIN presentations remaining before blocking.

Returns
the number of remaining attempts
Exceptions
IllegalStateExceptionif the PIN has not been checked
Since
0.9

◆ getPlatform()

uint8_t keyple::calypso::transaction::CalypsoPo::getPlatform ( ) const

The platform identification byte is the reference of the chip

Returns
the platform identification byte

◆ getPoClass()

const PoClass & keyple::calypso::transaction::CalypsoPo::getPoClass ( ) const

The PO class is the ISO7816 class to be used with the current PO.

It determined from the PO revision

Two classes are possible: LEGACY and ISO.

Returns
the PO class determined from the PO revision

◆ getRevision()

PoRevision keyple::calypso::transaction::CalypsoPo::getRevision ( ) const

The PO revision indicates the generation of the product presented.

It will also have an impact on the internal construction of some commands to take into account the specificities of the different POs.

Returns
an enum giving the identified PO revision

◆ getSerialNumberExpirationBytes()

const std::vector< uint8_t > & keyple::calypso::transaction::CalypsoPo::getSerialNumberExpirationBytes ( ) const
protected

◆ getSessionModification()

uint8_t keyple::calypso::transaction::CalypsoPo::getSessionModification ( ) const

Depending on the type of PO, the session modification byte indicates the maximum number of bytes that can be modified or the number of possible write commands in a session.

Returns
the Session Modifications byte

◆ getSoftwareIssuer()

uint8_t keyple::calypso::transaction::CalypsoPo::getSoftwareIssuer ( ) const

The Software Issuer byte indicates the entity responsible for the software of the selected application.

Returns
the Software Issuer byte

◆ getSoftwareRevision()

uint8_t keyple::calypso::transaction::CalypsoPo::getSoftwareRevision ( ) const

The Software Revision field may be set to any fixed value by the Software Issuer of the Calypso application.

Returns
the Software Revision byte

◆ getSoftwareVersion()

uint8_t keyple::calypso::transaction::CalypsoPo::getSoftwareVersion ( ) const

The Software Version field may be set to any fixed value by the Software Issuer of the Calypso application.

Returns
the Software Version byte

◆ getStartupInfo()

const std::string keyple::calypso::transaction::CalypsoPo::getStartupInfo ( ) const
Returns
the startup info field from the FCI as an HEX string
Since
0.9

◆ getSvBalance()

int keyple::calypso::transaction::CalypsoPo::getSvBalance ( ) const

Gets the current SV balance

Returns
the current SV balance value
Exceptions
IllegalStateExceptionif no SV Get command has been executed
Since
0.9

◆ getSvDebitLogAllRecords()

const std::vector< std::shared_ptr< SvDebitLogRecord > > keyple::calypso::transaction::CalypsoPo::getSvDebitLogAllRecords ( ) const

Gets all available SV debit log records

Returns
a list of SV debit log record objects or null if not available
Exceptions
NoSuchElementExceptionif requested log is not found.
Since
0.9

◆ getSvDebitLogLastRecord()

const std::shared_ptr< SvDebitLogRecord > keyple::calypso::transaction::CalypsoPo::getSvDebitLogLastRecord ( )

Gets the last SV debit log record

Returns
a last SV debit log record object or null if not available
Exceptions
NoSuchElementExceptionif requested log is not found.
Since
0.9

◆ getSvLastTNum()

int keyple::calypso::transaction::CalypsoPo::getSvLastTNum ( ) const

Gets the last SV transaction number

Returns
the last SV transaction number value
Exceptions
IllegalStateExceptionif no SV Get command has been executed
Since
0.9

◆ getSvLoadLogRecord()

const std::shared_ptr< SvLoadLogRecord > keyple::calypso::transaction::CalypsoPo::getSvLoadLogRecord ( )

Gets the last SV load log record

Returns
a last SV load log record object or null if not available
Exceptions
NoSuchElementExceptionif requested log is not found.
Since
0.9

◆ isConfidentialSessionModeSupported()

bool keyple::calypso::transaction::CalypsoPo::isConfidentialSessionModeSupported ( ) const

Indicates whether the Confidential Session Mode is supported or not (since rev 3.2).

This boolean is interpreted from the Application Type byte

Returns
true if the Confidential Session Mode is supported

◆ isDeselectRatificationSupported()

bool keyple::calypso::transaction::CalypsoPo::isDeselectRatificationSupported ( ) const

Indicates if the ratification is done on deselect (ratification command not necessary)

This boolean is interpreted from the Application Type byte

Returns
true if the ratification command is required

◆ isDfInvalidated()

bool keyple::calypso::transaction::CalypsoPo::isDfInvalidated ( ) const

Indicated whether the PO has been invalidated or not.

An invalidated PO has 6283 as status word in response to the Select Application command.

Returns
true if the PO has been invalidated.

◆ isDfRatified()

bool keyple::calypso::transaction::CalypsoPo::isDfRatified ( ) const

Indicated whether the last session with this PO has been ratified or not.

Returns
true if the PO has been ratified.
Exceptions
IllegalStateExceptionif these methods is call when no session has been opened

◆ isModificationsCounterInBytes()

bool keyple::calypso::transaction::CalypsoPo::isModificationsCounterInBytes ( ) const

Specifies whether the change counter allowed in session is established in number of operations or number of bytes modified.

This varies depending on the revision of the PO.

Returns
true if the counter is number of bytes

◆ isPinBlocked()

bool keyple::calypso::transaction::CalypsoPo::isPinBlocked ( ) const

Indicates if the PIN is blocked. The maximum number of incorrect PIN submissions has been reached.

Returns
true if the PIN status is blocked
Exceptions
IllegalStateExceptionif the PIN has not been checked
Since
0.9

◆ isPinFeatureAvailable()

bool keyple::calypso::transaction::CalypsoPo::isPinFeatureAvailable ( ) const

Indicates whether the PO has the Calypso PIN feature.

This boolean is interpreted from the Application Type byte

Returns
true if the PO has the PIN feature

◆ isPublicAuthenticationSupported()

bool keyple::calypso::transaction::CalypsoPo::isPublicAuthenticationSupported ( ) const

Indicates whether the Public Authentication is supported or not (since rev 3.3).

This boolean is interpreted from the Application Type byte

Returns
true if the Public Authentication is supported

◆ isSerialNumberExpiring()

bool keyple::calypso::transaction::CalypsoPo::isSerialNumberExpiring ( ) const
protected

◆ isSvFeatureAvailable()

bool keyple::calypso::transaction::CalypsoPo::isSvFeatureAvailable ( ) const

Indicates whether the PO has the Calypso Stored Value feature.

This boolean is interpreted from the Application Type byte

Returns
true if the PO has the Stored Value feature

◆ restoreFiles()

void keyple::calypso::transaction::CalypsoPo::restoreFiles ( )

(package-private)
Restore the last backup of Elementary Files.
This method should be used when SW of the PO close secure session command is unsuccessful or if secure session is aborted.

◆ setContent() [1/2]

void keyple::calypso::transaction::CalypsoPo::setContent ( const uint8_t  sfi,
const int  numRecord,
const std::vector< uint8_t > &  content 
)

(package-private)
Set or replace the entire content of the specified record numRecord of the provided SFI by the provided content.
If EF does not exist, then it is created.

Parameters
sfithe SFI
numRecordthe record number (should be
>=
1)
contentthe content (should be not empty)

◆ setContent() [2/2]

void keyple::calypso::transaction::CalypsoPo::setContent ( const uint8_t  sfi,
const int  numRecord,
const std::vector< uint8_t > &  content,
const int  offset 
)

(package-private)
Set or replace the content at the specified offset of record numRecord of the provided SFI by a copy of the provided content.
If EF does not exist, then it is created.
If actual record content is not set or has a size

<

offset, then missing data will be padded with 0.

Parameters
sfithe SFI
numRecordthe record number (should be
>=
1)
contentthe content (should be not empty)
offsetthe offset (should be
>=
0)

◆ setCounter()

void keyple::calypso::transaction::CalypsoPo::setCounter ( const uint8_t  sfi,
const int  numCounter,
const std::vector< uint8_t > &  content 
)

(package-private)
Sets a counter value in record #1 of the provided SFI.
If EF does not exist, then it is created.

Parameters
sfithe SFI
numCounterthe counter number (should be
>=
1)
contentthe counter value (should be not null and 3 bytes length)

◆ setDfRatified()

void keyple::calypso::transaction::CalypsoPo::setDfRatified ( const bool  dfRatified)

(package-private)
Set the ratification status

Parameters
dfRatifiedtrue if the session was ratified
Since
0.9

◆ setDirectoryHeader()

CalypsoPo * keyple::calypso::transaction::CalypsoPo::setDirectoryHeader ( const std::shared_ptr< DirectoryHeader directoryHeader)

(package-private)
Sets the DF metadata.

Parameters
directoryHeaderthe DF metadata (should be not null)
Returns
the current instance.

◆ setFileHeader()

void keyple::calypso::transaction::CalypsoPo::setFileHeader ( const uint8_t  sfi,
const std::shared_ptr< FileHeader header 
)

(package-private)
Sets the provided keyple::calypso::transaction::FileHeader to the EF having the provided SFI.
If EF does not exist, then it is created.

Parameters
sfithe SFI
headerthe file header (should be not null)

◆ setPinAttemptRemaining()

void keyple::calypso::transaction::CalypsoPo::setPinAttemptRemaining ( const int  pinAttemptCounter)

(package-private)
Sets the PIN attempts counter.
The PIN attempt counter is interpreted to give the results of the methods keyple::calypso::transaction::CalypsoPo::isPinBlocked() and keyple::calypso::transaction::CalypsoPo::getPinAttemptRemaining().

Parameters
pinAttemptCounterthe number of remaining attempts to present the PIN code

◆ setSvData()

void keyple::calypso::transaction::CalypsoPo::setSvData ( const int  svBalance,
const int  svLastTNum,
const std::shared_ptr< SvLoadLogRecord svLoadLogRecord,
const std::shared_ptr< SvDebitLogRecord svDebitLogRecord 
)

(package-private)
Sets the Stored Value data from the SV Get command

Parameters
svBalancethe current SV balance
svLastTNumthe last SV transaction number
svLoadLogRecordthe SV load log record (may be null if not available)
svDebitLogRecordthe SV debit log record (may be null if not available)

The documentation for this class was generated from the following files:
keyple::core::selection::AbstractMatchingSe::hasAtr
bool hasAtr() const
Definition: AbstractMatchingSe.cpp:63