Extends the IsoSmartCard interface of the "Keypop Reader API" to provide additional functionality specific to Calypso cards. More...

#include <keypop/calypso/card/card/CalypsoCard.hpp>

Inheritance diagram for keypop::calypso::card::card::CalypsoCard:

[legend]

Collaboration diagram for keypop::calypso::card::card::CalypsoCard:

[legend]

Public Types
enum class	ProductType { PRIME_REVISION_1 , PRIME_REVISION_2 , PRIME_REVISION_3 , LIGHT , BASIC , UNKNOWN }
	All Calypso Card products supported by this API. More...

Public Member Functions
virtual const ProductType &	getProductType () const =0
	Gets the card product type. More...

virtual bool	isHce () const =0
	Indicates if the card is a Calypso HCE (Host Card Emulation) . More...

virtual bool	isDfInvalidated () const =0
	Tells if the current DF is invalidated or not. More...

virtual const std::vector< uint8_t > &	getDfName () const =0
	Gets the DF name as an array of bytes. More...

virtual const std::vector< uint8_t >	getApplicationSerialNumber () const =0
	Gets the Calypso application serial number as an array of bytes. More...

virtual const std::vector< uint8_t > &	getStartupInfoRawData () const =0
	Gets the raw Calypso startup information. More...

virtual uint8_t	getPlatform () const =0
	Gets the platform identification byte which is the reference of the chip. More...

virtual uint8_t	getApplicationType () const =0
	Gets the Application Type byte which determines the Calypso product type and various options. More...

virtual uint8_t	getApplicationSubtype () const =0
	Gets the Application Subtype that provides a reference to the file structure of the Calypso DF. More...

virtual uint8_t	getSoftwareIssuer () const =0
	Gets the Software Issuer byte that indicates the entity responsible for the software of the selected application. More...

virtual uint8_t	getSoftwareVersion () const =0
	Gets the Software Version field that may be set to any fixed value by the Software Issuer of the Calypso application. More...

virtual uint8_t	getSoftwareRevision () const =0
	Gets the Software Revision field that may be set to any fixed value by the Software Issuer of the Calypso application. More...

virtual uint8_t	getSessionModification () const =0
	Gets the session modification byte from the startup info structure. More...

virtual const std::vector< uint8_t >	getTraceabilityInformation () const =0
	Gets the traceability information of the product. More...

virtual const std::vector< std::uint8_t > &	getCardPublicKey () const =0
	Returns the card public key. More...

virtual const std::vector< std::uint8_t > &	getCardCertificate () const =0
	Returns the card certificate. More...

virtual const std::vector< std::uint8_t > &	getCaCertificate () const =0
	Returns the CA certificate. More...

virtual const std::shared_ptr< DirectoryHeader >	getDirectoryHeader () const =0
	Returns the metadata of the current DF. More...

virtual const std::shared_ptr< ElementaryFile >	getFileBySfi (const uint8_t sfi) const =0
	Returns a reference to the ElementaryFile that has the provided SFI. More...

virtual const std::shared_ptr< ElementaryFile >	getFileByLid (const uint16_t lid) const =0
	Returns a reference to the ElementaryFile that has the provided LID value. More...

virtual const std::vector< std::shared_ptr< ElementaryFile > > &	getFiles () const =0
	Returns a reference to the set of all known Elementary Files contains inside the current DF. More...

virtual bool	isDfRatified () const =0
	Tells if the last session with this card has been ratified or not. More...

virtual int	getTransactionCounter () const =0
	Returns the transaction counter value provided in the output data of the last successful "Open Secure Session" command. More...

virtual bool	isPkiModeSupported () const =0
	Indicates whether the Public Key Authentication is supported or not (since rev 3.3). More...

virtual bool	isExtendedModeSupported () const =0
	Indicates whether the Extended Mode is supported or not (since rev 3.2). More...

virtual bool	isRatificationOnDeselectSupported () const =0
	Indicates if the ratification is done on deselect (ratification command not necessary). More...

virtual bool	isPinFeatureAvailable () const =0
	Indicates whether the card has the Calypso PIN feature. More...

virtual bool	isPinBlocked () const =0
	Indicates if the PIN is blocked. More...

virtual int	getPinAttemptRemaining () const =0
	Gives the number of erroneous PIN presentations remaining before blocking. More...

virtual bool	isSvFeatureAvailable () const =0
	Indicates whether the card has the Calypso Stored Value feature. More...

virtual int	getSvBalance () const =0
	Gets the current SV balance value. More...

virtual int	getSvLastTNum () const =0
	Gets the last SV transaction number. More...

virtual const std::shared_ptr< SvLoadLogRecord >	getSvLoadLogRecord ()=0
	Gets a reference to the last SvLoadLogRecord. More...

virtual const std::shared_ptr< SvDebitLogRecord >	getSvDebitLogLastRecord ()=0
	Gets a reference to the last SvDebitLogRecord. More...

virtual const std::vector< std::shared_ptr< SvDebitLogRecord > >	getSvDebitLogAllRecords () const =0
	Gets list of references to the SvDebitLogRecord read from the card. More...

	operator std::string ()

Detailed Description

Extends the IsoSmartCard interface of the "Keypop Reader API" to provide additional functionality specific to Calypso cards.

An instance of

CalypsoCard

is obtained by casting the IsoSmartCard object from the selection process defined by the "Keypop Reader API".

It is a dynamic view of the card's content, regularly updated from the selection stage to the end of the transaction.

The various information contained in CalypsoCard includes:

The application identification fields (revision/version, class, DF name, serial number, ATR, issuer)
The indication of the presence of optional features (Stored Value, PIN, Rev3.2 mode, ratification management)
The management information of the modification buffer
The invalidation status
The files, counters, SV data read or modified during the execution of the processes defined by the card transaction manager.

Since: 1.0.0

Definition at line 58 of file CalypsoCard.hpp.

Member Enumeration Documentation

◆ ProductType

enum class keypop::calypso::card::card::CalypsoCard::ProductType

strong

All Calypso Card products supported by this API.

Since: 1.0.0

Enumerator
PRIME_REVISION_1	Card Calypso Prime revision 1.x. Since 1.0.0
PRIME_REVISION_2	Card Calypso Prime revision 2.x. Since 1.0.0
PRIME_REVISION_3	Card Calypso Prime revision 3.x. Since 1.0.0
LIGHT	Card Calypso Light. Since 1.0.0
BASIC	Card Calypso Basic. Since 1.0.0
UNKNOWN	Application type is equal to 0 or FFh or if the data provided by the selection process is not properly formatted (bad TLV data). Since 1.0.0

Definition at line 65 of file CalypsoCard.hpp.

Member Function Documentation

◆ getApplicationSerialNumber()

virtual const std::vector< uint8_t > keypop::calypso::card::card::CalypsoCard::getApplicationSerialNumber ( ) const

pure virtual

Gets the Calypso application serial number as an array of bytes.

Returns: A not null byte array containing the Application Serial Number (8 bytes).

Since: 1.0.0

◆ getApplicationSubtype()

virtual uint8_t keypop::calypso::card::card::CalypsoCard::getApplicationSubtype ( ) const

pure virtual

Gets the Application Subtype that provides a reference to the file structure of the Calypso DF.

Returns: The Application Subtype byte

Since: 1.0.0

◆ getApplicationType()

virtual uint8_t keypop::calypso::card::card::CalypsoCard::getApplicationType ( ) const

pure virtual

Gets the Application Type byte which determines the Calypso product type and various options.

Returns: The Application Type byte.

Since: 1.0.0

◆ getCaCertificate()

virtual const std::vector< std::uint8_t > & keypop::calypso::card::card::CalypsoCard::getCaCertificate ( ) const

pure virtual

Returns the CA certificate.

Returns: An empty array if the public key is not available.

See also: CalypsoCardSelectionExtension::prepareGetData(GetDataTag); TransactionManager::prepareGetData(GetDataTag); SecurePkiModeTransactionManager::prepareOpenSecureSession()

Since: 2.1.0

◆ getCardCertificate()

virtual const std::vector< std::uint8_t > & keypop::calypso::card::card::CalypsoCard::getCardCertificate ( ) const

pure virtual

Returns the card certificate.

Returns: An empty array if the public key is not available.

See also: CalypsoCardSelectionExtension::prepareGetData(GetDataTag); TransactionManager::prepareGetData(GetDataTag); SecurePkiModeTransactionManager::prepareOpenSecureSession()

Since: 2.1.0

◆ getCardPublicKey()

virtual const std::vector< std::uint8_t > & keypop::calypso::card::card::CalypsoCard::getCardPublicKey ( ) const

pure virtual

Returns the card public key.

Returns: An empty array if the public key is not available.

See also: CalypsoCardSelectionExtension::prepareGetData(GetDataTag); TransactionManager::prepareGetData(GetDataTag); SecurePkiModeTransactionManager::prepareOpenSecureSession()

Since: 2.1.0

◆ getDfName()

virtual const std::vector< uint8_t > & keypop::calypso::card::card::CalypsoCard::getDfName ( ) const

pure virtual

Gets the DF name as an array of bytes.

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 not null byte array containing the DF Name bytes (5 to 16 bytes)

Since: 1.0.0

◆ getDirectoryHeader()

virtual const std::shared_ptr< DirectoryHeader > keypop::calypso::card::card::CalypsoCard::getDirectoryHeader ( ) const

pure virtual

Returns the metadata of the current DF.

Returns: Null if is not set.

See also: CalypsoCardSelectionExtension::prepareSelectFile(short); CalypsoCardSelectionExtension::prepareSelectFile(SelectFileControl); TransactionManager::prepareSelectFile(short); TransactionManager::prepareSelectFile(SelectFileControl)

Since: 1.0.0

◆ getFileByLid()

virtual const std::shared_ptr< ElementaryFile > keypop::calypso::card::card::CalypsoCard::getFileByLid ( const uint16_t lid ) const

pure virtual

Returns a reference to the 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

lid	The LID to search.

Returns: Null if the requested EF is not found.

Since: 1.0.0

◆ getFileBySfi()

virtual const std::shared_ptr< ElementaryFile > keypop::calypso::card::card::CalypsoCard::getFileBySfi ( const uint8_t sfi ) const

pure virtual

Returns a reference to the ElementaryFile that has the provided SFI.

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

sfi	The SFI to search.

Returns: Null if the requested EF is not found or if the SFI is equal to 0.

Since: 1.0.0

◆ getFiles()

virtual const std::vector< std::shared_ptr< ElementaryFile > > & keypop::calypso::card::card::CalypsoCard::getFiles ( ) const

pure virtual

Returns a reference to the set of all known Elementary Files contains inside the current DF.

Note that if a secure session is actually running, then the set contains all session modifications, which can be canceled if the secure session fails.

Returns: A not null reference (it may be empty if no one EF is set).

Since: 1.1.0

◆ getPinAttemptRemaining()

virtual int keypop::calypso::card::card::CalypsoCard::getPinAttemptRemaining ( ) const

pure virtual

Gives the number of erroneous PIN presentations remaining before blocking.

Returns: The number of remaining attempts.

Exceptions

IllegalStateException If the PIN has not been checked.

See also: TransactionManager::prepareCheckPinStatus(); TransactionManager::prepareVerifyPin(byte[])

Since: 1.0.0

◆ getPlatform()

virtual uint8_t keypop::calypso::card::card::CalypsoCard::getPlatform ( ) const

pure virtual

Gets the platform identification byte which is the reference of the chip.

Returns: The platform identification byte.

Since: 1.0.0

◆ getProductType()

virtual const ProductType & keypop::calypso::card::card::CalypsoCard::getProductType ( ) const

pure virtual

Gets the card product type.

Returns: A not null reference.

Since: 1.0.0

◆ getSessionModification()

virtual uint8_t keypop::calypso::card::card::CalypsoCard::getSessionModification ( ) const

pure virtual

Gets the session modification byte from the startup info structure.

Depending on the type of card, 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 Modification byte.

Since: 1.0.0

◆ getSoftwareIssuer()

virtual uint8_t keypop::calypso::card::card::CalypsoCard::getSoftwareIssuer ( ) const

pure virtual

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

Returns: The Software Issuer byte.

Since: 1.0.0

◆ getSoftwareRevision()

virtual uint8_t keypop::calypso::card::card::CalypsoCard::getSoftwareRevision ( ) const

pure virtual

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

Returns: The Software Revision byte.

Since: 1.0.0

◆ getSoftwareVersion()

virtual uint8_t keypop::calypso::card::card::CalypsoCard::getSoftwareVersion ( ) const

pure virtual

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

Returns: The Software Version byte.

Since: 1.0.0

◆ getStartupInfoRawData()

virtual const std::vector< uint8_t > & keypop::calypso::card::card::CalypsoCard::getStartupInfoRawData ( ) const

pure virtual

Gets the raw Calypso startup information.

Returns: A not null byte array.

Since: 1.0.0

◆ getSvBalance()

virtual int keypop::calypso::card::card::CalypsoCard::getSvBalance ( ) const

pure virtual

Gets the current SV balance value.

Returns: An int

Exceptions

IllegalStateException If no SV Get command has been executed.

See also: SecureSymmetricCryptoTransactionManager::prepareSvGet(SvOperation, SvAction); SecureSymmetricCryptoTransactionManager::prepareSvDebit(int); SecureSymmetricCryptoTransactionManager::prepareSvDebit(int, byte[], byte[]); SecureSymmetricCryptoTransactionManager::prepareSvReload(int); SecureSymmetricCryptoTransactionManager::prepareSvReload(int, byte[], byte[], byte[])

Since: 1.0.0

◆ getSvDebitLogAllRecords()

virtual const std::vector< std::shared_ptr< SvDebitLogRecord > > keypop::calypso::card::card::CalypsoCard::getSvDebitLogAllRecords ( ) const

pure virtual

Gets list of references to the SvDebitLogRecord read from the card.

Returns: An empty list if no log records are available.

See also: SecureSymmetricCryptoTransactionManager::prepareSvGet(SvOperation, SvAction); SecureSymmetricCryptoTransactionManager::prepareSvDebit(int); SecureSymmetricCryptoTransactionManager::prepareSvDebit(int, byte[], byte[]); SecureSymmetricCryptoTransactionManager::prepareSvReload(int); SecureSymmetricCryptoTransactionManager::prepareSvReload(int, byte[], byte[], byte[])

Since: 1.0.0

◆ getSvDebitLogLastRecord()

virtual const std::shared_ptr< SvDebitLogRecord > keypop::calypso::card::card::CalypsoCard::getSvDebitLogLastRecord ( )

pure virtual

Gets a reference to the last SvDebitLogRecord.

Returns: A last SV debit log record object or null if not available.

See also: SecureSymmetricCryptoTransactionManager::prepareSvGet(SvOperation, SvAction); SecureSymmetricCryptoTransactionManager::prepareSvDebit(int); SecureSymmetricCryptoTransactionManager::prepareSvDebit(int, byte[], byte[]); SecureSymmetricCryptoTransactionManager::prepareSvReload(int); SecureSymmetricCryptoTransactionManager::prepareSvReload(int, byte[], byte[], byte[])

Since: 1.0.0

◆ getSvLastTNum()

virtual int keypop::calypso::card::card::CalypsoCard::getSvLastTNum ( ) const

pure virtual

Gets the last SV transaction number.

Returns: An int

Exceptions

IllegalStateException If no SV Get command has been executed.

See also: SecureSymmetricCryptoTransactionManager::prepareSvGet(SvOperation, SvAction); SecureSymmetricCryptoTransactionManager::prepareSvDebit(int); SecureSymmetricCryptoTransactionManager::prepareSvDebit(int, byte[], byte[]); SecureSymmetricCryptoTransactionManager::prepareSvReload(int); SecureSymmetricCryptoTransactionManager::prepareSvReload(int, byte[], byte[], byte[])

Since: 1.0.0

◆ getSvLoadLogRecord()

virtual const std::shared_ptr< SvLoadLogRecord > keypop::calypso::card::card::CalypsoCard::getSvLoadLogRecord ( )

pure virtual

Gets a reference to the last SvLoadLogRecord.

Returns: A last SV load log record object or null if not available.

See also: SecureSymmetricCryptoTransactionManager::prepareSvGet(SvOperation, SvAction); SecureSymmetricCryptoTransactionManager::prepareSvDebit(int); SecureSymmetricCryptoTransactionManager::prepareSvDebit(int, byte[], byte[]); SecureSymmetricCryptoTransactionManager::prepareSvReload(int); SecureSymmetricCryptoTransactionManager::prepareSvReload(int, byte[], byte[], byte[])

Since: 1.0.0

◆ getTraceabilityInformation()

virtual const std::vector< uint8_t > keypop::calypso::card::card::CalypsoCard::getTraceabilityInformation ( ) const

pure virtual

Gets the traceability information of the product.

The returned array contains the software issuer ID and the discretionary data.

Returns: An empty array if the traceability information is not available.

See also: CalypsoCardSelectionExtension::prepareGetData(GetDataTag); TransactionManager::prepareGetData(GetDataTag)

Since: 1.1.0

◆ getTransactionCounter()

virtual int keypop::calypso::card::card::CalypsoCard::getTransactionCounter ( ) const

pure virtual

Returns the transaction counter value provided in the output data of the last successful "Open Secure Session" command.

Please note that there are other commands that can decrement the original card counter (e.g. Change Key, Change/Verify PIN, SV Debit/Undebit/Reload). For these othe commands, the counter value returned by this method will not be updated.

Returns: A positive value.

Exceptions

IllegalStateException If no session has been opened.

See also: CalypsoCardSelectionExtension# preparePreOpenSecureSession(WriteAccessLevel); SecureSymmetricCryptoTransactionManager #prepareOpenSecureSession(WriteAccessLevel)

Since: 1.2.0

◆ isDfInvalidated()

virtual bool keypop::calypso::card::card::CalypsoCard::isDfInvalidated ( ) const

pure virtual

Tells if the current DF is invalidated or not.

The invalidation status is determined either from the response to the Select Application command or from the response to a Select File (DF) command.

For a PRIME_REVISION_3 card, a 6283h status word is returned in response to the Select Application command when the corresponding DF is invalidated.

For older Calypso cards it may be necessary to execute a Select File command in order to determine the invalidation status.

Returns: True if the current DF has been invalidated.

Since: 1.0.0

◆ isDfRatified()

virtual bool keypop::calypso::card::card::CalypsoCard::isDfRatified ( ) const

pure virtual

Tells if the last session with this card has been ratified or not.

Returns: True if the card has been ratified.

Exceptions

IllegalStateException If no session has been opened.

See also: CalypsoCardSelectionExtension::preparePreOpenSecureSession(WriteAccessLevel); SecureSymmetricCryptoTransactionManager::prepareOpenSecureSession(WriteAccessLevel)

Since: 1.0.0

◆ isExtendedModeSupported()

virtual bool keypop::calypso::card::card::CalypsoCard::isExtendedModeSupported ( ) const

pure virtual

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

This boolean is initially the result of the interpretation of the application type byte but may be updated after the secure session is opened. Indeed, depending on the type of key used, the extended mode functionalities may not be available (non-AES keys) and this information is provided by the card in response to the "Open Secure Session" command.

Returns: True if the Extended Mode is supported.

Since: 1.0.0

◆ isHce()

virtual bool keypop::calypso::card::card::CalypsoCard::isHce ( ) const

pure virtual

Indicates if the card is a Calypso HCE (Host Card Emulation) .

Returns: True if the card is a Calypso HCE.

Since: 1.0.0

◆ isPinBlocked()

virtual bool keypop::calypso::card::card::CalypsoCard::isPinBlocked ( ) const

pure virtual

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

IllegalStateException If the PIN has not been checked.

See also: TransactionManager::prepareCheckPinStatus(); TransactionManager::prepareVerifyPin(byte[])

Since: 1.0.0

◆ isPinFeatureAvailable()

virtual bool keypop::calypso::card::card::CalypsoCard::isPinFeatureAvailable ( ) const

pure virtual

Indicates whether the card has the Calypso PIN feature.

This boolean is interpreted from the Application Type byte

Returns: True if the card has the PIN feature.

Since: 1.0.0

◆ isPkiModeSupported()

virtual bool keypop::calypso::card::card::CalypsoCard::isPkiModeSupported ( ) const

pure virtual

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

This boolean is interpreted from the Application Type byte

Returns: True if the Public Key Authentication is supported.

Since: 1.0.0

◆ isRatificationOnDeselectSupported()

virtual bool keypop::calypso::card::card::CalypsoCard::isRatificationOnDeselectSupported ( ) const

pure virtual

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 on deselect is supported.

Since: 1.0.0

◆ isSvFeatureAvailable()

virtual bool keypop::calypso::card::card::CalypsoCard::isSvFeatureAvailable ( ) const

pure virtual

Indicates whether the card has the Calypso Stored Value feature.

This boolean is interpreted from the Application Type byte

Returns: True if the card has the Stored Value feature

Since: 1.0.0

◆ operator std::string()

keypop::calypso::card::card::CalypsoCard::operator std::string ( )

inline

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

keypop/calypso/card/card/CalypsoCard.hpp

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ ProductType

Member Function Documentation

◆ getApplicationSerialNumber()

◆ getApplicationSubtype()

◆ getApplicationType()

◆ getCaCertificate()

◆ getCardCertificate()

◆ getCardPublicKey()

◆ getDfName()

◆ getDirectoryHeader()

◆ getFileByLid()

◆ getFileBySfi()

◆ getFiles()

◆ getPinAttemptRemaining()

◆ getPlatform()

◆ getProductType()

◆ getSessionModification()

◆ getSoftwareIssuer()

◆ getSoftwareRevision()

◆ getSoftwareVersion()

◆ getStartupInfoRawData()

◆ getSvBalance()

◆ getSvDebitLogAllRecords()

◆ getSvDebitLogLastRecord()

◆ getSvLastTNum()

◆ getSvLoadLogRecord()

◆ getTraceabilityInformation()

◆ getTransactionCounter()

◆ isDfInvalidated()

◆ isDfRatified()

◆ isExtendedModeSupported()

◆ isHce()

◆ isPinBlocked()

◆ isPinFeatureAvailable()

◆ isPkiModeSupported()

◆ isRatificationOnDeselectSupported()

◆ isSvFeatureAvailable()

◆ operator std::string()