public class OwnerPIN extends Object implements PIN
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.
PINException
,
PIN
,
Shareable
,
JCSystem
Constructor and Description |
---|
OwnerPIN(byte tryLimit,
byte maxPINSize)
Constructor.
|
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. |
public OwnerPIN(byte tryLimit, byte maxPINSize) throws PINException
PIN
instance with validated
flag set to false
.tryLimit
- the maximum number of times an incorrect PIN can be presented.
tryLimit
must be >=1maxPINSize
- the maximum allowed PIN size. maxPINSize
must
be >=1PINException
- 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.
protected boolean getValidatedFlag()
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.protected void setValidatedFlag(boolean value)
OwnerPIN
to control or
override the internal PIN state of the OwnerPIN
.value
- the new value for the validated flagpublic byte getTriesRemaining()
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.getTriesRemaining
in interface PIN
public boolean check(byte[] pin, short offset, byte length) throws ArrayIndexOutOfBoundsException, NullPointerException
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:
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.
offset
or length
parameter
is negative an ArrayIndexOutOfBoundsException
exception is thrown.
offset+length
is greater than pin.length
, the length
of the pin
array, an ArrayIndexOutOfBoundsException
exception is thrown.
pin
parameter is null
a NullPointerException
exception is thrown.
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.check
in interface PIN
pin
- the byte array containing the PIN value being checkedoffset
- the starting offset in the pin
arraylength
- the length of pin
true
if the PIN value matches; false
otherwiseArrayIndexOutOfBoundsException
- if the check operation would cause access of data outside
array bounds.NullPointerException
- if pin
is null
public boolean isValidated()
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.isValidated
in interface PIN
true
if validated; false
otherwisepublic void reset()
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.public void update(byte[] pin, short offset, byte length) throws PINException
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.
pin
- the byte array containing the new PIN valueoffset
- the starting offset in the pin arraylength
- the length of the new PINPINException
- with the following reason codes:
PINException.ILLEGAL_VALUE
if length
is greater than configured maximum PIN size.
JCSystem.beginTransaction()
public void resetAndUnblock()
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
.Copyright © 1998, 2015, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms