Package org.calypsonet.terminal.calypso.transaction

Interface CardTransactionManager

  • All Superinterfaces:
    CommonTransactionManager<CardTransactionManager,​CardSecuritySetting>
    public interface CardTransactionManager
extends CommonTransactionManager<CardTransactionManager,​CardSecuritySetting>
    Service providing the high-level API to manage transactions with a Calypso card.

    Depending on the type of operations required, the presence of a SAM may be necessary.

    The CalypsoCard object provided to the build is kept and updated at each step of using the service. It is the main container of the data handled during the transaction and acts as a card image.

    There are two main steps in using the methods of this service:

    • A command preparation step during which the application invokes prefixed "prepare" methods that will add to an internal list of commands to be executed by the card. The incoming data to the card are placed in CalypsoCard.
    • A processing step corresponding to the prefixed "process" methods, which will carry out the communications with the card and if necessary the SAM. The outgoing data from the card are placed in CalypsoCard.

    Technical or data errors, security conditions, etc. are reported as exceptions.

    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:
    1.0.0

    • Method Detail

      • getCardReader

        @Deprecated
org.calypsonet.terminal.reader.CardReader getCardReader()
        Deprecated.
        Useless accessor (will be soon removed).
        Gets the reader used to communicate with the target card on which the transaction is performed.
        Returns:
        A not null reference.
        Since:
        1.0.0

      • getCardSecuritySetting

        @Deprecated
CardSecuritySetting getCardSecuritySetting()
        Deprecated.
        Use CommonTransactionManager.getSecuritySetting() instead. (will be soon removed)
        Gets the settings defining the security parameters of the transaction.
        Returns:
        Null if the transaction does not use security settings.
        Since:
        1.0.0

      • prepareSelectFile

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

        Once this command is processed, the result is available in CalypsoCard through the ElementaryFile.getHeader() methods.

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

      • prepareGetData

        CardTransactionManager prepareGetData​(GetDataTag tag)
        Adds a command APDU to retrieve the data indicated by the provided tag.

        The data returned by the command is used to update the current CalypsoCard object.

        Parameters:
        tag - The tag to use.
        Returns:
        The object instance.
        Throws:
        java.lang.UnsupportedOperationException - If the Get Data command with the provided tag is not supported.
        java.lang.IllegalArgumentException - If tag is null.
        Since:
        1.0.0

      • prepareReadRecordFile

        @Deprecated
CardTransactionManager prepareReadRecordFile​(byte sfi,
                                             int recordNumber)
        Deprecated.
        Use prepareReadRecord(byte, int) method instead. (will be soon removed)
        Schedules the execution of a Read Records command to read a single record from the indicated EF.

        Once this command is processed, the result is available in CalypsoCard.

        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 prepareReadRecordFile(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:
        java.lang.IllegalArgumentException - If one of the provided arguments is out of range.
        java.lang.IllegalStateException - If this method is invoked inside a secure session in contact mode.
        Since:
        1.0.0

      • prepareReadRecordFile

        @Deprecated
CardTransactionManager prepareReadRecordFile​(byte sfi,
                                             int firstRecordNumber,
                                             int numberOfRecords,
                                             int recordSize)
        Deprecated.
        Use prepareReadRecords(byte, int, int, int) method instead. (will be soon removed)
        Schedules the execution of a Read Records command to read one or more records from the indicated EF.

        Once this command is processed, the result is available in CalypsoCard.

        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.
        firstRecordNumber - The record to read (or first record to read in case of several records)
        numberOfRecords - The number of records expected.
        recordSize - The record length.
        Returns:
        The current instance.
        Throws:
        java.lang.IllegalArgumentException - If one of the provided argument is out of range.
        Since:
        1.0.0

      • prepareReadCounterFile

        @Deprecated
CardTransactionManager prepareReadCounterFile​(byte sfi,
                                              int countersNumber)
        Deprecated.
        Use prepareReadCounter(byte, int) method instead. (will be soon removed)
        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.

        Once this command is processed, the result is available in CalypsoCard.

        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.
        countersNumber - The number of the last counter to be read.
        Returns:
        The current instance.
        Throws:
        java.lang.IllegalArgumentException - If one of the provided argument is out of range.
        Since:
        1.0.0

      • prepareReadRecord

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

        Once this command is processed, the result is available in CalypsoCard.

        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 prepareReadRecordFile(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:
        java.lang.IllegalArgumentException - If one of the provided arguments is out of range.
        java.lang.IllegalStateException - If this method is invoked inside a secure session in contact mode.
        Since:
        1.1.0

      • prepareReadRecords

        CardTransactionManager 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.

        Once this command is processed, the result is available in CalypsoCard.

        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:
        java.lang.IllegalArgumentException - If one of the provided argument is out of range.
        Since:
        1.1.0

      • prepareReadRecordsPartially

        CardTransactionManager 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.

        Once this command is processed, the result is available in CalypsoCard.

        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:
        java.lang.UnsupportedOperationException - If this command is not supported by this card.
        java.lang.IllegalArgumentException - If one of the provided argument is out of range.
        Since:
        1.1.0

      • prepareReadBinary

        CardTransactionManager 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.

        Once this command is processed, the result is available in CalypsoCard.

        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:
        java.lang.UnsupportedOperationException - If this command is not supported by this card.
        java.lang.IllegalArgumentException - If one of the provided argument is out of range.
        Since:
        1.1.0

      • prepareReadCounter

        CardTransactionManager 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.

        Once this command is processed, the result is available in CalypsoCard.

        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:
        java.lang.IllegalArgumentException - If one of the provided argument is out of range.
        Since:
        1.1.0

      • prepareSearchRecords

        CardTransactionManager 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:
        java.lang.UnsupportedOperationException - If the "Search Record Multiple" command is not available for this card.
        java.lang.IllegalArgumentException - If the input data is inconsistent.
        Since:
        1.1.0
        See Also:
        SearchCommandData

      • prepareCheckPinStatus

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

        The PIN status will be made available in CalypsoCard after the execution of process command.
        Adds it to the list of commands to be sent with the next process command.

        See CalypsoCard.isPinBlocked() and CalypsoCard.getPinAttemptRemaining() methods.

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

      • prepareAppendRecord

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

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

        Note: CalypsoCard is filled with the provided input data.

        Parameters:
        sfi - The sfi to select.
        recordData - The new record data to write.
        Returns:
        The current instance.
        Throws:
        java.lang.IllegalArgumentException - If one of the provided argument is out of range.
        Since:
        1.0.0

      • prepareUpdateRecord

        CardTransactionManager prepareUpdateRecord​(byte sfi,
                                           int recordNumber,
                                           byte[] recordData)
        Schedules the execution of a 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.

        Note: CalypsoCard is filled with the provided input data.

        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:
        java.lang.IllegalArgumentException - If one of the provided argument is out of range.
        Since:
        1.0.0

      • prepareWriteRecord

        CardTransactionManager 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.

        Note: CalypsoCard is filled with the provided input data.

        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:
        java.lang.IllegalArgumentException - If one of the provided argument is out of range.
        Since:
        1.0.0

      • prepareUpdateBinary

        CardTransactionManager prepareUpdateBinary​(byte sfi,
                                           int offset,
                                           byte[] data)
        Schedules the execution of a 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.

        Note: CalypsoCard is filled with the provided input data.

        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:
        java.lang.UnsupportedOperationException - If this command is not supported by this card.
        java.lang.IllegalArgumentException - If one of the provided argument is out of range.
        Since:
        1.1.0

      • prepareWriteBinary

        CardTransactionManager prepareWriteBinary​(byte sfi,
                                          int offset,
                                          byte[] data)
        Schedules the execution of a Write Binary command 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.

        Note: CalypsoCard is computed with the provided input data.

        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:
        java.lang.UnsupportedOperationException - If this command is not supported by this card.
        java.lang.IllegalArgumentException - If one of the provided argument is out of range.
        Since:
        1.1.0

      • prepareIncreaseCounter

        CardTransactionManager prepareIncreaseCounter​(byte sfi,
                                              int counterNumber,
                                              int incValue)
        Schedules the execution of a Increase command to increase the target counter.

        Note 1: CalypsoCard is updated with the provided input data.

        Note 2: in the case where this method is invoked before the invocation of processClosing(), the counter must have been read previously otherwise an IllegalStateException will be raised during the execution of processClosing().

        Note 3: 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.

        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:
        java.lang.IllegalArgumentException - If one of the provided argument is out of range.
        Since:
        1.0.0

      • prepareIncreaseCounters

        CardTransactionManager prepareIncreaseCounters​(byte sfi,
                                               java.util.Map<java.lang.Integer,​java.lang.Integer> counterNumberToIncValueMap)
        Schedules the execution of a 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.

        Note 1: CalypsoCard is updated with the provided input data.

        Note 2: in the case where this method is invoked before the invocation of processClosing(), the counter must have been read previously otherwise an IllegalStateException will be raised during the execution of processClosing().

        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:
        java.lang.IllegalArgumentException - If one of the provided argument is out of range or if the map is null or empty.
        Since:
        1.1.0

      • prepareDecreaseCounter

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

        Note 1: CalypsoCard is updated with the provided input data.

        Note 2: in the case where this method is invoked before the invocation of processClosing(), the counter must have been read previously otherwise an IllegalStateException will be raised during the execution of processClosing().

        Note 3: 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.

        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:
        java.lang.IllegalArgumentException - If one of the provided argument is out of range.
        Since:
        1.0.0

      • prepareDecreaseCounters

        CardTransactionManager prepareDecreaseCounters​(byte sfi,
                                               java.util.Map<java.lang.Integer,​java.lang.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.

        Note 1: CalypsoCard is updated with the provided input data.

        Note 2: in the case where this method is invoked before the invocation of processClosing(), the counter must have been read previously otherwise an IllegalStateException will be raised during the execution of processClosing().

        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:
        java.lang.IllegalArgumentException - If one of the provided argument is out of range or if the map is null or empty.
        Since:
        1.1.0

      • prepareSetCounter

        CardTransactionManager prepareSetCounter​(byte sfi,
                                         int counterNumber,
                                         int newValue)
        Schedules the execution of a command to set the value of the target counter.

        It builds an Increase or Decrease command and add it to the list of commands to be sent with the next process command in order to set the target counter to the specified value.
        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).

        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:
        java.lang.IllegalArgumentException - If one of the provided argument is out of range.
        java.lang.IllegalStateException - If the current counter value is unknown.
        Since:
        1.0.0

      • prepareSvReload

        CardTransactionManager 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.

        Note #1: a communication with the SAM is done here.

        Note #2: 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:
        java.lang.IllegalArgumentException - If one of the provided argument is out of range.
        java.lang.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.
        Since:
        1.0.0

      • prepareSvReload

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

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

        Note #2: a communication with the SAM is done here.

        Note #3: 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:
        java.lang.IllegalArgumentException - If the provided argument is out of range.
        java.lang.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.
        Since:
        1.0.0

      • prepareSvDebit

        CardTransactionManager 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.

        Note #1: a communication with the SAM is done here.

        Note #2: the key used is the reload 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:
        java.lang.IllegalArgumentException - If one of the provided argument is out of range.
        java.lang.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.
        Since:
        1.0.0

      • prepareSvDebit

        CardTransactionManager 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.

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

        Note #2: a communication with the SAM is done here.

        Note #3: the key used is the reload key.The information fields such as date and time are set to 0. The extraInfo field propagated in Logs are automatically generated with the type of transaction and amount.

        Note #4: operations that would result in a negative balance are forbidden (SV Exception raised).

        Note #5: 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:
        java.lang.IllegalArgumentException - If one of the provided argument is out of range.
        java.lang.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.
        Since:
        1.0.0

      • prepareInvalidate

        CardTransactionManager prepareInvalidate()
        Schedules the execution of a 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).

        Returns:
        The current instance.
        Throws:
        java.lang.IllegalStateException - If the card is already invalidated.
        Since:
        1.0.0

      • prepareRehabilitate

        CardTransactionManager 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).

        Returns:
        The current instance.
        Throws:
        java.lang.IllegalStateException - If the card is not invalidated.
        Since:
        1.0.0

      • prepareReleaseCardChannel

        CardTransactionManager prepareReleaseCardChannel()
        Requests the closing of the card channel.

        If this command is called before a "process" command (except for processOpening) then the last transmission to the card will be associated with the indication CLOSE_AFTER in order to close the card channel.

        Note: this command must imperatively be called at the end of any transaction, whether it ended normally or not.

        In case the transaction was interrupted (exception), an additional invocation of processCardCommands must be made to effectively close the channel.

        Returns:
        The current instance.
        Since:
        1.0.0

      • prepareEarlyMutualAuthentication

        CardTransactionManager prepareEarlyMutualAuthentication()
        Requests to mutually authenticate the card and the terminal before the secure session is closed.

        This ensures the authenticity of the card before sending sensitive commands.

        The use of this feature will penalize the execution time of the secure session and should therefore be used only for the case mentioned above. As a reminder, closing the secure session also performs a mutual authentication of the card and the terminal.

        When it is needed, it is advised to use this command only once at the beginning of the secure session.

        Returns:
        The current instance.
        Throws:
        java.lang.UnsupportedOperationException - The "Manage Secure Session" command is not available for this context (Card and/or SAM does not support the extended mode).
        Since:
        1.5.0
        See Also:
        prepareActivateEncryption(), prepareDeactivateEncryption()

      • prepareActivateEncryption

        CardTransactionManager prepareActivateEncryption()
        Requests the encryption of all following commands.

        This ensures data confidentiality and prevents man-in-the-middle attacks.

        The use of data encryption is resource intensive and increases transaction times. It is therefore recommended to limit encryption to commands that require it.

        Furthermore, if mutual authentication is also required, for performance reasons, it is advised to place the prepareEarlyMutualAuthentication and prepareActivateEncryption calls consecutively (in any order) for optimization purpose.

        This command only makes sense in the context of a secure session.

        Returns:
        The current instance.
        Throws:
        java.lang.UnsupportedOperationException - The "Manage Secure Session" command is not available for this context (Card and/or SAM does not support the extended mode).
        Since:
        1.5.0
        See Also:
        prepareDeactivateEncryption(), prepareEarlyMutualAuthentication()

      • prepareDeactivateEncryption

        CardTransactionManager prepareDeactivateEncryption()
        Requests to stop encryption for the following commands.

        This restores the exchange operations with the card to its normal mode.

        This command only makes sense in the context of a secure session in which encryption of commands has been previously requested.

        Note: the processClosing() method automatically stops the encryption.

        Returns:
        The current instance.
        Throws:
        java.lang.UnsupportedOperationException - The "Manage Secure Session" command is not available for this context (Card and/or SAM does not support the extended mode).
        Since:
        1.5.0
        See Also:
        prepareActivateEncryption(), prepareEarlyMutualAuthentication(), processClosing()

      • processCardCommands

        @Deprecated
CardTransactionManager processCardCommands()
        Deprecated.
        Use CommonTransactionManager.processCommands() instead. (will be soon removed)
        Process all previously prepared card commands outside or inside a Secure Session.
        • All APDUs resulting from prepared commands are grouped and sent to the card.
        • The CalypsoCard object is updated with the result of the executed commands.
        • If a secure session is opened, except in the case where reloading or debit SV operations have been prepared, the invocation of this method does not generate communication with the SAM. The data necessary for the calculation of the terminal signature are kept to be sent to the SAM at the time of the invocation of processClosing().
          The card channel is kept open.
        • If no secure session is opened, the card channel is closed depending on whether or not prepareReleaseCardChannel has been called.
        • The card session buffer overflows are managed in the same way as in processOpening(org.calypsonet.terminal.calypso.WriteAccessLevel). For example, when the multiple session mode is enabled, the commands are separated in as many sessions as necessary to respect the capacity of the card buffer.
        Returns:
        The current instance.
        Throws:
        ReaderIOException - If a communication error with the card reader or SAM reader occurs.
        CardIOException - If a communication error with the card occurs.
        SamIOException - If a communication error with the SAM occurs.
        InvalidSignatureException - If a signature associated to a prepared signature verification SAM command is invalid.
        UnexpectedCommandStatusException - If a command returns an unexpected status.
        InconsistentDataException - If inconsistent data have been detected.
        SessionBufferOverflowException - If a secure session is open and multiple session mode is disabled and the session buffer capacity is not sufficient.
        CardSignatureNotVerifiableException - If a secure session is open and multiple session mode is enabled and an intermediate session is correctly closed but the SAM is no longer available to verify the card signature.
        InvalidCardSignatureException - If a secure session is open and multiple session mode is enabled and an intermediate session is correctly closed but the card signature is incorrect.
        SelectFileException - If a "Select File" prepared card command indicated that the file was not found.
        Since:
        1.0.0

      • processVerifyPin

        CardTransactionManager processVerifyPin​(byte[] pin)
        Performs a PIN verification, 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 CardSecuritySetting (by default the transmission is encrypted).

        If the execution is done out of session but an encrypted transmission is requested, then CardTransactionManager must be constructed with CardSecuritySetting

        If CardTransactionManager is constructed without CardSecuritySetting the transmission in done in plain.

        The card channel is closed if prepareReleaseCardChannel is called before this command.

        Parameters:
        pin - The PIN code value (4-byte long byte array).
        Returns:
        The current instance.
        Throws:
        java.lang.UnsupportedOperationException - If the PIN feature is not available for this card.
        java.lang.IllegalArgumentException - If the provided argument is out of range.
        java.lang.IllegalStateException - If commands have been prepared before invoking this process method.
        ReaderIOException - If a communication error with the card reader or SAM reader occurs.
        CardIOException - If a communication error with the card occurs.
        SamIOException - If a communication error with the SAM occurs.
        UnexpectedCommandStatusException - If a command returns an unexpected status.
        InconsistentDataException - If inconsistent data have been detected.
        Since:
        1.0.0

      • processChangePin

        CardTransactionManager processChangePin​(byte[] newPin)
        Replaces 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 CardSecuritySetting (by default the transmission is encrypted).

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

        Parameters:
        newPin - The new PIN code value (4-byte long byte array).
        Returns:
        The current instance.
        Throws:
        java.lang.UnsupportedOperationException - If the PIN feature is not available for this card.
        java.lang.IllegalArgumentException - If the provided argument is out of range.
        java.lang.IllegalStateException - If the command is executed while a secure session is open.
        ReaderIOException - If a communication error with the card reader or SAM reader occurs.
        CardIOException - If a communication error with the card occurs.
        SamIOException - If a communication error with the SAM occurs.
        UnexpectedCommandStatusException - If a command returns an unexpected status.
        InconsistentDataException - If inconsistent data have been detected.
        Since:
        1.0.0

      • processChangeKey

        CardTransactionManager processChangeKey​(int keyIndex,
                                        byte newKif,
                                        byte newKvc,
                                        byte issuerKif,
                                        byte issuerKvc)
        Replaces one of the current card keys with another key present in the SAM.

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

        The change key process transfers the key from the SAM to the card. The new key is diversified by the SAM 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 SAM.

        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:
        java.lang.UnsupportedOperationException - If the Change Key command is not available for this card.
        java.lang.IllegalArgumentException - If the provided key index is out of range.
        java.lang.IllegalStateException - If the command is executed while a secure session is open.
        ReaderIOException - If a communication error with the card reader or SAM reader occurs.
        CardIOException - If a communication error with the card occurs.
        SamIOException - If a communication error with the SAM occurs.
        UnexpectedCommandStatusException - If a command returns an unexpected status.
        InconsistentDataException - If inconsistent data have been detected.
        Since:
        1.1.0

      • processOpening

        CardTransactionManager processOpening​(WriteAccessLevel writeAccessLevel)
        Opens a Calypso Secure Session and then executes all previously prepared commands.

        It is the starting point of the sequence:

        Each of the steps in this sequence may or may not be preceded by the preparation of one or more commands and ends with an update of the CalypsoCard object provided when CardTransactionManager was created.

        As a prerequisite for invoking this method, since the Calypso Secure Session involves the use of a SAM, the CardTransactionManager must have been built in secure mode, i.e. the constructor used must be the one expecting a reference to a valid CardSecuritySetting object, otherwise a IllegalStateException is raised.

        The secure session is opened with the WriteAccessLevel passed as an argument depending on whether it is a personalization, reload or debit transaction profile.

        The possible overflow of the internal session buffer of the card is managed in two ways depending on the setting chosen in CardSecuritySetting.

        • If the session was opened with the default atomic mode and the previously prepared commands will cause the buffer to be exceeded, then an SessionBufferOverflowException is raised and no transmission to the card is made.
        • If the session was opened with the multiple session mode and the buffer is to be exceeded then a split into several secure sessions is performed automatically. However, regardless of the number of intermediate sessions performed, a secure session is opened at the end of the execution of this method.

        Be aware that in the "MULTIPLE" case we lose the benefit of the atomicity of the secure session.

        Card and SAM exchanges in detail

        When executing this method, communications with the card and the SAM are (in that order) :

        • Sending the card diversifier (Calypso card serial number) to the SAM and receiving the terminal challenge
        • Grouped sending to the card of
          • the open secure session command including the challenge terminal.
          • all previously prepared commands
        • Receiving grouped responses and updating CalypsoCard with the collected data.
        For optimization purposes, if the first command prepared is the reading of a single record of a card file then this one is replaced by a setting of the session opening command allowing the retrieval of this data in response to this command.

        Please note that the CAAD mechanism may require a file to be read before being modified. For this mechanism to work properly, this reading must not be placed in the first position of the prepared commands in order to be correctly taken into account by the SAM.

        Other operations carried out

        • The card KIF, KVC and card challenge received in response to the open secure session command are kept for a later initialization of the session's digest (see processClosing()).
        • All data received in response to the open secure session command and the responses to the prepared commands are also stored for later calculation of the digest.
        • If a list of authorized KVCs has been defined in CardSecuritySetting and the KVC of the card does not belong to this list then a UnauthorizedKeyException is thrown.

        All unexpected results (communication errors, data or security errors, etc. are notified to the calling application through dedicated exceptions.

        Note: to understand in detail how the secure session works please refer to the card specification documents.

        Parameters:
        writeAccessLevel - An WriteAccessLevel enum entry.
        Returns:
        The current instance.
        Throws:
        java.lang.IllegalArgumentException - If the provided argument is null.
        java.lang.IllegalStateException - If no CardSecuritySetting is available.
        ReaderIOException - If a communication error with the card reader or SAM reader occurs.
        CardIOException - If a communication error with the card occurs.
        SamIOException - If a communication error with the SAM occurs.
        InvalidSignatureException - If a signature associated to a prepared signature verification SAM command is invalid.
        UnexpectedCommandStatusException - If a command returns an unexpected status.
        InconsistentDataException - If inconsistent data have been detected.
        UnauthorizedKeyException - If the card requires an unauthorized session key.
        SessionBufferOverflowException - If multiple session mode is disabled and the session buffer capacity is not sufficient.
        CardSignatureNotVerifiableException - If multiple session mode is enabled and an intermediate session is correctly closed but the SAM is no longer available to verify the card signature.
        InvalidCardSignatureException - If multiple session mode is enabled and an intermediate session is correctly closed but the card signature is incorrect.
        SelectFileException - If a "Select File" prepared card command indicated that the file was not found.
        Since:
        1.0.0

      • processClosing

        CardTransactionManager processClosing()
        Terminates the Secure Session sequence started with processOpening(WriteAccessLevel).

        Nominal case

        The previously prepared commands are integrated into the calculation of the session digest by the SAM before execution by the card by anticipating their responses.

        Thus, the session closing command containing the terminal signature is integrated into the same APDU group sent to the card via a final card request.

        Upon reception of the response from the card, the signature of the card is verified with the SAM.

        If the method terminates normally, it means that the secure session closing and all related security checks have been successful; conversely, if one of these operations fails, an exception is raised.

        Stored Value

        If the SV counter was debited or reloaded during the session, an additional verification specific to the SV is performed by the SAM.

        Ratification

        A ratification command is added after the close secure session command when the communication is done in a contactless mode.

        The logical channel is closed or left open depending on whether the prepareReleaseCardChannel() method has been called before or not.

        Card and SAM exchanges in detail

        • All the data exchanged with the card so far, to which are added the last prepared orders and their anticipated answers, are sent to the SAM for the calculation of the session digest. The terminal signature calculation request is also integrated in the same group of SAM Apdu.
        • All previously prepared commands are sent to the card along with the session closing command and possibly the ratification command within a single card request.
        • The responses received from the card are integrated into CalypsoCard.
          Note: the reception of the answers of this final card request from the card is tolerant to the non-reception of the answer to the ratification order.
        • The data received from the card in response to the logout (card session signature and possibly SV signature) are sent to the SAM for verification.
        Returns:
        The current instance.
        Throws:
        java.lang.IllegalStateException - If no session is open.
        ReaderIOException - If a communication error with the card reader or SAM reader occurs.
        CardIOException - If a communication error with the card occurs.
        SamIOException - If a communication error with the SAM occurs.
        InvalidSignatureException - If a signature associated to a prepared signature verification SAM command is invalid.
        UnexpectedCommandStatusException - If a command returns an unexpected status.
        InconsistentDataException - If inconsistent data have been detected.
        SessionBufferOverflowException - If multiple session mode is disabled and the session buffer capacity is not sufficient.
        CardSignatureNotVerifiableException - If session is correctly closed but the SAM is no longer available to verify the card signature.
        InvalidCardSignatureException - If session is correctly closed but the card signature is incorrect.
        Since:
        1.0.0

      • processCancel

        CardTransactionManager processCancel()
        Aborts a Secure Session.

        Send the appropriate command to the card

        Clean up internal data and status.

        Returns:
        The current instance.
        Throws:
        java.lang.IllegalStateException - If no session is open.
        ReaderIOException - If a communication error with the card reader occurs.
        CardIOException - If a communication error with the card occurs.
        UnexpectedCommandStatusException - If the command returns an unexpected status.
        Since:
        1.0.0