PasswordFrameworkProvider (BlackBerry JDE 6.0.0 API Reference)

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

net.rim.device.api.userauthenticator
Interface PasswordFrameworkProvider

public interface PasswordFrameworkProvider

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

If the active user authenticator wants to participate in the password-unlock process, then it should implement this interface. This allows the system to retrieve the information it requires to properly incorporate the user authenticator's requirements:

A resource ID (into the user authenticator's locale-appropriate resource bundle) that the security framework should use to provide the text of the authentication prompt message
The maximum number of authentication unsuccessful attempts the user authenticator allows for the user before the authentication token will lock itself
The number of remaining authentication attempts the user has before the authentication token will lock itself

This interface provides a way for the system to proxy user interface handling for the user authenticator; as such, the implementing user authenticator should not construct any UI around the various password events, but rely on the system itself to handle this.

Dealing with latency when communicating with the authentication token

Because the implementor may have to communicate with the authentication token in order to resolve PasswordFrameworkProvider.getMaxAuthenticationAttempts() and PasswordFrameworkProvider.getRemainingAuthenticationAttempts(), those methods could take significant time to complete. Therefore, the implementor should be aware that the invoker of these methods should invoke them on a background thread so they don't hold up event handling.

Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

Field Summary
	`static int`	`MAX_PASSWORD_LENGTH` Maximum length of passwords that implementing authenticators should support.
	`static int`	`PROMPT_CONTEXT_AUTHENTICATE` The password challenge occurs when the user proceeds to unlock the device.
	`static int`	`PROMPT_CONTEXT_INITIALIZE` The password challenge occurs when the user activates this user authenticator from the password options screen.
	`static int`	`PROMPT_CONTEXT_INITIALIZE_FORCED` The password challenge occurs when the IT administrator has forced the use this authenticator through IT policy.
	`static int`	`PROMPT_CONTEXT_REINITIALIZE` The password challenge occurs when the authenticator is already initialized, the Custom Fields of the user Authenticator are changed, and the `getPasswordPromptRequired` returns true. .

Method Summary
	`int`	`getMaxAuthenticationAttempts()` Retrieve the maximum number of authentication attempts the implementor allows.
	`int`	`getMaxPasswordLength()` Determine the maximum password length the implementor supports.
	`int`	`getMinPasswordLength()` Determine the minimum password length the implementor supports.
	`String`	`getPasswordPrompt(int context)` Provide the text shown when prompting for the user authenticator password.
	`boolean`	`getPasswordPromptRequired(int context, UserAuthenticatorContextObject contextObj)` Determine if an initialized authenticator requires a password change at this time.
	`int`	`getRemainingAuthenticationAttempts()` Retrieve the number of remaining authentication attempts the user may make.

Field Detail

MAX_PASSWORD_LENGTH

static final int MAX_PASSWORD_LENGTH

Maximum length of passwords that implementing authenticators should support.

See Also:: Constant Field Values
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

PROMPT_CONTEXT_INITIALIZE

static final int PROMPT_CONTEXT_INITIALIZE

The password challenge occurs when the user activates this user authenticator from the password options screen.

The device's user must enter the user authenticator password in order to initialize the user authenticator when selecting it as the active authenticator from the password options screen.

Collecting the password in this context
In this context, the system will invoke UserAuthenticator.initialize(net.rim.device.api.userauthenticator.SecurityUIManager, net.rim.device.api.util.DataBuffer, net.rim.device.api.util.DataBuffer, net.rim.device.api.userauthenticator.UserAuthenticatorContextObject) to collect the user's password.

See Also:: Constant Field Values
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

PROMPT_CONTEXT_INITIALIZE_FORCED

static final int PROMPT_CONTEXT_INITIALIZE_FORCED

The password challenge occurs when the IT administrator has forced the use this authenticator through IT policy.

The user must enter the user authenticator password in order to initialize the user authenticator when IT policy forces it to activate.

Default value
If the system passes this value into PasswordFrameworkProvider.getPasswordPrompt(int), and you don't return a resource ID, the system will use a properly localized version of "Your IT administrator requires that your user authenticator be initialized. Please enter your user authenticator password".

See Also:: Constant Field Values
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

PROMPT_CONTEXT_AUTHENTICATE

static final int PROMPT_CONTEXT_AUTHENTICATE

The password challenge occurs when the user proceeds to unlock the device.

The user must enter the user authenticator password in order to unlock the device. The system shows the prompt in a single dialog with the device password prompt directly above it. However, if this authenticator also implements HiddenDevicePasswordProvider, then the system presents a dialog prompting only for the user authenticator password.

Collecting the password in this context
In this context, the system will invoke UserAuthenticator.authenticate(net.rim.device.api.userauthenticator.SecurityUIManager, net.rim.device.api.util.DataBuffer, net.rim.device.api.userauthenticator.UserAuthenticatorContextObject) to collect the user's password.

See Also:: Constant Field Values
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

PROMPT_CONTEXT_REINITIALIZE

static final int PROMPT_CONTEXT_REINITIALIZE

The password challenge occurs when the authenticator is already initialized, the Custom Fields of the user Authenticator are changed, and the getPasswordPromptRequired returns true. .

The user must enter the user authenticator password in order to initialize send the password ones more to UserAuthenticator.authenticate(net.rim.device.api.userauthenticator.SecurityUIManager, net.rim.device.api.util.DataBuffer, net.rim.device.api.userauthenticator.UserAuthenticatorContextObject)

Default value
If the system passes this value into PasswordFrameworkProvider.getPasswordPrompt(int), and you don't return a resource ID, the system will use a properly localized version of "The changes to your settings require that user authenticator be re-initialized. Please enter your user authenticator password".

See Also:: Constant Field Values
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

Method Detail

getMaxAuthenticationAttempts

int getMaxAuthenticationAttempts()
                                 throws UserAuthenticationException

Retrieve the maximum number of authentication attempts the implementor allows.

The implementing user authenticator should provide the caller with the maximum number of attempts it will support before the authentication token will lock itself.

Note: Invokers of this method should invoke it on a background thread.

Returns:: Maximum number of authentication attempts allowed. Two special values might be returned: Integer.MAX_VALUE if an infinite number of attempts are allowed; -1 if the maximum number of attempts is not known (for example, if the user authenticator refuses to disclose the value).
Throws:: UserAuthenticationException - Thrown if an error occurs with the authenticator.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

getRemainingAuthenticationAttempts

int getRemainingAuthenticationAttempts()
                                       throws UserAuthenticationException

Retrieve the number of remaining authentication attempts the user may make.

The implementing user authenticator should provide the caller with number of authentication attempts the user may yet make before the authentication token locks itself.

Note: Invokers of this method should invoke it on a background thread.

Returns:: The remaining number of authentication attempts before the authentication token locks itself. Two special values might be returned: Integer.MAX_VALUE if the user may make any number of additional attempts; -1 if the number of remaining attempts allowed is unknown (for example, if the user authenticator refuses to disclose the value).
Throws:: UserAuthenticationException - Thrown if an error occurs with the authenticator.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

getPasswordPrompt

String getPasswordPrompt(int context)

Provide the text shown when prompting for the user authenticator password.

The string should not contain a ":", as it will be automatically appended by the framework.

Parameters:: context - Context in which the password challenge occurs; one of the constant members defined in this interface.
Returns:: Text string the framework should present to the user for the password prompt.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

getMaxPasswordLength

int getMaxPasswordLength()

Determine the maximum password length the implementor supports.

The system will prevent the user from entering a password longer than this size.

Returns:: Maximum password length that this authenticator supports; if 0, less than 0, or greater than PasswordFrameworkProvider.MAX_PASSWORD_LENGTH, then the system assumes that the maximum password length will be the value of MAX_PASSWORD_LENGTH.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

getMinPasswordLength

int getMinPasswordLength()

Determine the minimum password length the implementor supports.

The system will prevent the user from entering a password shorter than this size.

Returns:: Minimum password length that this authenticator supports; the system will enforce a boundary on this value between 0 and the value returned by PasswordFrameworkProvider.getMaxPasswordLength() (for example, if this method returns less than 0, the system will assume the minimum length is 0).
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

getPasswordPromptRequired

boolean getPasswordPromptRequired(int context,
                                  UserAuthenticatorContextObject contextObj)

Determine if an initialized authenticator requires a password change at this time. The system will call this function when some of the fields of an initialized authenticator are changed.

Parameters:: context - Context in which we are called; one of the constant members defined in this interface.; contextObj - Provides extra context that this authenticator may need in order to determine if it needs to prompt for the password at this time.
Returns:: true if a password prompt is required; false otherwise.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0