Device Security

Introduction to the Device Security Service

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)

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

Device Security Terminology

This section describes terminology that is associated with Device Security.

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

Android

DeviceChecks.ROOT_ENABLED.

This function uses the Rootbeer library to check if root access is present on the device.

iOS

This check is not available for iOS.

Cordova

This check is not available for Cordova.

Xamarin

This check is not available for Xamarin.

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.

Configuring your Development Environment for the Device Security Service

Downloading the Mobile Services Configuration File

  1. Navigate to your project in OpenShift.

  2. On the Overview screen, expand your Mobile Client to view the CLIENT INFO.

  3. Copy the configuration to your clipboard.

  4. Save the contents of the clipboard to a new file called mobile-services.json.

    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.
  5. Follow the platform-specific instructions:

Android

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

app/src/main/assets/mobile-services.json

iOS

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

<app directory>/mobile-services.json

Ensure that mobile-services.json is a member of the project in the Xcode Project Navigator.
Cordova

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

src/mobile-services.json

Xamarin

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

Resources/mobile-services.json

Setting up Device Security service SDK

Importing the libraries

Android
  1. Add the following dependency in your app’s build.gradle:

    dependencies {
        implementation 'org.aerogear:android-security:2.0.0'
    }
  2. Get an instance of SecurityService to start using the SDK.

    SecurityService securityService = new SecurityService();
    It is user responsibility to manage the SecurityService lifecycle.
iOS
  1. Add the dependency to your Podfile

    target '[TARGET NAME]' do
        pod 'AGSSecurity', '2.0.0'
    end
  2. Update the dependencies by running in your terminal

    $ pod install
  3. Import AGSSecurity and instantiate the SecurityService to start using the SDK

    import AGSSecurity
    
    let security = AGSSecurity()
    Any subsequent call to AGSSecurity returns the same instance of the SecurityService.
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();
    Any new instantiation of SecurityService returns the same instance.
Xamarin
  1. Install NuGet

  2. Install the AeroGear Security package

    $ dotnet add package AeroGear.Mobile.Security --version 2.0.1
  3. Install the specific packages for Android:

    $ dotnet add package AeroGear.Mobile.Security.Platform.Android --version 2.0.1

    And for iOS:

    $ dotnet add package AeroGear.Mobile.Security.Platform.iOS --version 2.0.1
  4. Initialize the SDK by adding the following line to your Android application’s MainActivity.cs:

    protected override void OnCreate(Bundle savedInstanceState)
    {
        base.OnCreate(savedInstanceState);
    
        SecurityService.InitializeService();
        // ...
    }

    And to your iOS application’s AppDelegate.cs:

    public override bool FinishedLaunching(UIApplication app, NSDictionary options)
    {
        SecurityService.InitializeService();
        // ...
    }
  5. Get an instance of SecurityService to start using the SDK:

    var securityService = MobileCore.GetService<SecurityService>();
    Any subsequent call to MobileCore#getInstance returns the same instance of SecurityService.

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, mind that Device Checks can be performed either individually or together.

Root Access Detection

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

Android
SecurityService securityService = new SecurityService();

DeviceCheckResult result = securityService.check(DeviceCheckType.ROOT_ENABLED);
iOS
let security = AGSSecurity()
let result = security.check(JailbrokenDeviceCheck())
Cordova
new SecurityService()
    .check(DeviceCheckType.rootEnabled)
    .then(result => {
        // Handle the security result metric
        // result: { id: string, name: string, passed: boolean }
    });
Xamarin

Use ROOT_ENABLED for Android:

var securityService = MobileCore.GetService<SecurityService>();

DeviceCheckResult result = securityService.Check(DeviceChecks.ROOT_ENABLED);

Use JAILBREAK_ENABLED for iOS:

var securityService = MobileCore.GetService<SecurityService>();

DeviceCheckResult result = securityService.Check(DeviceChecks.JAILBREAK_ENABLED);

Developer Mode Detection

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

Android
SecurityService securityService = new SecurityService();

DeviceCheckResult result = securityService.check(DeviceCheckType.DEVELOPER_MODE_ENABLED);
iOS

This check is not available for iOS.

Cordova

This check is not available for Cordova.

Xamarin
This check is available for Android only.
var securityService = MobileCore.GetService<SecurityService>();

DeviceCheckResult result = securityService.Check(DeviceChecks.DEVELOPER_MODE_ENABLED);

Debugger Detection

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

Android
SecurityService securityService = new SecurityService();

DeviceCheckResult result = securityService.check(DeviceCheckType.DEBUGGER_ENABLED);
iOS
let security = AGSSecurity()
let result = security.check(DebuggerAttachedCheck())
Cordova
new SecurityService()
    .check(DeviceCheckType.debugModeEnabled)
    .then(result => {
        // Handle the security result metric
        // result: { id: string, name: string, passed: boolean }
    });
Xamarin

Use DEBUGGER_ENABLED for Android:

var securityService = MobileCore.GetService<SecurityService>();

DeviceCheckResult result = securityService.Check(DeviceChecks.DEBUGGER_ENABLED);

Use DEBUGGER_ATTACHED for iOS:

var securityService = MobileCore.GetService<SecurityService>();

DeviceCheckResult result = securityService.Check(DeviceChecks.DEBUGGER_ATTACHED);

Emulator Detection

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

Android
SecurityService securityService = new SecurityService();

DeviceCheckResult result = securityService.check(DeviceCheckType.IS_EMULATOR);
iOS
let security = AGSSecurity()
let result = security.check(IsEmulatorCheck())
Cordova
new SecurityService()
    .check(DeviceCheckType.isEmulator)
    .then(result => {
        // Handle the security result metric
        // result: { id: string, name: string, passed: boolean }
    });
Xamarin
var securityService = MobileCore.GetService<SecurityService>();

DeviceCheckResult result = securityService.Check(DeviceChecks.IS_EMULATOR);

Device Lock Detection

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

Android
SecurityService securityService = new SecurityService();

DeviceCheckResult result = securityService.check(DeviceCheckType.SCREEN_LOCK_ENABLED);
iOS
let security = AGSSecurity()
let result = security.check(DeviceLockEnabledCheck())
Cordova
For iOS devices this check requires iOS 8 or above.
new SecurityService()
    .check(DeviceCheckType.screenLockEnabled)
    .then(result => {
        // Handle the security result metric
        // result: { id: string, name: string, passed: boolean }
    });
Xamarin
var securityService = MobileCore.GetService<SecurityService>();

DeviceCheckResult result = securityService.Check(DeviceChecks.SCREEN_LOCK_ENABLED);

App Data Backup Detection

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

Android
SecurityService securityService = new SecurityService();

DeviceCheckResult result = securityService.check(DeviceCheckType.BACKUP_ENABLED);
iOS

This check is not available for iOS.

Cordova

This is not available for Cordova.

Xamarin
This check is available for Android only.
var securityService = MobileCore.GetService<SecurityService>();

DeviceCheckResult result = securityService.Check(DeviceChecks.BACKUP_ENABLED);

Device Encryption Detection

Use this to detect whether a devices filesystem is encrypted.

Android
SecurityService securityService = new SecurityService();

DeviceCheckResult result = securityService.check(DeviceCheckType.ENCRYPTION_ENABLED);
iOS

This check is not available for iOS.

Cordova

This is not available for Cordova.

Xamarin
This check is available for Android only.
var securityService = MobileCore.GetService<SecurityService>();

DeviceCheckResult result = securityService.Check(DeviceChecks.ENCRYPTION_ENABLED);

Invoking Multiple Device Checks

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

Synchronously

Android
  1. Get a SyncCheckExecutor from SecurityService:

    SecurityService securityService = new SecurityService();
    SyncDeviceCheckExecutor syncCheckExecutor = securityService.getCheckExecutor();
  2. Add your checks and execute synchronously:

    Map<String, DeviceCheckResult> results = syncCheckExecutor
        .addCheck(DeviceCheckType.<check_type>)
        // Add more checks here
        .execute();
iOS

Invoke multiple checks using the checkMany function:

let checks = [DeviceLockEnabledCheck(), IsEmulatorCheck(), /** Add more checks here */ ]
let results = security.checkMany(checks)
DeviceCheckResult objects in the returning array stay in the same order they were provided.
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
);
DeviceCheckResult objects in the returning array stay in the same order they were provided.
Xamarin
  1. Build a SyncDeviceCheckExecutor from SecurityService and execute:

    var securityService = MobileCore.GetService<SecurityService>();
    
    var checkExecutor = securityService.GetSyncExecutor()
                            .WithDeviceCheck(DeviceChecks.ROOT_ENABLED)
                            .WithDeviceCheck(DeviceChecks.DEVELOPER_MODE_ENABLED)
                            // Add more checks here
                            .Build()
    Dictionary<string, DeviceCheckResult> results = checkExecutor.Execute();

Asynchronously

Android
  1. Get an AsyncCheckExecutor from SecurityService:

    SecurityService securityService = new SecurityService();
    AsyncDeviceCheckExecutor asyncCheckExecutor = securityService.getAsyncCheckExecutor();
  2. Add your checks and execute synchronously:

    Map<String, Future<DeviceCheckResult>> results = asyncCheckExecutor
        .addCheck(DeviceCheckType.<check_type>)
        // Add more checks here
        .execute();
iOS

Executing multiple checks asynchronously is not supported at the moment for this platform.

Cordova

Invoke multiple checks using the checkMany method:

const checkResults = securityService.checkMany(
    DeviceCheckType.rootEnabled,
    DevoceCheckType.isEmulator,
    // Add more checks here
)
.then(results => {
    // Handle results
});
This method returns a Promise with an array containing all DeviceCheckResult objects in the same order they were provided.
Xamarin

Executing multiple checks asynchronously is not supported at the moment for this platform.

Additional Resources

Adding Custom Device Checks

Besides the Provided Device Checks it’s also possible to make use of your own custom checks. Follow the next steps depending on your platform to implement them:

Android
  1. Extend the AbstractDeviceCheck interface:

    class CustomDeviceCheck extends AbstractDeviceCheck {
    
        @Override
        protected boolean execute(@NonNull final Context context) {
            // Implement security check logic here
            return false;
        }
    
    }
  2. Instantiate it to execute it, using the instance of SecurityService:

    SecurityService securityService = new SecurityService();
    
    DeviceCheck customDeviceCheck = new CustomDeviceCheck();
    DeviceCheckResult result = securityService.check(customDeviceCheck);
iOS
  1. Implement the DeviceCheck interface:

    public class MyCustomCheck: DeviceCheck {
    
        public let name = "Custom Check"
    
        public init() {}
    
        public func check() -> DeviceCheckResult {
            // Implement security check logic here
            return nil
        }
    
    }
  2. Use the check function as usual:

    let security = AGSSecurity()
    let result = security.check(MyCustomCheck())
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();
    
    securityService.check(new CustomDeviceCheck())
        .then(result => {
            // Handle result
        });
Xamarin
  1. Implement the IDeviceCheck interface:

    class CustomDeviceCheck : IDeviceCheck
    {
        public string GetName()
        {
            return "Custom check";
        }
    
        public string GetId()
        {
            return typeof(CustomDeviceCheck).FullName;
        }
    
        public DeviceCheckResult Check()
        {
            // Implement security check logic here
            return null;
        }
    }
  2. Instantiate it to execute it, using the instance of SecurityService:

    var securityService = MobileCore.GetService<SecurityService>();
    
    DeviceCheckResult result = securityService.Check(new CustomDeviceCheck());

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.

Android

Report individual checks via the checkAndSendMetric method:

MetricsService metricsService = MobileCore.getInstance(MetricsService.class);
SecurityService securityService = new SecurityService();

DeviceCheckResult result = securityService.checkAndSendMetric(DeviceCheckType.<check_type>, metricsService);

Or alternatively report multiple checks using a CheckExecutor:

MetricsService metricsService = mobileCore.getInstance(MetricsService.class);
Map<String, DeviceCheckResult> results = DeviceCheckExecutor.Builder.newSyncExecutor(this.getContext())
    .withDeviceCheck(DeviceCheckType.<check_type>)
    // Add other checks...
    .withMetricsService(metricsService)
    .build()
    .execute();
iOS

Report individual checks via the checkAndPublishMetric function:

let result = security.checkAndPublishMetric(DeviceLockEnabledCheck())

Or alternatively report multiple checks using the checkManyAndPublishMetric function:

let checks = [DeviceLockEnabledCheck(), IsEmulatorCheck(), /** Add more checks here */ ]
let results = security.checkManyAndPublishMetric(checks)
Cordova

Report individual checks via the checkAndPublishMetric method:

new SecurityService()
    .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()
    .checkManyAndPublishMetric(
        DeviceCheckType.rootEnabled,
        DeviceCheckType.isEmulator,
        // Add more checks here
    )
    .then(results => {
        // Handle the security results array
    });
Xamarin

Report individual checks:

var securityService = MobileCore.GetService<SecurityService>();
var metricsService = MobileCore.GetService<MetricsService>();

DeviceCheckResult result = securityService.Check(DeviceChecks.ROOT_ENABLED, metricsService);

Or alternatively report multiple checks using a CheckExecutor:

var securityService = MobileCore.GetService<SecurityService>();
var metricsService = MobileCore.GetService<MetricsService>();

var checkExecutor = securityService.GetSyncExecutor()
                        .WithDeviceCheck(DeviceChecks.ROOT_ENABLED)
                        .WithDeviceCheck(DeviceChecks.DEVELOPER_MODE_ENABLED)
                        .WithMetricsService(metricsService)
                        // Add more checks here
                        .Build()
Dictionary<string, DeviceCheckResult> results = checkExecutor.Execute();

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.

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.