org.simalliance.openmobileapi

Class AuthenticationProvider

java.lang.Object

org.simalliance.openmobileapi.Provider

org.simalliance.openmobileapi.AuthenticationProvider

public class AuthenticationProvider
extends Provider

This Authentication class can be used to privilege a certain communication channel to the Secure Element for operations that requires a PIN authentication. Besides the PIN verification for authentication this class provides also PIN management command for changing, deactivating or activating PINs.

Prerequisites: The PIN operations performed by this AuthenticationProvider class are based on the ISO/IEC 7816-4 specification and require a preselected applet on the specified communication channel to the Secure Element that implements ISO/IEC 7816-4 compliant PIN commands.

Notes:

• If used by multiple threads, synchronization is up to the application.
• Each operation needs an access to the Secure Element. If the access can not be granted because of a closed channel or a missing security condition the called method will return an error.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	AuthenticationProvider.PinID This PIN ID uniquely identifies a PIN in the Secure Element system.

Constructor Summary

Constructors

Constructor and Description
AuthenticationProvider(Channel channel) Encapsulates the defined channel by an AuthenticationProvider object that can be used for applying PIN commands on it.

Method Summary

Methods

Modifier and Type	Method and Description
void	activatePin(AuthenticationProvider.PinID pinID, byte[] pin) Activates the PIN.
void	changePin(AuthenticationProvider.PinID pinID, byte[] oldPin, byte[] newPin) Changes the PIN.
void	deactivatePin(AuthenticationProvider.PinID pinID, byte[] pin) Deactivates the PIN.
int	getRetryCounter(AuthenticationProvider.PinID pinID) Returns the retry counter of the referenced PIN.
void	resetPin(AuthenticationProvider.PinID pinID, byte[] resetPin, byte[] newPin) Resets the PIN with the reset PIN or just resets the retry counter.
boolean	verifyPin(AuthenticationProvider.PinID pinID, byte[] pin) Performs a PIN verification.

Methods inherited from class org.simalliance.openmobileapi.Provider

getChannel

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AuthenticationProvider

public AuthenticationProvider(Channel channel)
                       throws java.lang.IllegalStateException

Encapsulates the defined channel by an AuthenticationProvider object that can be used for applying PIN commands on it.

Parameters:

channel - The channel that should be privileged for operations that requires a PIN authentication.

Throws:

java.lang.IllegalStateException - if the defined channel is closed.

Method Detail

verifyPin

public boolean verifyPin(AuthenticationProvider.PinID pinID,
                byte[] pin)
                  throws java.lang.IllegalArgumentException,
                         java.lang.IllegalStateException,
                         java.lang.UnsupportedOperationException,
                         java.io.IOException

Performs a PIN verification.

Parameters:

pinID - The PIN ID references the PIN in the Secure Element which shall be used for the verification.

pin - The PIN that shall be verified.

Returns:

True if the authentication was successful, False if the authentication fails.

Throws:

java.lang.IllegalArgumentException - if the PIN reference as defined couldn't be found in the Secure Element. TODO: should be an IllegalReferenceError

java.lang.IllegalArgumentException - if the PIN value has a bad coding or a wrong length (empty or too long).

java.lang.IllegalStateException - if the used channel is closed.

java.lang.UnsupportedOperationException - if this operation is not supported.

java.io.IOException - Lower-lever API exception.

changePin

public void changePin(AuthenticationProvider.PinID pinID,
             byte[] oldPin,
             byte[] newPin)
               throws java.lang.SecurityException,
                      java.lang.IllegalArgumentException,
                      java.lang.IllegalStateException,
                      java.lang.UnsupportedOperationException,
                      java.io.IOException

Changes the PIN.

Note: This method is based on the ISO/IEC 7816-4 command CHANGE REFERENCE DATA.

Parameters:

pinID - The PIN ID references the PIN in the Secure Element which shall be changed.

oldPin - The old PIN that shall be changed.

newPin - The PIN that shall be set as new PIN.

Throws:

java.lang.SecurityException - if old PIN does not match with the PIN stored in the SE. The PIN is not changed.

java.lang.IllegalArgumentException - if the PIN reference as defined couldn't be found in the Secure Element. TODO: should be an IllegalReferenceError

java.lang.IllegalArgumentException - if the value of oldPin or newPIN has a bad coding or a wrong length (empty or too long).

java.lang.IllegalStateException - if the used channel is closed.

java.lang.UnsupportedOperationException - if this operation is not supported.

java.io.IOException - Lower-lever API exception.

resetPin

public void resetPin(AuthenticationProvider.PinID pinID,
            byte[] resetPin,
            byte[] newPin)
              throws java.lang.SecurityException,
                     java.lang.IllegalArgumentException,
                     java.lang.IllegalStateException,
                     java.lang.UnsupportedOperationException,
                     java.io.IOException

Resets the PIN with the reset PIN or just resets the retry counter.

Note: This method is based on the ISO/IEC 7816-4 command RESET RETRY COUNTER.

Parameters:

pinID - The PIN ID references the PIN in the Secure Element which shall be reset.

resetPin - The reset PIN that shall be used for reset.

newPin - The PIN that shall be set as new PIN. Can be omitted with null if just the reset counter shall be reset.

Throws:

java.lang.SecurityException - if resetPin does not match with the "resetPin" stored in the SE. The PIN or reset counter is not changed.

java.lang.IllegalArgumentException - if the PIN ID reference as defined couldn't be found in the secure element. TODO: should be an IllegalReferenceError

java.lang.IllegalArgumentException - if the value of resetPin or newPin has a bad coding or a wrong length (empty or too long).

java.lang.IllegalStateException - if the used channel is closed.

java.lang.UnsupportedOperationException - if the resetPin is not defined, or if the operation is not supported.

java.io.IOException - Lower-lever API exception.

getRetryCounter

public int getRetryCounter(AuthenticationProvider.PinID pinID)
                    throws java.lang.IllegalArgumentException,
                           java.lang.IllegalStateException,
                           java.lang.UnsupportedOperationException,
                           java.io.IOException

Returns the retry counter of the referenced PIN.

Note: This method is based on the ISO/IEC 7816-4 command VERIFY.

Parameters:

pinID - The PIN ID references the PIN in the Secure Element and its retry counter.

Returns:

The retry counter of the referenced PIN.

Throws:

java.lang.IllegalArgumentException - if the PIN reference as defined couldn't be found in the Secure Element. TODO: should be an IllegalReferenceError

java.lang.IllegalStateException - if the used channel is closed or if PIN PIN verification is not required for this pinID.

java.lang.UnsupportedOperationException - if this operation is not supported.

java.io.IOException - Lower-lever API exception.

java.lang.IllegalArgumentException - if pinID is null.

activatePin

public void activatePin(AuthenticationProvider.PinID pinID,
               byte[] pin)
                 throws java.lang.SecurityException,
                        java.lang.IllegalStateException,
                        java.lang.IllegalArgumentException,
                        java.lang.UnsupportedOperationException,
                        java.io.IOException

Activates the PIN. Thus a deactivated PIN can be used again.

Note: This method is based on the ISO/IEC 7816-4 command ENABLE VERIFICATION REQUIREMENT.

Parameters:

pinID - The PIN ID references the PIN in the Secure Element which shall be activated

pin - the verification PIN for activating the PIN if required. Can be omitted with null if not required.

Throws:

java.lang.SecurityException - if the defined pin does not match with the PIN needed for the activation. The PIN state will not be changed.

java.lang.IllegalStateException - if the used channel is closed.

java.lang.IllegalArgumentException - if the PIN reference as defined couldn't be found in the Secure Element TODO: should be an IllegalReferenceError

java.lang.IllegalArgumentException - if the PIN value has a bad coding or a wrong length (empty or too long).

java.lang.UnsupportedOperationException - if this operation is not supported.

java.io.IOException - Lower-lever API exception.

deactivatePin

public void deactivatePin(AuthenticationProvider.PinID pinID,
                 byte[] pin)
                   throws java.lang.SecurityException,
                          java.lang.IllegalStateException,
                          java.lang.IllegalArgumentException,
                          java.lang.UnsupportedOperationException,
                          java.io.IOException

Deactivates the PIN. Thus the objects which are protected by the PIN can now be used without this restriction until activatePin() is called.

Note - This method is based on the ISO/IEC 7816-4 command DISABLE VERIFICATION REQUIREMENT.

Parameters:

pinID - The PIN ID references the PIN in the Secure Element which shall be deactivated.

pin - the verification PIN for deactivating the pin if required. Can be omitted with null if not required.

Throws:

java.lang.SecurityException - if the defined pin does not match with the PIN needed for the deactivation. The PIN state will not be changed.

java.lang.IllegalStateException - if the used channel is closed.

java.lang.IllegalArgumentException - if the PIN reference as defined couldn't be found in the Secure Element TODO: should be an IllegalReferenceError

java.lang.IllegalArgumentException - if the PIN value has a bad coding or a wrong length (empty or too long).

java.lang.UnsupportedOperationException - if this operation is not supported.

java.io.IOException - Lower-lever API exception.