javacard.framework.PIN Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of jcardsim Show documentation
jCardSim is open-source library contains implementation of Java Card API
There is a newer version: 2.2.2
/*
 * Copyright 2011 Licel LLC.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package javacard.framework;

/**
 * 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 be
 *  presented before the PIN is blocked. When the PIN is blocked, it
 *  cannot 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 PIN
 *  presentation is permitted before the PIN becomes blocked.
 * 
Validated flag - true if a valid PIN has been presented. This flag is
 *   reset 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.
 *
 */
public interface PIN {

    /**
     * Returns the number of times remaining that an incorrect PIN can
     * be presented before the PIN is blocked.
     * @return the number of times remaining
     */
    public abstract byte getTriesRemaining();

    /**
     * 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.
     * @param pin the byte array containing the PIN value being checked
     * @param offset the starting offset in the pin array
     * @param length the length of pin
     * @return true if the PIN value matches; false otherwise
     * @throws ArrayIndexOutOfBoundsException if the check operation would cause access of data outside array bounds.
     * @throws NullPointerException if pin is null
     */
    public abstract boolean check(byte pin[], short offset, byte length)
            throws ArrayIndexOutOfBoundsException, NullPointerException;

    /**
     * Returns true if a valid PIN value has been presented since the last
     * card reset or last call to reset().
     * @return true if validated; false otherwise
     */
    public abstract boolean isValidated();

    /**
     * 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.
     */
    public abstract void reset();
}