javacard.framework

Class OwnerPIN

java.lang.Object

javacard.framework.OwnerPIN

All Implemented Interfaces:

PIN

public class OwnerPIN
extends Object
implements PIN

This class represents an Owner PIN, implements Personal Identification Number functionality as defined in the PIN interface, and provides the ability to update the PIN and thus owner functionality.

The implementation of this class 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.

If an implementation of this class creates transient arrays, it must ensure that they are CLEAR_ON_RESET transient objects.

The protected methods getValidatedFlag and setValidatedFlag allow a subclass of this class to optimize the storage for the validated boolean state.

Some methods of instances of this class are only suitable for sharing when there exists a trust relationship among the applets. A typical shared usage would use a proxy PIN interface which extends both the PIN interface and the Shareable interface and re-declares the methods of the PIN interface.

Any of the methods of the OwnerPIN may be called with a transaction in progress. None of the methods of OwnerPIN class initiate or alter the state of the transaction if one is in progress.

See Also:

PINException, PIN, Shareable, JCSystem

Constructor Summary

Constructors

Constructor and Description
OwnerPIN(byte tryLimit, byte maxPINSize) Constructor.

Method Summary

Methods

Modifier and Type	Method and 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.
protected boolean	getValidatedFlag() This protected method returns the validated flag.
boolean	isValidated() Returns true if a valid PIN has been presented since the last card reset or last call to reset().
void	reset() If the validated flag is set, this method resets the validated flag and resets the PIN try counter to the value of the PIN try limit.
void	resetAndUnblock() This method resets the validated flag and resets the PIN try counter to the value of the PIN try limit and clears the blocking state of the PIN.
protected void	setValidatedFlag(boolean value) This protected method sets the value of the validated flag.
void	update(byte[] pin, short offset, byte length) This method sets a new value for the PIN and resets the PIN try counter to the value of the PIN try limit.

Methods inherited from class java.lang.Object

equals

Constructor Detail

OwnerPIN

public OwnerPIN(byte tryLimit,
        byte maxPINSize)
         throws PINException

Constructor. Allocates a new PIN instance with validated flag set to false.

Parameters:

tryLimit - the maximum number of times an incorrect PIN can be presented. tryLimit must be >=1

maxPINSize - the maximum allowed PIN size. maxPINSize must be >=1

Throws:

PINException - with the following reason codes:

• PINException.ILLEGAL_VALUE if tryLimit parameter is less than 1.
• PINException.ILLEGAL_VALUE if maxPINSize parameter is less than 1.

Method Detail

getValidatedFlag

protected boolean getValidatedFlag()

This protected method returns the validated flag. This method is intended for subclass of this OwnerPIN to access or override the internal PIN state of the OwnerPIN.

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

Returns:

the boolean state of the PIN validated flag

setValidatedFlag

protected void setValidatedFlag(boolean value)

This protected method sets the value of the validated flag. This method is intended for subclass of this OwnerPIN to control or override the internal PIN state of the OwnerPIN.

Parameters:

value - the new value for the validated flag

getTriesRemaining

public 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, this method sets the result in an internal state which can be rechecked using assertion methods of the SensitiveResult class, if supported by the platform.

Specified by:

getTriesRemaining in interface PIN

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, 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, this method sets 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 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 has been presented since the last card reset or last call to reset().

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

Specified by:

isValidated in interface PIN

Returns:

true if validated; false otherwise

reset

public void reset()

If the validated flag is set, this method resets the validated flag and resets the PIN try counter to the value of the PIN try limit. Even if a transaction is in progress, update of internal state - the try counter, the validated flag, shall not participate in the transaction. If the validated flag is not set, this method does nothing.

Specified by:

reset in interface PIN

update

public void update(byte[] pin,
          short offset,
          byte length)
            throws PINException

This method sets a new value for the PIN and resets the PIN try counter to the value of the PIN try limit. It also resets the validated flag.

This method copies the input pin parameter into an internal representation. If a transaction is in progress, the new pin and try counter update must be conditional i.e the copy operation must use the transaction facility.

Parameters:

pin - the byte array containing the new PIN value

offset - the starting offset in the pin array

length - the length of the new PIN

Throws:

PINException - with the following reason codes:

• PINException.ILLEGAL_VALUE if length is greater than configured maximum PIN size.

See Also:

JCSystem.beginTransaction()

resetAndUnblock

public void resetAndUnblock()

This method resets the validated flag and resets the PIN try counter to the value of the PIN try limit and clears the blocking state of 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. This method is used by the owner to re-enable the blocked PIN.