OwnerPIN (Java Card API, Connected Edition)
Date: 2009-12-11

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javacard.framework
Class OwnerPIN

    java.lang.Object
      javacard.framework.OwnerPIN

All Implemented Interfaces:
  PIN

    @TransactionType(value=SUPPORTS)
    @SensitiveType(sensitivity=FULL)
    public class OwnerPIN

extends Object
implements 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:
  `PINException`, `PIN`, `Shareable`, `JCSystem`

Constructor Summary
`OwnerPIN(byte tryLimit, byte maxPINSize)` Constructor.

Method Summary
`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.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### OwnerPIN

    public OwnerPIN(byte tryLimit,
                    byte maxPINSize)
             throws 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:
    `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:
    `getTriesRemaining` in interface `PIN`
  Returns:
    the number of times remaining

### check

    @TransactionType(value=NOT_SUPPORTED)
    public boolean check(byte[] pin,
                                                           short offset,
                                                           byte length)
                  throws ArrayIndexOutOfBoundsException,
                         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:
    `check` in interface `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:
    `ArrayIndexOutOfBoundsException` - if the check operation would cause access of data outside array bounds.
    `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:
    `isValidated` in interface `PIN`
  Returns:
    `true` if validated; `false` otherwise

### reset

    @TransactionType(value=NOT_SUPPORTED)
    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, shall not participate in the transaction. If the validated flag is not set, this method does nothing.

  Specified by:
    `reset` in interface `PIN`

### update

    public void update(byte[] pin,
                       short offset,
                       byte length)
                throws 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. Note:

  - This method may not clear the blocking state to re-enable the blocked `PIN`.

  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:
    - `PINException.ILLEGAL_VALUE` if length is greater than configured maximum PIN size.
  See Also:
    `JCSystem.beginTransaction()`

### resetAndUnblock

    @TransactionType(value=NOT_SUPPORTED)
    public 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`. 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`.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (c) 2009 Sun Microsystems, Inc. All rights reserved.