Rebar Android Getting Started

Monkton, Inc. 2019

This documentation is intended to be a step by step getting started guide for Android. You should be able to clone from Github and after adding the Rebar AAR and JAR files, make minor configuration changes, 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 Kotlin for code level examples.

Rebar Android AAR

Rebar is distributed for Android in an AAR file and a single JAR file for some cryptographic items. These archive file include all the necessary resources for Rebar to work in an app.

Rebar is a combination of JNI, Java, and Kotlin. In the future, Java will be completely replaced with Kotkin. We strongly believe newer languages like Kotlin will reduce the complexity and errors found in projects, thus our reason for adopting.

Rebar AAR Deployment

Once you have the Rebar AAR library, you will need to add a module to your Android Studio Solution to consume the AAR. Follow the Add your library as a dependency instructions located here: https://developer.android.com/studio/projects/android-library.html

Name the module rebar-core

Once you have complete this, copy the AAR to the new module folder. Rebar is versioned and deployed in a versioned manner. You will need to ensure that the artifacts.add("default", file('rebar.<current version>.aar')) declaration with the appropriate version.

To add the Rebar AAR module to your project, in the app module add:

dependencies {
	...
	implementation project(':rebar-core')
}

Additionally, you will need to add the ccj-3.0.1.jar file to the project libs folder.

Note: Rebar cannot be used in Open Source Projects.

Additional Files

local.properties

To perform signing of the app for debug and release, you will need to add the following entries to the local.properties file.

signing.certificate.jks=<path to your JKS file for signing apps>
signing.certificate.password=<password for the JKS file>

signing.certificate.release.jks=<path to your JKS file for signing apps>
signing.certificate.release.password=<password for the JKS file>

FIPS Signer

You will also need to add the fips-signer.jar jar to the root of your Android Studio solution.

SWID Tag File

In the assets folder, you will need to embed the app.swidtag file. Customize the SWID tag to include your organizations information. During build, the version number will automatically be updated.

Github

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

We strongly recommend cloning our sample Android project located here: https://github.com/monktoninc/rebar-android-samples

This project will demonstrate core functionality of Rebar for Android. Questions can be sent to support@monkton.io

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

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

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

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

You will need to add the Rebar AAR to the Rebar-Core module that is located in the sample project.

Gradle updates - App Signing and SWID tags

Due to the nature of FIPS - we need to perform a FIPS signature operation on the generated APK. At the end of the app's gradle file (build.gradle) add the following:

def getLocalVariable(key) {

    Properties properties = new Properties()
    properties.load(project.rootProject.file('local.properties').newDataInputStream())
    def var = properties.getProperty(key, null)
    if (var == null)
        throw new GradleException(key + " Not Found.")

    return var
}


// Updates the app.swigtag version
gradle.taskGraph.beforeTask { task ->
    if (task.name.contains('preBuild')) {
        exec {
            commandLine 'sh', 'swidtag.sh'
        }
    }
}

// We need to embed the FIPS signature and then resign the APK
gradle.taskGraph.afterTask { task ->

    if (task.name.contains('assembleDebug') && task.project.name.contains("rebarsample")) {
        exec {
            commandLine 'sh' , 'build-sign' , 'debug' , 'rebarsample-debug.apk' , getLocalVariable('signing.certificate.jks') , 'Monkton' , '' , getLocalVariable('signing.certificate.password')
        }
    }
    else if (task.name.contains('assembleRelease') && task.project.name.contains("rebarsample")) {
        exec {
            commandLine 'sh' , 'build-sign' , 'release' , 'rebarsample-release-unsigned.apk' , getLocalVariable('signing.certificate.release.jks') , 'Monkton' , 'rebarsample-signed.apk' , getLocalVariable('signing.certificate.release.password')
        }
    }
}

This will perform two functions:

In NIAP Application Protection Profile 1.3, App SWID tags are necessary. This shell script will update the App SWID tag automatically with the app version number.

Additionally, the afterTask function will perform a signing operation on the app after it has been built, signed, and before it will be run or deployed on a device.

We have included the build-sign shell script with a parameterized set of values. This will enable you to customize the signature operation for your environment. The code above will pull the JKS file path and JKS file password and send them as variables to the build-sign script.

Failure to do so will cause the app to crash on startup.

Rebar to Existing Projects


Please see the Rebar Android AAR and Gradle updates sections of this document

Embedding Configuration Files

Please consult the Android App Config page for configuring the Android App Config

This is already configured in the project template

General Rebar Configuration


Configuration Files

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

Developing with Rebar

Mandatory Components

There are a few mandatory components of developing with Rebar.

Each app at a minimum must:

  • Have an Application class that extends from io.monkton.rebar.ui.RebarApplication
  • All Activity classes must extend from io.monkton.rebar.ui.AuthenticatedActivity

Class Inheritance

RebarApplication

The core functionality of a Rebar Application is to configure App wide settings upon startup. This is done in the RebarApplication class, which should be the super class of the app's Application class.

The Application class should override the `` method to configure the app with application desired capabilities. This is a chance for the app to configure the app configuration as well as register databases used within the app.


    /**
     * Performs the setup and configuration of the Rebar application
     */
    override fun setupConfiguration() {
        super.setupConfiguration()

        // Set the configuration for the app controller, this will customize app functionality
        AppController.getInstance().config = SampleAppConfiguration()

        // Register a custom database class
        DatabaseManager.getInstance().register(SampleAppDatabase::class.javaObjectType)

    }

Activities

All Activity classes should extend from the io.monkton.rebar.ui.AuthenticatedActivity class. The AuthenticatedActivity. This class provides hooks into the core functionality of Rebar to protect the user interface. If overriding any of the onResume, onCreate, etc methods - be sure to call the super class method. Failure to do so may cause erratic an insecure behavior.

Databases

All databases must inherit from io.monkton.rebar.business.database.Database, the root database class. This class manages all security and encryption for the database file. Each database must be registered in the RebarAppDelegate's setupConfiguration method as noted in the RebarApplication section above.

Further details on how to configure these classes are located in the Android App Databases documentation.

App Configuration Class

A single configuration should be created that extends from the io.monkton.rebar.ui.AppConfiguration class. The configuration must be registered in the RebarAppDelegate's setupConfiguration method as noted in the RebarApplication section above.

Further details on how to configure this class are located in the Android App Config 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 rebar.screen.main configuration setting) within the UI code to accommodate Rebar.

Data at Rest (Storing files and data)

For secure database access, you must inherit from io.monkton.rebar.business.database.Database, please read the App Databases documentation as well as the Android Data at Rest for more information.

For storing and reading flat files please read the Android 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.

Last Updated: February 04, 2019