Package org.calypsonet.terminal.calypso.card

Interface CalypsoCard

  • All Superinterfaces:
    org.calypsonet.terminal.reader.selection.spi.SmartCard
    public interface CalypsoCard
extends org.calypsonet.terminal.reader.selection.spi.SmartCard
    A dynamic view of the card's content, regularly updated from the selection stage to the end of the transaction.

    An instance of CalypsoCard is obtained by casting the SmartCard object from the selection process defined by the Terminal Reader API and updated by the CardTransactionManager.

    The various information contained in CalypsoCard includes:

    • The application identification fields (revision/version, class, DF name, serial number, ATR, issuer)
    • The indication of the presence of optional features (Stored Value, PIN, Rev3.2 mode, ratification management)
    • The management information of the modification buffer
    • The invalidation status
    • The files, counters, SV data read or modified during the execution of the processes defined by the card transaction manager.
    Since:
    1.0.0

    • Method Detail

      • getProductType

        CalypsoCard.ProductType getProductType()
        Gets the card product type.
        Returns:
        A not null reference.
        Since:
        1.0.0

      • isHce

        boolean isHce()
        Indicates if the card is a Calypso HCE (Host Card Emulation) .
        Returns:
        True if the card is a Calypso HCE.
        Since:
        1.0.0

      • isDfInvalidated

        boolean isDfInvalidated()
        Tells if the current DF is invalidated or not.

        The invalidation status is determined either from the response to the Select Application command or from the response to a Select File (DF) command.

        For a PRIME_REVISION_3 card, a 6283h status word is returned in response to the Select Application command when the corresponding DF is invalidated.

        For older Calypso cards it may be necessary to execute a Select File command in order to determine the invalidation status.

        Returns:
        True if the current DF has been invalidated.
        Since:
        1.0.0

      • getDfName

        byte[] getDfName()
        Gets the DF name as an array of bytes.

        The DF name is the name of the application DF as defined in ISO/IEC 7816-4.

        It also corresponds to the complete representation of the target covered by the AID value provided in the selection command.

        The AID selects the application by specifying all or part of the targeted DF Name (5 bytes minimum).

        Returns:
        A not null byte array containing the DF Name bytes (5 to 16 bytes)
        Since:
        1.0.0

      • getApplicationSerialNumber

        byte[] getApplicationSerialNumber()
        Gets the Calypso application serial number as an array of bytes.
        Returns:
        A not null byte array containing the Application Serial Number (8 bytes).
        Since:
        1.0.0

      • getStartupInfoRawData

        byte[] getStartupInfoRawData()
        Gets the raw Calypso startup information.
        Returns:
        A not null byte array.
        Since:
        1.0.0

      • getPlatform

        byte getPlatform()
        Gets the platform identification byte which is the reference of the chip.
        Returns:
        The platform identification byte.
        Since:
        1.0.0

      • getApplicationType

        byte getApplicationType()
        Gets the Application Type byte which determines the Calypso product type and various options.
        Returns:
        The Application Type byte.
        Since:
        1.0.0

      • getApplicationSubtype

        byte getApplicationSubtype()
        Gets the Application Subtype that provides a reference to the file structure of the Calypso DF.
        Returns:
        The Application Subtype byte
        Since:
        1.0.0

      • getSoftwareIssuer

        byte getSoftwareIssuer()
        Gets the Software Issuer byte that indicates the entity responsible for the software of the selected application.
        Returns:
        The Software Issuer byte.
        Since:
        1.0.0

      • getSoftwareVersion

        byte getSoftwareVersion()
        Gets the Software Version field that may be set to any fixed value by the Software Issuer of the Calypso application.
        Returns:
        The Software Version byte.
        Since:
        1.0.0

      • getSoftwareRevision

        byte getSoftwareRevision()
        Gets the Software Revision field that may be set to any fixed value by the Software Issuer of the Calypso application.
        Returns:
        The Software Revision byte.
        Since:
        1.0.0

      • getSessionModification

        byte getSessionModification()
        Gets the session modification byte from the startup info structure.

        Depending on the type of card, the session modification byte indicates the maximum number of bytes that can be modified or the number of possible write commands in a session.

        Returns:
        The Session Modification byte.
        Since:
        1.0.0

      • getTraceabilityInformation

        byte[] getTraceabilityInformation()
        Gets the traceability information of the product.

        The returned array contains the software issuer ID and the discretionary data.

        Returns:
        An empty array if the traceability information is not available.
        Since:
        1.1.0

      • getDirectoryHeader

        DirectoryHeader getDirectoryHeader()
        Returns the metadata of the current DF.
        Returns:
        Null if is not set.
        Since:
        1.0.0

      • getFileBySfi

        ElementaryFile getFileBySfi​(byte sfi)
        Returns a reference to the ElementaryFile that has the provided SFI.

        Note that if a secure session is actually running, then the object contains all session modifications, which can be canceled if the secure session fails.

        Parameters:
        sfi - The SFI to search.
        Returns:
        Null if the requested EF is not found or if the SFI is equal to 0.
        Since:
        1.0.0

      • getFileByLid

        ElementaryFile getFileByLid​(short lid)
        Returns a reference to the ElementaryFile that has the provided LID value.

        Note that if a secure session is actually running, then the object contains all session modifications, which can be canceled if the secure session fails.

        Parameters:
        lid - The LID to search.
        Returns:
        Null if the requested EF is not found.
        Since:
        1.0.0

      • getAllFiles

        @Deprecated
java.util.Map<java.lang.Byte,​ElementaryFile> getAllFiles()
        Deprecated.
        Since an EF may not have an SFI, the getFiles() method must be used instead. (will be soon removed)
        Gets a reference to a map of all known Elementary Files by their associated SFI.

        Note that if a secure session is actually running, then the map contains all session modifications, which can be canceled if the secure session fails.

        Returns:
        A not null reference (it may be empty if no one EF is set).
        Since:
        1.0.0

      • getFiles

        java.util.Set<ElementaryFile> getFiles()
        Returns a reference to the set of all known Elementary Files contains inside the current DF.

        Note that if a secure session is actually running, then the set contains all session modifications, which can be canceled if the secure session fails.

        Returns:
        A not null reference (it may be empty if no one EF is set).
        Since:
        1.1.0

      • isDfRatified

        boolean isDfRatified()
        Tells if the last session with this card has been ratified or not.
        Returns:
        True if the card has been ratified.
        Throws:
        java.lang.IllegalStateException - If no session has been opened.
        Since:
        1.0.0

      • getTransactionCounter

        int getTransactionCounter()
        Returns the transaction counter value provided in the output data of the last successful "Open Secure Session" command.

        Please note that there are other commands that can decrement the original card counter (e.g. Change Key, Change/Verify PIN, SV Debit/Undebit/Reload). For these other commands, the counter value returned by this method will not be updated.

        Returns:
        A positive value.
        Throws:
        java.lang.IllegalStateException - If no session has been opened.
        Since:
        1.2.0

      • isPkiModeSupported

        boolean isPkiModeSupported()
        Indicates whether the Public Key Authentication is supported or not (since rev 3.3).

        This boolean is interpreted from the Application Type byte

        Returns:
        True if the Public Key Authentication is supported.
        Since:
        1.0.0

      • isExtendedModeSupported

        boolean isExtendedModeSupported()
        Indicates whether the Extended Mode is supported or not (since rev 3.2).

        This boolean is initially the result of the interpretation of the application type byte but may be updated after the secure session is opened. Indeed, depending on the type of key used, the extended mode functionalities may not be available (non-AES keys) and this information is provided by the card in response to the "Open Secure Session" command.

        Returns:
        True if the Extended Mode is supported.
        Since:
        1.0.0

      • isRatificationOnDeselectSupported

        boolean isRatificationOnDeselectSupported()
        Indicates if the ratification is done on deselect (ratification command not necessary).

        This boolean is interpreted from the Application Type byte

        Returns:
        True if the ratification on deselect is supported.
        Since:
        1.0.0

      • isPinFeatureAvailable

        boolean isPinFeatureAvailable()
        Indicates whether the card has the Calypso PIN feature.

        This boolean is interpreted from the Application Type byte

        Returns:
        True if the card has the PIN feature.
        Since:
        1.0.0

      • isPinBlocked

        boolean isPinBlocked()
        Indicates if the PIN is blocked. The maximum number of incorrect PIN submissions has been reached.
        Returns:
        True if the PIN status is blocked
        Throws:
        java.lang.IllegalStateException - If the PIN has not been checked.
        Since:
        1.0.0

      • getPinAttemptRemaining

        int getPinAttemptRemaining()
        Gives the number of erroneous PIN presentations remaining before blocking.
        Returns:
        The number of remaining attempts.
        Throws:
        java.lang.IllegalStateException - If the PIN has not been checked.
        Since:
        1.0.0

      • isSvFeatureAvailable

        boolean isSvFeatureAvailable()
        Indicates whether the card has the Calypso Stored Value feature.

        This boolean is interpreted from the Application Type byte

        Returns:
        True if the card has the Stored Value feature
        Since:
        1.0.0

      • getSvBalance

        int getSvBalance()
        Gets the current SV balance value
        Returns:
        An int
        Throws:
        java.lang.IllegalStateException - If no SV Get command has been executed.
        Since:
        1.0.0

      • getSvLastTNum

        int getSvLastTNum()
        Gets the last SV transaction number
        Returns:
        An int
        Throws:
        java.lang.IllegalStateException - If no SV Get command has been executed.
        Since:
        1.0.0

      • getSvLoadLogRecord

        SvLoadLogRecord getSvLoadLogRecord()
        Gets a reference to the last SvLoadLogRecord
        Returns:
        A last SV load log record object or null if not available.
        Since:
        1.0.0

      • getSvDebitLogLastRecord

        SvDebitLogRecord getSvDebitLogLastRecord()
        Gets a reference to the last SvDebitLogRecord
        Returns:
        A last SV debit log record object or null if not available.
        Since:
        1.0.0

      • getSvDebitLogAllRecords

        java.util.List<SvDebitLogRecord> getSvDebitLogAllRecords()
        Gets list of references to the SvDebitLogRecord read from the card.
        Returns:
        An empty list if no log records are available.
        Since:
        1.0.0