Package net.rim.device.api.userauthenticator

This package contains classes and interfaces that let you create and register a user authentication module.

See:
Description

Interface Summary

PasswordFrameworkProvider

Allows the implementing user authenticator to provide the required information to participate in the password-unlock process.

Class Summary

SecurityUIManager	This manager class provides simple user-interface services to user authenticators.
UserAuthenticator	User authenticator module providing the primary means of interaction with a user authentication token.
UserAuthenticatorContextObject	Context objects employed to pass generic data between a user authenticator and the security framework.
UserAuthenticatorManager	System-wide singleton manager to handle user authenticators loaded on the device.

Exception Summary

UserAuthenticationAccessDeniedException	Thrown when the user is unable to authenticate with a user authenticator.
UserAuthenticationCancelException	Thrown when the user cancels the authentication process.
UserAuthenticationException	Thrown when user authentication fails.

Package net.rim.device.api.userauthenticator Description

This package contains classes and interfaces that let you create and register a user authentication module. By creating your own user authentication module, you can provide users with a custom authentication mechanism in addition to the device password. You could, for example, incorporate custom user authentication hardware into the authentication process used by BlackBerry® devices.

Implementation overview

The majority of the work required to implement a user authentication module involves implementing methods of the abstract UserAuthenticator class. The implemented portions of this class are used by the security framework on a BlackBerry device to: initialize the user authentication module, store its name and state, and prompt it to handle user authentication when required.

After implementing a class derived from the UserAuthenticator class, you register it with the device authentication framework by using the registerUserAuthenticator() method of the UserAuthenticatorManager class.

User Interface

There are two circumstances that require a user authenticator to interact with the user of a device: when the user chooses and activates the authenticator and when the security framework requests authentication from the user (most commonly, when the device is locked and a user attempts to unlock the device).

To help user authentication modules safely and easily perform any required user interaction tasks, the framework provides a temporary UI manager implemented by the SecurityUIManager class. When invoking UserAuthenticator methods that might have to interact with the user, a SecurityUIManager is passed as a parameter. If the authenticator interacts with the user, it should use the methods of the SecurityUIManager to do so.

Notice, however, that each security UI manager that the authenticator receives is functional only for the scope of the method to which it is provided. Once the method returns, the framework invalidates the manager, and it cannot be used again.

Options screen

You can provide a Field to display information about your authentication module on the Options->Password screen where a user can select from the authentication methods available on the device. You do so by implementing the getFieldImpl() method of the UserAuthenticator class. The framework calls this method when it requires a Field to display on behalf of your authenticator. An integer-valued context is passed to the method to indicate how the Field will be used. The CONTEXT_OPTIONS_SCREEN value indicates that the Field will be presented to the user on the options screen.

Passphrase authentication

If you are creating an authenticator that relies on a user-supplied passphrase for authentication, then you can leverage the standard device password collecting process by implementing the following interface.

PasswordFrameworkProvider

If you implement this interface in your authenticator, the security framework presents the user with a dialog that collects both the device password and the authentication password. You do not have to implement any UI. The security framework returns the collected password to your authenticator by passing a UserAuthenticatorContextObject to your implementations of the initializeImpl(), authenticateImpl(), and verifyPolicySettingsImpl() methods of the UserAuthenticator class. You retrieve the password by invoking the get method of the context object with UserAuthenticatorContextObject.PASSWORD specified as the parameter.

Registering smart cards with the user authenticator framework

The net.rim.device.api.smartcard package provides a convenient way for you to register smart card drivers as authenticators in the user authenticator framework. You do so by invoking the addSmartCard(newCard,true) method of the SmartCardFactory class. Smart card drivers that are registered this way appear in the list of available Smart Card Authenticators in the authentication options list, and the driver for the currently inserted smart card is chosen as the active smart card authenticator.

You may, however, decide to separate the functionality used to drive the card from the functionality used to perform user authentication. In this case, invoke addSmartCard(newCard,false) to register your smart card driver and register a separate user authenticator module to let users leverage any custom authentication options your card supports.