javacard.framework
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.

A typical card global PIN usage will combine an instance of OwnerPIN class and a
a Proxy PIN interface which extends both the PIN and the Shareable interfaces
and re-declares the methods of the PIN interface.
The OwnerPIN 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.

check

Compares pin against the PIN value. If they match and the
PIN is not blocked, it sets the validated flag
and resets the try counter to its maximum. If it does not match,
it decrements the try counter 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.