Securing your mobile app

Red Hat Managed Integration 1

For Red Hat Managed Integration 1.5

Red Hat Customer Content Services

Abstract

This document provides a comprehensive description and usage instructions for the Device Checks service, Red Hat Managed Integration 1.5.

Preface

This guide does not address all mobile security topics. See the OWASP Mobile Security Project for an introduction to mobile security. Red Hat helps you achieve security:

Chapter 1. Using the Mobile Security Service

1.1. Setting Up the Mobile Security Service

1.1.1. Binding a Mobile App with the Mobile Security Service

To use mobile services, you must represent your mobile app in Mobile Developer Console, and that app must be associated with the mobile service. This association is called binding and it is necessary for your mobile app to use that service.

This section describes how to set up the Mobile Security service.

Prerequisites

  • You have created a Mobile App.

Procedure

To bind a Mobile App with a mobile service:

  1. Launch Mobile Developer Console.
  2. Click on the Mobile App on the Overview screen.
  3. Navigate to Mobile Services tab.

    mobile clients services all unbound down
    Note

    It is possible to bind a Mobile App with a mobile service in the OpenShift console, however such bindings are not valid for the purposes of this procedure.

  4. Click Bind to App for Mobile Security.
  5. Fill out the binding parameters required by the Mobile Security Service.

The Mobile Security service will now be expandable, details about the service can be viewed.

1.2. Configuring your Development Environment for the Mobile Security Service

1.2.1. Downloading the Mobile Services Configuration File

  1. Open your Mobile App in Mobile Developer Console.
  2. Copy the mobile-services.json configuration to your clipboard.
  3. Save the contents of the clipboard to a new file called mobile-services.json.

    Note

    The mobile-services.json file is the link between your provisioned services on OpenShift and the mobile app you are developing. This file provides all required configuration to initialise the various SDKs and get them hooked up/connected to the back-end services.

  4. Follow the platform-specific instructions:
Cordova

Move mobile-services.json to the following location in your application project:

src/mobile-services.json

1.2.2. Setting up Mobile Security service SDK

1.2.2.1. Importing the libraries

Cordova
  1. Install the AeroGear Security package from NPM:

    $ npm install @aerogear/security --save
  2. Add the AeroGear Security plugin for Cordova:

    $ cordova plugin add @aerogear/cordova-plugin-aerogear-security
  3. Import and instantiate SecurityService to start using the SDK:

    const SecurityService = require("@aerogear/security");
    
    const appSecurity = new SecurityService.AppSecurity(app.config);
    Note

    Any new instantiation of SecurityService returns the same instance.

1.3. Implementing the Mobile Security service in your mobile app

Call the appSecurity clientInit function to implement the App Security Service. Call this service on application initialization, for example:

appSecurity.clientInit()
.then(clientInit => {
  /**
    You can use clientInit.data.disabled boolean
    to check if app has been disabled by admin.

    The disabled message is returned if the app is
    disabled at clientInit.data.disabledMessage
    This contains a string with a disabled message
    from the server set by the admin.
  */
}).catch(err  => {
  /**
    You can handle errors connecting to the
    mobile security service here. i.e. if the
    client is offline that error will be caught
    here and you can return a response at this
    point
    */
});

1.4. Managing mobile apps using the Mobile Security Console

To access the Mobile Security Console:

  1. Retrieve the console URL from the list of available services in the Mobile Developer Console (MDC).
  2. Open the URL in a browser.

Overview of the Mobile Security Console

The Mobile Security Console allows you to monitor mobile apps, deployed versions, and disable versions of those mobile apps.

Opening the console lists all applications. Click on an application to view deployed versions of that mobile app.

A deployed version is registered with the Mobile Security service when a version of the app is released, for example, 1.2.3, and that version of the app is run on a device at least once.

Below is a detailed description of each of these views and the information you can expect each to contain.

Application details view

This view provides statistics and information about each deployed version of an application:

  • App Version: The version of the application.
  • Current Installs: Total number of current installed versions of this version of the application.
  • Launches: Total number of launches of this version of the application.
  • Last launched: The last time this application version was launched.
  • Disable on Startup: Whether this application version is disabled on startup.
  • Custom Disable Message: A custom message that is displayed when this version of the mobile app is disabled.

1.4.1. Enabling and disabling mobile app versions

To enable/disable one or more versions of the application:

  1. Toggle the checkbox for that version in the Disable on Startup column.
  2. Confirm these changes by clicking the Save button to persist these changes.

Navigating away from this screen with unsaved changes prompts you to save or discard these changes.

To disable all versions of an application:

  • Click the Disable App button.

1.4.2. Adding or updating a custom disabled message

To add or update a custom message for the version(s) of an application:

  1. Enter the message in the text field for that version under the Custom Disable Message column.
  2. Confirm these changes by clicking the Save button to persist these changes.

Navigating away from this screen with unsaved changes prompts you to save or discard these changes.

Chapter 2. Implementing Device Checks in your mobile app

The Device Security service allows you to easily configure and manage device security, and trust checks for your mobile application.

  • Perform a range of device trust checks on the mobile device, such as checking if the device is rooted, and allows you take proactive action based on the results.
  • Distribute SSL certificates with a Mobile App to create a direct chain of trust (certificate pinning).
Note

Device Security is not currently associated with an OpenShift service, so there are no provisioning or binding tasks associated with using Device Security.

Prerequisites

  • You understand Device Checks.
  • You have logged into the OpenShift console and the Mobile Developer Console.
  • You are developing an Ionic app, plain Cordova is not supported.

2.1. Device Checks Terminology

This section describes terminology that is associated with Device Checks.

Root Access Detection (ROOT_ENABLED)

Use it to help prevent your app running in a device that has been rooted/jailbroken. A device is considered rooted if any of the following are true:

  • A custom key has been used to sign the kernel
  • The su binaries are present
Developer Mode Detection (DEVELOPER_MODE_ENABLED)
To detect if Developer Mode has been enabled on the device the DeviceCheckType#DEVELOPER_MODE_ENABLED function can be used. This function uses Android’s Settings class.
Debugger Detection (DEBUGGER_ENABLED)
To detect if an Android debugger is attached to the app the DeviceCheckType#DEBUGGER_ENABLED function can be used. This function uses Android’s Debug class.
Emulator Detection (IS_EMULATOR)
To detect if the app is being run on an emulator the DeviceCheckType#IS_EMULATOR function can be used. This function uses Android’s Build class.
Device Lock Detection (SCREEN_LOCK_ENABLED)
To detect if a device has a lock screen set (with pin, fingerprint, pattern) the DeviceCheckType#SCREEN_LOCK_ENABLED function can be used. This function uses Android’s KeyguardManager class.
App Data Backup Detection (BACKUP_ENABLED)
To detect whether the application’s data is configured to be synchronized across devices the DeviceCheckType#BACKUP_ENABLED function can be used. The allowBackup flag determines whether to allow the application to participate in the backup and restore infrastructure, which might be interesting to avoid depending on your app’s needs.
Device Encryption Detection (ENCRYPTION_ENABLED)
To detect whether the devices' filesystem is encrypted the DeviceCheckType#ENCRYPTION_ENABLED function can be used. This function uses Android’s DevicePolicyManager class.

Chapter 3. Configuring your Development Environment for the Device Checks Service

Chapter 4. Downloading the Configuration File

The mobile-services.json file provides the information for your mobile app to communicate with services. After you change any configuration in the Mobile Developer Console, it is important to update that file in your IDE.

Prerequisites

  • The configuration of your Mobile App in Mobile Developer Console is up-to-date.
  • You have set up your mobile app development environment.

Procedure

  1. Open your Mobile App in Mobile Developer Console.
  2. Copy the mobile-services.json configuration to your clipboard.
  3. Save the contents of the clipboard to a new file called mobile-services.json.

    Note

    The mobile-services.json file is the link between your provisioned services on OpenShift and the mobile app you are developing. This file provides all required configuration to initialise the various SDKs and get them hooked up/connected to the back-end services.

  4. Move mobile-services.json to the following location in your application project:

    src/mobile-services.json

4.1. Setting up Device Checks service SDK

This guide will help you to set up the Device Checks service SDK in your App.

4.1.1. Importing the libraries

Cordova
  1. Install the AeroGear Security package from NPM

    $ npm install @aerogear/security
  2. Add the AeroGear Security plugin for Cordova:

    $ cordova plugin add @aerogear/cordova-plugin-aerogear-security
  3. Import and instantiate SecurityService to start using the SDK:

    const SecurityService = require("@aerogear/security");
    
    const securityService = new SecurityService(app.metrics);
    Note

    Any new instantiation of SecurityService returns the same instance.

Chapter 5. Performing Device Trust Checks in your Device

This section describes what Device Trust Checks are available and how to execute them for the supported platforms. Also note that Device Checks can be performed either individually or together.

5.1. Root Access Detection

Use this to help prevent your app running in a device that has been rooted/jailbroken.

Cordova
new SecurityService(app.metrics)
    .check(DeviceCheckType.rootEnabled)
    .then(result => {
        // Handle the security result metric
        // result: { id: string, name: string, passed: boolean }
    });

5.2. Developer Mode Detection

Use this to detect if Developer Mode has been enabled on the device.

Cordova
This check is not available for Cordova.

5.3. Debugger Detection

Use this to detect if a debugger is attached to the app.

Cordova
new SecurityService(app.metrics)
    .check(DeviceCheckType.debugModeEnabled)
    .then(result => {
        // Handle the security result metric
        // result: { id: string, name: string, passed: boolean }
    });

5.4. Emulator Detection

Use this to detect if the app is being run on an emulator.

Cordova
new SecurityService(app.metrics)
    .check(DeviceCheckType.isEmulator)
    .then(result => {
        // Handle the security result metric
        // result: { id: string, name: string, passed: boolean }
    });

5.5. Device Lock Detection

Use this to detect if a device has a lock screen set (with pin, fingerprint, pattern…​).

Cordova
Note

For iOS devices this check requires iOS 8 or above.

new SecurityService(app.metrics)
    .check(DeviceCheckType.screenLockEnabled)
    .then(result => {
        // Handle the security result metric
        // result: { id: string, name: string, passed: boolean }
    });

5.6. App Data Backup Detection

Use this to detect whether the application’s data is configured to be synchronized across devices.

Cordova
This is not available for Cordova.

5.7. Device Encryption Detection

Use this to detect whether a devices filesystem is encrypted.

Cordova
This is not available for Cordova.

5.8. Invoking Multiple Device Checks

Device Checks can be run in group, both synchronously and asynchronously.

Synchronously

Cordova

Executing multiple checks synchronously is not directly supported. Instead, it’s possible to use the await operator.

const results = await securityService.checkMany(
    DeviceCheckType.rootEnabled,
    DeviceCheckType.isEmulator,
    // Add more checks here
);
Note

DeviceCheckResult objects in the returning array stay in the same order they were provided.

Asynchronously

Cordova

Invoke multiple checks using the checkMany method:

const checkResults = securityService.checkMany(
    DeviceCheckType.rootEnabled,
    DevoceCheckType.isEmulator,
    // Add more checks here
)
.then(results => {
    // Handle results
});
Note

This method returns a Promise with an array containing all DeviceCheckResult objects in the same order they were provided.

5.9. Additional Resources

Adding Custom Device Checks

It is possible to make use of your own custom checks. Follow the next steps depending on your platform to implement them:

Cordova
  1. Implement the DeviceCheck interface:

    class CustomDeviceCheck implements DeviceCheck {
    
        get name(): string {
            return "My Custom Check";
        }
    
        public check(): Promise<DeviceCheckResult> {
            // Implement device check logic here
            return null;
        }
    
    }
  2. Instantiate it to execute it, using the instance of SecurityService:

    const securityService = new SecurityService(app.metrics);
    
    securityService.check(new CustomDeviceCheck())
        .then(result => {
            // Handle result
        });

Reporting Device Checks Results Via the Metrics Service

In order to report the results of Device Checks utilize this service in conjunction with the Mobile Metrics service.

Cordova

Report individual checks via the checkAndPublishMetric method:

new SecurityService(app.metrics)
    .checkAndPublishMetric(DeviceCheckType.rootEnabled)
    .then(result => {
        // Handle the security result metric
        // result: { id: string, name: string, passed: boolean }
    });

Or alternatively report multiple checks using the checkManyAndPublishMetric method:

new SecurityService(app.metrics)
    .checkManyAndPublishMetric(
        DeviceCheckType.rootEnabled,
        DeviceCheckType.isEmulator,
        // Add more checks here
    )
    .then(results => {
        // Handle the security results array
    });

Chapter 6. Certificate Pinning in Android Devices

Certificate pinning can be enabled in individual SDKs through the mobile-services.json file. Certificate pinning will only be enabled for services which are used directly by the SDKs. For other services SPKI pinning is used. Mobile services must have pinning configured separately. For more information on setting up certificate pinning for mobile services see the Android network security guide.

6.1. Generating Pinning Configuration

The AeroGear SDK gets its configuration from the https section of the mobile-services.json file in a project.

{
    "services":[],
    "https": {
        "certificatePins": [{
            "host": "example.sync.service",
            "certificateHash": "exampleHash"
        }]
    }
}

To include the https section in configuration when generating it using the Mobile CLI use the --include-cert-pins flag when retrieving a client configuration. By default, self-signed or invalid certs will not be permitted to be included in the certificate pinning configuration. To allow these to be included use the --insecure-skip-tls-verify flag.

$ ./mobile get clientconfig <client name> --include-cert-pins --insecure-skip-tls-verify

Using Pinning Configuration

If the https section is included in the mobile-services.json file then certificate pinning will automatically be enabled for mobile services.

Considerations

If the certificate authority of a service changes then the mobile-services.json file will need to be regenerated in order to retrieve the correct https configuration. The app will then need to be rebuilt and republished for the end users to consume. If this is not done then an app may become incapable of making network requests to other services.

Legal Notice

Copyright © 2019 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.