#include <SamCommandProcessor.h>

Public Member Functions
	SamCommandProcessor (const std::shared_ptr< CalypsoCard > calypsoCard, const std::shared_ptr< CardSecuritySetting > cardSecuritySetting)

const std::vector< uint8_t >	getSessionTerminalChallenge ()

const std::shared_ptr< uint8_t >	computeKvc (const WriteAccessLevel writeAccessLevel, const std::shared_ptr< uint8_t > kvc) const

const std::shared_ptr< uint8_t >	computeKif (const WriteAccessLevel writeAccessLevel, const std::shared_ptr< uint8_t > kif, const std::shared_ptr< uint8_t > kvc)

void	initializeDigester (const bool sessionEncryption, const bool verificationMode, const uint8_t kif, const uint8_t kvc, const std::vector< uint8_t > &digestData)

void	pushCardExchangedData (const std::vector< std::shared_ptr< ApduRequestSpi > > &requests, const std::vector< std::shared_ptr< ApduResponseApi > > &responses, const int startIndex)

const std::vector< uint8_t >	getTerminalSignature ()

void	authenticateCardSignature (const std::vector< uint8_t > &cardSignatureLo)

const std::vector< uint8_t >	getEncryptedKey (const std::vector< uint8_t > &poChallenge, const uint8_t cipheringKif, const uint8_t cipheringKvc, const uint8_t sourceKif, const uint8_t sourceKvc)

const std::vector< uint8_t >	getCipheredPinData (const std::vector< uint8_t > &poChallenge, const std::vector< uint8_t > &currentPin, const std::vector< uint8_t > &newPin)

const std::vector< uint8_t >	getSvReloadComplementaryData (const std::shared_ptr< CmdCardSvReload > cmdCardSvReload, const std::vector< uint8_t > &svGetHeader, const std::vector< uint8_t > &svGetData)

const std::vector< uint8_t >	getSvDebitComplementaryData (const std::shared_ptr< CmdCardSvDebit > cmdCardSvDebit, const std::vector< uint8_t > &svGetHeader, const std::vector< uint8_t > &svGetData)

const std::vector< uint8_t >	getSvUndebitComplementaryData (const std::shared_ptr< CmdCardSvUndebit > cmdCardSvUndebit, const std::vector< uint8_t > &svGetHeader, const std::vector< uint8_t > &svGetData)

void	checkSvStatus (const std::vector< uint8_t > &svOperationResponseData)

Detailed Description

(package-private)
The SamCommandProcessor class is dedicated to the management of commands sent to the SAM.

In particular, it manages the cryptographic computations related to the secure session (digest computation).

It also will integrate the SAM commands used for Stored Value and PIN/key management. In session, these commands need to be carefully synchronized with the digest calculation.

Since: 2.0.0

Definition at line 59 of file SamCommandProcessor.h.

Constructor & Destructor Documentation

◆ SamCommandProcessor()

keyple::card::calypso::SamCommandProcessor::SamCommandProcessor	(	const std::shared_ptr< CalypsoCard >	calypsoCard,
		const std::shared_ptr< CardSecuritySetting >	cardSecuritySetting
	)

Constructor

Parameters

calypsoCard	The initial card data provided by the selection process.
cardSecuritySetting	the security settings from the application layer.

Since: 2.0.0

Definition at line 69 of file SamCommandProcessor.cpp.

Member Function Documentation

◆ authenticateCardSignature()

void keyple::card::calypso::SamCommandProcessor::authenticateCardSignature ( const std::vector< uint8_t > & cardSignatureLo )

Authenticates the signature part from the card

Executes the Digest Authenticate command with the card part of the signature.

Parameters

cardSignatureLo the card part of the signature.

Exceptions

CalypsoSamCommandException	if the SAM has responded with an error status
ReaderBrokenCommunicationException	if the communication with the SAM reader has failed.
CardBrokenCommunicationException	if the communication with the SAM has failed.
DesynchronizedExchangesException	if the APDU SAM exchanges are out of sync

Since: 2.0.0

Definition at line 374 of file SamCommandProcessor.cpp.

◆ checkSvStatus()

void keyple::card::calypso::SamCommandProcessor::checkSvStatus ( const std::vector< uint8_t > & svOperationResponseData )

Checks the status of the last SV operation

The card signature is compared by the SAM with the one it has computed on its side.

Parameters

svOperationResponseData the data of the SV operation performed.

Exceptions

CalypsoSamCommandException	if the SAM has responded with an error status
ReaderBrokenCommunicationException	if the communication with the SAM reader has failed.
CardBrokenCommunicationException	if the communication with the SAM has failed.

Since: 2.0.0

Definition at line 660 of file SamCommandProcessor.cpp.

◆ computeKif()

const std::shared_ptr< uint8_t > keyple::card::calypso::SamCommandProcessor::computeKif	(	const WriteAccessLevel	writeAccessLevel,
		const std::shared_ptr< uint8_t >	kif,
		const std::shared_ptr< uint8_t >	kvc
	)

(package-private)
Gets the KIF to use according to the provided write access level and KVC.

Parameters

writeAccessLevel	The write access level.
kif	The card KIF value.
kvc	The previously computed KVC value.

Returns: Null if the card did not provide a KIF value and if there's no default KIF value.

Since: 2.0.0

Definition at line 157 of file SamCommandProcessor.cpp.

◆ computeKvc()

const std::shared_ptr< uint8_t > keyple::card::calypso::SamCommandProcessor::computeKvc	(	const WriteAccessLevel	writeAccessLevel,
		const std::shared_ptr< uint8_t >	kvc
	)		const

(package-private)
Gets the KVC to use according to the provided write access and the card's KVC.

Parameters

writeAccessLevel	The write access level.
kvc	The card KVC value.

Returns: Null if the card did not provide a KVC value and if there's no default KVC value.

Since: 2.0.0

Definition at line 146 of file SamCommandProcessor.cpp.

◆ getCipheredPinData()

const std::vector< uint8_t > keyple::card::calypso::SamCommandProcessor::getCipheredPinData	(	const std::vector< uint8_t > &	poChallenge,
		const std::vector< uint8_t > &	currentPin,
		const std::vector< uint8_t > &	newPin
	)

(package-private)
Compute the PIN ciphered data for the encrypted PIN verification or PIN update commands

Parameters

poChallenge	the challenge from the card.
currentPin	the current PIN value.
newPin	the new PIN value (set to null if the operation is a PIN presentation).

Returns: the PIN ciphered data

Exceptions

CalypsoSamCommandException	if the SAM has responded with an error status
ReaderBrokenCommunicationException	if the communication with the SAM reader has failed.
CardBrokenCommunicationException	if the communication with the SAM has failed.

Since: 2.0.0

Definition at line 463 of file SamCommandProcessor.cpp.

◆ getEncryptedKey()

const std::vector< uint8_t > keyple::card::calypso::SamCommandProcessor::getEncryptedKey	(	const std::vector< uint8_t > &	poChallenge,
		const uint8_t	cipheringKif,
		const uint8_t	cipheringKvc,
		const uint8_t	sourceKif,
		const uint8_t	sourceKvc
	)

(package-private)
Compute the encrypted key data for the "Change Key" command.

Parameters

poChallenge	The challenge from the card.
cipheringKif	The KIF of the key used for encryption.
cipheringKvc	The KVC of the key used for encryption.
sourceKif	The KIF of the key to encrypt.
sourceKvc	The KVC of the key to encrypt.

Returns: An array of 32 bytes containing the encrypted key.

Exceptions

CalypsoSamCommandException	if the SAM has responded with an error status
ReaderBrokenCommunicationException	if the communication with the SAM reader has failed.
CardBrokenCommunicationException	if the communication with the SAM has failed.

Since: 2.1.0

Definition at line 409 of file SamCommandProcessor.cpp.

◆ getSessionTerminalChallenge()

const std::vector< uint8_t > keyple::card::calypso::SamCommandProcessor::getSessionTerminalChallenge ( )

Gets the terminal challenge

Performs key diversification if necessary by sending the SAM Select Diversifier command prior to the Get Challenge command. The diversification flag is set to avoid further unnecessary diversification operations.

If the key diversification is already done, the Select Diversifier command is omitted.

The length of the challenge varies from one card product type to another. This information can be found in the CardResource class field.

Returns: the terminal challenge as an array of bytes

Exceptions

CalypsoSamCommandException	if the SAM has responded with an error status
ReaderBrokenCommunicationException	if the communication with the SAM reader has failed.
CardBrokenCommunicationException	if the communication with the SAM has failed.
DesynchronizedExchangesException	if the APDU SAM exchanges are out of sync

Since: 2.0.0

Definition at line 87 of file SamCommandProcessor.cpp.

◆ getSvDebitComplementaryData()

const std::vector< uint8_t > keyple::card::calypso::SamCommandProcessor::getSvDebitComplementaryData	(	const std::shared_ptr< CmdCardSvDebit >	cmdCardSvDebit,
		const std::vector< uint8_t > &	svGetHeader,
		const std::vector< uint8_t > &	svGetData
	)

Computes the cryptographic data required for the SvDebit command.

Use the data from the SvGet command and the partial data from the SvDebit command for this purpose.

The returned data will be used to finalize the card SvDebit command.

Parameters

svGetHeader	the SV Get command header.
svGetData	the SV Get command response data.

Returns: the complementary security data to finalize the SvDebit card command (sam ID + SV prepare load output)

Exceptions

CalypsoSamCommandException	if the SAM has responded with an error status
ReaderBrokenCommunicationException	if the communication with the SAM reader has failed.
CardBrokenCommunicationException	if the communication with the SAM has failed.

Since: 2.0.0

Definition at line 630 of file SamCommandProcessor.cpp.

◆ getSvReloadComplementaryData()

const std::vector< uint8_t > keyple::card::calypso::SamCommandProcessor::getSvReloadComplementaryData	(	const std::shared_ptr< CmdCardSvReload >	cmdCardSvReload,
		const std::vector< uint8_t > &	svGetHeader,
		const std::vector< uint8_t > &	svGetData
	)

Computes the cryptographic data required for the SvReload command.

Use the data from the SvGet command and the partial data from the SvReload command for this purpose.

The returned data will be used to finalize the card SvReload command.

Parameters

cmdCardSvReload	the SvDebit command providing the SvReload partial data.
svGetHeader	the SV Get command header.
svGetData	the SV Get command response data.

Returns: the complementary security data to finalize the SvReload card command (sam ID + SV prepare load output)

Exceptions

CalypsoSamCommandException	if the SAM has responded with an error status
ReaderBrokenCommunicationException	if the communication with the SAM reader has failed.
CardBrokenCommunicationException	if the communication with the SAM has failed.

Since: 2.0.0

Definition at line 615 of file SamCommandProcessor.cpp.

◆ getSvUndebitComplementaryData()

const std::vector< uint8_t > keyple::card::calypso::SamCommandProcessor::getSvUndebitComplementaryData	(	const std::shared_ptr< CmdCardSvUndebit >	cmdCardSvUndebit,
		const std::vector< uint8_t > &	svGetHeader,
		const std::vector< uint8_t > &	svGetData
	)

Computes the cryptographic data required for the SvUndebit command.

Use the data from the SvGet command and the partial data from the SvUndebit command for this purpose.

The returned data will be used to finalize the card SvUndebit command.

Parameters

svGetHeader	the SV Get command header.
svGetData	the SV Get command response data.

Returns: the complementary security data to finalize the SvUndebit card command (sam ID + SV prepare load output)

Exceptions

CalypsoSamCommandException	if the SAM has responded with an error status
ReaderBrokenCommunicationException	if the communication with the SAM reader has failed.
CardBrokenCommunicationException	if the communication with the SAM has failed.

Since: 2.0.0

Definition at line 645 of file SamCommandProcessor.cpp.

◆ getTerminalSignature()

const std::vector< uint8_t > keyple::card::calypso::SamCommandProcessor::getTerminalSignature ( )

Gets the terminal signature from the SAM

All remaining data in the digest cache is sent to the SAM and the Digest Close command is executed.

Returns: the terminal signature

Exceptions

CalypsoSamCommandException	if the SAM has responded with an error status
ReaderBrokenCommunicationException	if the communication with the SAM reader has failed.
CardBrokenCommunicationException	if the communication with the SAM has failed.
DesynchronizedExchangesException	if the APDU SAM exchanges are out of sync

Since: 2.0.0

Definition at line 314 of file SamCommandProcessor.cpp.

◆ initializeDigester()

void keyple::card::calypso::SamCommandProcessor::initializeDigester	(	const bool	sessionEncryption,
		const bool	verificationMode,
		const uint8_t	kif,
		const uint8_t	kvc,
		const std::vector< uint8_t > &	digestData
	)

Initializes the digest computation process

Resets the digest data cache, then fills a first packet with the provided data (from open secure session).

Keeps the session parameters, sets the KIF if not defined

Note: there is no communication with the SAM here.

Parameters

sessionEncryption	true if the session is encrypted.
verificationMode	true if the verification mode is active.
kif	the KIF.
kvc	the KVC.
digestData	a first packet of data to digest.

Since: 2.0.0

Definition at line 177 of file SamCommandProcessor.cpp.

◆ pushCardExchangedData()

void keyple::card::calypso::SamCommandProcessor::pushCardExchangedData	(	const std::vector< std::shared_ptr< ApduRequestSpi > > &	requests,
		const std::vector< std::shared_ptr< ApduResponseApi > > &	responses,
		const int	startIndex
	)

Appends a list full card exchange (request and response) to the digest data cache.
The startIndex argument makes it possible not to include the beginning of the list when necessary.

Parameters

requests	card request list.
responses	card response list.
startIndex	starting point in the list.

Since: 2.0.0

Definition at line 236 of file SamCommandProcessor.cpp.

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

/github/workspace/src/main/SamCommandProcessor.h
/github/workspace/src/main/SamCommandProcessor.cpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ SamCommandProcessor()

Member Function Documentation

◆ authenticateCardSignature()

◆ checkSvStatus()

◆ computeKif()

◆ computeKvc()

◆ getCipheredPinData()

◆ getEncryptedKey()

◆ getSessionTerminalChallenge()

◆ getSvDebitComplementaryData()

◆ getSvReloadComplementaryData()

◆ getSvUndebitComplementaryData()

◆ getTerminalSignature()

◆ initializeDigester()

◆ pushCardExchangedData()