EHS Special Features

Overview

This guide covers advanced EHS features such as Kiosk Mode and Secure Mode. It assumes a working knowledge of Enterprise Home Screen and use of its Advanced Settings through direct manipulation of the enterprisehomescreen.xml config file. For those not familiar with these procedures, please refer to the About and Setup pages and the Advanced Settings Guide before continuing.

Note: Many of the capabilities of EHS can be accomplished manually on the device, programmatically through EMDK or remotely using StageNow or a third-party mobile device management (MDM) system (if supported by that MDM system). EHS simply puts the capabilities into a single tool.

Kiosk Mode

Kiosk Mode is designed for devices to run a single application, often with a touch-based UI. Examples include retail price checkers, auto parts look-ups, patient check-in systems and so on. Kiosk Mode also can be useful when dedicating a device to a single user and/or task, such as a retail clerk's hand-held barcode scanner. Kiosk Mode places the app in full-screen mode and prevents the BACK and HOME keys from being used to exit the app. This is the main difference between Kiosk Mode and the EHS Auto-Launch feature.

Android Platform Notes:

• On devices running Android 5.x Lollipop, Kiosk Mode should not be used with Screen Pinning, an Android L feature that works in a similar way.
• On devices running Android 4.4 KitKat, a "please wait" prompt remains displayed when starting up the device in Kiosk Mode. Press the HOME key to launch the Kiosk-Mode app and resume normal behavior.

Kiosk Mode tags:

<kiosk> - Specifies the app that will run when Kiosk mode is enabled

<kiosk_mode_enabled> - Toggles the feature on and off

Enable Kiosk Mode

In the enterprisehomescreen.xml file:

1. Specify the Kiosk app in the <kiosk> section of the config file.
2. Enter a value of '1' in the <kiosk_mode_enabled> tag in the Preferences section of the file.
3. If USB Debugging is desired in Kiosk Mode, enter a value of '0' in the <usb_debugging_disabled> tag.
   (See Disable Kiosk Mode below for details).

Security Note: When using Kiosk Mode, be sure to disable 'key remapping' and other possible methods of launching applications, which would thereby defeat Kiosk Mode safeguards.

Disable Kiosk Mode

Once Kiosk Mode is enabled it can be disabled in only one of two ways (without writing custom program code):

• If USB Debugging was not disabled for User Mode, disable Kiosk Mode by pushing to the device a config file with a value of '0' in the <kiosk_mode_enabled> tag.

• If USB Debugging was disabled for User Mode, perform a factory reset.

Control Kiosk Mode Programmatically

Kiosk Mode can be controlled from within an Android application using Android Intents. The following JavaScript code shows how to enable and disable Kiosk Mode programmatically:

//Disable Kiosk Mode:
Intent intent = new Intent("com.symbol.enterprisehomescreen.actions.MODIFY_KIOSK_MODE");
 Intent.putExtra("enable",false);
 sendBroadcast(intent);

//Enable Kiosk Mode:
Intent intent = new Intent("com.symbol.enterprisehomescreen.actions.MODIFY_KIOSK_MODE");
 Intent.putExtra("enable",true);
 sendBroadcast(intent);

Security Note: When using Kiosk Mode, be sure to disable "key remapping" and other possible methods of launching applications, which would thereby defeat Kiosk Mode safeguards.

---

Secure Mode

In Secure Mode, EHS will accept only a signed EHS configuration file, thereby preventing unauthorized changes to the file. To operate in Secure mode, EHS requires a signed config file (enterprisehomescreen.xml) and a matching signature file (enterprisehomescreen.pem).

A device that is not in Secure Mode is considered to be running in Normal Mode. When in Normal Mode (the default), EHS will accept an unsigned config file and act on any configuration settings within it, as long as the name of the file and its contents meet EHS specifications.

Enable Secure Mode

These instructions require Android Debug Bridge (ADB) for communication with the device and OpenSSL for the creation of device certificate and private key files. If necessary, please install ADB and OpenSSL for Windows before proceeding.

1. Create a device root certificate (caroot.pem) and private key (privatekey.pem) using the following OpenSSL command:

C:\OpenSSL-Win32\bin\openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout privatekey.pem -out caroot.pem

2. Using a text editor, create a certificate.xml file as shown below:

<?xml version="1.0" encoding="UTF-8"?>
<certificate>
        <install>
                <source>/sdcard/caroot.pem</source>
                <alias>CARootCert1</alias>
        </install>
</certificate>

3. Copy the caroot.pem to the SD card on the device.

4. Push certificate.xml to the device using Android File Browser or the following command ADB:

adb push certificate.xml /enterprise/device/settings/mdm/autoimport/

This will cause the root certificate to be installed on the device.

5. To confirm installation, pull the Results.xml file with the following command:

adb pull /enterprise/device/settings/mdm/autoimport/Results.xml.

6. Create the EHS configuration file (enterprisehomescreen.xml) as described in the Advanced Settings section.

7. Sign the config file using the following OpenSSL command:

C:\OpenSSL-Win32\bin\openssl dgst -sign privatekey.pem -out enterprisehomescreen.pem enterprisehomescreen.xml

If successful, the process of signing the enterprisehomescreen.xml file will produce a signature file called enterprisehomescreen.pem.

Important: Be sure to use the same version of OpenSSL to sign the config file as was used to generate the root certificate.

8. Push the signed config and signature files to the /enterprise/usr folder.

9. Install and run the EHS APK as described in the Setup Guide.

At launch, EHS will attempt to match the config and signatures files with the device certificate. If successful, EHS will run in Secure mode and implement the settings in the signed config file.

To confirm, the current operating mode can be viewed in the Preferences panel when in Admin Mode. The image below shows that Secure Mode is OFF:

If matching is unsuccessful, the device will go into a Lockdown State (see below).

Note: When running in Secure Mode, the configuration and signature files are no longer stored in the /enterprise/usr folder. To retrieve the config file when the device is in Secure Mode, use the Export Configuration File option available under Tools menu in Admin Mode.

---

Disable Secure Mode

The first step in returning a device to Normal Mode is to disable Secure Mode. This requires removal of EHS from the device and must be done by an administrator.

To remove EHS from a device running in Secure Mode:

• Enter Admin Mode and uninstall EHS, or
• Perform an Enterprise Reset (refer to the device manual for details).

With Secure-Mode EHS removed, follow the EHS Setup Guide for normal installation.

---

Lockdown State

A device running in Secure Mode will enter Lockdown State if the signed config file (enterprisehomescreen.xml) and its matching signature file (enterprisehomescreen.pem) cannot be verified against the corresponding certificate installed on the device. When this state is reached, the device will display a screen similar to the image below along with the reason for the lockdown.

Recovery from Lockdown State

There are two ways to recover from Lockdown State and return a device to Secure Mode operation:

Method 1: Replace Signature Files

Copy the valid EHS config and signature files to the /enterprise/usr directory on the device. This will cause EHS to exit the Lockdown State, import the config file and return to Secure Mode. The valid files can be copied manually via ADB or deployed using an MDM.

Method 2: Delete Signature File

Log into Admin Mode and delete the signature file from the /enterprise/usr directory. This will cause EHS to exit the Lockdown State and enter Secure Mode. This method will work only if EHS was already running in Secure Mode. If EHS was previously running in Normal Mode and entered Lockdown State due to an unsuccessful attempt to switch to Secure Mode, EHS returns to Normal Mode when the signature file is deleted.

Note: Whether running in Normal or Secure Mode, reaching the maximum number of 10 unsuccessful admin login attempts (or the number otherwise specified in the EHS config file) will disable Admin Mode login. To exit this state, copy a valid config file (and its matching signature file if previously running in Secure Mode) to the device or delete the existing signature file remotely via MDM.

---

EHS Log

EHS records all major activities, failures and security events in the /enterprise/usr/enterprisehomescreen.log file. These include failed attempts to enter Admin Mode, switches of the operating mode and all EHS errors.

The log is a plain text file and can be retrieved with ADB or an MDM and viewed with any text editor.

---

EHS File Interactions

How EHS reacts to file operations