Package org.eclipse.keypop.calypso.card.transaction

Interface SecureSymmetricCryptoTransactionManager<T extends SecureSymmetricCryptoTransactionManager<T>>

Type Parameters:
T - The type of the lowest level child object.
All Superinterfaces:
SecureTransactionManager<T>, TransactionManager<T>
All Known Subinterfaces:
SecureExtendedModeTransactionManager, SecureRegularModeTransactionManager
public interface SecureSymmetricCryptoTransactionManager<T extends SecureSymmetricCryptoTransactionManager<T>> extends SecureTransactionManager<T>
Contains operations common to all card transactions secured by "symmetric" key cryptographic algorithms.

See SecureTransactionManager parent interface for more information and details of available card operations.

Since:
2.0.0

  • Method Details

    • prepareOpenSecureSession

      T prepareOpenSecureSession(WriteAccessLevel writeAccessLevel)
      Schedules the execution of an "Open Secure Session" command.

      The secure session will be opened with the provided WriteAccessLevel depending on whether it is a personalization, reload or debit transaction profile.

      Note that if the next prepared command is a "Read One Record" or "Read One Or More Counters", then it will by default be merged with the "Open Secure Session" command for optimization purposes except if the "pre-open" mode is active.

      This mechanism may in some cases be incompatible with the security constraints and can be disabled via the SymmetricCryptoSecuritySetting.disableReadOnSessionOpening() method.

      Parameters:
      writeAccessLevel - The write access level to be used.
      Returns:
      The current instance.
      Throws:
      IllegalArgumentException - If the provided argument is null.
      IllegalStateException - In the following cases:
      Since:
      1.6.0
      See Also:

    • prepareSvGet

      T prepareSvGet(SvOperation svOperation, SvAction svAction)
      Schedules the execution of a "SV Get" command to prepare an SV operation or simply retrieves the current SV status.

      Data will be available in CalypsoCard using the dedicated SV data management methods.

      Parameters:
      svOperation - Informs about the nature of the intended operation: debit or reload.
      svAction - The type of action: DO a debit or a positive reload, UNDO an undebit or a negative reload.
      Returns:
      The current instance.
      Throws:
      UnsupportedOperationException - If the SV feature is not available for this card.
      IllegalArgumentException - If one of the arguments is null.
      Since:
      1.0.0

    • prepareSvReload

      T prepareSvReload(int amount, byte[] date, byte[] time, byte[] free)
      Schedules the execution of a "SV Reload" command to increase the current SV balance and using the provided additional data.

      Data will be available in CalypsoCard using the dedicated SV data management methods.

      Note: the key used is the reload key.

      Parameters:
      amount - The value to be reloaded, positive or negative integer in the range. -8388608..8388607
      date - 2-byte free value.
      time - 2-byte free value.
      free - 2-byte free value.
      Returns:
      The current instance.
      Throws:
      IllegalArgumentException - If one of the provided argument is out of range.
      IllegalStateException - In one of the following cases:
      • Another SV command was already prepared inside the same secure session.
      • The SV command is not placed in the first position in the list of prepared commands.
      • The SV command does not follow a "SV Get" command.
      • The command and the SV operation are not consistent.
      SessionBufferOverflowException - If the command will overflow the modifications buffer size and the multiple session is not allowed.
      Since:
      1.0.0

    • prepareSvReload

      T prepareSvReload(int amount)
      Schedules the execution of a "SV Reload" command to increase the current SV balance.

      Data will be available in CalypsoCard using the dedicated SV data management methods.

      Note 1: the optional SV additional data are set to zero.

      Note 2: the key used is the reload key.

      Parameters:
      amount - The value to be reloaded, positive integer in the range 0..8388607 for a DO. action, in the range 0..8388608 for an UNDO action.
      Returns:
      The current instance.
      Throws:
      IllegalArgumentException - If the provided argument is out of range.
      IllegalStateException - In one of the following cases:
      • Another SV command was already prepared inside the same secure session.
      • The SV command is not placed in the first position in the list of prepared commands.
      • The SV command does not follow a "SV Get" command.
      • The command and the SV operation are not consistent.
      SessionBufferOverflowException - If the command will overflow the modifications buffer size and the multiple session is not allowed.
      Since:
      1.0.0

    • prepareSvDebit

      T prepareSvDebit(int amount, byte[] date, byte[] time)
      Schedules the execution of a "SV Debit" or "SV Undebit" command to increase the current SV balance or to partially or totally cancels the last SV debit command and using the provided additional data.

      It consists in decreasing the current balance of the SV by a certain amount or canceling a previous debit according to the type operation chosen in when invoking the previous SV Get command.

      Data will be available in CalypsoCard using the dedicated SV data management methods.

      Note 1: the key used is the debit key

      Parameters:
      amount - The amount to be subtracted or added, positive integer in the range 0..32767 when subtracted and 0..32768 when added.
      date - 2-byte free value.
      time - 2-byte free value.
      Returns:
      The current instance.
      Throws:
      IllegalArgumentException - If one of the provided argument is out of range.
      IllegalStateException - In one of the following cases:
      • New value is negative and negative balances are not allowed.
      • Another SV command was already prepared inside the same secure session.
      • The SV command is not placed in the first position in the list of prepared commands.
      • The SV command does not follow a "SV Get" command.
      • The command and the SV operation are not consistent.
      SessionBufferOverflowException - If the command will overflow the modifications buffer size and the multiple session is not allowed.
      Since:
      1.0.0

    • prepareSvDebit

      T prepareSvDebit(int amount)
      Schedules the execution of a "SV Debit" or "SV Undebit" command to increase the current SV balance or to partially or totally cancels the last SV debit command.

      It consists in decreasing the current balance of the SV by a certain amount or canceling a previous debit.

      Data will be available in CalypsoCard using the dedicated SV data management methods.

      Note 1: the optional SV additional data are set to zero.

      Note 2: the key used is the debit key.

      Parameters:
      amount - The amount to be subtracted or added, positive integer in the range 0..32767 when subtracted and 0..32768 when added.
      Returns:
      The current instance.
      Throws:
      IllegalArgumentException - If one of the provided argument is out of range.
      IllegalStateException - In one of the following cases:
      • New value is negative and negative balances are not allowed.
      • Another SV command was already prepared inside the same secure session.
      • The SV command is not placed in the first position in the list of prepared commands.
      • The SV command does not follow a "SV Get" command.
      • The command and the SV operation are not consistent.
      SessionBufferOverflowException - If the command will overflow the modifications buffer size and the multiple session is not allowed.
      Since:
      1.0.0

    • prepareInvalidate

      T prepareInvalidate()
      Schedules the execution of an "Invalidate" command.

      This command is usually executed within a secure session with the DEBIT key (depends on the access rights given to this command in the file structure of the card).

      The DF status will be available in CalypsoCard using the CalypsoCard.isDfInvalidated() method.

      Returns:
      The current instance.
      Throws:
      IllegalStateException - If the card is already invalidated.
      SessionBufferOverflowException - If the command will overflow the modifications buffer size and the multiple session is not allowed.
      Since:
      1.0.0

    • prepareRehabilitate

      T prepareRehabilitate()
      Schedules the execution of a "Rehabilitate" command.

      This command is usually executed within a secure session with the PERSONALIZATION key (depends on the access rights given to this command in the file structure of the card).

      The DF status will be available in CalypsoCard using the CalypsoCard.isDfInvalidated() method.

      Returns:
      The current instance.
      Throws:
      IllegalStateException - If the card is not invalidated.
      SessionBufferOverflowException - If the command will overflow the modifications buffer size and the multiple session is not allowed.
      Since:
      1.0.0

    • prepareChangeKey

      T prepareChangeKey(int keyIndex, byte newKif, byte newKvc, byte issuerKif, byte issuerKvc)
      Schedules the execution of "Change Key" command to replace one of the current card keys with another key present in the cryptographic module.

      This command can be performed only out of a secure session.

      The change key process transfers the key from the cryptographic module to the card. The new key is diversified by the cryptographic module from a primary key and encrypted using the indicated issuer key to secure the transfer to the card. All provided KIFs and KVCs must be present in the cryptographic module.

      Parameters:
      keyIndex - The index of the key to be replaced (1 for the issuer key, 2 for the load key, 3 for the debit key).
      newKif - The KIF of the new key.
      newKvc - The KVC of the new key.
      issuerKif - The KIF of the current card's issuer key.
      issuerKvc - The KVC of the current card's issuer key.
      Returns:
      The current instance.
      Throws:
      UnsupportedOperationException - If the Change Key command is not available for this card.
      IllegalArgumentException - If the provided key index is out of range.
      IllegalStateException - If the command is executed while a secure session is open.
      Since:
      1.6.0