Development Guide BlackBerry Dynamics SDK for Cordova Published: 2017-10-18 SWD-20171204152634181 Contents About this guide............................................................................................................... 5 BlackBerry Dynamics background....................................................................................6 BlackBerry Dynamics API reference..................................................................................................................................6 US FIPS 140-2 compliance...............................................................................................................................................6 Easy Activation.................................................................................................................................................................7 Securing cut-copy-paste on devices (Data Leakage Prevention, or DLP).............................................................................7 Shared Services Framework..............................................................................................................................................8 Support for fingerprint authentication................................................................................................................................8 Support for client certificates............................................................................................................................................8 Support for "No Password" security policy.........................................................................................................................9 Support for Ionic/AngularJS version 1 and Ionic/AngularJS version 2 on iOS......................................................................10 Support for Ionic and AngularJS version 1 on Android......................................................................................................10 Support for Ionic and AngularJS version 2 on Android......................................................................................................11 Bypassing the App Lock screen.......................................................................................................................................11 Locales...........................................................................................................................................................................11 Requirements.................................................................................................................13 BlackBerry Dynamics software versions..........................................................................................................................13 Compatibility with earlier releases............................................................................................................................13 Unsupported BlackBerry Dynamics features............................................................................................................13 Software requirements....................................................................................................................................................14 Recommended development environment: macOS, not Windows 10........................................................................15 Character encoding for build files: UTF-8.................................................................................................................15 BlackBerry Dynamics entitlement ID and version.............................................................................................................15 Distinction from and use with native language identifiers..........................................................................................17 Including BlackBerry Dynamics entitlement version metadata for the Shared Service Framework.............................18 Setting preferences in config.xml for BlackBerry Dynamics......................................................................................19 Deprecated classes and methods...................................................................................................................................20 Steps to get started with the BlackBerry Dynamics SDK for Cordova................................21 Getting started step-by-step............................................................................................................................................21 Install the BlackBerry Dynamics SDK for Cordova ...........................................................................................................21 Install BlackBerry Dynamics SDK for Android or BlackBerry Dynamics SDK for iOS...................................................22 Directory structure and description of installed plugins.............................................................................................22 Working with the plugins.................................................................................................24 Checking versions of installed plugins..............................................................................................................................26 About the security of Cordova localStorage......................................................................................................................26 Sample apps.................................................................................................................. 28 Testing and troubleshooting............................................................................................29 Automated test support library for iOS.............................................................................................................................29 Logging and diagnostics..................................................................................................................................................29 Log message categories...........................................................................................................................................29 Configure detailed logging for the Xcode console......................................................................................................30 Configure selective logging for the Xcode console.....................................................................................................30 Configure logging in Good Control............................................................................................................................30 GDLogManager class for log uploading.....................................................................................................................31 Readying your app for deployment: server setup............................................................. 32 Legal notice....................................................................................................................33 About this guide About this guide 1 This guide is an introduction to the BlackBerry Dynamics software development kit (SDK) for Cordova. The guide focuses on how to install the BlackBerry Dynamics SDK for Cordova, how to use the provided plugins, and introduces the sample apps that are packaged with the SDK. This guide is intended for software developers who already have an understanding of developing software with Cordova. For detailed, guided steps to install SDK, see Getting Started. This guide is not a tutorial on programming with Cordova. It assumes that you have working knowledge of the language and concepts. The guide also assumes that you have installed the supported version of Cordova. For information about how to install, see the instructions from Apache Project at https://cordova.apache.org/docs/en/latest/ or the Node.js site at https:// www.npmjs.com/package/cordova 5 BlackBerry Dynamics background BlackBerry Dynamics background 2 The following sections provide some background information that can help you understand the features of the BlackBerry Dynamics SDK. The way that these features are implemented in your environment will depend on how your administrator has configured your organization's servers, your network, and other infrastructure. BlackBerry Dynamics API reference The BlackBerry Dynamics SDK API reference describes the available interfaces, classes, methods, and much more. You can access the API reference: • Online at https://community.blackberry.com/view-doc.jspa?fileName=index.html&docType=android. • In the installed directories for the BlackBerry Dynamics SDK. You can access the API reference: • Online at https://community.blackberry.com/view-doc.jspa?fileName=index.html. • In the installed directories for the BlackBerry Dynamics SDK. In Xcode, the BlackBerry Dynamics SDK Reference can be viewed from the Organizer window in the Documentation section in Xcode. You can access the API reference at https://developer.blackberry.com/files/BlackBerry-Dynamics-for-Cordova/index.html. US FIPS 140-2 compliance BlackBerry Dynamics apps must be built to be compliant with U.S. Federal Information Processing Standards (FIPS) 140-2. The BlackBerry Dynamics SDK distribution contains FIPS canisters and tools and by default enforces FIPS compliance. On Android, FIPS compliance is automatic; no special build steps are required. There are two sides to enabling FIPS: the app itself and the policy server, either Good Control or BlackBerry UEM. The app When an app starts, it must start in FIPS-compliant mode. The BlackBerry Dynamics SDK determines whether a service is running in FIPS mode when the app communicates with the server to receive policies. All apps must be written for FIPS compliance. 6 BlackBerry Dynamics background The policy server For pointers to more details on FIPS policies, see the documentation for servers described in Readying your app for deployment: server setup. What FIPS compliance enforces Enabling FIPS compliance enforces the following constraints: • MD4 and MD5 are prohibited by FIPS, which means that access to NTLM- or NTLM2-protected web pages and files is blocked. • Wrapped apps are blocked. • In secure socket key exchanges with ephemeral keys, with servers that are not configured to use Diffie-Hellman keys of sufficient length, BlackBerry Dynamics retries with static RSA cipher suites. Easy Activation The Easy Activation feature simplifies the provisioning process by allowing a BlackBerry Dynamics app to hand off activation to an app that is already installed on the device and can act as the activation delegate. The user has to retrieve and manually enter an access key only the first time they install a BlackBerry Dynamics app. For more information about enabling Easy Activation, see the Easy Activation Feature Overview. Securing cut-copy-paste on devices (Data Leakage Prevention, or DLP) You can use the BlackBerry Dynamics SDK to protect certain data copied and pasted between apps on your users' devices. For , you don't need to do any additional programming to support secure cut and paste. Server administrators must enable the Data Leakage Prevention policies in the management console. To enable sharing among a group of apps, the apps must be provisioned from the same BlackBerry Control service for each user. If the Data Leakage Prevention settings are enabled in your environment, you can work around them when you need to debug your app. For more information, see https://community.blackberry.com/view-doc.jspa? fileName=screencapturecontrol.html&docType=android. 7 BlackBerry Dynamics background Shared Services Framework BlackBerry Dynamics-enabled apps can communicate with each other using the Shared Services Framework. There are two kinds of shared services: • Server-side services • Client-side services The BlackBerry Dynamics SDK contains sample apps that show how these services work. For a conceptual background, see BlackBerry Dynamics Services Framework. Support for fingerprint authentication BlackBerry Dynamics's support for fingerprint recognition is a supplement to standard BlackBerry Dynamics secure user authentication, not a replacement for it. BlackBerry Dynamics includes the following kinds of policies related to fi ngerprint authenticaton. These settings are configured by way of policies in the server. • Allow or disallow fingerprint authentication for BlackBerry Dynamics-based apps in general. • If fingerprint authentication is allowed in general, you can also allow or disallow it for BlackBerry Dynamics apps immediately after app coldstart. If you do not allow it after app coldstart, the user must enter the password for the app. • Require the end user to enter a password after a specified interval. Note: For app developers, no additional programming work is necessary for fingerprint authentication, except for Samsung Pass, some linking directives are needed. See Info: Add Samsung Pass to your BlackBerry Dynamics app. For more information see BlackBerry Dynamics and Fingerprint Authentication Support for client certificates BlackBerry Dynamics supports many popular uses of client-side Public Key Infrastructure (PKI) certificates to secure apps and communications: • General requirements for working with PKI certs • Description of client certificate sharing among BlackBerry Dynamics apps on a device • Kerberos PKINIT: client certificates in the Kerberos authentication model. (This is not Kerberos Constrained Delegation, or KCD). 8 BlackBerry Dynamics background Support for "No Password" security policy The BlackBerry Dynamics Runtime now supports the security policy for not requiring the end user to set an app password. Security consideration • Consider the security ramifications in your environment carefully. Enabling "no password" is only one of the design options available. Others include authentication delegation, enabling "no password" on certain devices only, device management, and more. You should consider enabling "no password" for select groups of users whose devices are under tight control via device management profiles or other controls. • Do not enable "no password" and authentication delegation in the same policy set. • Enabling "no password" does not permit authentication in the background, because there is no authentication. Software prerequisites 1. Standalone Good Control 3.0.50.70 or later or BlackBerry UEM 12.7 or later 2. The "No Password" policy must be enabled and applied to the desired users or app group. User-visible changes and behavior With a BlackBerry Dynamics app that is protected by a security policy that requires a password, if the administrator changes the security policy to "Do not require a user password": • The user is shown an informational screen stating that a password is no longer required for the app. • The user is then in "No Password mode" and is never prompted for password again. If the user is in "No Password mode" and the administrator changes the security policy to require a password: • The user is prompted to set a password. • The user is shown an informational screen stating that a password is now required for the app. Optional APIs for Android for "No Password" policy You can call the GDAndroid.getInstance().canAuthorizeAutonomously method to find out if an app is protected by the security policy to require a password. Call GDAndroid.serviceInit( ) to start the authorization process when your app has received a GCM message or background broadcast/explicit intent. The sample app GDInteraction illustrates the use of these methods. For syntax and details, see the SDK programming reference. 9 BlackBerry Dynamics background Optional APIs for iOS for "No Password" policy You can query the state of the policy with [GDiOS sharedInstance].canAuthorizeAutonomously. If your app has received an APNS message or a Background Fetch period, or has been launched in the background, you can call the [GDiOS sharedInstance].authorizeAutonomously method to start the authorization process. The SecureStore sample app illustrates the use of these methods. For syntax and details, see the SDK programming reference. Support for Ionic/AngularJS version 1 and Ionic/ AngularJS version 2 on iOS On iOS, the BlackBerry Dynamics SDK for Cordova supports all features of AngularJS versions 1.x.x and versions 2.x.x. Ionic with these versions of AngularJS built in are also supported. Support for Ionic and AngularJS version 1 on Android Except as noted below, the BlackBerry Dynamics SDK for Cordova supports all features of AngularJS version 1.x.x on Android. Ionic with these versions of AngularJS built in are also supported. Not supported on Android: Ionic and AngularJS version 1 loading local resources Loading local bundled resources from the android_assets folder is not supported for Angular v1.x on Android. Not supported on Android: Ionic and AngularJS version 1 $http method PATCH The $http HTTP method PATCH is not supported. Using $http.patch returns a 400 Bad Request. Not supported on Android:Ionic and AngularJS version 1 synchronous requests Synchronous HTTP requests via XMLHttpRequest are not supported. Instead, they are treated as asynchronous. Not supported on Android: Ionic and AngularJS version 1 file upload with FormData() A file upload with FormData() is not supported. Instead, use BlackBerry Dynamics FileTransfer plugin for file upload and download. For more information on cordova-plugin-bbd-filetransfer, see Directory structure and description of installed plugins. 10