SecurityControl

@objc
public class SecurityControl : NSObject

Class to manage initialization of the runtime library.

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

Initialization States

The BlackBerry 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 InitializationState/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.
The first time enableSecurity() is called, the runtime enters the InitializationState/registration state. In this state the library is initialized, secure storage is provisioned and the recommended settings 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 InitializationState/tokenValidation state.
Once validated the library will automatically transition to the InitializationState/active state. In this state all the principle interfaces may be utilized. The application should generally wait to be notified of transition to the InitializationState/active state before attempting to utilize any other BlackBerry 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 InitializationState/tokenExpired. 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 InitializationState/authenticationRequired to enable this feature. See AppAuthentication for details.

Initialize and Control Library

shared
The SecurityControl singleton instance.
Declaration
Swift

public static let shared: SecurityControl
enableSecurity()
Call this function to initialize the runtime library.

Overview

Initialization sets up security policies and configurations as recommended by BlackBerry. For information on the default settings or to change the configuration please refer to the Configuration section of this reference.

Usage

The library must be in the initial for the request to be successful.

The following demonstrates how to initialize the library within your class.

Import the BlackBerrySecurity module into your class.
```
import BlackBerrySecurity
```
Initialize the BlackBerrySecurity framework and invoke enableSecurity.
```
SecurityControl.shared.enableSecurity()
```
After initialization the runtime will transition to the registration. 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 provideToken(_:).
Declaration
Swift

@discardableResult public func enableSecurity() -> Bool
Return Value

true in case of successful initialization, false otherwise.
enableSecurity(with:)
Call this function to initialize the runtime library with configuration.

Overview

Use this variant of enableSecurity to provide specific configuration during initialization.

Usage

The library must be in the initial for the request to be successful.

The following demonstrates how to initialize the library and include the configuration to enable application authentication.

Initialize the BlackBerrySecurity framework and invoke enableSecurity.
```
let configuration = [SecurityControl.configurationKeyAuthenticationRequired: true]
SecurityControl.shared.enableSecurity(with: configuration)
```
After initialization the runtime will transition to the authenticationRequired. For details on how to set the password, see AppAuthentication.
Declaration
Swift

@discardableResult public func enableSecurity(with configuration: [String : Any]) -> Bool
Return Value

true in case of successful initialization, false otherwise.


                    
                    
                    provideToken(_:)

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 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 RFC-7519 JSON Web Token Reference).

To retrieve the ID token from your IDP you’ll need to have already authenticated the user.

Usage

Call this function, including a valid OpenID Connect JWT Identity Token from your Identity Provider, to transition the runtime fromregistration to active.

For more information on configuring your Identity Provider, see the Developer Guide

Declaration

Swift

public func provideToken(_ token: Data)

Parameters


                                token

A string data of JSON Web Token (JWT) identity token which identifies the user from your OpenID Connect IDP.

deactivate()
Deactivate the library and disable security checks.

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

#### Usage This method cannot be called when the library is in the process of initializing, i.e. immediately after calling enableSecurity() or enableSecurity(with:), etc.
Declaration
Swift

@discardableResult public func deactivate() -> Bool
Return Value

true in case of successful deactivation, false otherwise.
configurationKeyClientID
Configuration key value for providing the BlackBerry Application Client ID. Optionally use this instead of setting ClientID within ‘BlackBerrySecuritySettings’ dictionary in application plist.

Set Client ID as a string.
Declaration
Swift

public static var configurationKeyClientID: String
configurationKeyAuthenticationRequired
Configuration key value to indicate if authentication should be required by the runtime.

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

See AppAuthentication.
Declaration
Swift

public static var configurationKeyAuthenticationRequired: String
configurationKeyPasswordMaxInvalidAttempts
Configuration 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.
Declaration
Swift

public static var configurationKeyPasswordMaxInvalidAttempts: String

Handle State Changes

InitializationState
The possible initialization state of the library.
See more
Declaration
Swift

public enum InitializationState : Int, CaseIterable


                    
                    
                    onStateChange

Callback to handle when the runtime library state changes.

Usage

This example would call the function ‘handleStateChange’ to process the change of InitializationState.

 SecurityControl.shared.onStateChange = handleBlackBerrySecurityStateChange

The function could then handle the tokenExpired state for example:

func handleBlackBerrySecurityStateChange(newState: SecurityControl.InitializationState) {
    if (newState == .error) {
        showAlert(title: "Error", text: "An error occurred initializing BlackBerry Security.")
    }
}

For further examples please refer to the sample application.

Declaration

Swift

public var onStateChange: ((InitializationState) -> Void)?

state
The initialization state of the runtime.
Declaration
Swift

public var state: InitializationState { get }

Errors

httpStatusCode
An HTTP status code in the case of errorType property equals otherHttpResponse.
Declaration
Swift

public private(set) var httpStatusCode: Int { get }
errorType
The returned ErrorType enum in case of error.
Declaration
Swift

public var errorType: ErrorType { get }

SecurityControl

Initialization States

Application Authentication

Initialize and Control Library

Declaration

Overview

Usage

Declaration

Return Value

Overview

Usage

Declaration

Return Value

Overview

Usage

Declaration

Parameters

Declaration

Return Value

Declaration

Declaration

Declaration

Handle State Changes

Declaration

Usage

Declaration

Declaration

Errors

Declaration

Declaration