Package org.eclipse.keypop.calypso.crypto.symmetric.spi

Interface SymmetricCryptoCardTransactionManagerSpi

public interface SymmetricCryptoCardTransactionManagerSpi

Calypso card symmetric key cryptography service.

It defines the API needed by a terminal to perform the cryptographic operations required by a Calypso card when using symmetric keys.

An instance of this interface can be obtained via the method SymmetricCryptoCardTransactionManagerFactorySpi.createCardTransactionManager(byte[], boolean, List).

Since:

0.1.0

Method Summary

Modifier and Type	Method	Description
void	activateEncryption()	Activates the encryption/decryption of the data sent/received during the secure session.
byte[]	cipherPinForModification(byte[] cardChallenge, byte[] currentPin, byte[] newPin, java.lang.Byte kif, java.lang.Byte kvc)	Computes a block of encrypted data to be sent to the card for a PIN modification.
byte[]	cipherPinForPresentation(byte[] cardChallenge, byte[] pin, java.lang.Byte kif, java.lang.Byte kvc)	Computes a block of encrypted data to be sent to the card for an enciphered PIN presentation.
void	computeSvCommandSecurityData(SvCommandSecurityDataApi data)	Computes the needed data to operate SV card commands.
void	deactivateEncryption()	Deactivates the encryption/decryption of the data sent/received during the secure session.
byte[]	finalizeTerminalSessionMac()	Finalizes the digest computation and returns the terminal part of the session MAC.
byte[]	generateCipheredCardKey(byte[] cardChallenge, byte issuerKeyKif, byte issuerKeyKvc, byte targetKeyKif, byte targetKeyKvc)	Generates an encrypted key data block for loading a key into a card.
byte[]	generateTerminalSessionMac()	Generates the terminal part of the session MAC used for an early mutual authentication.
byte[]	initTerminalSecureSessionContext()	Initializes the crypto service context for operating a Secure Session with a card and gets the terminal challenge.
void	initTerminalSessionMac(byte[] openSecureSessionDataOut, byte kif, byte kvc)	Stores the data needed to initialize the session MAC computation for a Secure Session.
boolean	isCardSessionMacValid(byte[] cardSessionMac)	Verifies the card part of the session MAC finalizing the mutual authentication process.
boolean	isCardSvMacValid(byte[] cardSvMac)	Verifies the SV card MAC.
void	synchronize()	Synchronizes data of the associated card transaction crypto extension if needed.
byte[]	updateTerminalSessionMac(byte[] cardApdu)	Updates the digest computation with data sent or received from the card.

Method Detail

initTerminalSecureSessionContext

byte[] initTerminalSecureSessionContext()
                                 throws SymmetricCryptoException,
                                        SymmetricCryptoIOException

Initializes the crypto service context for operating a Secure Session with a card and gets the terminal challenge.

Returns:

The terminal challenge.

Throws:

SymmetricCryptoException - If an internal error occurred.

SymmetricCryptoIOException - If an IO error occurred when processing a command.

Since:

0.1.0

initTerminalSessionMac

void initTerminalSessionMac(byte[] openSecureSessionDataOut,
                            byte kif,
                            byte kvc)
                     throws SymmetricCryptoException,
                            SymmetricCryptoIOException

Stores the data needed to initialize the session MAC computation for a Secure Session.

Parameters:

openSecureSessionDataOut - The data out from the card Open Secure Session command.

kif - The card KIF.

kvc - The card KVC.

Throws:

SymmetricCryptoException - If an internal error occurred.

SymmetricCryptoIOException - If an IO error occurred when processing a command.

Since:

0.1.0

updateTerminalSessionMac

byte[] updateTerminalSessionMac(byte[] cardApdu)
                         throws SymmetricCryptoException,
                                SymmetricCryptoIOException

Updates the digest computation with data sent or received from the card.

Returns encrypted/decrypted data when the encryption is active.

Parameters:

cardApdu - A byte array containing either the input or output data of a card command APDU.

Returns:

null if the encryption is not activate, either the ciphered or deciphered command data if the encryption is active.

Throws:

SymmetricCryptoException - If an internal error occurred.

SymmetricCryptoIOException - If an IO error occurred when processing a command.

Since:

0.1.0

finalizeTerminalSessionMac

byte[] finalizeTerminalSessionMac()
                           throws SymmetricCryptoException,
                                  SymmetricCryptoIOException

Finalizes the digest computation and returns the terminal part of the session MAC.

Returns:

A byte array containing the terminal session MAC.

Throws:

SymmetricCryptoException - If an internal error occurred.

SymmetricCryptoIOException - If an IO error occurred when processing a command.

Since:

0.1.0

generateTerminalSessionMac

byte[] generateTerminalSessionMac()
                           throws SymmetricCryptoException,
                                  SymmetricCryptoIOException

Generates the terminal part of the session MAC used for an early mutual authentication.

Returns:

A byte array containing the terminal session MAC.

Throws:

SymmetricCryptoException - If an internal error occurred.

SymmetricCryptoIOException - If an IO error occurred when processing a command.

Since:

0.1.0

activateEncryption

void activateEncryption()
                 throws SymmetricCryptoException,
                        SymmetricCryptoIOException

Activates the encryption/decryption of the data sent/received during the secure session.

Throws:

SymmetricCryptoException - If an internal error occurred.

SymmetricCryptoIOException - If an IO error occurred when processing a command.

Since:

0.1.0

deactivateEncryption

void deactivateEncryption()
                   throws SymmetricCryptoException,
                          SymmetricCryptoIOException

Deactivates the encryption/decryption of the data sent/received during the secure session.

Throws:

SymmetricCryptoException - If an internal error occurred.

SymmetricCryptoIOException - If an IO error occurred when processing a command.

Since:

0.1.0

isCardSessionMacValid

boolean isCardSessionMacValid(byte[] cardSessionMac)
                       throws SymmetricCryptoException,
                              SymmetricCryptoIOException

Verifies the card part of the session MAC finalizing the mutual authentication process.

Parameters:

cardSessionMac - A byte array containing the card session MAC.

Returns:

true if the card session MAC is validated.

Throws:

SymmetricCryptoException - If an internal error occurred.

SymmetricCryptoIOException - If an IO error occurred when processing a command.

Since:

0.1.0

computeSvCommandSecurityData

void computeSvCommandSecurityData(SvCommandSecurityDataApi data)
                           throws SymmetricCryptoException,
                                  SymmetricCryptoIOException

Computes the needed data to operate SV card commands.

Parameters:

data - The data involved in the preparation of an SV Reload/Debit/Undebit command.

Throws:

SymmetricCryptoException - If an internal error occurred.

SymmetricCryptoIOException - If an IO error occurred when processing a command.

Since:

0.1.0

isCardSvMacValid

boolean isCardSvMacValid(byte[] cardSvMac)
                  throws SymmetricCryptoException,
                         SymmetricCryptoIOException

Verifies the SV card MAC.

Parameters:

cardSvMac - A byte array containing the card SV MAC.

Returns:

true if the card SV MAC is validated.

Throws:

SymmetricCryptoException - If an internal error occurred.

SymmetricCryptoIOException - If an IO error occurred when processing a command.

Since:

0.1.0

cipherPinForPresentation

byte[] cipherPinForPresentation(byte[] cardChallenge,
                                byte[] pin,
                                java.lang.Byte kif,
                                java.lang.Byte kvc)
                         throws SymmetricCryptoException,
                                SymmetricCryptoIOException

Computes a block of encrypted data to be sent to the card for an enciphered PIN presentation.

Note: the kif and kvc parameters are ignored when PIN verification is performed within a Secure Session.

Parameters:

cardChallenge - A byte array containing the card challenge.

pin - A byte array containing the 4-byte PIN value.

kif - The PIN encryption key KIF.

kvc - The PIN encryption key KVC.

Returns:

A byte array containing the encrypted data block to sent to the card.

Throws:

SymmetricCryptoException - If an internal error occurred.

SymmetricCryptoIOException - If an IO error occurred when processing a command.

Since:

0.1.0

cipherPinForModification

byte[] cipherPinForModification(byte[] cardChallenge,
                                byte[] currentPin,
                                byte[] newPin,
                                java.lang.Byte kif,
                                java.lang.Byte kvc)
                         throws SymmetricCryptoException,
                                SymmetricCryptoIOException

Computes a block of encrypted data to be sent to the card for a PIN modification.

Note: the kif and kvc parameters are ignored when PIN modification is performed within a Secure Session.

Parameters:

cardChallenge - A byte array containing the card challenge.

currentPin - A byte array containing the 4-byte current PIN value.

newPin - A byte array containing the 4-byte new PIN value.

kif - The PIN encryption key KIF.

kvc - The PIN encryption key KVC.

Returns:

A byte array containing the encrypted data block to sent to the card.

Throws:

SymmetricCryptoException - If an internal error occurred.

SymmetricCryptoIOException - If an IO error occurred when processing a command.

Since:

0.1.0

generateCipheredCardKey

byte[] generateCipheredCardKey(byte[] cardChallenge,
                               byte issuerKeyKif,
                               byte issuerKeyKvc,
                               byte targetKeyKif,
                               byte targetKeyKvc)
                        throws SymmetricCryptoException,
                               SymmetricCryptoIOException

Generates an encrypted key data block for loading a key into a card.

Parameters:

cardChallenge - A byte array containing the card challenge.

issuerKeyKif - The issuer key KIF.

issuerKeyKvc - The issuer key KVC.

targetKeyKif - The target key KIF.

targetKeyKvc - The target key KVC.

Returns:

A byte array containing the encrypted data block to sent to the card.

Throws:

SymmetricCryptoException - If an internal error occurred.

SymmetricCryptoIOException - If an IO error occurred when processing a command.

Since:

0.1.0

synchronize

void synchronize()
          throws SymmetricCryptoException,
                 SymmetricCryptoIOException

Synchronizes data of the associated card transaction crypto extension if needed.

Throws:

SymmetricCryptoException - If an internal error occurred.

SymmetricCryptoIOException - If an IO error occurred when processing a command.

Since:

0.1.0