USER GUIDE - ENTERPRISE HOME SCREEN Version 1.6

Motorola Solutions

Enterprise Home Screen (EHS)

User Guide

Revision K

January 2015

Introduction

Enterprise Home Screen (EHS) is a replacement application launcher, for Motorola Solutions Android devices, designed to allow only specified applications to be launched.

For customers for whom the AppLock functionality of the Motorola Solutions extensions (Mx) does not meet their requirements, Enterprise Home Screen may provide a more suitable alternative.

Glossary

 

User screen

images/user_screen_jb.png

 

Admin screen

images/admin_screen_jb.png

 

Context menu

images/context_menu_jb.png

 

APK ( .apk )

An APK is a software installation package built for the Android operating system.

Installation

The following instructions assume that you have the device drivers installed and are able to read/write to the SD card on the device.

  1. Connect the device to a PC via a cradle or USB adapter cup.

  2. Copy the EHS .apk file to the On Device Storage (SD card) folder of the device.

  3. Open File Browser from the Android application launcher screen.

  4. Navigate to the SD card and tap on the EHS .apk file.

  5. Tap on the Install button.

  6. Once the application is installed, tap the Done button.

  7. Tap the Home button.

  8. Tap Enterprise Home Screen followed by Always.

     

    images/complete_action_using_jb.png

     

  9. Now reboot the device. This is mandatory.

Note If the Just once button was tapped instead of the Always button at step eight above, launch the Calculator app and continue from step seven above.

User mode

This is the default mode in EHS. The user screen displays only the applications/links specified in the configuration. Tapping any of the displayed application icons will launch that application.

 

User screen with context menu showing

images/context_menu_jb.png

 

Pressing the MENU button will bring up a context menu from which you can access wireless and battery information, the tools menu and information about EHS.

Tools menu

This lists the specified applications as a list and provides access to the admin mode.

 

Tools menu

images/tools_jb.png

 

To access admin mode, select the Admin Login option and enter the admin password when prompted.

 

Admin login

images/admin_login_jb.png

 

The number of failed login attempts is limited (default ten). The count of failed login attempts is reset on a successfully login. Once the number of failed login attempts has been exceeded, further login attempts will result in a message being displayed and the user will not be able to login any more. The xml configuration file has to be replaced to reset the failed login count and allow the user to be able to attempt to login again.

Admin mode

This mode allows access to all the applications installed on the device.

This mode also allows applications to be added to and removed from the user screen.

  • To add an application to the user screen, long press the application icon until a confirmation dialog appears then press OK.

  • To remove an application from the user screen, long press the application icon until a confirmation dialog appears then press OK.

Admin screen showing context menu

images/admin_context_jb.png

 

Pressing the MENU button will bring up a context menu from which you can access wireless and battery information, the tools menu and information about EHS as per the user screen. Additionally, access is also provided to EHS preferences.

Tools menu showing Export Configuration File

images/export.png

 

Pressing the Export Configuration File menu will bring up a folder selection dialog where the external storage is selected as the default. Option is also provided to change it to any writable folder in the device.

EHS preferences screen

Once in admin mode, the context menu will include an additional entry which gives access to a screen where you can change EHS preferences. The preferences screen reads the values from the xml configuration file and any changes made are written back to that file.

Configuration

Enterprise Home Screen is configured via an xml file found in the /enterprise/usr/ folder in the internal memory of the device. This file is read each time the User or Admin screen comes to the foreground.

Example Configuration:
<?xml version="1.0" encoding="utf-8"?>
<config>
    <kiosk>
        <application label="Calculator" package="com.android.calculator2" activity=""/>
    </kiosk>
    <applications>
        <application label="Rapid Deployment" package="com.motorola.msp"
            activity="com.motorola.msp.client.RDMenu"/>
        <application label="Calculator" package="com.android.calculator2" activity=""/>
        <link label="ET1 Video" url="http://www.youtube.com/watch?v=ERlIzLt-h6s"/>
    </applications>
    <tools>
        <application label="Calculator" package="com.android.calculator2" activity=""/>
        <application label="Rapid Deployment" package="com.motorola.msp"
            activity="com.motorola.msp.client.RDMenu"/>
    </tools>
    <passwords>
        <admin></admin>
    </passwords>
    <preferences>
        <title>Enterprise Home Screen</title>
        <icon_label_background_color>#AAFFFFFF</icon_label_background_color>
        <icon_label_text_color>#FF000000</icon_label_text_color>
        <orientation></orientation>
        <bypass_keyguard>1</bypass_keyguard>
        <auto_launch_enable>0</auto_launch_enable>
        <wallpaper></wallpaper>
        <kiosk_mode_enabled>0</kiosk_mode_enabled>
        <disable_status_bar_settings_icon>1</disable_status_bar_settings_icon>
        <disable_statusbar_pulldown>0</disable_statusbar_pulldown>
        <install_shortcuts>0</install_shortcuts>
        <exit_instead_of_reboot>0</exit_instead_of_reboot>
        <airplane_option_disabled>1</airplane_option_disabled>
        <keyguard_camera_disabled>1</keyguard_camera_disabled>
        <keyguard_search_disabled>1</keyguard_search_disabled>
    </preferences>
</config>

Auto launch (optional)

Auto launch will allow you to start any number of applications at startup, but will not stop the user from pressing BACK or HOME to exit auto launched applications.

<auto_launch>
    <application delay="8000" package="com.android.calculator2" activity=""/>
    <application delay="5000" package="com.rovio.angrybirds" activity=""/>
</auto_launch>

The delay attribute will allow you to set a wait time (in milliseconds) before the specified application is launched. If your application is installed on the SD card then you must use a delay to allow for the time it takes Android to mount the SD card.

Auto launch preferences

<preferences>
    <auto_launch_enable>0</auto_launch_enable>
</preferences>
Valid node values
0

disable (default)

1

enable

Note <auto_launch_enable> must also be set to 1 before EHS will use the <auto_launch> section.

Kiosk launch (optional)

This section specifies the application that will be launched in Kiosk mode.

<kiosk>
        <application label="Calculator" package="com.android.calculator2" activity=""/>
</kiosk>

Kiosk preferences

Kiosk mode will allow you to specify one application to run at startup and will prevent the user from pressing BACK or HOME to exit that program.

<preferences>
     <kiosk_mode_enabled>1</kiosk_mode_enabled>
</preferences>
Valid node values
0

disabled (default when not specified)

1

enabled

Note <kiosk_mode_enabled> must also be set to 1 in the preferences section before EHS will lock the device into the specified application.
Warning

Once you have set this setting you will not be able to exit Kiosk mode unless you do one of the following:

  1. Inside a custom developed application the Android developer has the option to write code to disable and enable Kiosk Mode. This is done through an Android specific method called intent.

  2. Send the following intent to EHS… 

    Intent intent = new Intent("com.motorolasolutions.enterprisehomescreen.actions.MODIFY_KIOSK_MODE");
Intent.putExtra("enable",false);
sendBroadcast(intent);

  3. Change Intent.putExtra("enable",true); re-enable Kiosk mode

Applications

This section will add icons to the "User" home screen.

<applications>
        <application label="Calculator" package="com.android.calculator2" activity=""/>
        <link label="ET1 Video" url="http://www.youtube.com/watch?v=ERlIzLt-h6s"/>
</applications>

<application> node

EHS will display the applications icon

The label attribute

specifies the text that will be displayed below the application icon.

The package attribute

should be set to the application’s package name.

The activity attribute (optional)

should be set to the application activity.

Note Some applications require an activity to be specified in order to launch. See MSP agent in main example.
Tip

An alternative way to add an application to this section is to login as admin in EHS, long press on any icon, and answer YES to the prompt (EHS will handle adding the application to the xml configuration file).

Repeating this process will remove the added application.

<link> node representing a web address or file

EHS will use the icon of the default Web Browser application.

The label attribute

specifies the text that will be displayed below the icon.

The url attribute

should be set to the full address of the web site you would like displayed (i.e. http://… or https://… or file://…). Only html files are supported under file://

The package attribute (optional)

should be set to the application’s package name.

The activity attribute (optional)

should be set to the application activity.

Tip

The package and activity attributes can be used to launch the url via a specified app. For example, to open the url in the Mozilla Mobile browser, the link node would look as follows…

<link label="Mozilla Mobile" url="http://www.mozilla.org/en-US/mobile/" package="org.mozilla.firefox" activity="org.mozilla.firefox.App" />

By default EHS will launch a link using the Android default browser. In order to launch different browser in EHS, the package and activity names must be specified. If the specified browser does not exist on the device, EHS will not display the link on its screen

<link> node representing a local or remote application added using intents

In the case of shortcuts added to remote or local applications using intents, a new link tag with the following attributes will be added to the configuration file automatically.

The label attribute

represents the shortcut name. Same as the value of "Intent.EXTRA_SHORTCUT_NAME".

The uri attribute

represents the intent in text format. Same as the URI representation of the intent data "Intent.EXTRA_SHORTCUT_INTENT".

The icon attribute

specifies the path of the icon file stored in the device. If the extra data "Intent.EXTRA_SHORTCUT_ICON" is available in the received broadcast intent, the icon will be stored in the device as an image file.

The icon_ref attribute

specifies the package name to retrieve the icon later. If the extra data "Intent.EXTRA_SHORTCUT_ICON_RESOURCE" is available in the received broadcast intent, the icon will be generated runtime using the package name. Hence no need to store the icon image in the device.

Tip

For example, in a shortcut added to the remote application "Microsoft Excel" via Citrix Receiver, the link node would look as follows…

<link label="Microsoft Excel" icon="/enterprise/usr/ehs_data/images/MicrosoftExcel.png" uri="citrixreceiver://launchapp?pid=1&inname=citrixcloud%3AMicrosoft+Excel+MS&fname=Microsoft+Excel&shortcutCookie=681181718&mobile=0&unikey=0#Intent;action=android.intent.action.VIEW;launchFlags=0x14000000;end" />

Tools

Applications listed in this section will be displayed in the Tools screen (accessed from the context menu).

<tools>
    <application label="Calculator" package="com.android.calculator2" activity=""/>
    <application label="Rapid Deployment" package="com.motorola.msp" activity="com.motorola.msp.client.RDMenu"/>
</tools>

images/tools_jb.png

Passwords

This section holds the admin password for EHS. The password is 256 bit AES encrypted by EHS. The password can be changed via the Tools screen once logged in as admin. Default password is blank.

<passwords>
    <admin></admin>
</passwords>

Tap Ok to login. It is recommended that you change the password after logging in the first time.

Preferences

This section allows you to customize the look and feel of EHS.

Title

The text displayed in the title bar can be changed as follows…

<preferences>
    <title>Enterprise Home Screen</title>
</preferences>

Icon label background color

The background color of the icon labels can be changed as follows…

<preferences>
    <icon_label_background_color>#AAFFFFFF</icon_label_background_color>
</preferences>

Icon label text color

The foreground/text color of the icon labels can be changed as follows…

<preferences>
    <icon_label_text_color>#FF000000</icon_label_text_color>
</preferences>
Note
Color format

Supported formats are: #RRGGBB, #AARRGGBB, "red", "blue", "green", "black", "white", "gray", "cyan", "magenta", "yellow", "lightgray" and "darkgray".

For example…

<icon_label_text_color>#75A319</icon_label_text_color>
<icon_label_text_color>#80EF671B</icon_label_text_color>
<icon_label_text_color>magenta</icon_label_text_color>

#RRGGBB and #AARRGGBB represent hexadecimal color values where…

AA

specifies the opacity (ranging from 00 to FF)

RR

specifies the level of RED (ranging from 00 to FF)

GG

specifies the level of GREEN (ranging from 00 to FF)

BB

specifies the level of BLUE (ranging from 00 to FF)

 
The following web-site may be helpful in determining the RGB values for a desired color…

http://www.colorpicker.com/

Orientation

The orientation of EHS can be fixed by setting the following value to either "landscape" or "portrait"…

<preferences>
    <orientation>landscape</orientation>
</preferences>
Valid node values
landscape

 

portrait

 

default

(default when not specified)

Note Omitting this preference or leaving it blank will cause the orientation to be determined by the Android system settings.

Bypass keyguard

Setting the following value to one will cause EHS to bypass any keyguard/unlock screen including Mx multi-user login screen. So if Mx multi-user has to be used with EHS, bypass keyguard should not be enabled.

Note If Mx multi-user has been enabled in the device and also the keyguard is bypassed, Mx will then consider it as a non-admin user throughout the system. 
<preferences>
    <bypass_keyguard>1</bypass_keyguard>
</preferences>
Valid node values
0

normal

1

bypass (default when not specified)

Warning When bypass keyguard is enabled, launching a web page from a specified link or launching the web browser itself may not work at the first attempt after device is rebooted. To overcome this, either disable bypass keyguard or press on the HOME button once.

Wallpaper

The image EHS uses for the background can be changed by setting the following value…

<preferences>
    <wallpaper>/enterprise/usr/mybackground.png</wallpaper>
</preferences>
Note

Only Portable Network Graphics (png) format image files are supported.

Images in the /enterprise/usr/ folder are supported. Images on the SD card, however, are not supported.

Fullscreen

EHS can be made full screen by setting the following value…

<preferences>
    <fullscreen>1</fullscreen>
</preferences>
Valid node values
0

normal (default when not specified)

1

fullscreen

Note

This only makes EHS full screen. Any apps launched from EHS will not appear full screen unless designed to do so.

On Android 4.4 KitKat devices, the device status/notification bar will still be visible and could be accessed by pulling down the bar even when the EHS is made full screen. To disable this pulling down the bar, use the "Disable status bar pull down" option in EHS.

Admin max attempts

The maximum number of admin login attempts can be set by the following value…

<preferences>
    <admin_max_attempts>10</admin_max_attempts>
</preferences>

If this node is not present or contains no value, the default of ten will be used.

Note

When the number of consecutive failed login attempts reaches the number specified above, further login attempts will not be allowed. EHS tracks the number of consecutive failed login attempts by adding an attribute to the password admin node…

<passwords>
    <admin attempts="10"></admin>
</passwords>

In order to allow further login attempts, this attribute needs to be removed. This can be done by pushing a new enterprisehomescreen.xml file to the device.

Admin inactivity timeout

An admin inactivity timeout (in seconds, default sixty) can be specified which on expiry causes the automatic logout of admin mode…

<preferences>
    <admin_inactivity_timeout>60</admin_inactivity_timeout>
</preferences>

If this node is not present or contains no value, the default of sixty seconds will be used.

The minimum inactivity timeout is fifteen seconds; lower values than this will be ignored.

Setting the value to zero will disable the inactivity timeout.

Note

This inactivity timeout only counts down whilst EHS is in foreground. If an app is launched, i.e. EHS is no longer in foreground, the inactivity timeout is stopped and then reset once EHS returns to foreground.

Disable status bar Settings icon

Warning The "Disable status bar settings icon" is being deprecated and will be removed in the future. This feature is replaced with the new "Disable Applications" feature which can be used to disable the system Settings application. Disabling the Settings application will not remove the icon from the notification bar but clicking on the icon will not launch the application. The "Exit instead of reboot" option is also being deprecated since this feature is used in conjunction with the "Disable status bar settings icon" feature.

The Settings icon in the status/notification bar can be disabled on those devices that support this feature…

<preferences>
    <disable_status_bar_settings_icon>1</disable_status_bar_settings_icon>
</preferences>
Valid node values
0

enable

1

disable

When not specified, this will default to the current system setting.

Warning In order for this setting to take effect, the device must be rebooted. EHS will automatically reboot the device, without warning, when this setting is applied or changed.
Note It is recommended that you restore/set the Settings icon before uninstalling EHS.

Disable status bar pulldown

The status/notification bar pulldown can be disabled via the following…

<preferences>
    <disable_statusbar_pulldown>1</disable_statusbar_pulldown>
</preferences>
Valid node values
0

enable (default when not specified)

1

disable

Exit instead of reboot

Warning The "Exit instead of reboot" option is also being deprecated since this feature which used in conjunction with the "Disable status bar settings icon" feature is also being deprecated. The "Disable status bar settings icon" is being deprecated and will be removed in the future. This feature is replaced with the new "Disable Applications" feature which can be used to disable the system Settings application. Disabling the Settings application will not remove the icon from the notification bar but clicking on the icon will not launch the application.

This setting is intended for use by MDMs (Mobile Device Managers), and will cause EHS to exit instead of reboot when a setting that requires a reboot is applied/changed.

<preferences>
    <exit_instead_of_reboot>1</exit_instead_of_reboot>
</preferences>
Valid node values
0

reboot (default when not specified)

1

exit

Note If EHS has been set as the default launcher, then the OS will restart EHS after it exits.

Disable applications

Any system or custom application in the device can be disabled/enabled using the following settings. The Application must be defined by its package name. Please note the package name of an Android application may not be the same on different OS versions.

<preferences>
        <apps_disabled>
                <application package="com.android.settings"/>
                <application package="com.android.quicksearchbox"/>
        </apps_disabled>
        <apps_enabled>
                <application package="com.android.gallery3d"/>
        </apps_enabled>
</preferences>

To disable/enable an application, its package name should be given under "apps_disabled" or "apps_enabled" respectively.

When the EHS configuration file is manually updated, in order to re-enable after disabling an application, the application must be listed under "apps_enabled" in the configuration file. Failure to add this entry will keep the application in disabled state.

If either of these nodes is not found in the EHS configuration file, EHS will disable the system settings and search applications by default.

If the node is present, the apps defined in the configuration file will be enabled/disabled instead of EHS defaults.

If the same application name is present under both "apps_disabled" and "apps_enabled" that app will be disabled.

Note Uninstalling EHS will not revert the app enabled/disabled settings to the previous state. Make sure to set the app state to the original state, if required, before uninstalling EHS. The following apps are normally enabled by default. 
<preferences>
        <apps_enabled>
                <application package="com.android.settings"/>
                <application package="com.android.quicksearchbox"/>
        </apps_enabled>
</preferences>

Disable Airplane/Flight option

Airplane/Flight option under power menu can be disabled on those devices that support this feature.

<preferences>
        <airplane_option_disabled>1</airplane_option_disabled>
</preferences>
Valid node values
0

enable

1

disable (default when not specified)

Disable Camera on keyguard/unlock screen

Camera application can be disabled/enabled on the keyguard/unlock screen using the following setting, so that the camera application launch can be blocked/allowed from the keyguard screen.

Note Disabling/enabling Camera in keyguard will have effect only when the device keyguard has a Camera icon on it and also the camera application is enabled in the device. If there is no Camera icon on the keyguard or it’s already disabled in the device, this setting will have no effect. 
<preferences>
        <keyguard_camera_disabled>1</keyguard_camera_disabled>
</preferences>
Valid node values
0

enable

1

disable (default when not specified)

Disable Search on keyguard/unlock screen

Search application can be disabled/enabled on the keyguard/unlock screen using the following setting, so that the Search application launch can be blocked/allowed from the keyguard screen.

Note Disabling/enabling Search in keyguard will have effect only when the device keyguard has a Search icon on it and also the Search application is enabled in the device. If there is no Search icon on the keyguard or it’s already disabled in the device, this setting will have no effect. 
<preferences>
        <keyguard_search_disabled>1</keyguard_search_disabled>
</preferences>
Valid node values
0

enable

1

disable (default when not specified)

Install shortcuts

Setting the following value to one will cause EHS to allow intents to add shortcuts to remote and local applications. By default this is disabled, means listening to these intents are disabled in EHS.

<preferences>
   <install_shortcuts>0</install_shortcuts>
</preferences>
Valid node values
0

disable (default when not specified)

1

enable

Install shortcuts using intents

EHS allows intents to add shortcuts to remote and local applications in the device. For this, EHS setting Install shortcuts should be enabled in advance. Then EHS will listen to the Android broadcast intent "com.android.launcher.action.INSTALL_SHORTCUT". When EHS receives this broadcast intent, it will create a shortcut on the user screen using the data extracted from the received intent. The same data will be written to the configuration file under "Applications" node. Please refer to <link> node for more information.

Note Adding duplicate shortcuts to the same local or remote application is allowed. But shortcuts being added before installing EHS or before making EHS the default launcher will not be considered. To remove existing shortcuts from user screen, the corresponding "link" tag has to be deleted from the configuration file.

EHS Operating Modes

Introduction

EHS supports two operating modes:

Unsecure Mode

In the Unsecure mode, EHS will not determine if the configuration file was created by the authorized person. EHS will import and act upon any configuration file provided the name of the file and its contents meet EHS requirements.

Secure Mode

In the Secure mode, EHS will accept only the signed configuration file. The Secure mode is provided to prevent unauthorized persons from getting control of EHS by accessing and modifying the EHS configuration file (enterprisehomescreen.xml). To operate in the Secure mode, EHS requires the signed configuration file (enterprisehomescreen.xml) and the matching signature file (enterprisehomescreen.pem).

Installing EHS to run in Unsecure mode

  • Install and run the EHS APK as described in Installation section.

  • If the EHS configuration file is provided in the /enterprise/usr folder without the .pem file, EHS will import the file and run in the Unsecure mode. Refer to Configuration for instructions on creating the configuration file. WARNING: In the Unsecure mode, the configuration files will remain in the /enterprise/usr folder.

  • If the EHS configuration file is not provided, EHS will run in the Unsecure mode using the default settings.

  • Follow the above steps for manual as well as MDM deployments

  • To determine if EHS is running in Unsecure mode, follow the directions provided in Identifying Operating Mode

Installing EHS to run in Secure mode

  • Create the Device Certificate as described in Creating Device certificate and Private Key

  • Install the Device Certificate on the device as described in Installing Device certificate

  • Create the EHS configuration file (enterprisehomescreen.xml) as described in the Configuration section.

  • Sign the EHS configuration file as described in Signing EHS configuration file. A successful signing produces the matching signature file (enterprisehomescreen.pem).

  • Copy the signed configuration and signature files to the /enterprise/usr folder.

  • Install and run the EHS APK as described in Installation section.

  • EHS will attempt to match the configuration and signatures files with the device certificate.

  • If the matching is successful, EHS will run in the Secure mode and import the configuration file. WARNING: In the secure mode, the configuration and signature files will be removed from the /enterprise/usr folder.

  • If the matching is unsuccessful, the device will go into the Lock down state as described in Lock down state.

  • Follow the above steps for manual as well as MDM deployments

  • To determine if EHS is running in Secure mode, follow the directions provided in Identifying Operating Mode

  • To retrieve the configuration file when the device is in secure mode, use the Export Configuration File option available under Tools menu once logged in as Admin.

Switching to Secure mode when running in Unsecure Mode

Warning The configuration (.xml) file must be copied first and then the Signature file (.pem). Failure to follow this order will result in Lock down state , but for a brief period only. It will come out from lock down state once the configuration file is copied.

  • EHS will attempt to match the configuration and signatures files with the device certificate.

  • If the matching is successful, EHS will run in the Secure mode.

  • If the matching is unsuccessful, the device will go into the Lock down state as described in the Lock down state.

  • Follow the above steps for manual as well as MDM deployments

  • To determine if EHS is running in Secure mode, follow the directions provided in Identifying Operating Mode

Switching to Unsecure mode when running in Secure Mode

  • Uninstall EHS. Only the EHS Admin can uninstall EHS.

  • OR

  • Enterprise reset the device. Refer to the device user guide for instructions on Enterprise resetting the device.

  • Follow the instructions under Installing EHS to run in Unsecure mode section.

Creating Device certificate and Private Key

  • Create a device certificate (caroot.pem) and a private key file (privatekey.pem) using OpenSSL as described below. To install OpenSSL, follow the instructions under Appendix: Installing OpenSSL tool on Windows PC

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

Warning Use same version of OpenSSL to generate certificate and to sign configuration file.

Installing Device certificate

  • To install the device root certificate (eg. caroot.pem) first you have to create 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>

  • Copy the created caroot.pem on the device sdcard.

  • Push certificate.xml file using following ADB command or FileBrowser. Then the device root certificate will be installed in the device.

    • CMD>adb push certificate.xml /enterprise/device/settings/mdm/autoimport/

  • Use following command to pull Results.xml, which indicates whether the certificate installation is successful or not.

    • CMD>adb pull /enterprise/device/settings/mdm/autoimport/Results.xml.

Signing EHS configuration file

  • Sign the EHS configuration file (enterprisehomescreen.xml) using the private key (privatekey.pem). The private key is created as described in Creating Private Key . The signing of the Configuration file will create the EHS signature (enterprisehomescreen.pem) file.

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

Identifying Operating Mode

  • To identify the current Operating Mode of the EHS, log in as Admin and view the Admin UI. The field Secure Mode will be set to ON when in Secure mode. This field will be set to OFF if EHS is running in Unsecure mode. The Secure Mode field is read-only and cannot be used to change the operating mode. Also, there is no entry in the configuration file that specifies the operating mode.

images/securemode.png

Additional information on Operating Mode

  • Logging : EHS logs the activities in the enterprisehomescreen.log file. Some of these activities are errors, exceeding allowed Admin login attempts and switching the Operating mode.

  • In both Secure and Unsecure modes, the EHS admin is allowed to change/reset the password.

Lock down state

  • To operate in the Secure mode, the signed configuration file (enterprisehomescreen.xml ) and the matching signature file (enterprisehomescreen.pem) must be provided in the/enterprise/usr folder. EHS will attempt to verify these files against the corresponding device certificate installed on the device. If the verification fails, EHS will go into the Lock down state. In the Lock down state, the Lock down screen will appear. This screen will display the reason for locking down the device and no user activity will be permitted except an option for the EHS Admin to log in.

images/lock.png

Exiting the Lock down state

  • One of the following methods can be used to exit the Lock down state:

    • Copy valid EHS configuration and signature files to the /enterprise/usr folder. EHS will exit the lock down state, import the configuration file and function in the Secure mode. The valid files can be deployed using MDM or copied manually by the EHS Admin.

    • Delete the signature file from the /enterprise/usr folder. EHS will exit the Lock down state and enter into the secure mode. This method will work only if EHS is already running in the Secure mode. EHS will remain in the lock down state if EHS was previously running under the Unsecure mode and an unsuccessful attempt was made to switch to the Secure mode

Warning If the number of unsuccessful Admin login attempts reached the maximum limit specified in the EHS Configuration file, EHS will go into permanent Lock down state. The only way to exit is to copy valid configuration and signature files or delete the existing signature file remotely via MDM.

How EHS reacts to file operations

Current mode

Operation

Results

Recovery

Unsecure mode

Copy a new enterprisehomescreen.xml file into /enterprise/usr folder

New configuration takes effect. Still the device is running in unsecure mode.

Unsecure mode

Copy an invalid pem file (i.e. this pem file does not match the xml file in /enterprise/usr folder)

Lock down screen shows up immediately

Delete the pem file in /enterprise/usr folder via admin login to the device or remotely . Device will resume in unsecure mode with existing configuration.

Unsecure mode

Copy a new xml file first and then the pem file (corresponding to that new xml file) into /enterprise/usr folder

Once the xml file is detected the new configuration takes effect in unsecure mode.

When the pem file is copied:

If signature verification is SUCCESS : Device goes to secure mode.

If signature verification is FAIL: Lock down screen shows up immediately with Error.

Unsecure mode

Copy a new pem file first and then the xml file (corresponding to that new pem file) into /enterprise/usr folder

As soon as pem file is copied the device will go to lock down state. Once the relevant xml file is copied, lock down screen will vanish and device will go to secure mode with new configuration taking effect.

WARNING: The recommended way is to copy the xml file first and the pem file the second

Current mode

Operation

Results

Recovery

Secure mode

Copy a new xml file into /enterprise/usr folder

New configuration does NOT take effect, since the relevant pem file has not been copied. Hence the device remains in the previous configuration, in secure mode.

Note: Device does not go to lock down state in this case"

Secure mode

Copy a new xml file and the pem file (corresponding to that new xml file) into /enterprise/usr folder

If signature verification is SUCCESS: Device remains in secure mode. New configuration takes effect.

If signature verification is FAIL: New configuration does NOT take effect.Device goes to lock down state."

Delete the xml file and pem file in /enterprise/usr folder via admin login to the device or remotely. Device will resume in secure mode with previous configuration."

Secure mode

Copy only a pem file into /enterprise/usr folder.

Lock down screen shows up immediately

Option 1: Copy the xml file (corresponding to the pem file) via Admin login to the device or remotely. Lock down screen will vanish immediately and the new configuration will take effect.

Option 2: Delete the pem file in /enterprise/usr folder: lock down screen will vanish immediately and the device will remain in previous configuration."

Current state

Operation

Results

lock down state

Admin logins to the device and copy a new xml file and the relevant pem file via file browser in the device.

If signature verification is SUCCESS: Device enters into secure mode. New configuration takes effect.

If signature verification is FAIL: Lock down screen shows up again. New configuration does NOT take effect.

lock down state

Copy a new xml file and the relevant pem file remotely.

If signature verification is SUCCESS: Lock down screen vanishes abruptly. Device enters into secure mode. New configuration takes effect.

If signature verification is FAIL: Lock down screen remains. New configuration does NOT take effect.

lock down state

Delete the pem file in /enterprise/usr folder via admin login to the device or remotely.

If the device was in secure mode previously: Lock down screen vanishes and the device will resume in secure mode with previous configuration.

If the device was in unsecure mode previously: Lock down screen vanishes and the device will resume in unsecure mode with previous configuration.

lock down state

Do not change any files in the /enterprise/usr folder. Then Uninstall EHS and Install EHS again

When EHS is launched, lock down screen shows up in the device.

lock down state

Delete the xml file and pem file in /enterprise/usr folder. Then Uninstall EHS and Install EHS again

EHS is launched in unsecure mode

Important notes

Recent apps list

  • Any apps/activities launched from EHS will not be added to Android’s recent app list.

  • However, should a launched app/activity subsequently launch another app/activity then that may appear in Android’s recent app list (this depends on the implementation of the former app/activity).

  • To clear the recent apps list either reboot the device or press and hold the Home button until the list of recent apps appears, then press and hold an app in the list until a context menu appears, then select Remove from list and repeat for the remaining apps.

  • If previously used app list is not deleted using one of the above two methods, it may get activated back when the Back button on the device is pressed and even the default home screeen can be seen instead of the Enterprise Home Screen.

EHS internal information for third party applications

  • Package name: com.motorolasolutions.enterprisehomescreen

  • Main activity/class name: com.motorolasolutions.enterprisehomescreen.HomeScreenActivity

Appendix: Installing OpenSSL tool on Windows PC

  1. Download OpenSSL tool for W32/W64 bit machine from the below URL

  2. Install the tool on your PC by double clicking on exe file.

  3. During Installation, Setup will warn for installation of Visual C++ 2008. We do not require it so, just cancel (click on cancel button) and proceed further to complete installation.

  4. Open the command prompt. Go to the OpenSSL installed folder. By default the OpenSSL is installed in C:\OpenSSL-Win32\

    • $ cd C:\OpenSSL-Win32\bin

  5. Set the OpenSSL configuration Environment variable by executing the following command in command prompt.

    • $ Set OPENSSL_CONF=C:\OpenSSL-Win32\bin\openssl.cfg