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 thePIN
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
andsetValidatedFlag
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 theShareable
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 ofOwnerPIN
class initiate or alter the state of the transaction if one is in progress.- See Also:
PINException
,PIN
,Shareable
,JCSystem
-
-
Constructor Summary
Constructors Constructor Description OwnerPIN(byte tryLimit, byte maxPINSize)
Constructor.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description boolean
check(byte[] pin, short offset, byte length)
Comparespin
against the PIN value.byte
getTriesRemaining()
Returns the number of times remaining that an incorrect PIN can be presented before thePIN
is blocked.protected boolean
getValidatedFlag()
This protected method returns the validated flag.boolean
isValidated()
Returnstrue
if a valid PIN has been presented since the last card reset or last call toreset()
.void
reset()
If the validated flag is set, this method resets the validated flag and resets thePIN
try counter to the value of thePIN
try limit.void
resetAndUnblock()
This method resets the validated flag and resets thePIN
try counter to the value of thePIN
try limit and clears the blocking state of thePIN
.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 thePIN
try counter to the value of thePIN
try limit.
-
-
-
Constructor Detail
-
OwnerPIN
public OwnerPIN(byte tryLimit, byte maxPINSize) throws PINException
Constructor. Allocates a newPIN
instance with validated flag set tofalse
.- Parameters:
tryLimit
- the maximum number of times an incorrect PIN can be presented.tryLimit
must be >=1maxPINSize
- the maximum allowed PIN size.maxPINSize
must be >=1- Throws:
PINException
- with the following reason codes:PINException.ILLEGAL_VALUE
iftryLimit
parameter is less than 1.PINException.ILLEGAL_VALUE
ifmaxPINSize
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 thisOwnerPIN
to access or override the internal PIN state of theOwnerPIN
.In addition to returning a
boolean
result, this method sets the result in an internal state which can be rechecked using assertion methods of theSensitiveResult
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 thisOwnerPIN
to control or override the internal PIN state of theOwnerPIN
.- 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 thePIN
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 theSensitiveResult
class, if supported by the platform.- Specified by:
getTriesRemaining
in interfacePIN
- Returns:
- the number of times remaining
-
check
public boolean check(byte[] pin, short offset, byte length) throws ArrayIndexOutOfBoundsException, NullPointerException
Comparespin
against the PIN value. If they match and thePIN
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 thePIN
. 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
orArrayIndexOutOfBoundsException
is thrown, the validated flag must be set to false, the try counter must be decremented and, thePIN
blocked if the counter reaches zero. - If
offset
orlength
parameter is negative anArrayIndexOutOfBoundsException
exception is thrown. - If
offset+length
is greater thanpin.length
, the length of thepin
array, anArrayIndexOutOfBoundsException
exception is thrown. - If
pin
parameter isnull
aNullPointerException
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 theSensitiveResult
class, if supported by the platform.- Specified by:
check
in interfacePIN
- Parameters:
pin
- the byte array containing the PIN value being checkedoffset
- the starting offset in thepin
arraylength
- the length ofpin
- Returns:
true
if the PIN value matches;false
otherwise- Throws:
ArrayIndexOutOfBoundsException
- if the check operation would cause access of data outside array bounds.NullPointerException
- ifpin
isnull
- If
-
isValidated
public boolean isValidated()
Returnstrue
if a valid PIN has been presented since the last card reset or last call toreset()
.In addition to returning a
boolean
result, this method sets the result in an internal state which can be rechecked using assertion methods of theSensitiveResult
class, if supported by the platform.- Specified by:
isValidated
in interfacePIN
- Returns:
true
if validated;false
otherwise
-
reset
public void reset()
If the validated flag is set, this method resets the validated flag and resets thePIN
try counter to the value of thePIN
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.
-
update
public void update(byte[] pin, short offset, byte length) throws PINException
This method sets a new value for the PIN and resets thePIN
try counter to the value of thePIN
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 valueoffset
- the starting offset in the pin arraylength
- 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 thePIN
try counter to the value of thePIN
try limit and clears the blocking state of thePIN
. 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 blockedPIN
.
-
-