**javacard.framework** 
 ====Class OwnerPIN  ====
  *[[javacard:java-card-api:object|java.lang.Object]] \\ 


**All Implemented Interfaces:** [[javacard:java-card-api:PIN|PIN]]  
 



 ----

public class **OwnerPIN**extends [[javacard:java-card-api:Object|Object]] implements [[javacard:java-card-api:PIN|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:**[[javacard:java-card-api:PINException|PINException]] , 
[[javacard:java-card-api:PIN|PIN]] , 
[[javacard:java-card-api:Shareable|Shareable]] , 
[[javacard:java-card-api:JCSystem|JCSystem]]  
 


 ----







^ Constructor Summary ^^ 
| **[[javacard:java-card-api:OwnerPIN#OwnerPIN(byte, byte)|OwnerPIN]] **(byte tryLimit,byte maxPINSize)          Constructor. |

 




^ Method Summary ^^ 
| ** boolean** | **[[javacard:java-card-api:OwnerPIN#check(byte[], short, byte)|check]] **(byte[] pin,short offset,byte length)          Compares pin against the PIN value. |
| ** byte** | **[[javacard:java-card-api:OwnerPIN#getTriesRemaining()|getTriesRemaining]] **()          Returns the number of times remaining that an incorrect PIN can be presented before the PIN is blocked. |
| **protected  boolean** | **[[javacard:java-card-api:OwnerPIN#getValidatedFlag()|getValidatedFlag]] **()          This protected method returns the validated flag. |
| ** boolean** | **[[javacard:java-card-api:OwnerPIN#isValidated()|isValidated]] **()          Returns true if a valid PIN has been presented since the last card reset or last call to reset(). |
| ** void** | **[[javacard:java-card-api:OwnerPIN#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. |
| ** void** | **[[javacard:java-card-api:OwnerPIN#resetAndUnblock()|resetAndUnblock]] **()          This method resets the validated flag and resets the PIN try counter to the value of the PIN try limit. |
| **protected  void** | **[[javacard:java-card-api:OwnerPIN#setValidatedFlag(boolean)|setValidatedFlag]] **(boolean value)          This protected method sets the value of the validated flag. |
| ** void** | **[[javacard:java-card-api:OwnerPIN#update(byte[], short, byte)|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 ^ 
| [[javacard:java-card-api:Object#equals(java.lang.Object)|equals]]  |

 






^ Constructor Detail ^ 



 === OwnerPIN === 
public **OwnerPIN**(byte tryLimit,
byte maxPINSize)
throws [[javacard:java-card-api:PINException|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:**
[[javacard:java-card-api:PINException|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.

 
 


 
 



**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.

 
 

**Specified by:**[[javacard:java-card-api:PIN#getTriesRemaining()|getTriesRemaining]]  in interface [[javacard:java-card-api:PIN|PIN]]  
 

 
 



**Returns:**the number of times remaining 
 

 
 



 ----


 === check === 
public 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.//
 \\  

 
 

**Specified by:**[[javacard:java-card-api:PIN#check(byte[], short, byte)|check]]  in interface [[javacard:java-card-api:PIN|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:**
[[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 === 
public boolean **isValidated**()

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

 
 

**Specified by:**[[javacard:java-card-api:PIN#isValidated()|isValidated]]  in interface [[javacard:java-card-api:PIN|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, and the blocking state,
 shall not participate in the transaction.
 If the validated flag is not set, this method does nothing.

 
 

**Specified by:**[[javacard:java-card-api:PIN#reset()|reset]]  in interface [[javacard:java-card-api:PIN|PIN]]  
 

 
 



 
 



 ----


 === update === 
public void **update**(byte[] pin,
short offset,
byte length)
throws [[javacard:java-card-api:PINException|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:**
[[javacard:java-card-api:PINException|PINException]]  - with the following reason codes:
 \\ 
 
  *PINException.ILLEGAL_VALUE if length is greater than configured maximum PIN size.
 \\   
 
**See Also:**[[javacard:java-card-api:JCSystem#beginTransaction()|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.
 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.