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.

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.

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. .

MAX_PASSWORD_LENGTH

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.

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".

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.

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. .

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".

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.

getMaxAuthenticationAttempts

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).

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.

getRemainingAuthenticationAttempts

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).

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.

getPasswordPrompt

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.

getPasswordPromptRequired

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.