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, Byte kif, Byte kvc)
    Computes a block of encrypted data to be sent to the card for a PIN modification.
    byte[]
    cipherPinForPresentation(byte[] cardChallenge, byte[] pin, Byte kif, 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 Details

    • 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, Byte kif, 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, Byte kif, 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