Package javacard.framework

Interface PIN

  • All Known Subinterfaces:
    OwnerPINx, OwnerPINxWithPredecrement
    All Known Implementing Classes:
    OwnerPIN
    public interface PIN
    This interface represents a PIN. An implementation must maintain these internal values:
    • PIN value.
    • Try limit - the maximum number of times an incorrect PIN can be presented before the PIN is blocked. When the PIN is blocked, it cannot be validated even on valid PIN presentation.
    • Max PIN size - the maximum length of PIN allowed.
    • Try counter - the remaining number of times an incorrect PIN presentation is permitted before the PIN becomes blocked.
    • Validated flag - true if a valid PIN has been presented. This flag is reset on every card reset.
    This interface does not make any assumptions about where the data for the PIN value comparison is stored.

    An owner implementation of this interface must provide a way to initialize/update the PIN value. The owner implementation of the interface must protect against attacks based on program flow prediction. In addition, even if a transaction is in progress, update of internal state such as the try counter, the validated flag, and the blocking state, shall not participate in the transaction during PIN presentation.

    This interface does not make any assumptions about how the blocking state is internally represented: the blocking state is concomitant to the try counter value being equal to zero.

    A typical card global PIN usage will combine an instance of the OwnerPIN class or of an OwnerPINx-implementing class and a Proxy PIN interface which extends both the PIN and the Shareable interfaces and re-declares the methods of the PIN interface. The OwnerPIN or OwnerPINx instance would be manipulated only by the owner who has update privilege. All others would access the global PIN functionality via the proxy PIN interface.

    See Also:
    OwnerPIN, OwnerPINx, OwnerPINxWithPredecrement, OwnerPINBuilder, Shareable

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      boolean check​(byte[] pin, short offset, byte length)
      Compares pin against the PIN value.
      byte getTriesRemaining()
      Returns the number of times remaining that an incorrect PIN can be presented before the PIN is blocked.
      boolean isValidated()
      Returns the validated flag; true if a valid PIN value has been presented since the last card reset and the validated flag was not reset since then by a call to reset or by any owner PIN administrative method operations (see OwnerPIN and OwnerPINx).
      void reset()
      If the validated flag is set, this method resets the validated flag.

    • Method Detail

      • getTriesRemaining

        byte getTriesRemaining()
        Returns the number of times remaining that an incorrect PIN can be presented before the PIN is blocked.

        In addition to returning a byte result, platform-implementations of this method set the result in an internal state which can be rechecked using assertion methods of the SensitiveResult class, if supported by the platform.

        Returns:
        the number of times remaining

      • check

        boolean check​(byte[] pin,
              short offset,
              byte length)
       throws ArrayIndexOutOfBoundsException,
              NullPointerException
        Compares pin against the PIN value. If the PIN is not already blocked then:
        • if the PIN value matches, it sets the validated flag and resets the try counter to its maximum;
        • otherwise, it resets the validated flag, decrements the try counter - if not assumed to having been pre-decremented - and, if the counter has reached zero, blocks the PIN.

        Even if a transaction is in progress, update of internal state - the try counter, the validated flag, and the blocking state, shall not participate in the transaction.

        Note:

        • If NullPointerException or ArrayIndexOutOfBoundsException is thrown, the validated flag must be set to false, the try counter must be decremented and, the PIN blocked if the counter reaches zero.
        • If offset or length parameter is negative an ArrayIndexOutOfBoundsException exception is thrown.
        • If offset+length is greater than pin.length, the length of the pin array, an ArrayIndexOutOfBoundsException exception is thrown.
        • If pin parameter is null a NullPointerException exception is thrown.

        In addition to returning a boolean result, platform-implementations of this method set the result in an internal state which can be rechecked using assertion methods of the SensitiveResult class, if supported by the platform.

        Parameters:
        pin - the byte array containing the PIN value being checked
        offset - the starting offset in the pin array
        length - the length of pin
        Returns:
        true if the PIN value matches; false otherwise
        Throws:
        ArrayIndexOutOfBoundsException - if the check operation would cause access of data outside array bounds.
        NullPointerException - if pin is null

      • isValidated

        boolean isValidated()
        Returns the validated flag; true if a valid PIN value has been presented since the last card reset and the validated flag was not reset since then by a call to reset or by any owner PIN administrative method operations (see OwnerPIN and OwnerPINx).

        In addition to returning a boolean result, platform-implementations of this method set the result in an internal state which can be rechecked using assertion methods of the SensitiveResult class, if supported by the platform.

        Returns:
        true if validated; false otherwise

      • reset

        void reset()
        If the validated flag is set, this method resets the validated flag. If the validated flag is not set, this method does nothing.