Rebar Android Getting Started

Monkton, Inc.

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.

GitHub

Monkton publishes examples under the MIT license to Github. These are free to use as starting templates for your projects. Below we will still cover what needs to occur to add Rebar to an existing Android project.

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

Once you have done that, you can follow the checklist and the instructions included below:

Checklist for Integrating Rebar into a New Project

Rebar into a new project

  • Clone the GitHub Android project

    Perform a git clone of the Android project

  • Add rebar.*.aar SDK library to the rebar-core project

    This will enable compilation with Rebar

  • Configure the local.properties file

    Add keys for the build.gradle file to auto-sign binaries

  • Copy dependent libraries

    Ensure that fips-signer.jar and ccj-3.0.1.jar are integrated into the project.

  • Update swig tag

    Fill out the app.swidtag to represent your company and project

  • Download app-config.json files

    Download and add your app-config.json file from the Rebar Hub and integrate into your project

  • Update build.gradle for your project

    The We need to embed the FIPS signature and then resign the APK section of the build.gradle to use your project APK name and local.properties fields

  • Integrate Rebar Application and Activities files

    Rebar requires some bootstrap components to be configured for the App, ensure that you have extended from the correct classes.

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.

Below the Rebar AAR Deployment section will discuss how to integrate this AAR into your project.

Rebar AAR Updates

The rebar-core project will enable you to update the Rebar Android SDK AAR at any time. To update the Rebar SDK, simply:

  1. Copy the updated AAR to the rebar-core project
  2. Update build.gradle and set the file AAR name to the updated Rebar SDK

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>

Project Library Dependencies

There are two major dependencies that need to be integrated into your Rebar project:

  1. ccj-3.0.1.jar: This file helps with FIPS Validated cryptography
  2. fips-signer.jar: This file performs our FIPS Validated signature operations

Adding ccj-3.0.1.jar

Within your app module, copy the ccj-3.0.1.jar file into libs/ccj-3.0.1.jar. This will ensure the cryptographic functions are enabled.

Adding fips-signer.jar

Within the root project, copy the fips-signer.jar file. This will perform the FIPS Signature operation that occurs within the build.gradle task to perform the signature operations.

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.

This is an example app.swidtag file:

<?xml version="1.0" encoding="UTF-8"?>
<SoftwareIdentity
    name="Sample App"
    tagId="io.monkton.sample"
    version="APP_VERSION"
    versionScheme="multipartnumeric"
    tagVersion="1"
	
    xml:lang="en"	
    xmlns:vTag="http://tagvault.org/xsd/swid-extensions-2015.xsd"
    xmlns="http://standards.iso.org/iso/19770/-2/2015/schema.xsd" 
    xmlns:ds="http://www.w3.org/2000/09/xmldsig11#" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 	
    xsi:schemaLocation="http://standards.iso.org/iso/19770/-2/2015/schema.xsd http://standards.iso.org/iso/19770/-2/2015-current/schema.xsd">

  <!-- this software is created, licensed and tagged by the same org -->
  <Entity
    name="Monkton, Inc."
    regid="https://monkton.io"
    role="softwareCreator licensor tagCreator" />

</SoftwareIdentity>

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.

Note This is already configured in the project template. You will need to customize for your project name and local.properties values.

Embedding Configuration Files

Rebar's app-config.json files are configuration files that enable deployment for different environments. They contain core security and configuration data for your apps.

These files can be obtained from your Rebar Hub App page. The stubs will automatically generate the security configurations for the app as well as other configuration data.

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

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

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

Class inheritance is an important part of using Rebar. It enables your apps to inherit specific security functions of Rebar.

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.