Adding Rebar to existing iOS Projects

Monkton, Inc.

This documentation is intended to be a step by step getting started guide for iOS and integrating Rebar into existing apps. Monkton will help with these efforts to rapidly get your organization up and running.

At present our documentation only covers Swift for code level examples.

This checklist will walk through steps within this document. It is intended to be a high level overview:

Integration Checklist

  • Create a new Target for your app

    A new target will allow you to keep Rebar specific code out of your main code base and app if you are bifurcating them.

  • Understand the Rebar SDK

    The Rebar SDK is comprised of two frameworks, understand where you should deploy them

  • Integrate the Rebar SDK into your app

    A few steps are necessary to integrate Rebar into your app, be sure to perform each step correctly

    • Add Frameworks to project

      Adding the frameworks is the first step to using Rebar within your project

    • Configure Framework Search Paths

      Ensure that the search paths for Frameworks are properly set

    • Adding Build Flags

      Some components of Rebar require some legacy Objective C components to be loaded

  • Create App Delegate, App Configuration, and App Database classes

    Necessary to get Rebar working, these will be the bootstraps for apps you build with Rebar

  • Set iOS Deployment Target

    Configures the correct deployment target for the minimum iOS version

  • Configure Entitlements

    Ensure that entitlements for the app are set correctly

  • Integrate Build Scripts

    Rebar requires a few minor build scripts to properly build, these provide an automated means to perform those steps

  • Update CI/CD Pipeline

    If you are using GitLab, ensure that your CI/CD pipeline includes unpacking the rebar-sdk.zip folder.

Rebar iOS Frameworks

Rebar is composed of two frameworks, Rebar.framework and RebarSupport.framework.

Rebar.framework is a Swift framework that has a majority of the user interface and business logic. Our releases will keep this framework on the latest version of Swift.

Note At this time for XCode, Swift frameworks must be on the same version of Swift. Rebar is currently on Swift 5.

RebarSupport.framework is an Objective-C framework that combines some user interface logic, some business logic, and low level implementation code of many security features.

Both libraries are necessary for any project to work and inherit Rebar's security and compliance features.

Example folder structure for an app

Note Monkton strongly encourages all app development to be done in Swift.

Rebar Integration Tips

The Rebar SDK is an SDK that performs various hardening functions for mobile apps. A few main integration points must be hit for building the app. We strongly suggest creating a new and separate iOS App target specifically for the hardened version. This will enable development to continue unabated. With this, we strongly suggest defining integration classes as using that target only along with precompiler #if / #endif flags around code not relevant to your core product.

#if REBAR_APP
/**
 Perform a Rebar specific call
 */
func rebarCall() {

}
#endif

For instance, there are a few core classes for Rebar you must integrate:

  • A custom AppDelegate extending from RebarAppDelegate
  • A custom AppConfiguration extending from RebarAppConfiguration

New Deployment Target

Before starting on your project, we suggest building out a new Target for deployment. This is done by selecting your Project, navigating to "Targets" and creating a new one. The best option is to select your main target and Duplicate it—giving it a name like your-project-name-Rebar to keep code segregated.

When adding new files to the project, be sure to select the proper targets for the files (For instance, when you add the custom RebarAppDelegate class)

This will allow you to continue unabated in development of your core product and allows you to segregate code for Rebar out of it.

With that, you will need to create the new App Delegate class and remove your current App Delegate from the Target Membership (Hidden in the Inspector window) while ensuring your new App Delegate that extends the RebarAppDelegate class is available in the Target Membership.

Framework Deployment

The Rebar SDK is deployed within your project directory. We strongly suggest creating a project folder called rebar-sdk within the root of your project. Place the rebar-sdk.zip file containing the Rebar SDK in the rebar-sdk folder. From there, you will unzip the directory. You should have a Production and Development folder within your rebar-sdk folder now.

Be sure to add to your .git-ignore file the paths: rebar-sdk/Production and rebar-sdk/Development—this will prevent the unpacked binaries from being stored in your repository during checkin.

You will want to ensure that, when you include this CI/CD pipeline into your project, you unzip the rebar-sdk.zip file before building.

The Rebar frameworks are "fat binaries" meaning they include "slices" of each applicable system they run on. The "Development" frameworks include the x86_64 simulator builds along with the arm64 slice. The "Production" builds include only the arm64 slice for devices. This is for App Store approval in addition to reducing the size of the binary. Monkton strongly urges you to include the "Strip Simulators" script as the

Note Bitcode is not enabled for our builds at this time.

Note The x86_64 simulator build does not include FIPS 140-2 support.

Note Rebar supports two iOS versions behind. At this time we support iOS 12 and iOS 13.

Integration Checklist

  • Create Rebar SDK Folder

    Within your root project directory, create a folder called rebar-sdk

  • Copy the Rebar SDK

    Within the rebar-sdk folder, copy the latest rebar-sdk.zip which contains the full Rebar SDK

  • Unpack the Rebar SDK

    Unzip the rebar-sdk.zip into the rebar-sdk folder

    • Validate Folders

      You should have a rebar-sdk/Development and rebar-sdk/Production with the Rebar SDK folders

  • Add Folders to .git-ignore

    Ensure that you don't commit unpacked binaries, leading to wasted space. Add the two paths to your ignore file: rebar-sdk/Development and rebar-sdk/Production

  • Update CI/CD Pipeline

    If you are using GitLab, ensure that your CI/CD pipeline includes unpacking the rebar-sdk.zip folder.

Bitcode

Bitcode is not enabled for Rebar and can't be for projects using Rebar at this time.

Configuring Frameworks in XCode

Under Target > Build Settings find the Framework Search Paths setting. Under Debug add the setting ${SRCROOT}/rebar-sdk/Development and under Release add the setting ${SRCROOT}/Production. The root location may depend on your project structure. For instance in internal Monkton projects, due to workspace structure, we use the value ${SRCROOT}/rebar-sdk

Additional build configurations can choose the appropriate library depending on the situation.

Add the -ObjC flag to the Other Linker Flags configuration.

Note This is already configured in the project template

Configuring Frameworks in XCode Checklist

  • Navigate to your desired target

    In Xcode, select the project, then in the details view select your desired target to modify. Find the Framework Search Paths setting

  • Configure Framework Search Paths

    Under Framework Search Paths add the values:

    • Debug

      ${SRCROOT}/rebar-sdk/Development

    • Release

      ${SRCROOT}/rebar-sdk/Production

  • Configure Other Linker Flags

    Navigate to Other Linker Flags and add the value -ObjC

iOS Deployment Target

iOS Deployment Target in Build Settings should be set to 12.0 or higher.

Configuring Entitlements

For the project, select the appropriate target and edit the capabilities. Scroll to Keychain Sharing and enable the value. Add two values $(AppIdentifierPrefix)YOUR-APP-IDENTIFIER and YOUR-TEAM-IDENTIFER.monktonapps - then follow the directions in Entitlements to finish.

YOUR-TEAM-IDENTIFER is your organizations internal Team ID appending with .monktonapps.

Note if you run the app and get an error about being able to read items from the keychain, you need to manually edit the Entitlements file and remove the $(AppIdentifierPrefix) value from the YOUR-TEAM-IDENTIFER.monktonapps value. This can be done by directly selecting the RebarApp.entitlements file in Xcode.

Note This is already configured in the project template

Build Phase Scripts

Monkton has condensed the Build Phase process down into two separate but important elements, embedding Rebar and components, and stripping out extraneous slices of the binaries. Due to limitations in Xcode, having a framework included from different folders for different builds, is simply not an option. To get around this, we must strip out simulator builds before the digital signature operation takes place.

They must be in the order of (as described below):

  • Rebar® Processing
  • Rebar® Simulator Strip
Configuring Built Scripts

Depending on your project setup, you may need to move around the source directories. For instance, in many of our internal projects at Monkton, we have a root folder (with the Workspace) and project divided into sub-projects. The rebar-sdk and files such as rebar-xcode-actions and rebar-xcode-strip exist there. Due to that, we will call the rebar-xcode-actions with the "${SRCROOT}/.." variable set, to get to the appropriate folder. Typically, you will only use "${SRCROOT}"

Example folder structure for an app

These steps are outlined in the next two sections.

Rebar® Processing

The rebar-xcode-actions script provides a variety of functions in one file. It embeds Rebar, it copies over the configuration files, and it digitally signs the Rebar binaries with the users credentials.

For each target you configure, you will need to add a Run Script in the Build Phases of the target. Name this script "Rebar® Processing". This can be done by tapping the "+" and selecting New Run Script

Add the following:

# Performs the embedding of Rebar as well as injection of configuration files
${SRCROOT}/helpers/rebar-xcode-actions \
    "${SRCROOT}" \
    "${SRCROOT}" \
    "${CONFIGURATION}" \
    "${BUILT_PRODUCTS_DIR}" \
    "${PRODUCT_NAME}" \
    "${EXPANDED_CODE_SIGN_IDENTITY_NAME}" \
    "false"

This will copy the Rebar binaries, embed config files, and then sign them for the application.

Note This is already configured in the project template

Rebar® Simulator Strip

This script will strip out any Simulator slices from the Rebar Permissions libraries:

For each target you configure, you will need to add a Run Script in the Build Phases of the target. Name this script "Rebar® Simulator Strip". This can be done by tapping the "+" and selecting New Run Script

${SRCROOT}/helpers/rebar-xcode-strip \
    "${CONFIGURATION}" \
    "${TARGET_BUILD_DIR}" \
    "${WRAPPER_NAME}" \
    "false"

Embedding Configuration Files

Deploying the app configuration files is the next step. These are the app-config.json files that drive the local configuration for the app. Documentation on these configuration files is located here. These files already exist. You will need to modify them for your project to customize settings.

Structure is as follows:

${PROJECT_DIR}/config/production/app-config.json

${PROJECT_DIR}/config/development/app-config.json

${PROJECT_DIR}/config/test/app-config.json

You will be required to update the rebar-xcode-actions to add any customized config definitions. By default, the script performs the copy actions defined below:

if [ "${CONFIGURATION}" == "Debug" ]; then
cp -r "${PROJECT_DIR}/config/development/app-config.json" "${BUILT_PRODUCTS_DIR}/${PRODUCT_NAME}.app"
fi
if [ "${CONFIGURATION}" == "Test" ]; then
cp -r "${PROJECT_DIR}/config/test/app-config.json" "${BUILT_PRODUCTS_DIR}/${PRODUCT_NAME}.app"
fi
if [ "${CONFIGURATION}" == "Release" ]; then
cp -r "${PROJECT_DIR}/config/production/app-config.json" "${BUILT_PRODUCTS_DIR}/${PRODUCT_NAME}.app"
fi

Note This is already configured in the rebar-xcode-actions bash script

General Rebar Configuration

Entitlements

The entitlements file (RebarApp.entitlements in the Github project) needs to be modified for Keychain Access Groups. Modify the $(AppIdentifierPrefix)YOUR-APP-IDENTIFIER to have the suffix be your bundle id. The 2nd item, $(AppIdentifierPrefix)monktonapps should map to rebar.keychain.group in your app-config.json file.

Note This requires customization

Configuration Files

The configuration files are located under the Config folder within the sample project. You will need to customize these settings, the documentation on these configuration files is located here.

Developing with Rebar

Includes

For Swift, both Rebar and RebarSupport should be included in the necessary files

import Rebar
import RebarSupport

Class Inheritance

App Delegate

The App's app delegate should extend from RebarAppDelegate and implement the configureApp function. Any overridden methods should invoke the superclass implementation.

@UIApplicationMain
class AppDelegate: RebarAppDelegate {

	override func configureApp() {
		// Set the configuration
				RebarAppController.default.setConfiguration(MyAppAppConfiguration());

		// Set the Database configuration
		RebarDatabaseManager.default.register(MyAppDatabase.self);
		
	}

}

Databases

All databases must inherit from RebarDatabase, the root database class. This class manages all security and encryption for the database file. Each database must be registered in the RebarAppDelegate's configureApp method as noted in the App Delegate section above.

Further details on how to configure these classes are located in the Application Databases class documentation.

App Configuration Class

A single configuration should be created that extends from the RebarAppConfiguration class. The configuration must be registered in the RebarAppDelegate's configureApp method as noted in the App Delegate section above.

Further details on how to configure this class are located in the Application Configuration class documentation.

App UI design

Building the App UI is straight forward. Interfaces can be build via code, storyboards, or NIBs. Whatever the development team is comfortable with.

Main UI Screen

The UI of the app being developed should be developed as one normally would, Rebar instantiates, contains, and manages the UI for the entire lifecycle of the App. There is no customization necessary (beyond the mainScreen configuration below) within the UI code to accommodate Rebar.

If the main UI class is a NIB or via code, the app-config.json configuration main-screen can be set. This is the class name of the main UI class. If the development is in Swift, the class must also declare the @objc above the class definition. This is necessary to instantiate the UI.

If the class uses storyboards, within the Application Configuration class class you can define as below:

	// Gets the main app screen
	public override func mainScreen() -> UIViewController? {
		let mainStoryboard: UIStoryboard = UIStoryboard(name: "MyMainViewControllerStoryboard", bundle: NSBundle(forClass: self.dynamicType))
		let setViewController: MyMainViewControllerStoryboard! = mainStoryboard.instantiateViewControllerWithIdentifier("MyMainViewControllerStoryboard") as! MyMainViewControllerStoryboard
		return setViewController;
		
	}

If the interface uses NIBs, the interfaces can be loaded from their NIB automatically within the class files:

class MySettingsViewController : UIViewController {

	required init() {
		super.init(nibName: "MySettingsViewController", bundle: NSBundle(forClass: self.dynamicType));
		
	}

}

welcomeScreen

This method allows for the instantiation of a welcome screen class. This should return the a view controller that allows the user to create an account or login to the app. This can instantiate a UIViewController itself or instantiate and return a storyboard.

This is an optional setting in the app-config.json file if you aren't implementing a storyboard or overriding this method.

To instantiate a storyboard in iOS, see the example below:

	// Gets the main app screen
	public override func welcomeScreen() -> UIViewController? {
		let mainStoryboard: UIStoryboard = UIStoryboard(name: "MyMainViewControllerStoryboard", bundle: NSBundle(forClass: self.dynamicType))
		let setViewController: MyMainViewControllerStoryboard! = mainStoryboard.instantiateViewControllerWithIdentifier("MyMainViewControllerStoryboard") as! MyMainViewControllerStoryboard
		return setViewController;
		
	}

Data at Rest (Storing files and data)

For secure database access, you must inherit from RebarDatabase, please read the App Databases documentation as well as the Data at Rest for more information.

For storing and reading flat files please read the Data at Rest documentation. Rebar implements the RebarFileManager to read and write files securely.

For storing settings, the RebarUserDefaults provides access to securely store settings, this is available in the Data at Rest documentation

Data in Transit (Network calls)

For secure web service calls (HTTPS/TLS) please consult the Data in Transit documentation.

At this time only HTTPS calls are supported. Rebar will support other protocols in the near future.