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

Interface TransactionManager<T extends TransactionManager<T>>

Type Parameters:
T - The type of the lowest level child object.
All Known Subinterfaces:
FreeTransactionManager, SecureExtendedModeTransactionManager, SecurePkiModeTransactionManager, SecureRegularModeTransactionManager, SecureSymmetricCryptoTransactionManager<T>, SecureTransactionManager<T>
public interface TransactionManager<T extends TransactionManager<T>>
Contains operations common to all card transactions.

To exchange data with the card, it is first necessary to prepare the commands to be transmitted to the card and then to process the prepared commands via the processCommands(ChannelControl) method.

The card commands preparation step makes it possible to group commands together in order to minimize network data exchanges (especially useful in a distributed architecture).

The CalypsoCard object registered with the manager is updated during the transaction after each data exchange with the card.

For all "prepare" type commands, unless otherwise specified, here are the ranges of values checked for the various parameters:

  • SFI: [0..30] (0 indicates the current EF)
  • Record number: [1..250]
  • Counter number: [1..83]
  • Counter value: [0..16777215]
  • Offset: [0..249] or [0..32767] for binary files (0 indicates the first byte)
  • Input data length: [1..250] or [1..32767] for binary files
Since:
2.0.0

  • Method Summary

    Modifier and Type
    Method
    Description
    List<byte[]>
    getTransactionAuditData()
    Returns the audit data of the transaction containing all APDU exchanges with the card and the cryptographic module.
    T
    prepareAppendRecord(byte sfi, byte[] recordData)
    Schedules the execution of an "Append Record" command to adds the data provided in the indicated "cyclic" file.
    T
    prepareChangePin(byte[] newPin)
    Schedules the execution of a "Change PIN" command to replace the current PIN with the new value provided.
    T
    prepareCheckPinStatus()
    Schedules the execution of a "Verify Pin" command without PIN presentation in order to get the attempt counter.
    T
    prepareDecreaseCounter(byte sfi, int counterNumber, int decValue)
    Schedules the execution of a "Decrease" command to decrease the target counter.
    T
    prepareDecreaseCounters(byte sfi, Map<Integer,Integer> counterNumberToDecValueMap)
    Schedules the execution of a "Decrease Multiple" command or multiple "Decrease" commands to decrease multiple target counters at the same time.
    T
    prepareGenerateAsymmetricKeyPair()
    Schedules the execution of a "Generate Asymmetric Key Pair" command.
    T
    prepareGetData(GetDataTag tag)
    Schedules the execution of one or more "Get Data" command to retrieve the data indicated by the provided data type.
    T
    prepareIncreaseCounter(byte sfi, int counterNumber, int incValue)
    Schedules the execution of an "Increase" command to increase the target counter.
    T
    prepareIncreaseCounters(byte sfi, Map<Integer,Integer> counterNumberToIncValueMap)
    Schedules the execution of an "Increase Multiple" command or multiple "Increase" commands to increase multiple target counters at the same time.
    T
    preparePutData(PutDataTag tag, byte[] data)
    Schedules the execution of one or more "Put Data" command to inject the provided data associated with the provided data type.
    T
    prepareReadBinary(byte sfi, int offset, int nbBytesToRead)
    Schedules the execution of one or multiple "Read Binary" commands to read all or part of the indicated "binary" EF.
    T
    prepareReadCounter(byte sfi, int nbCountersToRead)
    Schedules the execution of a "Read Records" command to reads a record of the indicated EF, which should be a "counter" file.
    T
    prepareReadRecord(byte sfi, int recordNumber)
    Schedules the execution of a "Read Records" command to read a single record from the indicated EF.
    T
    prepareReadRecords(byte sfi, int fromRecordNumber, int toRecordNumber, int recordSize)
    Schedules the execution of a "Read Records" command to read one or more records from the indicated EF.
    T
    prepareReadRecordsPartially(byte sfi, int fromRecordNumber, int toRecordNumber, int offset, int nbBytesToRead)
    Schedules the execution of one or multiple "Read Record Multiple" commands to read all or parts of multiple records of the indicated EF.
    T
    prepareSearchRecords(SearchCommandData data)
    Schedules the execution of a "Search Record Multiple" command to search data in the records of the indicated EF, from a given record to the last record of the file.
    T
    prepareSelectFile(short lid)
    Schedules the execution of a "Select File" command to select an EF by its LID in the current DF.
    T
    prepareSelectFile(SelectFileControl selectFileControl)
    Schedules the execution of a "Select File" command using a navigation selectFileControl defined by the ISO standard.
    T
    prepareSetCounter(byte sfi, int counterNumber, int newValue)
    Schedules the execution of an "Increase" or "Decrease" command to set the value of the target counter.
    T
    prepareSvReadAllLogs()
    Schedules the execution of "Read Records" commands to read all SV logs.
    T
    prepareUpdateBinary(byte sfi, int offset, byte[] data)
    Schedules the execution of one or multiple "Update Binary" command to replace the indicated data of a "binary" file with the new data given from the indicated offset.
    T
    prepareUpdateRecord(byte sfi, int recordNumber, byte[] recordData)
    Schedules the execution of an "Update Record" command to overwrites the target file's record contents with the provided data.
    T
    prepareVerifyPin(byte[] pin)
    Schedules the execution of a "Verify PIN" command in order to authenticate the cardholder and/or unlock access to certain card files.
    T
    prepareWriteBinary(byte sfi, int offset, byte[] data)
    Schedules the execution of one or multiple "Write Binary" commands to write over the indicated data of a "binary" file.
    T
    prepareWriteRecord(byte sfi, int recordNumber, byte[] recordData)
    Schedules the execution of a "Write Record" command to updates the target file's record contents with the result of a binary OR between the existing data and the provided data.
    T
    processCommands(ChannelControl channelControl)
    Processes all previously prepared commands and closes the physical channel if requested.

  • Method Details

    • prepareSelectFile

      T prepareSelectFile(short lid)
      Schedules the execution of a "Select File" command to select an EF by its LID in the current DF.

      Data will be available in CalypsoCard using the CalypsoCard.getFileBySfi(byte)/CalypsoCard.getFileByLid(short) and ElementaryFile.getHeader() methods.

      Caution: the command will fail if the selected file is not an EF.

      Parameters:
      lid - The LID of the EF to select.
      Returns:
      The current instance.
      Since:
      1.1.0

    • prepareSelectFile

      T prepareSelectFile(SelectFileControl selectFileControl)
      Schedules the execution of a "Select File" command using a navigation selectFileControl defined by the ISO standard.

      Data will be available in CalypsoCard using the ElementaryFile.getHeader() method.

      Parameters:
      selectFileControl - A SelectFileControl enum entry.
      Returns:
      The current instance.
      Throws:
      IllegalArgumentException - If selectFileControl is null.
      Since:
      1.0.0

    • prepareGetData

      T prepareGetData(GetDataTag tag)
      Schedules the execution of one or more "Get Data" command to retrieve the data indicated by the provided data type.

      Data will be available in CalypsoCard using the ElementaryFile.getHeader() or CalypsoCard.getDirectoryHeader() methods, depending on the provided tag.

      Parameters:
      tag - The data type.
      Returns:
      The current instance.
      Throws:
      UnsupportedOperationException - If the Get Data command with the provided tag is not supported.
      IllegalArgumentException - If tag is null.
      Since:
      1.0.0

    • preparePutData

      T preparePutData(PutDataTag tag, byte[] data)
      Schedules the execution of one or more "Put Data" command to inject the provided data associated with the provided data type.
      Parameters:
      tag - The data type.
      data - The data to inject.
      Returns:
      The current instance.
      Throws:
      UnsupportedOperationException - If the Put Data command with the provided tag is not supported.
      IllegalArgumentException - If tag is null or data is empty.
      Since:
      2.1.0

    • prepareReadRecord

      T prepareReadRecord(byte sfi, int recordNumber)
      Schedules the execution of a "Read Records" command to read a single record from the indicated EF.

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

      Depending on whether we are inside a secure session, there are two types of behavior following this command:

      • Outside a secure session (best effort mode): the following "process" command will not fail whatever the existence of the targeted file or record (the CalypsoCard object may not be filled).
      • Inside a secure session in contactless mode (strict mode): the following "process" command will fail if the targeted file or record does not exist (the CalypsoCard object is always filled or an exception is raised when the reading failed).

      This method should not be used inside a secure session in contact mode because additional exchanges with the card will be operated and will corrupt the security of the session. Instead, use the method prepareReadRecords(byte, int, int, int) for this case and provide valid parameters.

      Parameters:
      sfi - The SFI of the EF to read.
      recordNumber - The record to read.
      Returns:
      The current instance.
      Throws:
      IllegalArgumentException - If one of the provided arguments is out of range.
      IllegalStateException - If this method is called inside a secure session in contact mode.
      Since:
      1.1.0

    • prepareReadRecords

      T prepareReadRecords(byte sfi, int fromRecordNumber, int toRecordNumber, int recordSize)
      Schedules the execution of a "Read Records" command to read one or more records from the indicated EF.

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

      Depending on whether we are inside a secure session, there are two types of behavior following this command:

      • Outside a secure session (best effort mode): the following "process" command will not fail whatever the existence of the targeted file or record (the CalypsoCard object may not be filled).
      • Inside a secure session (strict mode): the following "process" command will fail if the targeted file or record does not exist (the CalypsoCard object is always filled or an exception is raised when the reading failed).
        Invalid parameters could lead to additional exchanges with the card and thus corrupt the security of the session.
      Parameters:
      sfi - The SFI of the EF.
      fromRecordNumber - The number of the first record to read.
      toRecordNumber - The number of the last record to read.
      recordSize - The record length.
      Returns:
      The current instance.
      Throws:
      IllegalArgumentException - If one of the provided argument is out of range.
      Since:
      1.1.0

    • prepareReadRecordsPartially

      T prepareReadRecordsPartially(byte sfi, int fromRecordNumber, int toRecordNumber, int offset, int nbBytesToRead)
      Schedules the execution of one or multiple "Read Record Multiple" commands to read all or parts of multiple records of the indicated EF.

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

      Depending on whether we are inside a secure session, there are two types of behavior following this command:

      • Outside a secure session (best effort mode): the following "process" command will not fail whatever the existence of the targeted file or the validity of the offset and number of bytes to read (the CalypsoCard object may not be filled).
      • Inside a secure session (strict mode): the following "process" command will fail if the targeted file does not exist or if the offset and number of bytes to read are not valid (the CalypsoCard object is always filled or an exception is raised when the reading failed).
        Invalid parameters could lead to additional exchanges with the card and thus corrupt the security of the session.
      Parameters:
      sfi - The SFI of the EF.
      fromRecordNumber - The number of the first record to read.
      toRecordNumber - The number of the last record to read.
      offset - The offset in the records where to start reading (0 indicates the first byte).
      nbBytesToRead - The number of bytes to read from each record.
      Returns:
      The current instance.
      Throws:
      UnsupportedOperationException - If this command is not supported by this card.
      IllegalArgumentException - If one of the provided argument is out of range.
      Since:
      1.1.0

    • prepareReadBinary

      T prepareReadBinary(byte sfi, int offset, int nbBytesToRead)
      Schedules the execution of one or multiple "Read Binary" commands to read all or part of the indicated "binary" EF.

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

      Depending on whether we are inside a secure session, there are two types of behavior following this command:

      • Outside a secure session (best effort mode): the following "process" command will not fail whatever the existence of the targeted file or the validity of the offset and number of bytes to read (the CalypsoCard object may not be filled).
      • Inside a secure session (strict mode): the following "process" command will fail if the targeted file does not exist or if the offset and number of bytes to read are not valid (the CalypsoCard object is always filled or an exception is raised when the reading failed).
        Invalid parameters could lead to additional exchanges with the card and thus corrupt the security of the session.
      Parameters:
      sfi - The SFI of the EF.
      offset - The offset (0 indicates the first byte).
      nbBytesToRead - The number of bytes to read.
      Returns:
      The current instance.
      Throws:
      UnsupportedOperationException - If this command is not supported by this card.
      IllegalArgumentException - If one of the provided argument is out of range.
      Since:
      1.1.0

    • prepareReadCounter

      T prepareReadCounter(byte sfi, int nbCountersToRead)
      Schedules the execution of a "Read Records" command to reads a record of the indicated EF, which should be a "counter" file.

      The record will be read up to the counter location indicated in parameter.
      Thus, all previous counters will also be read.

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

      Depending on whether we are inside a secure session, there are two types of behavior following this command:

      • Outside a secure session (best effort mode): the following "process" command will not fail whatever the existence of the targeted file or counter (the CalypsoCard object may not be filled).
      • Inside a secure session (strict mode): the following "process" command will fail if the targeted file or counter does not exist (the CalypsoCard object is always filled or an exception is raised when the reading failed).
        Invalid parameters could lead to additional exchanges with the card and thus corrupt the security of the session.
      Parameters:
      sfi - The SFI of the EF.
      nbCountersToRead - The number of counters to read.
      Returns:
      The current instance.
      Throws:
      IllegalArgumentException - If one of the provided argument is out of range.
      Since:
      1.1.0

    • prepareSearchRecords

      T prepareSearchRecords(SearchCommandData data)
      Schedules the execution of a "Search Record Multiple" command to search data in the records of the indicated EF, from a given record to the last record of the file. It will return the list of record numbers containing these data, and if requested it will read the first record content.

      The command is only possible with a "linear", "cyclic", Counters or Simulated "counter" EF.

      The command searches if the given data are present in the records of the file. During the search, an optional mask is applied. The mask allows to specify precisely the bits to be taken into account in the comparison.

      See SearchCommandData class for a description of the parameters.

      Once this command is processed, the result is available in the provided input/output SearchCommandData object, and the content of the first matching record in CalypsoCard if requested.

      Depending on whether we are inside a secure session, there are two types of behavior following this command:

      • Outside a secure session (best effort mode): the following "process" command will not fail whatever the existence of the targeted file or the validity of the record number and offset (the SearchCommandData and CalypsoCard objects may not be updated).
      • Inside a secure session (strict mode): the following "process" command will fail if the targeted file does not exist or if the record number and the offset are not valid (the SearchCommandData and CalypsoCard objects are always filled or an exception is raised when the reading failed).
      Parameters:
      data - The input/output data containing the parameters of the command.
      Returns:
      The current instance.
      Throws:
      UnsupportedOperationException - If the "Search Record Multiple" command is not available for this card.
      IllegalArgumentException - If the input data is inconsistent.
      Since:
      1.1.0
      See Also:

    • prepareCheckPinStatus

      T prepareCheckPinStatus()
      Schedules the execution of a "Verify Pin" command without PIN presentation in order to get the attempt counter.

      The PIN status will be available in CalypsoCard using the CalypsoCard.getPinAttemptRemaining() and CalypsoCard.isPinBlocked() methods.

      Returns:
      The current instance.
      Throws:
      UnsupportedOperationException - If the PIN feature is not available for this card.
      Since:
      1.0.0

    • prepareAppendRecord

      T prepareAppendRecord(byte sfi, byte[] recordData)
      Schedules the execution of an "Append Record" command to adds the data provided in the indicated "cyclic" file.

      A new record is added, the oldest record is deleted.

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

      Parameters:
      sfi - The sfi to select.
      recordData - The new record data to write.
      Returns:
      The current instance.
      Throws:
      IllegalArgumentException - If one of the provided argument is out of range.
      SessionBufferOverflowException - If the command will overflow the modifications buffer size and the multiple session is not allowed.
      Since:
      1.0.0

    • prepareUpdateRecord

      T prepareUpdateRecord(byte sfi, int recordNumber, byte[] recordData)
      Schedules the execution of an "Update Record" command to overwrites the target file's record contents with the provided data.

      If the input data is shorter than the record size, only the first bytes will be overwritten.

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

      Parameters:
      sfi - The sfi to select.
      recordNumber - The record to update.
      recordData - The new record data. If length < RecSize, bytes beyond length are. left unchanged.
      Returns:
      The current instance.
      Throws:
      IllegalArgumentException - If one of the provided argument is out of range.
      SessionBufferOverflowException - If the command will overflow the modifications buffer size and the multiple session is not allowed.
      Since:
      1.0.0

    • prepareWriteRecord

      T prepareWriteRecord(byte sfi, int recordNumber, byte[] recordData)
      Schedules the execution of a "Write Record" command to updates the target file's record contents with the result of a binary OR between the existing data and the provided data.

      If the input data is shorter than the record size, only the first bytes will be overwritten.

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

      Parameters:
      sfi - The sfi to select.
      recordNumber - The record to write.
      recordData - The data to overwrite in the record. If length < RecSize, bytes. beyond length are left unchanged.
      Returns:
      The current instance.
      Throws:
      IllegalArgumentException - If one of the provided argument is out of range.
      SessionBufferOverflowException - If the command will overflow the modifications buffer size and the multiple session is not allowed.
      Since:
      1.0.0

    • prepareUpdateBinary

      T prepareUpdateBinary(byte sfi, int offset, byte[] data)
      Schedules the execution of one or multiple "Update Binary" command to replace the indicated data of a "binary" file with the new data given from the indicated offset.

      The data of the file before the offset and after the data given are left unchanged.

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

      Parameters:
      sfi - The SFI of the EF to select.
      offset - The offset (0 indicates the first byte).
      data - The new data.
      Returns:
      The current instance.
      Throws:
      UnsupportedOperationException - If this command is not supported by this card.
      IllegalArgumentException - If one of the provided argument is out of range.
      SessionBufferOverflowException - If the command will overflow the modifications buffer size and the multiple session is not allowed.
      Since:
      1.1.0

    • prepareWriteBinary

      T prepareWriteBinary(byte sfi, int offset, byte[] data)
      Schedules the execution of one or multiple "Write Binary" commands to write over the indicated data of a "binary" file. The new data will be the result of a binary OR operation between the existing data and the data given in the command from the indicated offset.

      The data of the file before the offset and after the data given are left unchanged.

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

      Parameters:
      sfi - The SFI of the EF to select.
      offset - The offset (0 indicates the first byte).
      data - The data to write over the existing data.
      Returns:
      The current instance.
      Throws:
      UnsupportedOperationException - If this command is not supported by this card.
      IllegalArgumentException - If one of the provided argument is out of range.
      SessionBufferOverflowException - If the command will overflow the modifications buffer size and the multiple session is not allowed.
      Since:
      1.1.0

    • prepareIncreaseCounter

      T prepareIncreaseCounter(byte sfi, int counterNumber, int incValue)
      Schedules the execution of an "Increase" command to increase the target counter.

      If several counters of the same file have to be incremented at the same time of the transaction, it is recommended to use the method prepareIncreaseCounters(byte, Map) for optimization reasons.

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

      Parameters:
      sfi - SFI of the EF to select.
      counterNumber - The number of the counter (must be zero in case of a simulated counter).
      incValue - Value to add to the counter (defined as a positive int <= 16777215 [FFFFFFh])
      Returns:
      The current instance.
      Throws:
      IllegalArgumentException - If one of the provided argument is out of range.
      SessionBufferOverflowException - If the command will overflow the modifications buffer size and the multiple session is not allowed.
      Since:
      1.0.0

    • prepareIncreaseCounters

      T prepareIncreaseCounters(byte sfi, Map<Integer,Integer> counterNumberToIncValueMap)
      Schedules the execution of an "Increase Multiple" command or multiple "Increase" commands to increase multiple target counters at the same time.

      The decision to execute one or the other command is made according to the type of card.

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

      Parameters:
      sfi - SFI of the EF to select.
      counterNumberToIncValueMap - The map containing the counter numbers to be incremented and their associated increment values.
      Returns:
      The current instance.
      Throws:
      IllegalArgumentException - If one of the provided argument is out of range or if the map is null or empty.
      SessionBufferOverflowException - If the command will overflow the modifications buffer size and the multiple session is not allowed.
      Since:
      1.1.0

    • prepareDecreaseCounter

      T prepareDecreaseCounter(byte sfi, int counterNumber, int decValue)
      Schedules the execution of a "Decrease" command to decrease the target counter.

      If several counters of the same file have to be decremented at the same time of the transaction, it is recommended to use the method prepareDecreaseCounters(byte, Map) for optimization reasons.

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

      Parameters:
      sfi - SFI of the EF to select.
      counterNumber - The number of the counter (must be zero in case of a simulated counter).
      decValue - Value to subtract to the counter (defined as a positive int <= 16777215 [FFFFFFh])
      Returns:
      The current instance.
      Throws:
      IllegalArgumentException - If one of the provided argument is out of range.
      SessionBufferOverflowException - If the command will overflow the modifications buffer size and the multiple session is not allowed.
      Since:
      1.0.0

    • prepareDecreaseCounters

      T prepareDecreaseCounters(byte sfi, Map<Integer,Integer> counterNumberToDecValueMap)
      Schedules the execution of a "Decrease Multiple" command or multiple "Decrease" commands to decrease multiple target counters at the same time.

      The decision to execute one or the other command is made according to the type of card.

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

      Parameters:
      sfi - SFI of the EF to select.
      counterNumberToDecValueMap - The map containing the counter numbers to be decremented and their associated decrement values.
      Returns:
      The current instance.
      Throws:
      IllegalArgumentException - If one of the provided argument is out of range or if the map is null or empty.
      SessionBufferOverflowException - If the command will overflow the modifications buffer size and the multiple session is not allowed.
      Since:
      1.1.0

    • prepareSetCounter

      T prepareSetCounter(byte sfi, int counterNumber, int newValue)
      Schedules the execution of an "Increase" or "Decrease" command to set the value of the target counter.

      The operation (Increase or Decrease) is selected according to whether the difference between the current value and the desired value is negative (Increase) or positive (Decrease).

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

      Note: it is assumed here that:

      • the counter value has been read before,
      • the type of session (and associated access rights) is consistent with the requested operation: reload session if the counter is to be incremented, debit if it is to be decremented.
        No control is performed on this point by this method; the closing of the session will determine the success of the operation..
      Parameters:
      counterNumber - >= 1: Counters file, number of the counter. 0: Simulated "counter" file.
      sfi - SFI of the EF to select.
      newValue - The desired value for the counter (defined as a positive int <= 16777215 [FFFFFFh])
      Returns:
      The current instance.
      Throws:
      IllegalArgumentException - If one of the provided argument is out of range.
      IllegalStateException - If the current counter value is unknown.
      SessionBufferOverflowException - If the command will overflow the modifications buffer size and the multiple session is not allowed.
      Since:
      1.0.0

    • prepareSvReadAllLogs

      T prepareSvReadAllLogs()
      Schedules the execution of "Read Records" commands to read all SV logs.

      Note: this method requires that the selected application is of type Store Value (file structure 20h).

      The SV transaction logs are contained in two files with fixed identifiers:

      • The file whose SFI is 14h contains 1 record containing the unique reload log.
      • The file whose SFI is 15h contains 3 records containing the last three debit logs.

      Data will be available in CalypsoCard in raw format using the dedicated file and data management methods or in the form of dedicated objects using the CalypsoCard.getSvLoadLogRecord() and CalypsoCard.getSvDebitLogAllRecords() methods.

      Returns:
      The current instance.
      Throws:
      UnsupportedOperationException - If the SV feature is not available for this card.
      Since:
      1.0.0

    • prepareVerifyPin

      T prepareVerifyPin(byte[] pin)
      Schedules the execution of a "Verify PIN" command in order to authenticate the cardholder and/or unlock access to certain card files.

      This command can be performed both in and out of a secure session. The PIN code can be transmitted in plain text or encrypted according to the parameter set in SymmetricCryptoSecuritySetting.

      The PIN status will be available in CalypsoCard using the CalypsoCard.getPinAttemptRemaining() and CalypsoCard.isPinBlocked() methods.

      Parameters:
      pin - The PIN code value (4-byte long byte array).
      Returns:
      The current instance.
      Throws:
      UnsupportedOperationException - If the PIN feature is not available for this card.
      IllegalArgumentException - If the provided argument is out of range.
      Since:
      1.6.0

    • prepareChangePin

      T prepareChangePin(byte[] newPin)
      Schedules the execution of a "Change PIN" command to replace the current PIN with the new value provided.

      This command can be performed only out of a secure session. The new PIN code can be transmitted in plain text or encrypted according to the parameter set in SymmetricCryptoSecuritySetting.

      When the PIN is transmitted plain, this command must be preceded by a successful Verify PIN command (see prepareVerifyPin(byte[])).

      The PIN status will be available in CalypsoCard using the CalypsoCard.getPinAttemptRemaining() and CalypsoCard.isPinBlocked() methods.

      Parameters:
      newPin - The new PIN code value (4-byte long byte array).
      Returns:
      The current instance.
      Throws:
      UnsupportedOperationException - If the PIN feature is not available for this card.
      IllegalArgumentException - If the provided argument is out of range.
      IllegalStateException - If the command is executed while a secure session is open.
      Since:
      1.6.0

    • prepareGenerateAsymmetricKeyPair

      T prepareGenerateAsymmetricKeyPair()
      Schedules the execution of a "Generate Asymmetric Key Pair" command.

      After the execution, the generated key pair will be stored internally into the card. The public part can be retrieved via prepareGetData(GetDataTag).

      Returns:
      The current instance.
      Since:
      2.1.0

    • processCommands

      T processCommands(ChannelControl channelControl)
      Processes all previously prepared commands and closes the physical channel if requested.

      All APDUs corresponding to the prepared commands are sent to the card, their responses are retrieved and used to update the CalypsoCard associated with the transaction.

      For write commands, the CalypsoCard is updated only when the command is successful.

      The process is interrupted at the first failed command.

      Parameters:
      channelControl - Policy for managing the physical channel after executing commands to the card.
      Returns:
      The current instance.
      Throws:
      ReaderIOException - If a communication error with the card reader or the cryptographic module reader occurs.
      CardIOException - If a communication error with the card occurs.
      CryptoIOException - If a communication error with the cryptographic module occurs.
      CryptoException - If an error with the cryptographic module occurs.
      UnexpectedCommandStatusException - If a command returns an unexpected status.
      InconsistentDataException - If inconsistent data have been detected.
      UnauthorizedKeyException - If the card requires an unauthorized session key.
      CardSignatureNotVerifiableException - If a secure session is open and multiple session mode is enabled and an intermediate session is correctly closed but the cryptographic module is no longer available to verify the card MAC.
      InvalidCardSignatureException - If the card signature is incorrect. In the case of a card transaction secured by "symmetrical" cryptography (e.g. SAM), this indicates that the card has correctly closed the secure session, but the card session is not authentic because the MAC of the card is incorrect.
      SelectFileException - If a "Select File" prepared card command indicated that the file was not found.
      Since:
      1.6.0

    • getTransactionAuditData

      List<byte[]> getTransactionAuditData()
      Returns the audit data of the transaction containing all APDU exchanges with the card and the cryptographic module.
      Returns:
      An empty list if there is no audit data.
      Since:
      1.2.0