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:

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
Category: Signed static int MAX_PASSWORD_LENGTH
          Maximum length of passwords that implementing authenticators should support.
Category: Signed static int PROMPT_CONTEXT_AUTHENTICATE
          The password challenge occurs when the user proceeds to unlock the device.
Category: Signed static int PROMPT_CONTEXT_INITIALIZE
          The password challenge occurs when the user activates this user authenticator from the password options screen.
Category: Signed static int PROMPT_CONTEXT_INITIALIZE_FORCED
          The password challenge occurs when the IT administrator has forced the use this authenticator through IT policy.
Category: Signed 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
Category: Signed  int getMaxAuthenticationAttempts()
          Retrieve the maximum number of authentication attempts the implementor allows.
Category: Signed  int getMaxPasswordLength()
          Determine the maximum password length the implementor supports.
Category: Signed  int getMinPasswordLength()
          Determine the minimum password length the implementor supports.
Category: Signed  String getPasswordPrompt(int context)
          Provide the text shown when prompting for the user authenticator password.
Category: Signed  boolean getPasswordPromptRequired(int context, UserAuthenticatorContextObject contextObj)
          Determine if an initialized authenticator requires a password change at this time.
Category: Signed  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.

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 "User Authenticator Password".

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

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

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

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


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





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.