Back to Monkton

Rebar iOS Getting Started

Monkton, Inc. 2018

This documentation is intended to be a step by step getting started guide for iOS. You should be able to clone from Github and build the sample project without issue.

Some configuration items aren't necessary if you are downloading directly from Github, others will be necessary if you are adding Rebar to an already existing project.

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

Rebar iOS Frameworks

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

Rebar.framework is a pure 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.

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

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.

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

Framework Deployment

The Rebar SDK is deployed with the Rebar installer. This installer will install the frameworks in the /Library/Frameworks directory.

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.

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

At this time Bitcode is not enabled for our builds.

Under /Library/Frameworks you will find the Rebar folder. This folder will have the structure of:

  • /Library/Frameworks/Rebar/Development
  • /Library/Frameworks/Rebar/Production

Monkton has removed armv7 support in 2018 as non-64 bit processor support has been removed in iOS 11.

Github

Monkton publishes examples under the MIT license to Github. These are free to use as starting templates for your projects.

You can clone the Rebar iOS Sample via the command line (or your favorite GUI util):

git clone https://github.com/monktoninc/rebar-ios-samples.git

Additionally you can download directly as a zip file from Github:

https://github.com/monktoninc/rebar-ios-samples

From there, if the libraries are installed correctly under the Framework Deployment section the project should compile without a single error.

One Touch Setup

In our strive to make developing secure apps easy, you can simply run the ./setup-project.sh file in the project root.

Setup will prompt for:

  • Bundle Identifier: The identifier used within the app
  • Bundle Prefix: The prefix used by the app, also know as the Team Id found in the developer portal
  • API Url: The API Endpoint of your application, eg: https://api.example.com/v1
  • URL Scheme: The URL Scheme for the app to be opened by other apps

After running this script, the bulk of the setup is now done. Developers may need to chose the provisioning profile.

If there is a runtime error, permissions may need to be modified with chmod +x setup-project.sh

Bitcode

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

Compiling the Github samples

To be able to run the projects and authenticate, you will need to finish the Entitlements and Configuration Files sections of this guide, but at this point you should be able to compile the sample project without errors.

Rebar to Existing Projects


If you are adding Rebar to existing projects, please follow the steps below.

Configuring Frameworks in XCode

Each project will have to configure the frameworks separately. For each project go to Build Settings and search for Framework Search Paths. Under Debug enter the path to the Development libraries, which should be /Library/Frameworks/Rebar/Development. Under Release enter the path to the Production libraries, which should be /Library/Frameworks/Rebar/Production.

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

This is already configured in the project template

iOS Deployment Target

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

This is already configured in the project template

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 manually need to 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.

This is already configured in the project template

Build Phase Scripts

There are three critical build phase scripts that must be embedded in each target you wish to deploy.

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

  • Embedding Rebar Frameworks
  • Adding default configuration files
  • Project Dependency Signing

These steps are outlined in the next three sections.

Embedding Rebar Frameworks

The Rebar Frameworks must be embedded with a command line script in the Build Phases of the app build. They should not be included as Embedded Binaries in the application, but as Linked Binaries. Using them as Embedded Binaries will cause sporadic runtime issues.

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

Add the following:

mkdir -p "${BUILT_PRODUCTS_DIR}/${PRODUCT_NAME}.app/Frameworks"

if [ "${CONFIGURATION}" == "Debug" ]; then
cp -r "/Library/Frameworks/Rebar/Development/Rebar.framework" "${BUILT_PRODUCTS_DIR}/${PRODUCT_NAME}.app/Frameworks"
cp -r "/Library/Frameworks/Rebar/Development/RebarSupport.framework" "${BUILT_PRODUCTS_DIR}/${PRODUCT_NAME}.app/Frameworks"
fi
if [ "${CONFIGURATION}" == "Test" ]; then
cp -r "/Library/Frameworks/Rebar/Development/Rebar.framework" "${BUILT_PRODUCTS_DIR}/${PRODUCT_NAME}.app/Frameworks"
cp -r "/Library/Frameworks/Rebar/Development/RebarSupport.framework" "${BUILT_PRODUCTS_DIR}/${PRODUCT_NAME}.app/Frameworks"
fi
if [ "${CONFIGURATION}" == "Release" ]; then
cp -r "/Library/Frameworks/Rebar/Production/Rebar.framework" "${BUILT_PRODUCTS_DIR}/${PRODUCT_NAME}.app/Frameworks"
cp -r "/Library/Frameworks/Rebar/Production/RebarSupport.framework" "${BUILT_PRODUCTS_DIR}/${PRODUCT_NAME}.app/Frameworks"
fi

codesign --force --verbose --sign "${EXPANDED_CODE_SIGN_IDENTITY_NAME}" ${BUILT_PRODUCTS_DIR}/${PRODUCT_NAME}.app/Frameworks/Rebar.framework
codesign --force --verbose --sign "${EXPANDED_CODE_SIGN_IDENTITY_NAME}" ${BUILT_PRODUCTS_DIR}/${PRODUCT_NAME}.app/Frameworks/RebarSupport.framework

This will copy the Rebar binaries and then sign them for the application.

This is already configured in the project template

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_root}/config/production/app-config.json

{project_root}/config/development/app-config.json

{project_root}/config/test/app-config.json

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

Once added, you can add the following shell script:

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

This script determines which type of build is being run. Once that build is determined, it will copy the appropriate configuration file to the output app folder.

This is already configured in the project template

Project Dependency Signing

For each target you configure, you will need to add a Run Script in the Build Phases of the target. Name this script "Rebar™ Sign Dependencies". This can be done by tapping the "+" and selecting New Run Script - this script must be run last.

# Frameworks we want to build
TO_SIGN=(libcrypto libssl)
for i in "${TO_SIGN[@]}"
do
:
codesign --force --verbose --sign "${EXPANDED_CODE_SIGN_IDENTITY_NAME}" ${BUILT_PRODUCTS_DIR}/${PRODUCT_NAME}.app/Frameworks/RebarSupport.framework/Frameworks/$i.dylib
done

This is already configured in the project template

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, YOUR-TEAM-IDENTIFER.monktonapps should map to rebar.keychain.group in your app-config.json file.

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.getInstance().setConfiguration(MyAppAppConfiguration());

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

}

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.

Furhter 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.