Interface OwnerPINx

All Superinterfaces:

PIN

All Known Subinterfaces:

OwnerPINxWithPredecrement

public interface OwnerPINx
extends PIN

The OwnerPINx 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.

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

Some methods of this interface 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 OwnerPINx may be called with a transaction in progress. None of the methods of an OwnerPINx-implementing class must initiate or alter the state of the transaction if one is in progress.

While update of the internal state shall not participate in an on-going transaction during PIN presentation (using check), update of the internal state during administrative operations (e.g. setTriesRemaining) shall participate in a transaction, if one is in progress. Therefore, care must be taken to not mix PIN presentation operations and administrative operations within the same transaction.

Since:

3.0.5

See Also:

• PINException
• PIN
• Shareable
• JCSystem
• OwnerPINBuilder

Method Summary

Modifier and Type	Method	Description
byte	getTryLimit()	Returns the the maximum number of times an incorrect PIN can be presented before the PIN is blocked.
void	setTriesRemaining(byte remaining)	Sets the PIN try counter to the value of the remaining parameter and resets the validated flag.
void	setTryLimit(byte limit)	Sets the PIN try limit to the value of the limit parameter and resets the validated flag.
void	update(byte[] pin, short offset, byte length)	Sets a new value for the PIN and resets the PIN try counter to the value of the PIN try limit.

Methods inherited from interface PIN

check, getTriesRemaining, isValidated, reset

Modifier and Type	Method	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.
boolean	isValidated()	Returns the validated flag; true if a valid PIN value has been presented since the last card reset and the validated flag was not reset since then by a call to reset or by any owner PIN administrative method operations (see OwnerPIN and OwnerPINx).
void	reset()	If the validated flag is set, this method resets the validated flag.

Method Details

update

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

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:

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

See Also:

• JCSystem.beginTransaction

getTryLimit

byte getTryLimit()

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

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 maximum number of times an incorrect PIN can be presented.

setTryLimit

void setTryLimit(byte limit)

Sets the PIN try limit to the value of the limit parameter and resets the validated flag. The try counter is set to the the new try limit value.

Parameters:

limit - the new value for the maximum number of times an incorrect PIN can be presented; limit must be >=1.

Throws:

PINException - with the following reason codes:

• ILLEGAL_VALUE if limit parameter is less than 1.

setTriesRemaining

void setTriesRemaining(byte remaining)

Sets the PIN try counter to the value of the remaining parameter and resets the validated flag. If the new try counter value is zero, it blocks the PIN.

Parameters:

remaining - the new value for the remaining number of times an incorrect PIN can be presented; remaining must be greater or equal to 0 and lesser or equal to the current try limit.

Throws:

PINException - with the following reason codes:

• ILLEGAL_VALUE if remaining parameter is less than 0 or greater than the current try limit.