javacard.framework

Interface OwnerPINxWithPredecrement

All Superinterfaces:

OwnerPINx, PIN

public interface OwnerPINxWithPredecrement
extends OwnerPINx

The OwnerPINxWithPredecrement interface represents an Owner PIN, extends Personal Identification Number functionality as defined in the PIN interface, and provides the ability to update the PIN, update the try limit and try counter and thus owner functionality.

The OwnerPINxWithPredecrement interface extends the OwnerPINx to support the decrementing of the tries counter before any PIN validation attempts.

Since:

3.0.5

See Also:

OwnerPINx, OwnerPINBuilder

Method Summary

Methods

Modifier and Type	Method and Description
boolean	check(byte[] pin, short offset, byte length) Compares pin against the PIN value without decrementing the try counter.
byte	decrementTriesRemaining() Decrements the try counter if the PIN is not blocked.

Methods inherited from interface javacard.framework.OwnerPINx

getTryLimit, setTriesRemaining, setTryLimit, update

Methods inherited from interface javacard.framework.PIN

getTriesRemaining, isValidated, reset

Method Detail

decrementTriesRemaining

byte decrementTriesRemaining()

Decrements the try counter if the PIN is not blocked. It also resets the validated flag. This method must be called prior to calling the check method; the state for enforcing this constraint must be implemented as a CLEAR_ON_RESET transient object; it must also be cleared when the check method is called as well as when any other public method that affects the try counter, the validated flag, or the blocking state is called.

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.

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 after decrementing.

check

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

Compares pin against the PIN value without decrementing the try counter. If the PIN is not blocked then: if the PIN value matches, it sets the validated flag and resets the try counter to its maximum; otherwise if the PIN value does not match, 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:

• This method does not decrement the try counter. The try counter must have been pre-decremented by a prior call to the decrementTriesRemaining method. If the decrementTriesRemaining method has not been called prior to calling this method then a PINException exception is thrown; the state for enforcing this constraint must be implemented as a CLEAR_ON_RESET transient object; it must also be cleared when this method is called as well as when any other public method that affects the try counter, the validated flag, or the blocking state is called.
• If NullPointerException or ArrayIndexOutOfBoundsException is thrown, the validated flag must be set to false 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.

Specified by:

check in interface PIN

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 comparison is successful, false otherwise.

Throws:

ArrayIndexOutOfBoundsException - if the check operation would cause access of data outside array bounds.

NullPointerException - if pin is null

PINException - with the following reason codes:

• ILLEGAL_STATE if the decrementTriesRemaining method has not been called prior to calling this method.