**javacard.framework** 
 ====Interface PIN  ====

**All Known Implementing Classes:** [[javacard:java-card-api:OwnerPIN|OwnerPIN]]  
 



 ----





This interface represents a PIN. An implementation must maintain these internal values:
 
 \\ 
 
  *PIN value. 
 \\ 
  *Try limit - the maximum number of times an incorrect PIN can bepresented before the PIN is blocked. When the PIN is blocked, itcannot be validated even on valid PIN presentation. 
 \\ 
  *Max PIN size - the maximum length of PIN allowed. 
 \\ 
  *Try counter - the remaining number of times an incorrect PINpresentation is permitted before the PIN becomes blocked. 
 \\ 
  *Validated flag - true if a valid PIN has been presented. This flag isreset on every card reset. 
 \\  
 This interface does not make any assumptions about where the data
 for the PIN value comparison is stored.

 An owner implementation of this interface must provide a way to initialize/update
 the PIN value. The owner implementation of the interface 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.

 A typical card global PIN usage will combine an instance of OwnerPIN class and a 
 a Proxy PIN interface which extends both the PIN and the Shareable interfaces
 and re-declares the methods of the PIN interface.
 The OwnerPIN instance would be manipulated only by the owner who has update privilege.
 All others would access the global PIN functionality via the proxy PIN interface.




**See Also:**[[javacard:java-card-api:OwnerPIN|OwnerPIN]] , 
[[javacard:java-card-api:Shareable|Shareable]]  
 


 ----







^ Method Summary ^^ 
| ** boolean** | **[[javacard:java-card-api:PIN#check(byte[], short, byte)|check]] **(byte[] pin,short offset,byte length)          Compares pin against the PIN value. |
| ** byte** | **[[javacard:java-card-api:PIN#getTriesRemaining()|getTriesRemaining]] **()          Returns the number of times remaining that an incorrect PIN can be presented before the PIN is blocked. |
| ** boolean** | **[[javacard:java-card-api:PIN#isValidated()|isValidated]] **()          Returns true if a valid PIN value has been presented since the last card reset or last call to reset(). |
| ** void** | **[[javacard:java-card-api:PIN#reset()|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. |

 






^ Method Detail ^ 



 === getTriesRemaining === 
byte **getTriesRemaining**()

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

 
 


**Returns:**the number of times remaining 
 

 
 



 ----


 === check === 
boolean **check**(byte[] pin,
short offset,
byte length)
throws [[javacard:java-card-api:ArrayIndexOutOfBoundsException|ArrayIndexOutOfBoundsException]] ,
[[javacard:java-card-api:NullPointerException|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.//
 \\  

 
 

**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:**
[[javacard:java-card-api:ArrayIndexOutOfBoundsException|ArrayIndexOutOfBoundsException]]  - if the check operation would cause access of data outside array bounds.
 
 
[[javacard:java-card-api:NullPointerException|NullPointerException]]  - if pin is null 
 

 
 



 ----


 === isValidated === 
boolean **isValidated**()

Returns true if a valid PIN value has been presented since the last
 card reset or last call to reset().

 
 


**Returns:**true if validated; false otherwise 
 

 
 



 ----


 === 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.
 If the validated flag is not set, this method does nothing.