BlackBerry Dynamics

To run and test any BlackBerry Dynamics app, a BlackBerry UEM server is needed but, with considerable limitations, Enterprise Simulation Mode can be used to test an app without a connection to a BlackBerry UEM server

In Enterprise Simulation Mode, there is no user authentication at the enterprise level, so there will be no communication through the enterprise firewall. If the app requires a connection behind the firewall then a BlackBerry UEM server is needed.

Important: the Enterprise Simulation Mode is not intended for a production environment and it is limited to run on an iOS simulator only.

Although Enterprise Simulation Mode is not suitable for the production deployment of an app, it is useful during development, and for verifying proper execution and behavior when migrating existing apps to BlackBerry Dynamics.

In simulation mode, a valid activation key is not required to open the app because there is no direct communication with BlackBerry Dynamics servers. Communication with the BlackBerry Dynamics NOC, however, continues to take place.

To enable Enterprise Simulation Mode for a BlackBerry Dynamics app, add the following to the Info.plist file:

To disable it, change the value to GDEnterprise or remove the key altogether.

When a BlackBerry Dynamics app is running for the first time on a target, it needs to be activated with the BlackBerry Dynamics server. In Enterprise Simulation Mode, any email address and any 15-character access key are valid to complete the activation process. After the app is activated, the app will prompt the user to create a password.

The Password Requirements link at the bottom of the screen provides guidance on the required password complexity. When not running in Enterprise Simulation Mode the password complexity is controlled via policies managed by your IT admin through the UEM management console.

Enterprise Simulation Mode presents the following differences from standard enterprise execution:

• [Simulated] will appear in the BlackBerry Dynamics Runtime user interface
• Any email address and activation key will be accepted for enterprise activation
• No information is actually sent to enterprise servers, including the email address and activation key
• The provisioning and policy setup flow is simulated in the UI
• A hard-coded set of security and compliance policies are in effect; authentication is not delegated
• When run on a real device, not an emulator, the app will be wiped
• Attempts to change the mode from GDEnterprise to GDEnterpriseSimulation for an app that is already installed on a device will result in the app being wiped
• No lost-password recovery is available
• Inter-container Communication (ICC) cannot be used, which means that the BlackBerry Dynamics Services API cannot be used

Otherwise, the secure storage, secure communication, and push channel APIs are all available in Enterprise Simulation Mode.

The communication APIs will not be able to connect to any enterprise app servers through the UEM server, although direct connections to enterprise app servers can still be made, if, for example, the iOS Simulator is running on a machine that is on the enterprise network or VPN.

BlackBerry UEM or BlackBerry UEM Cloud instance is required to perform testing on an actual smartphone or tablet.

Follow the required steps to configure a BlackBerry Secured app for testing in UEM. If you do not yet have a UEM instance in place, you can configure one with a free developer trial license. Click here to generate a trial license and start configuring your server.

Once the servers are in place, continue with the following steps.

The BlackBerry Dynamics SDK includes the BlackBerry Dynamics Automated Test Support Library (ATSL) to support automated testing for your BlackBerry Dynamics apps.

The library includes helper functions for testing common user interactions in BlackBerry Dynamics apps, such as activation and authorization. The configuration and structure of the library are compatible with the tools offered by Apple for user interface testing.

It makes use of the following components:

• XCTest framework
• Accessibility identifiers

For more information about these components and iOS user interface testing, see Apple Documentation Archive: User Interface Testing.

You can use the BlackBerry Dynamics library and the native library components mentioned above to automate the building, execution, and reporting of your application tests.

Since the BlackBerry Dynamics ATSL is delivered as a framework, you cannot make your own changes to it. If you want to review the implementation and customize it, you can see the source on GitHub at https://github.com/blackberry/BlackBerry-Dynamics-iOS-Samples/tree/master/AutomatedTestSupportLibrary.

The secure file system is part of the BlackBerry Dynamics Secure Storage feature. For apps, the BlackBerry Dynamics secure file system behaves like the default file manager system, with the following differences:

• All data within the secure file system is stored on the device in an encrypted form.
• Directory and file names are also encrypted.
• There is no current working directory in the secure file system. Paths should always be specified as absolute paths, beginning with a / character.
• The secure file system cannot be accessed until BlackBerry Dynamics authorization processing is complete. For more information, see authorize in the GDiOS class reference.

Encryption and decryption are transparent to the app code:

• File-writing interfaces accept plain data. The BlackBerry Dynamics Runtime encrypts the data and stores it on the device.
• When a file-reading interface is utilized, the BlackBerry Dynamics Runtime decrypts what was stored and returns plain data.
• Path access interfaces accept plain parameters for directory and file names. The BlackBerry Dynamics Runtime encrypts the parameter values to create paths in the secure store.
• The directory and file names provided as return values are plain. The BlackBerry Dynamics Runtime decrypts paths in the secure store to generate the return values.

The encryption method used by the BlackBerry Dynamics Runtime generally requires that the user has entered a security password from which an encryption key is derived.

Since the GDFileManager class is a subclass of the native NSFileManager class, minimal changes are required. Simply replace references to NSFileManager with references to GDFileManager.

Comparing before and after code snippets from the two sample apps, you’ll observe the following changes:

Native

import Foundation
...

func writeToNativeFile() -> Bool {
    let text = "Text not protected."
    let fileData = text?.data(using: .utf8)
    let filePath = documentsFolderPathForNamed(name: "NativeFileTest.txt")

    //Create a plain file using FileManager
    let fileCreated = FileManager.default()
        .createFile(atPath: filePath,
            contents: fileData,
            attributes: nil)
    return fileCreated
}



Dynamics

import BlackBerryDynamics.SecureStore.File

...

func writeToGDFile() -> Bool {
    let text = "Text to be protected by BlackBerry Dynamics."
    let fileData = text?.data(using: .utf8)
    let filePath = documentsFolderPathForNamed(name: "EncryptedFileTest.txt")

    //Create an encrypted file using GDFileManager
    let fileCreated = GDFileManager.default()
        .createFile(atPath: filePath,
                contents: fileData,
                attributes: nil)
    return fileCreated
}

The secure SQL database is part of the BlackBerry Dynamics Secure Storage feature. Data stored in the secure SQL database is encrypted on the device by the BlackBerry Dynamics Runtime. The BlackBerry Dynamics secure SQL database is based on the SQLite library. Encryption is added by BlackBerry Dynamics transparently to the app. A secure SQL database cannot be accessed until BlackBerry Dynamics authorization processing is complete.

BlackBerry Dynamics apps access the secure database using replacements for the native SQLite. To access the replacement classes instead of the native classes, change the import statement sqlite3.h to GD_C.SecureStore.SQLite (for Swift sources) or BlackBerryDynamics/GD_C/sqlite3enc.h (for Objective-C sources)

For more information about using SQLite databases, refer to the Secure SQL Database API.

If you compare the modifications required for SQLite between the native samples and the BlackBerry Dynamics sample, you’ll notice that the changes are minimal. Updates are required to the import statements and opening and importing of an encrypted database. The rest of the SQLite in the app can remain as is. Here are the changes that were made:

Native

import SQLite

...

func openDatabase() -> Bool {
    let fileUrl = try! FileManager.default
            .url(for: .documentDirectory,
                in: .userDomainMask,
                appropriateFor:nil,
                create: false)
        .appendingPathComponent("plain_database.db")
    var db:OpaquePointer? = nil
    let result = sqlite3_open(fileUrl.path, &db)

    return result == SQLITE_OK
}


Dynamics

import GD_C.SecureStore.SQLite

...

func openDatabase() -> Bool {
    let fileUrl = try! FileManager.default
                .url(for: .documentDirectory,
                    in: .userDomainMask,
                    appropriateFor:nil,
                    create: false)
                .appendingPathComponent("encrypted_database.db")
    var db:OpaquePointer? = nil
    let result = sqlite3enc_open(fileUrl.path, &db)

    return result == SQLITE_OK
}

GDURLLoadingSystem

BlackBerry Dynamics applications can use the native URL Loading System. The native URL Loading System classes can be used to communicate with app servers that are residing behind an enterprise firewall or on the Internet. Once a connectivity profile is configured in BlackBerry UEM for secure communication, the native class NSURLSession or NSURLConnection should work as is.

See the BlackBerry Dynamics SDK API Reference and review the GDURLLoadingSystem class and NSURLSession support.

GDHttpRequest API as an alternative approach

In addition to the GDURLLoadingSystem, you can use the GD HTTP Request API to send HTTP requests, such as GET and POST, from the device to an app server. The app server can be on the Internet or behind the enterprise firewall as well. The GD HTTP Request API is based on the XML Http Request (XHR) standard.

BlackBerry Dynamics secure communications support HTTPS, using a Secure Socket Layer connection or SSL/TLS to send the HTTP request and receive the response. HTTP and HTTPS requests can be relayed by an HTTP or HTTPS proxy that resides on the Internet or behind the enterprise firewall. Authentication with the proxy is supported.

When making HTTPS requests through an HTTP proxy, SSL/TLS certificate verification must be disabled. Certificate verification while using an HTTP proxy is not supported. BlackBerry Dynamics HTTP data communication does not go via the proxy specified in the device's native settings, if any.

The BlackBerry Dynamics Runtime supports Basic Access, Digest Access, NTLM, and Kerberos for authentication with HTTP servers. Except for Kerberos, all of these mechanisms are also supported for authentication with HTTP proxies. The BlackBerry Dynamics Runtime supports Kerberos version 5 authentication.

By default, HTTP cookies received through BlackBerry Dynamics secure communication are handled automatically.

For more information, see the GDHTTPRequest class reference. The changes required for the GD HttpRequest class are listed below:

// Open a requested URL using URLSession
func requestData(url : String) {
    let nsUrl = URL(string: url)
    let urlRequest = URLRequest(url: nsUrl!)
    let session = URLSession.init(configuration: URLSessionConfiguration.default, delegate: self,
                delegateQueue: OperationQueue.init())


    let task = session.dataTask(with: urlRequest,
                completionHandler: { (data, response, error) in
                    DispatchQueue.main.async {
                        print(response ?? "res")
                    }
                })
    task.resume()
}

The GDSocket API is asynchronous and state-based. The app attaches its own event-handler callbacks to the GD Socket object. The callback functions are invoked when socket events occur, or when the socket changes state. The API functions that can be called by the app depend on the socket's state.

Sending data through a GDSocket is a two-stage operation. The first stage is to add the data to the socket's outbound buffer. The socket's outbound buffer is represented by the writeStream property and is accessed using the GDDirectByteBuffer API. The second stage is to send the contents of the buffer through the socket connection. To send the buffer, call the write function.

Reading data from a GDSocket is asynchronous. When data is received at the device, the data is stored in the socket's inbound buffer. The app is then notified that data is available to read, by invocation of the delegate onRead callback. In the callback, the app consumes the received data from the inbound buffer. The inbound buffer is represented by the readStream property and is accessed using the GDDirectByteBuffer API.

The GDSocket API supports the use of SSL/TLS to send and receive data. By default, the BlackBerry Dynamics runtime does not offer the TLSv1.1 or TLSv1.2 protocols for SSL/TLS connections with an app server.

These protocols can be enabled, as follows:

1. Add a new row to the application's Info.plist file:
   • Key:  GDControlTLSVersions
   • Type:  String  (the default)
2. Set the value to:
   • GDEnableTLS1.1  to enable the TLSv1.1 protocol.
   • GDEnableTLS1.2  to enable both TLSv1.1 and TLSv1.2 protocols.
   As an alternative, the value can instead be an array containing one or both of the above strings as separate items.

The GDSocket connections and HTTP requests can be used to connect to servers that are behind the enterprise firewall. The address of the destination app server must be registered in the BlackBerry UEM management console.

• The address could be registered as the app's server or as an additional server.
• The app server configuration in the UEM server can be obtained in the app code by using the getApplicationConfig(GDiOS) function.

The connection to the app server will be made through the BlackBerry Dynamics proxy infrastructure. Verify the status of the mobile app's connection to the proxy infrastructure before attempting to open the socket or sending the HTTP request.

The changes required for the GDSocket class are listed below:

Native

import CoreFoundation


...


class SocketHelper: StreamDelegate {

    func connectToServer() {
        var readStream: Unmanaged<CFReadStream>?
        var writeStream: Unmanaged<CFWriteStream>?

        var inputStream: InputStream
        var outputStream: OutputStream

        let port = UInt32(80)
        let host = "developer.blackberry.com" as CFString
                    CFStreamCreatePairWithSocketToHost(nil, host, port, &readStream, &writeStream)

        inputStream = readStream!.takeRetainedValue()
        outputStream = writeStream!.takeRetainedValue()

        inputStream.delegate = self
        outputStream.delegate = self

        inputStream.schedule(in: RunLoop.current, forMode: RunLoop.Mode.default)
        outputStream.schedule(in: RunLoop.current, forMode: RunLoop.Mode.default)

        inputStream.open()
        outputStream.open()

    }

    func stream(_ aStream: Stream, handle eventCode: Stream.Event) {
        ....
    }

}

Dynamics

import BlackBerryDynamics.SecureCommunication

...

class GDSocketHelper: GDSocketDelegate {

    func connectToServer() {
        let port = Int32(80)
        let host = NSString(string: "developer.blackberry.com")
        let gdSocket = GDSocket(host.utf8String!, onPort: port, andUseSSL: false)

        gdSocket.delegate = self
        gdSocket.connect()
    }

    func onOpen(_ socket: Any) {
        let gdSocket = socket as! GDSocket;
        let httpString = NSString(string:
                "GET http://developer.blackberry.com/ HTTP/1.1\r\n" +
                "Host:developer.blackberry.com:80\r\n" +
                "Connection:close\r\n" +
                "\r\n")

        gdSocket.writeStream?.write(httpString.utf8String!)
        gdSocket.write()
    }

    func onRead(_ socket: Any) {
        let gdSocket = socket as! GDSocket;
        let str = gdSocket.readStream?.unreadDataAsString()
        DispatchQueue.main.async {
            print(String(describing: str))
        }
        gdSocket.disconnect()
    }

    func onClose(_ socket: Any) {
        let gdSocket = socket as! GDSocket;
            // do something if necessary
    }
}

Copy and Paste

The BlackBerry Dynamics runtime may secure or block text in transit to or from the clipboard, depending on the policies for data leakage prevention (DLP) policy configured in BlackBerry UEM. The runtime secures text by encrypting it when it is cut or copied to the device clipboard, and then decrypting it when it is pasted from the clipboard. On iOS, these operations are handled automatically by the BlackBerry Dynamics Runtime.  No coding changes are required to support this on iOS.

Disable AutoFill

To block password AutoFill, make the TextField an implementation of BBDAutoFillBlockerField. The BBDAutoFillBlockerField class is open source and demonstrated in the AutoFillBlockingSample.