SecurityControl Class Reference

Class to manage initialization of the runtime library. More...

Description

This class contains the methods needed to initialize the BlackBerry Spark AppSecure library within your application.

Initialization States

The BlackBerry Spark AppSecure runtime maintains the initialization state of the library within the application. The programming interfaces that can be utilized by the application depend on its current initialization state.

The state of the runtime when the application starts is 'Initial'. In this state the application can call enableSecurity but cannot utilize any principal interfaces, such as getting the threat status or changing security configuration.

After the first time enableSecurity has been called, the runtime enters the 'Registration' state. In this state the library is initialized, secure storage is provisioned and the recommended setting for detecting threats is configured. However, the library is not yet active. To enable the library so it can retrieve the latest detection models from BlackBerry and scan for threats a valid user identity token is required.

Call provideToken including a valid OpenID Connect Identity token for the user. This token may be issued by any OpenID Connect compliant Identity Provider used by your application.

While the token is being validated by BlackBerry Identity the runtime will transition momentarily to the 'Token Validation' state. Once validated the library will automatically transition to the 'Active' state. In this state all the principle interfaces may be utilized. The application should generally wait to be notified of transition to the 'Active' state before attempting to utilize any other BlackBerry Spark AppSecure interfaces.

Access to the interfaces may be temporarily withdrawn if the Identity Token for the user expires. When this happens the initialization state changes to 'Token Expired'. To keep the library active, call provideToken with an updated Identity Token.

Application Authentication

This optional feature enables a user to set an application password or PIN during setup which is then required to subsequently login to the application. Requiring an application password further protects access to the runtime's Secure Storage and controls authorized access when the device is off-line.

Call enableSecurity() with the configuration key 'AuthenticationRequired' to enable this feature. See com.blackberry.security.auth.AppAuthentication for details.

Public Member Functions
boolean	enableSecurity ()
	Call this method to initialize BlackBerry Spark AppSecure runtime library. More...
boolean	enableSecurity (Bundle configuration)
	Call this method to initialize BlackBerry Spark AppSecure runtime library including configuration. More...
void	provideToken (String aToken)
	Provide the Identity Token (JWT) of your authenticated user from your Identity Provider. More...
void	registerReceiver (BroadcastReceiver receiver, IntentFilter filter)
	Register to receive local broadcasts from runtime library on library state changes or Threat status changes. More...
void	unregisterReceiver (BroadcastReceiver receiver)
	Remove a previously registered BroadcastReceiver. More...
boolean	isSecurityEnabled ()
	Checks if the runtime library has been enabled. More...
InitializationState	getCurrentState ()
	Provides the current state of runtime initialization. More...
boolean	deactivate ()
	Call this method to deactivate the runtime library. More...

Static Public Attributes
static final String	ACTION_INITIALIZATION_STATE_NOTIFICATION = "BBDInitializationStatus"
	Intent Filter key for InitializationState changes. More...
static final String	CONFIGURATION_KEY_CLIENTID = "ClientID"
	Constant key value for providing the BlackBerry Application Client ID. More...
static final String	CONFIGURATION_KEY_AUTHENTICATION_REQUIRED = "AuthenticationRequired"
	Constant key value to indicate if authentication should be required by the runtime. More...
static final String	CONFIGURATION_KEY_PASSWORD_MAX_ATTEMPTS = "PWMaxTries"
	Constant key value to control the number of unsuccessful login attempts permitted. More...

Member Function Documentation

enableSecurity() [1/2]

boolean enableSecurity

(

)

Initialization sets up security policies and configurations as recommended by BlackBerry.

The following example demonstrates how to initialize the library.

Example (Java)

private SecurityControl mSecurity;
 
protected void onCreate(Bundle savedInstanceState) {
 
...
 
// Initialize BlackBerry Security Library
mSecurity = new SecurityControl(this.getApplicationContext());
mSecurity.enableSecurity();
 
...
 
}

After initialization the runtime will transition to the REGISTRATION InitializationState. To register this instance of the runtime with BlackBerry and change the state to ACTIVE the next step is to provide a valid token from your Identity Provider. See SecurityControl.provideToken.

The library must be in the `INITIAL` InitializationState for the request to be successful.

Returns

`true` in case of successful initialization, `false` otherwise.

enableSecurity() [2/2]

boolean enableSecurity

(

Bundle

configuration

)

The following example demonstrates how to initialize the library with configuration to require an application password.

Example (Java)

private SecurityControl mSecurity;
 
protected void onCreate(Bundle savedInstanceState) {
 
...
 
// Initialize BlackBerry Security Library with authentication enabled and a maximum of 5 unsuccessful password attempts.
mSecurity = new SecurityControl(this.getApplicationContext());
Bundle configuration = new Bundle();
configuration.putBoolean(SecurityControl.CONFIGURATION_KEY_AUTHENTICATION_REQUIRED, true);
configuration.putInt(SecurityControl.CONFIGURATION_KEY_PASSWORD_MAX_ATTEMPTS, 5);
mSecurity.enableSecurity(configuration);
...
 
}

After initialization the runtime will transition to the AUTHENTICATION_REQUIRED`InitializationState`. For details on how to set the password, see AppAuthentication.setPassword.

The library must be in the `INITIAL` InitializationState for the request to be successful.

Returns

`true` in case of successful initialization, `false` otherwise.

provideToken()

void provideToken

(

String

aToken

)

Call this method to provide a JSON Web Token (JWT) identity token which belongs to the application end user. The ID token should be retrieved from your OpenID Connect Identity Provider (IDP) after the user has been authenticated.

Overview

The BlackBerry Spark AppSecure runtime reuses the existing user identity within your application to facilitate getting the latest security threat information from the BlackBerry Cloud. The library works with your user identity and management systems to provide strong authentication and authorization. An OpendID Connect Identity Token is used as authorization from your Identity Provider which avoids the need to rely on an application-specific API Key.

An ID Token is a JWT (JSON Web Token), that is a cryptographically signed Base64-encoded JSON object (See https://tools.ietf.org/html/rfc7519). To retrieve the ID token from your IDP you'll need to have already authenticated the user.

Usage

Call this method including a valid OpenID Connect JWT Identity Token from your Identity Provider to transition the runtime from REGISTRATION to ACTIVE InitializationState,

See the Getting Started section of the Developer Guide for detailed instructions on how to configure your Identity Provider.

registerReceiver()

void registerReceiver	(	BroadcastReceiver	receiver,
		IntentFilter	filter
	)

To receive a local broadcast when the InitializationState of the library changes register to intent action SecurityControl.ACTION_INITIALIZATION_STATE_NOTIFICATION,

Example (Java)

private SecurityControl mSecurity;
..
..
IntentFilter filter = new IntentFilter();
filter.addAction(ThreatStatus.ACTION_INITIALIZATION_STATE_NOTIFICATION);
 
mSecurity.registerReceiver(new BroadcastReceiver() {
@Override
   public void onReceive(Context context, Intent intent) {
             //Receive library InitializationState Notifications
             InitializationState state = (InitializationState) intent.getSerializableExtra(InitializationState.KEY_SERIALIZABLE);
             ErrorType error = (ErrorType)intent.getSerializableExtra(InitializationState.KEY_ERRORTYPE);
             int httpStatus = intent.getIntExtra(InitializationState.KEY_HTTPSTATUSCODE, 0);
             // flag to inform of a cancelled biometric authentication attempt
             boolean isBiometryCancelled = intent.getBooleanExtra(InitializationState.KEY_BIOMETRY_CANCELLED, false);
   }
 }, filter);

To receive a local broadcast when the ThreatStatus changes register to intent action SecurityControl.ACTION_THREAT_STATE_NOTIFICATION,

Example (Java)

private SecurityControl mSecurity;
..
..
IntentFilter filter = new IntentFilter();
filter.addAction(ThreatStatus.ACTION_THREAT_STATE_NOTIFICATION);
 
mSecurity.registerReceiver(new BroadcastReceiver() {
@Override
   public void onReceive(Context context, Intent intent) {
   //Receive Threat State Notification
   //schedule Application specific actions based on Threat State updates received
   }
 }, filter);

unregisterReceiver()

void unregisterReceiver

(

BroadcastReceiver

receiver

)

Remove or unregister a previously registered BroadcastReceiver

isSecurityEnabled()

boolean isSecurityEnabled

(

)

This method determines if the runtime library has been enabled.

Returns

true if the library is enabled.

getCurrentState()

InitializationState getCurrentState

(

)

This method returns the current InitializationState of the runtime. To be notified of state changes, use SecurityControl.registerReceiver.

deactivate()

boolean deactivate

(

)

This will remove all the settings and application data that has been stored by the application in secure storage.

Returns

`true` in case of successful deactivation, `false` otherwise.

Member Data Documentation

ACTION_INITIALIZATION_STATE_NOTIFICATION

final String ACTION_INITIALIZATION_STATE_NOTIFICATION = "BBDInitializationStatus"

static

This type of broadcast event will be dispatched when the InitializationState of the library changes

CONFIGURATION_KEY_CLIENTID

final String CONFIGURATION_KEY_CLIENTID = "ClientID"

static

Constant key value for providing the BlackBerry Application Client ID. Optionally use this instead of setting com.blackberry.security.ClientID within AndroidManifest.xml

Set Client ID value as a string.

CONFIGURATION_KEY_AUTHENTICATION_REQUIRED

final String CONFIGURATION_KEY_AUTHENTICATION_REQUIRED = "AuthenticationRequired"

static

Constant key value to indicate if authentication should be required by the runtime.

Set value as a boolean where true means authentication is enabled.

See com.blackberry.security.auth.AppAuthentication

CONFIGURATION_KEY_PASSWORD_MAX_ATTEMPTS

final String CONFIGURATION_KEY_PASSWORD_MAX_ATTEMPTS = "PWMaxTries"

static

Constant key value to control the number of unsuccessful login attempts permitted when entering the password. If this limit is exceed the runtime is deactivated and will need to be setup again.

Set max password attempts value as an int.