blackberry.com
BlackBerry Dynamics
Runtime library for iOS applications
from the application developer portal

Build-Time Configuration

BlackBerry Dynamics utilizes a number of capabilities of the operating system that require build-time configuration. Some build-time configuration is therefore mandatory for all applications.

Frameworks and Libraries

There are two options for including the BlackBerry Dynamics runtime in an application:

  • Build with the BlackBerry Dynamics runtime static library (GD.framework)
  • Build with the BlackBerry Dynamics runtime dynamic library, known as the dylib (BlackBerryDynamics.framework)
The BlackBerry Dynamics runtime static library requires the following frameworks and libraries to be included in the Link Binary With Libraries build phase (this is not necessary for the BlackBerry Dynamics runtime dylib):

The BlackBerry Dynamics runtime dylib requires 'BlackBerryDynamics.framework' to be included in the Link Binary With Libraries build phase and to be embedded into the application bundle as part of a Copy Files build phase (this is not necessary for the BlackBerry Dynamics runtime static library). Create a new Copy Files build phase by selecting the Build Phases tab of the application target in Xcode, click the '+' button at the top of that section, select 'New Copy Files Phase' from the drop down menu, select 'Frameworks' as the destination and add 'BlackBerryDynamics.framework'. Optionally rename the build phase to 'Embed Frameworks' by clicking on the 'Copy Files' title.

Common Third Party Software

Applications using the BlackBerry Dynamics runtime static library can use binary API compatibility to directly link to the third party libraries included in the runtime if required. Applications using the BlackBerry Dynamics runtime dylib can't directly link in this way but instead should include and maintain their own copies of any of these third party libraries if required.

See also:
Third Party Software page in the appendix.

Application Set-Up Types

The build-time configurations that are required in a BlackBerry Dynamics application depend on how the application was or will be set up:

  • If the application is set up directly in the enterprise management console, then it is an in-house application. In-house applications are typically developed by programmers working at the same enterprise as the end users.
  • If the application is set up via the application developer portal then it isn't an in-house application, for the purposes of build-time configuration. Applications with this type of set-up are typically developed by third parties, Partner applications, or by BlackBerry itself.

Note: Here, application set-up means the creation of the BlackBerry Dynamics entitlement identifier and version. It doesn't mean server address configuration, policy settings, nor end user entitlement, for example.

The following build-time configuration is mandatory for in-house applications. It applies with small variations to other types of application. See under Variations, below, for details.

Inter-Application Communication

All applications must support inter-application communication. This is required for:

  • Enforcement of any authentication delegation policy set by the enterprise.
  • Delegation of activation, to support Easy Activation.
  • Application-Based Services, see the GDService class reference for details.

BlackBerry Dynamics utilization of inter-application communication requires the following build-time configuration.

All applications must register a specific URL type on the device. The URL type must be the same as the application's native bundle identifier.

Within the URL type declaration, five URL schemes must be declared. Two schemes must be declared that are the same as the URL type, with .sc2 and .sc3 appended. An additional scheme must be declared that is the same as the URL type with .sc2. and then the BlackBerry Dynamics entitlement version appended. First and second discovery schemes com.good.gd.discovery and com.good.gd.discovery.enterprise must also be declared. The URL type and schemes would be declared in the application's Info.plist file, as usual.

For example, if the native bundle identifier of the application was com.example.gd.myapp then the URL type declared would also be com.example.gd.myapp and the URL schemes would be:

The Info.plist file of any of the official sample applications that come with the BlackBerry Dynamics SDK can be used as a guide. The second discovery scheme com.good.gd.discovery.enterprise is not included in the samples and must be added manually. Alternatively, add the following XML to the application's Info.plist file, using a text editor. Change all instances of com.iOS.App.ID to the native bundle identifier of the application and change 1.0.0.0 to the BlackBerry Dynamics entitlement version.

 <key>CFBundleURLTypes</key>
 <array>
     <dict>
         <key>CFBundleTypeRole</key>
         <string>None</string>
         <key>CFBundleURLName</key>
         <string>com.iOS.App.ID</string>
         <key>CFBundleURLSchemes</key>
         <array>
             <string>com.iOS.App.ID.sc2</string>
             <string>com.iOS.App.ID.sc2.1.0.0.0</string>
             <string>com.iOS.App.ID.sc3</string>
             <string>com.good.gd.discovery</string>
             <string>com.good.gd.discovery.enterprise</string>
         </array>
     </dict>
 </array>

Note that the first three CFBundleURLSchemes array items have suffixes of .sc2, .sc2.1.0.0.0 and .sc3 applied to the native bundle identifier. The CFBundleTypeRole element is not used by BlackBerry Dynamics and could take another value, as required by the application.

In case there are multiple Info.plist files, check that the correct one has been edited by opening the Info tab of the application target being built. The declarations just made should appear there.

The BlackBerry Dynamics runtime checks the configuration during authorization processing. The end user will not be authorized if the configuration is incorrect.

Updating from earlier versions

Some earlier versions of the BlackBerry Dynamics SDK for iOS required a fifth URL scheme declaration, with .sc appended. This isn't required in the current version and must be removed if present.

Data Sharing

Any BlackBerry Dynamics application that is part of a suite developed by the same enterprise must support data sharing. This is required for Easy Activation delegation between the applications in the suite. If an enterprise has only a single BlackBerry Dynamics application, then supporting data sharing is still advised because it has no disadvantages.

BlackBerry Dynamics utilization of data sharing requires the following build-time configuration:

  • All applications must be owned by the same developer team. They must be signed with provisioning profiles that have a common native App ID prefix.
  • Applications must switch on the Keychain Sharing capability. Applications must share a keychain group with the identifier: com.good.gd.data
    (The current state of Keychain Sharing in the application can be found in the application target, on the Capabilities tab.)

Variations

The above build-time configurations are for in-house BlackBerry Dynamics applications. Other types of application must use a variation with a different declaration of URL schemes. In-house URL scheme declarations are under Inter-Application Communication, above.

BlackBerry Dynamics applications that aren't in-house, partner applications, mustn't declare the second discovery scheme: com.good.gd.discovery.enterprise

BlackBerry Dynamics applications developed by BlackBerry must instead declare the second discovery scheme: com.good.gd.discovery.good

There is no second discovery scheme for partner BlackBerry Dynamics applications developed by third parties.

Face ID

Face ID is a facial recognition feature that is available on some iOS devices. The BlackBerry Dynamics management console has a policy setting by which the enterprise administrator can allow end users to authenticate using Face ID. Authentication processing for Face ID is handled by the BlackBerry Dynamics runtime, without reference to the application code. The purpose for which Face ID is used must be declared by the application, and this cannot be handled by the runtime.

A purpose for using Face ID must be declared by all BlackBerry Dynamics iOS applications. This is a mandatory build-time configuration. The declaration goes in the Info.plist file, in the NSFaceIDUsageDescription property. For example, the following key and value could be added.

 <key>NSFaceIDUsageDescription</key>
 <string>Enables authentication without a password.</string>

The value will be presented in a confirmation dialog for the end user, before the first attempt to authenticate using Face ID is made. Note that if enterprise policy doesn't allow the current end user to authenticate by this mechanism, then the dialog won't be shown.

Because this value is a message to the end user, it should be made available in different languages and in localized variations. This can be done by using InfoPlist.strings files. The mechanism is described in the Information Property List Key Reference on the apple.com developer website. See under Localizing Property List Values.

The Info.plist and InfoPlist.strings files of the sample applications that come with the BlackBerry Dynamics SDK contain values that can be used in any BlackBerry Dynamics application.

BlackBerry Dynamics Custom Linker

Use of a custom linker is mandatory for all BlackBerry Dynamics for iOS applications that use the BlackBerry Dynamics runtime static library, and is part of compliance with Federal Information Processing Standards (FIPS). The linker enables the BlackBerry Dynamics runtime to check its own binary integrity when the application runs. If the dylib is used, no special build-time configuration is needed to switch on run-time integrity checking in a BlackBerry Dynamics for iOS application.

Configure the linker using one of the following sets of instructions, depending on whether the application includes any Swift source files.

If the application has no Swift source then configure the linker as follows:

  1. Add the following settings to the project configuration:
     FIPS_PACKAGE=$(CURRENT_ARCH).sdk
     LDPLUSPLUS=$(HOME)/Library/Application Support/BlackBerry/Good.platform/iOS/FIPS_module/$FIPS_PACKAGE/bin/gd_fipsld
     LD=$(HOME)/Library/Application Support/BlackBerry/Good.platform/iOS/FIPS_module/$FIPS_PACKAGE/bin/gd_fipsld
    
    The settings can be added to an existing Xcode configuration (.xcconfig) file, if the application has one, or can be placed in a separate file.
    The above settings show the default installation location of the SDK for iOS. If a different installation location has been used, change the paths in the settings to the actual installation location.
  2. Set the version of iOS in the Deployment Target of the application to 6.0 or higher.
  3. Do not use the -all_load linker flag. This flag would be selected in the Other Linker Flags field in the Linking section, in the application target Build Settings. The -ObjC linker flag can be used instead.

If the application source includes one or more Swift files then configure the linker as follows:

  1. Add the following setting to the project configuration:
     LDUTILDIR=$(HOME)/Library/Application Support/BlackBerry/Good.platform/iOS/FIPS_module/$(CURRENT_ARCH).sdk/bin
    
    The setting can be added to an existing Xcode configuration (.xcconfig) file, if the application has one, or can be placed in a separate file.
    The above setting shows the default installation location of the SDK for iOS. If a different installation location has been used, change the path in the setting to the actual installation location.
  2. Set the version of iOS in the Deployment Target of the application to 6.0 or higher.
  3. Add the linker flag: -B ${LDUTILDIR}
    Linker flags can be edited in the Other Linker Flags field in the Linking section, in the application target Build Settings.
  4. Remove the -all_load linker flag, if it is present. This flag cannot be used with the custom linker. The -ObjC linker flag can be used instead.

The BlackBerry Dynamics runtime fails with an error message like the following if the custom linker is not configured:
"Crypto::initialise: FIPS_mode_set failed: fingerprint does not match"

Event Receiver Check

By default, the BlackBerry Dynamics runtime checks that there is a GDiOSDelegate event receiver when an authorize function is called. If there isn't, the runtime will raise an assertion and the program will terminate. This check must be switched off in the case that the application doesn't implement GDiOSDelegate and instead uses the GDState interface to monitor authorization.

The event receiver check can be turned off, as follows.

  1. Add a new row to the application's Info.plist file:
    • Key: BlackBerryDynamics
    • Type: Dictionary
    (In case there are multiple Info.plist files, check that the correct one has been edited by opening the Info tab of the application target being built. The row just added should appear there.)
  2. Within that row, add another new row:
    • Key: CheckEventReceiver
    • Type: Boolean
    • Value: No

Alternatively, add the following XML to the application's Info.plist file, using a text editor.

 <key>BlackBerryDynamics</key>
 <dict>
     <key>CheckEventReceiver</key>
     <false/>
 </dict>
See also:
GDState.

Support for App Thinnning

BlackBerry Dynamics supports App Thinning by slicing. In principle, App Thinning by use of on-demand resources is also supported but this isn't useful to typical BlackBerry Dynamics applications. Bitcode isn't supported.

Switching off Bitcode

All applications must switch off the Bitcode build option, i.e. set Enable Bitcode: No. The current state of the Bitcode build option in the application can be found in the Xcode Project Editor, on the Build Settings tab. The easiest way to locate the option may be to key "bitcode" in the search box.

See also:
App Thinning in the App Distribution Guide on the apple.com developer website.

Symbol Stripping

Stripping symbols from the executable increases the security of an application. It makes reverse engineering and binary modification more difficult.

Select the following options in the configuration for the production build.

The user interface for these options can be found in the Xcode Project Editor, on the Build Settings tab. The easiest way to locate the options may be to key the name of each setting in the search box.

The above settings will remove symbols and debugging information from the executable. It is OK not to select them in a debug build.

Check the Apple application developer website for more explanation of what these options do.

Known problem activating on simulator

There is a known problem activating a BlackBerry Dynamics application in the following setup:

The symptoms of the problem are that activation fails at the stage: Secure Data Transfer via AppKinetics. An error alert is displayed, as follows.

The following appears in the development environment console.

 GDDeviceApple::retrieveFromKeychainWithAttributeCheck, status -25300

The cause of the problem is that the application doesn't have access to the iOS keychain.

The problem can be fixed as follows.

  1. Create an Entitlements.plist file with the following content.
     <?xml version="1.0" encoding="UTF-8"?>
     <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
     <plist version="1.0">
       <dict>
         <key>application-identifier</key>
         <string>___VARIABLE_bundleIdentifierPrefix:bundleIdentifier___.___PACKAGENAME___</string>
       </dict>
     </plist>
    
  2. Add the file to the application project.
  3. Add the following settings to the project configuration.
     ENTITLEMENTS_REQUIRED=YES
     CODE_SIGN_ENTITLEMENTS[sdk=iphonesimulator10.*] = /path/to/Entitlements.plist
    
    Change /path/to/Entitlements.plist to the path of the Entitlements.plist file created in the preceding steps. The settings can be added to an existing Xcode configuration (.xcconfig) file, if the application has one, or can be placed in a separate file.

Build and run the application with the above fix.