net.rim.device.api.userauthenticator
Class UserAuthenticator

java.lang.Object
  extended by net.rim.device.api.userauthenticator.UserAuthenticator

public abstract class UserAuthenticator
extends Object

User authenticator module providing the primary means of interaction with a user authentication token.

Implementation

Note that to derive a user authenticator, you must provide implementations for all the "impl" methods. For each "impl" method there is a corresponding final method which you will not implement, but which the security framework will invoke to access that functionality: the security framework will never directly invoke the "impl" methods; they are wrapped by their final counterparts.

Authentication mechanisms supported

The implementor should use the various AUTHENTICATION_MECHANISM static members in this class to indicate to the security framework (through its invocation of UserAuthenticator.getAuthenticationMechanisms()) which mechanisms this authenticator supports.

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 AUTHENTICATION_MECHANISM_FINGERPRINT
          Provides fingerprint authentication.
Category: Signed static int AUTHENTICATION_MECHANISM_OTHER
          Provides an authentication mechanism other than smart card, fingerprint, or proximity.
Category: Signed static int AUTHENTICATION_MECHANISM_PROXIMITY
          Provides proximity authentication.
Category: Signed static int AUTHENTICATION_MECHANISM_SMART_CARD
          Provides smart card authentication.
Category: Signed static int CONTEXT_OPTIONS_SCREEN
          Add a field in the password options screen when this authenticator is active.
Category: Signed static int MAX_STATE_DATA_LENGTH
          Maximum allowed length of authenticator state data the system can handle.
 
Method Summary
Category: Signed  void authenticate(SecurityUIManager securityUIManager, DataBuffer sensitiveStateData, UserAuthenticatorContextObject context)
          Authenticate the device's user with this authenticator.
Category: Signed protected abstract  void authenticateImpl(SecurityUIManager securityUIManager, DataBuffer sensitiveStateData, UserAuthenticatorContextObject context)
          Authenticate the device's user with this authenticator.
Category: Signed  int getAuthenticationMechanisms()
          Retrieve the types of authentication that this authenticator supports.
Category: Signed protected abstract  int getAuthenticationMechanismsImpl()
          Provide the types of authentication that this authenticator supports.
Category: Signed  CodeSigningKey getCodeSigningKey()
          Retrieve code signing key that has signed this authenticator's module.
Category: Signed protected abstract  CodeSigningKey getCodeSigningKeyImpl()
          Provide code signing key that has signed this authenticator's module.
Category: Signed  Field getField(int context)
          Retrieve this user authenticator's field for presentation to the user.
Category: Signed protected abstract  Field getFieldImpl(int context)
          Retrieve this user authenticator's field for presentation to the user.
Category: Signed  Object getInformation(long id, Object parameter, Object defaultValue)
          Retrieve a property from this authenticator.
Category: Signed protected abstract  Object getInformationImpl(long id, Object parameter, Object defaultValue)
          Provide a property from this authenticator.
Category: Signed  String getName()
          Retrieve this authenticator's display name.
Category: Signed protected abstract  String getNameImpl()
          Provide this authenticator's display name.
Category: Signed  boolean initialize(SecurityUIManager securityUIManager, DataBuffer stateData, DataBuffer sensitiveStateData, UserAuthenticatorContextObject context)
          Initialize this authenticator.
Category: Signed protected abstract  boolean initializeImpl(SecurityUIManager securityUIManager, DataBuffer stateData, DataBuffer sensitiveStateData, UserAuthenticatorContextObject context)
          Initialize this authenticator.
Category: Signed  boolean isInitializationPossible()
          Determine if this authenticator has what it needs to be initialized.
Category: Signed protected abstract  boolean isInitializationPossibleImpl()
          Declare if this authenticator has what it needs to be initialized.
Category: Signed  boolean isInitialized()
          Determine if this authenticator is initialized.
Category: Signed protected abstract  boolean isInitializedImpl()
          Declare whether this authenticator is initialized.
Category: Signed  boolean setStateData(DataBuffer stateData)
          Set this authenticator's state data.
Category: Signed protected abstract  boolean setStateDataImpl(DataBuffer stateData)
          Set this authenticator's state data.
Category: Signed  String toString()
          Retrieve this authenticator's display name.
Category: Signed  void uninitialize()
          Uninitialize this authenticator.
Category: Signed protected abstract  void uninitializeImpl()
          Uninitialize this authenticator.
Category: Signed  void verifyPolicySettings(SecurityUIManager securityUIManager, DataBuffer stateData, DataBuffer sensitiveStateData, UserAuthenticatorContextObject context)
          Verify that the authenticator conforms to current IT policy settings.
Category: Signed protected abstract  void verifyPolicySettingsImpl(SecurityUIManager securityUIManager, DataBuffer stateData, DataBuffer sensitiveStateData, UserAuthenticatorContextObject context)
          Verify that the authenticator conforms to current IT policy settings.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 



Field Detail

AUTHENTICATION_MECHANISM_SMART_CARD

public static final int AUTHENTICATION_MECHANISM_SMART_CARD
Provides smart card authentication.

Used if this authenticator supports authentication with a smart card.

See Also:
UserAuthenticator.getAuthenticationMechanisms(), 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

AUTHENTICATION_MECHANISM_FINGERPRINT

public static final int AUTHENTICATION_MECHANISM_FINGERPRINT
Provides fingerprint authentication.

Used if this authenticator supports authentication by biometric fingerprint analysis.

See Also:
UserAuthenticator.getAuthenticationMechanisms(), 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

AUTHENTICATION_MECHANISM_PROXIMITY

public static final int AUTHENTICATION_MECHANISM_PROXIMITY
Provides proximity authentication.

Used if this authenticator supports authentication by proximity to the authentication token.

See Also:
UserAuthenticator.getAuthenticationMechanisms(), 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

AUTHENTICATION_MECHANISM_OTHER

public static final int AUTHENTICATION_MECHANISM_OTHER
Provides an authentication mechanism other than smart card, fingerprint, or proximity.

Used if this authenticator supports some method of authentication not specified by the other AUTHENTICATION_MECHANISM static members in this class.

See Also:
UserAuthenticator.getAuthenticationMechanisms(), 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

MAX_STATE_DATA_LENGTH

public static final int MAX_STATE_DATA_LENGTH
Maximum allowed length of authenticator state data the system can handle.

The security framework permits authenticator implementations to ask the system to store state data (and sensitive state data) that it will pass back to the authenticator after device resets, to allow the authenticator to rebuild its internal state from prior to the reset.

However, the storage resources for this state data are finite. Implementors must constrain by this value the state data they pass back and forth to the system in the state data buffer parameters for these methods: 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), UserAuthenticator.initializeImpl(net.rim.device.api.userauthenticator.SecurityUIManager, net.rim.device.api.util.DataBuffer, net.rim.device.api.util.DataBuffer, net.rim.device.api.userauthenticator.UserAuthenticatorContextObject), UserAuthenticator.verifyPolicySettings(net.rim.device.api.userauthenticator.SecurityUIManager, net.rim.device.api.util.DataBuffer, net.rim.device.api.util.DataBuffer, net.rim.device.api.userauthenticator.UserAuthenticatorContextObject), and UserAuthenticator.verifyPolicySettingsImpl(net.rim.device.api.userauthenticator.SecurityUIManager, net.rim.device.api.util.DataBuffer, net.rim.device.api.util.DataBuffer, net.rim.device.api.userauthenticator.UserAuthenticatorContextObject),

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

CONTEXT_OPTIONS_SCREEN

public static final int CONTEXT_OPTIONS_SCREEN
Add a field in the password options screen when this authenticator is active.

When the user opens the password options screen, the system will request and construct the field provided through getField method. However, the provided field will not actually appear until the user selects this authenticator's selection field in the authenticator choice field.

As long as this authenticator's selection field is not active, the provided field will remain hidden.

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

getName

public final String getName()
Retrieve this authenticator's display name.

Returns:
This authenticator's display name.
See Also:
UserAuthenticator.getNameImpl()
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

getNameImpl

protected abstract String getNameImpl()
Provide this authenticator's display name.

The security framework shows this name to the user in the password options screen (where the user chooses which authenticator to activate). You should ensure this method provides an appropriately localized string.

Returns:
This authenticator's display name.
See Also:
UserAuthenticator.getName()
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

getAuthenticationMechanisms

public final int getAuthenticationMechanisms()
Retrieve the types of authentication that this authenticator supports.

Returns:
Mask of the authentication type values that this authenticator supports.
See Also:
UserAuthenticator.getAuthenticationMechanismsImpl()
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

getAuthenticationMechanismsImpl

protected abstract int getAuthenticationMechanismsImpl()
Provide the types of authentication that this authenticator supports.

Derived classes must return the OR'd combination of all authentication mechanisms that this authenticator supports: use the various AUTHENTICATION_MECHANISM static members defined in this class.

The security framework uses this value to limit the available authenticators when the policy administrator sets the "Allowed Authentication Mechanisms" IT policy item: only those authenticators in accordance with the policy item's value will be eligible for activation.

For example, if your authenticator module provides fingerprint and proximity authentication, this method should return (AUTHENTICATION_MECHANISM_FINGERPRINT | AUTHENTICATION_MECHANISM_PROXIMITY).

Note: this call must be non-blocking; therefore, you should not query an external device (for example a bluetooth-connected authentication token) because of the possible latency with such a connection.

Returns:
Mask of the authentication type values that this authenticator supports.
See Also:
UserAuthenticator.getAuthenticationMechanisms()
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

initialize

public final boolean initialize(SecurityUIManager securityUIManager,
                                DataBuffer stateData,
                                DataBuffer sensitiveStateData,
                                UserAuthenticatorContextObject context)
                         throws UserAuthenticationException
Initialize this authenticator.

Parameters:
securityUIManager - UI manager this authenticator may use for user interaction.
stateData - Non-sensitive state data this authenticator can use to recreate itself; this method should restrict the number of bytes it puts into this buffer to UserAuthenticator.MAX_STATE_DATA_LENGTH or less.
sensitiveStateData - This authenticator's sensitive state data: the security system only presents this data to this authenticator at unlock, and hence this authenticator must not depend on this data to properly start up. This authenticator should not hold a reference to this data or persist it, and it should only be returned from this method. This method should restrict the number of bytes it puts into this buffer to UserAuthenticator.MAX_STATE_DATA_LENGTH or less.
context - Provides extra context that this authenticator may need in order to initialize itself.
Returns:
True if this authenticator has successfully initialized itself; otherwise, false.
Throws:
UserAuthenticationException - if the initialization could not complete (if, for example, the authentication token could not be found).
UserAuthenticationAccessDeniedException - if the user is unable to successfully authenticate with this authenticator.
UserAuthenticationCancelException - if the user prematurely cancels the authentication procedure.
See Also:
UserAuthenticator.initializeImpl(net.rim.device.api.userauthenticator.SecurityUIManager, net.rim.device.api.util.DataBuffer, net.rim.device.api.util.DataBuffer, net.rim.device.api.userauthenticator.UserAuthenticatorContextObject)
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

initializeImpl

protected abstract boolean initializeImpl(SecurityUIManager securityUIManager,
                                          DataBuffer stateData,
                                          DataBuffer sensitiveStateData,
                                          UserAuthenticatorContextObject context)
                                   throws UserAuthenticationException
Initialize this authenticator.

The security framework invokes this method when it must initialize your authenticator. The parameters you use depends on whether your authenticator implements PasswordFrameworkProvider. If you do not implement that interface, then you must handle the user interaction of the authentication process yourself. In this case you must use the simplified UI access granted through the provided security UI manager to do whatever interaction you must do with the user to initialize your module (i.e. authenticate the user). If you do implement the password framework provider interface, then you can piggy-back your authentication onto the back of the security framework's standard password-authentication procedure (the user will see a dialog prompting for the device password and a user authentication password). The security framework passes the gathered user authentication password on to you through this method's context parameter. In this case you may choose to use the provided UI manager to furnish additional information to the user, but you do not need to.

Note: the provided UI manager is of temporary use only; it will be disabled immediately when this method returns to the caller. Therefore, there is no point in maintaining a reference to it, or attempting to use it outside of the scope of this method.

Parameters:
securityUIManager - You may use this UI manager during the scope of this method to interact with the device's user in a simple fashion.
stateData - Non-sensitive state data this authenticator can use to recreate itself; this method should restrict the number of bytes it puts into this buffer to UserAuthenticator.MAX_STATE_DATA_LENGTH or less.
sensitiveStateData - This authenticator's sensitive state data: the security system only presents this data to this authenticator at unlock, and hence this authenticator must not depend on this data to properly start up. This authenticator should not hold a reference to this data or persist it, and it should only be returned from this method. This method should restrict the number of bytes it puts into this buffer to UserAuthenticator.MAX_STATE_DATA_LENGTH or less.
context - provides extra context that the authenticator may need in order to initialize the authenticator.
Returns:
True if this authenticator has successfully initialized itself; otherwise, false.
Throws:
UserAuthenticationException - if the initialization could not complete (if, for example, the authentication token could not be found).
UserAuthenticationAccessDeniedException - if the user is unable to successfully authenticate with this authenticator.
UserAuthenticationCancelException - if the user prematurely cancels the authentication procedure.
See Also:
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)
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

getCodeSigningKey

public final CodeSigningKey getCodeSigningKey()
Retrieve code signing key that has signed this authenticator's module.

Returns:
Key that signed the code module containing this authenticator, or null, if this authenticator doesn't support code-signing verification.
See Also:
UserAuthenticator.getCodeSigningKeyImpl()
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

getCodeSigningKeyImpl

protected abstract CodeSigningKey getCodeSigningKeyImpl()
Provide code signing key that has signed this authenticator's module.

If this authenticator returns a key through this method, then this authenticator's containing code module must always be signed with that key to properly support module upgrades while the user has the authenticator initialized.

If this method returns null, the system will disable code-signing verification for this authenticator's containing module; however, this is not recommended: higher security authenticators should use this functionality to permit the system to guard against malicious replacements of this authenticator's code module.

The system invokes this method immediately after successful initialization of this authenticator. If this method provides a key, the system immediately verifies that containing module is properly signed with the key. In the event that this authenticator's module is not properly signed with the returned key, the system immediately uninitializes this authenticator, effectively disabling it.

After each device reset, the system verifies that the containing code module is still signed with the key this method provided during initialization. If the module is no longer properly signed with the same key, the user will not be able to unlock the device (and the system will uninitialize this authenticator).

You can use the RIM Signing Authority software to create a code signing key to protects your code signing module.

Returns:
Key that signed the code module containing this authenticator, or null, if this authenticator doesn't support code-signing verification.
See Also:
UserAuthenticator.getCodeSigningKey()
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

uninitialize

public final void uninitialize()
Uninitialize this authenticator.

See Also:
UserAuthenticator.uninitializeImpl()
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

uninitializeImpl

protected abstract void uninitializeImpl()
Uninitialize this authenticator.

Your implementation should clear any state data maintained by your authenticator.

See Also:
UserAuthenticator.uninitialize()
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

isInitialized

public final boolean isInitialized()
Determine if this authenticator is initialized.

Returns:
True if this authenticator has successfully initialized; otherwise, false.
See Also:
UserAuthenticator.isInitializedImpl()
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

isInitializedImpl

protected abstract boolean isInitializedImpl()
Declare whether this authenticator is initialized.

Your implementation should only return true to this method if the authenticator has everything it requires to respond when the framework invokes UserAuthenticator.authenticate(net.rim.device.api.userauthenticator.SecurityUIManager, net.rim.device.api.util.DataBuffer, net.rim.device.api.userauthenticator.UserAuthenticatorContextObject).

Note: this method should not display any UI.

Returns:
True if this authenticator has successfully initialized and can be used for authentication; otherwise, false.
See Also:
UserAuthenticator.isInitialized()
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

authenticate

public final void authenticate(SecurityUIManager securityUIManager,
                               DataBuffer sensitiveStateData,
                               UserAuthenticatorContextObject context)
                        throws UserAuthenticationException
Authenticate the device's user with this authenticator.

Parameters:
securityUIManager - UI manager this authenticator may use for user interaction.
sensitiveStateData - Buffer where this authenticator can place the sensitive state data it may use for authentication.
context - Extra context that this authenticator may need in order to authenticate.
Throws:
UserAuthenticationException - If the authentication could not complete (if, for example, the authentication token could not be found).
UserAuthenticationAccessDeniedException - if the user is unable to successfully authenticate with the authenticator.
UserAuthenticationCancelException - If the user prematurely cancels the authentication procedure.
See Also:
UserAuthenticator.authenticateImpl(net.rim.device.api.userauthenticator.SecurityUIManager, net.rim.device.api.util.DataBuffer, net.rim.device.api.userauthenticator.UserAuthenticatorContextObject)
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

authenticateImpl

protected abstract void authenticateImpl(SecurityUIManager securityUIManager,
                                         DataBuffer sensitiveStateData,
                                         UserAuthenticatorContextObject context)
                                  throws UserAuthenticationException
Authenticate the device's user with this authenticator.

The security framework invokes this method when the user must authenticate with your authenticator. The parameters you use depends on whether your authenticator implements PasswordFrameworkProvider.

If you do not implement that interface, then you must handle the user interaction of the authentication process yourself. In this case, the security framework will provide null for the context parameter, and you must use the simplified UI access granted through the provided security UI manager to do whatever user-interaction you must do to authenticate the user.

If you do implement the password framework provider interface, then you can piggy-back your authentication onto the back of the security framework's standard password-authentication procedure (the user will see a dialog prompting for the device password and a user authentication password). The security framework passes the gathered user authentication password on to you through this method's context parameter. In this case you may choose to use the provided UI manager to furnish additional information to the user, but you do not need to.

Parameter notes

The provided UI manager is of temporary use only; it will be disabled immediately when this method returns to the caller. Therefore, there is no point in maintaining a reference to it, or attempting to use it outside of the scope of this method.

The sensitive state data buffer is an out parameter, providing a place where the implementation can pass state back to the security framework for storage. Implementors should take care not to hold a reference to this parameter, persist it, or use it outside the scope of this method. Implementors should also take care to respect the value of UserAuthenticator.MAX_STATE_DATA_LENGTH.

Parameters:
securityUIManager - You may use this UI manager during the scope of this method to interact with the device's user in a simple fashion.
sensitiveStateData - Buffer where this authenticator can place the sensitive state data it may use for authentication; the invoking system will protect and store this data, but will provide it back only during the unlock process, so it must not be depended upon for startup purposes.
context - Extra context that this authenticator may need in order to authenticate.
Throws:
UserAuthenticationException - If the authentication could not complete (if, for example, the authentication token could not be found).
UserAuthenticationAccessDeniedException - If the user is unable to successfully authenticate with the authenticator.
UserAuthenticationCancelException - If the user prematurely cancels the authentication procedure.
See Also:
UserAuthenticator.authenticate(net.rim.device.api.userauthenticator.SecurityUIManager, net.rim.device.api.util.DataBuffer, net.rim.device.api.userauthenticator.UserAuthenticatorContextObject)
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

setStateData

public final boolean setStateData(DataBuffer stateData)
Set this authenticator's state data.

Parameters:
stateData - Bundle of state data to be validated.
Returns:
True if the state data has been validated and accepted as value; otherwise, false.
See Also:
UserAuthenticator.setStateDataImpl(net.rim.device.api.util.DataBuffer)
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

setStateDataImpl

protected abstract boolean setStateDataImpl(DataBuffer stateData)
Set this authenticator's state data.

The framework will invoke this method if the device has reset, and if your authenticator is currently registered and was the active authenticator when the device reset. The framework furnishes its persisted copy of the state data to your authenticator to keep it in sync with its own state.

This bundle of state data should be exactly the same as the data you provided when the framework invoked UserAuthenticator.initialize(SecurityUIManager, DataBuffer, DataBuffer, UserAuthenticatorContextObject) during the initialization/activation process.

Your implementation should parse this data to verify its correctness and initialize any internal state you maintain with this data. If you determine that the data is invalid, this method should return false. In this case, the security framework will ensure that the user cannot unlock the device and your authenticator will no longer be accessed. To make the device usable again, the user will have to security wipe the device, removing user data and the choice of the active authenticator.

Latency and UI issues

Your implementation of this method should not present any UI.

Also because this method could involve latency in communication with the authentication token, invokers of this method will do so on a background thread, to avoid delaying event handling. Your implementation should also not block for any long period of time. If you have need to do additional initialization, you can complete that when the framework next invokes UserAuthenticator.authenticate(net.rim.device.api.userauthenticator.SecurityUIManager, net.rim.device.api.util.DataBuffer, net.rim.device.api.userauthenticator.UserAuthenticatorContextObject).

Parameters:
stateData - Bundle of state data that you must validate.
Returns:
True if your authenticator has validated the state data and accepted it as valid; otherwise, false.
See Also:
UserAuthenticator.setStateData(net.rim.device.api.util.DataBuffer)
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

getInformation

public final Object getInformation(long id,
                                   Object parameter,
                                   Object defaultValue)
                            throws UserAuthenticationException
Retrieve a property from this authenticator.

Parameters:
id - Identifier for the property being queried.
parameter - Parameter information for the property.
defaultValue - Default value for the property.
Returns:
Property matching query.
Throws:
UserAuthenticationException - If an error occurs and this authenticator cannot retrieve the requested information.
See Also:
UserAuthenticator.getInformationImpl(long, java.lang.Object, java.lang.Object)
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

getInformationImpl

protected abstract Object getInformationImpl(long id,
                                             Object parameter,
                                             Object defaultValue)
                                      throws UserAuthenticationException
Provide a property from this authenticator.

This is a generic accessor for parameterized information that might prove useful going forward. The security framework itself is not guaranteed to invoke UserAuthenticator.getInformation(long, java.lang.Object, java.lang.Object), however, it could be used in the future to provide access to transient property information about your authenticator.

Parameters:
id - Identifier for the property being queried.
parameter - Parameter information for the property.
defaultValue - Default value for the property.
Returns:
Property matching query.
Throws:
UserAuthenticationException - If an error occurs and this authenticator cannot retrieve the requested information.
See Also:
UserAuthenticator.getInformation(long, java.lang.Object, java.lang.Object)
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

isInitializationPossible

public final boolean isInitializationPossible()
                                       throws UserAuthenticationException
Determine if this authenticator has what it needs to be initialized.

Returns:
true if this authenticator could be initialized given the current state of the system; otherwise, false.
Throws:
UserAuthenticationException - If an error occurs and this authenticator cannot determine if it could be initialized.
See Also:
UserAuthenticator.isInitializationPossibleImpl()
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

isInitializationPossibleImpl

protected abstract boolean isInitializationPossibleImpl()
                                                 throws UserAuthenticationException
Declare if this authenticator has what it needs to be initialized.

For efficiency's sake, the security framework needs a way to determine if your user authenticator module has all the resources it needs to attempt initialization. For example, are the right drivers or dependent modules installed?

This method should not present any UI to the user. The security options item invokes UserAuthenticator.isInitializationPossible() to determine if it can present this user authenticator field in the options list presented to the user of authenticators that could be activated. If this method returns false, the user will not see this authenticator listed as one available for activation.

Returns:
true if this authenticator could be initialized given the current state of the system; otherwise, false.
Throws:
UserAuthenticationException - If an error occurs and this authenticator cannot determine if it could be initialized (for example, if the module has not yet, or cannot, load a driver required to communicate with the authentication token).
See Also:
UserAuthenticator.isInitializationPossible()
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

verifyPolicySettings

public final void verifyPolicySettings(SecurityUIManager securityUIManager,
                                       DataBuffer stateData,
                                       DataBuffer sensitiveStateData,
                                       UserAuthenticatorContextObject context)
                                throws UserAuthenticationException
Verify that the authenticator conforms to current IT policy settings.

Parameters:
securityUIManager - UI manager this authenticator may use for user interaction.
stateData - Buffer where this authenticator can place updated state data used to recreate itself at startup; must be less bytes than the value of UserAuthenticator.MAX_STATE_DATA_LENGTH.
sensitiveStateData - Buffer where this authenticator can place updated sensitive state data it may use for authentication during the unlock process; must be less bytes than the value of UserAuthenticator.MAX_STATE_DATA_LENGTH.
context - Extra context that this authenticator may need in order to verify the IT policies.
Throws:
UserAuthenticationException - if the authenticator cannot verify its conformance to the current policy settings.
See Also:
UserAuthenticator.verifyPolicySettingsImpl(net.rim.device.api.userauthenticator.SecurityUIManager, net.rim.device.api.util.DataBuffer, net.rim.device.api.util.DataBuffer, net.rim.device.api.userauthenticator.UserAuthenticatorContextObject)
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

verifyPolicySettingsImpl

protected abstract void verifyPolicySettingsImpl(SecurityUIManager securityUIManager,
                                                 DataBuffer stateData,
                                                 DataBuffer sensitiveStateData,
                                                 UserAuthenticatorContextObject context)
                                          throws UserAuthenticationException
Verify that the authenticator conforms to current IT policy settings.

If IT policy changes, the security framework invokes UserAuthenticator.verifyPolicySettings(net.rim.device.api.userauthenticator.SecurityUIManager, net.rim.device.api.util.DataBuffer, net.rim.device.api.util.DataBuffer, net.rim.device.api.userauthenticator.UserAuthenticatorContextObject) the next time the device locks, in order to ensure that this authenticator is still in accord with the policy settings. Note that all applicable IT policy items that apply to this authenticator must be respected by your implementation.

For example, a smart card user authenticator may not be currently configured to use an authentication certificate. If the IT policy administrator changes to mandate the use of one, the framework invokes this method and the authenticator will now need to be configured with an authentication certificate.

This method should block until the authenticator is correctly configured.

This method may use the provided security UI manager to provide a simple message to the user about the changes to the IT policy settings.

Parameter notes

The provided UI manager is of temporary use only; it will be disabled immediately when this method returns to the caller. Therefore, there is no point in maintaining a reference to it, or attempting to use it outside of the scope of this method.

The state data buffers are out parameters, providing a place where the implementation can pass state back to the security framework for storage. Implementors should take care note to hold a reference to these parameters, persist them, or use them outside the scope of this method. Implementors should also take care to respect the value of UserAuthenticator.MAX_STATE_DATA_LENGTH.

Parameters:
securityUIManager - UI manager this authenticator may use for user interaction.
stateData - Buffer where this authenticator can place updated state data used to recreate itself at startup. The state data you provide into this buffer replaces any previous state data this authenticator has provided. If you provide no data in this buffer, the system will remove any previously provided state data.
sensitiveStateData - Buffer where this authenticator can place the sensitive state data it may use for authentication; the invoking system will protect and store this data, but will provide it only at unlock time, so your implementation should not require this data for startup purposes. The data you provide into this buffer replaces any previously provided sensitive state data. If you provide no data in this buffer, the system will remove any previously provided sensitive state data.
context - Extra context that this authenticator may need in order to verify the IT policies.
Throws:
UserAuthenticationException - if this authenticator cannot verify its conformance to the current policy settings.
See Also:
UserAuthenticator.verifyPolicySettings(net.rim.device.api.userauthenticator.SecurityUIManager, net.rim.device.api.util.DataBuffer, net.rim.device.api.util.DataBuffer, net.rim.device.api.userauthenticator.UserAuthenticatorContextObject)
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

toString

public String toString()
Retrieve this authenticator's display name.

Overrides:
toString in class Object
Returns:
Display name of this authenticator.
See Also:
UserAuthenticator.getName()
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

getField

public final Field getField(int context)
Retrieve this user authenticator's field for presentation to the user.

Note that the implementing authenticator should ensure that the field is appropriately localized.

Parameters:
context - Current context for requesting the field; this should be one of the static data CONTEXT values defined in this interface.
Returns:
Field to present to the user for the provided context.
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

getFieldImpl

protected abstract Field getFieldImpl(int context)
Retrieve this user authenticator's field for presentation to the user.

Note that the implementing authenticator should ensure that the field is appropriately localized.

Parameters:
context - Current context for requesting the field; this should be one of the static data CONTEXT values defined in this interface.
Returns:
Field to present to the user for the provided context.
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-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal