javacard.framework
Interface PIN

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. Even if a transaction is in progress, internal state such as the try counter, the validated flag and the blocking state must not be conditionally updated during PIN presentation.

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

See Also:

OwnerPIN, Shareable

Method Summary

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 true if a valid PIN value has been presented since the last card reset or last call to reset().
void	reset() If the validated flag is set, this method resets it.

Method Detail

getTriesRemaining

public byte getTriesRemaining()

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

Returns:

the number of times remaining

check

public boolean check(byte[] pin,
                     short offset,
                     byte length)
              throws ArrayIndexOutOfBoundsException,
                     NullPointerException

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, internal state such as the try counter, the validated flag and the blocking state must not be conditionally updated.

Notes:

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

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

public boolean isValidated()

Returns true if a valid PIN value has been presented since the last card reset or last call to reset().

Returns:

true if validated; false otherwise

reset

public void reset()

If the validated flag is set, this method resets it. If the validated flag is not set, this method does nothing.