Skip to main content

USB Host Whitelisting

USB host whitelisting is a security measure used to control and restrict the types of USB devices that can connect to a computer or network. By maintaining a whitelist, only approved and trusted devices are allowed access, thereby reducing the risk of unauthorized devices causing harm or accessing sensitive data.

There are two primary USB operational modes: USB Host and USB Client (or Device) mode. A device operating in Host mode manages the communication, provides power and initiate data transfers to connected USB devices. USB Client mode refers to the devices (often referred to as peripherals) that connect to a USB Host. In Client mode, the device waits for commands from the Host and responds accordingly, sending data when requested or receiving and processing data sent by the Host.

Each device in the list is identified by the following elements:

  • ID - device ID, displayed as VID:PID where VID/PID stand for vendor/product ID respectively
  • Name - name of the device
  • Description - description of the device
  • Persistence - indicates the persistence of the device's whitelist in memory

The persistence levels are the following, in ascending order:

  • Reboot - Entries will persist through normal device reboots, but will be removed after an enterprise or factory reset
  • Enterprise reset - Entries will persist through normal device reboots and enterprise resets, but will be removed after a factory reset
  • Factory reset - Entries will persist through normal device reboots, enterprise resets, and factory resets, but could be removed with a change to the factory espresso package
  • Default - Entries with this level of persistence cannot be deleted

Devices added via Configuration Manager or Datalogic Settings will always be set to the Reboot as persistence level. To modify the Enterprise reset or Factory reset persistence level entries, an espresso package is required. Devices with the Default persistence level cannot be removed.

Configure USB Host Whitelisting via the Configuration Manager​

There are two device lists that are used by the Configuration Manager:

Required Libraries​

import com.datalogic.device.configuration.PropertyID;
import com.datalogic.device.configuration.ConfigurationManager;
import com.datalogic.device.configuration.BlobProperty;
import com.datalogic.device.configuration.UsbHostWhitelisting;

Read Default Whitelisted Devices​

ConfigurationManager cm = new ConfigurationManager(context);
BlobProperty blobProperty = (BlobProperty) cm.getPropertyById(PropertyID.USB_PREDEFINED_HOST_WHITELISTING);
UsbHostWhitelisting usbWhitelisting = (UsbHostWhitelisting) blobProperty.get();
usbWhitelisting.getWhitelistedDevices();

Read Editable Whitelisted Devices​

ConfigurationManager cm = new ConfigurationManager(context);
BlobProperty blobProperty = (BlobProperty) cm.getPropertyById(PropertyID.USB_HOST_WHITELISTING);
UsbHostWhitelisting usbWhitelisting = (UsbHostWhitelisting) blobProperty.get();
usbWhitelisting.getWhitelistedDevices();

Add a Device or a Device List to a Whitelist​

ConfigurationManager cm = new ConfigurationManager(context);
BlobProperty blobProperty = (BlobProperty) cm.getPropertyById(PropertyID.USB_HOST_WHITELISTING);
UsbHostWhitelisting usbWhitelisting = (UsbHostWhitelisting) blobProperty.get();

// Add a single device to whitelist
usbWhitelisting.add(new UsbWhitelistedDevice(0x058f,0x6459, "Flash Card Reader/Writer", "card reader"));

// OR

// Add a list of devices to whitelist
List<UsbWhitelistedDevice> devices = new ArrayList<>();
devices.add(new UsbWhitelistedDevice(0x1111, 0x2222, "device a", "generic device"));
devices.add(new UsbWhitelistedDevice(0x3333, 0x4444, "device b", "generic device"));
usbWhitelisting.add(devices);

// Update blob property and commit changes
blobProperty.set(usbWhitelisting);
cm.commit();
  • The new devices will be added to the Reboot whitelist
  • Any device that is already included in a whitelist will be discarded

Remove a Device or a Device List from a Whitelist​

ConfigurationManager cm = new ConfigurationManager(context);
BlobProperty blobProperty = (BlobProperty) cm.getPropertyById(PropertyID.USB_HOST_WHITELISTING);
UsbHostWhitelisting usbWhitelisting = (UsbHostWhitelisting) blobProperty.get();

// Remove a single device from whitelist 
boolean ret = usbWhitelisting.remove(new UsbWhitelistedDevice(0x058f, 0x6459, "", ""));

// OR

// Remove all devices from whitelist
usbWhitelisting.clear();

// Update blob property and commit changes
blobProperty.set(usbWhitelisting);
cm.commit();
  • Remove: remove a device from the Reboot whitelist based on the ID. Name and Description are optional.
  • Clear: discard all whitelist entries

Configure USB Host Whitelisting via the Android Intent​

The whitelist syntax must be the following:

[["vid","pid","name","description","persistence"],["vid","pid","name","description","persistence"], … ,[…]]

Add one or more devices to a whitelist​

Intent intent = new Intent(Intents.ACTION_CONFIGURATION_COMMIT);
HashMap<Integer,String> map = new HashMap<>();
map.put(PropertyID.USB_HOST_WHITELISTING, "[[\"04fb\",\"96a2\",\"mouse\",\"usb\",\"REBOOT\"],[\"05fb\",\"26a2\",\"keyboard\",\"usb\",\"REBOOT\"]]");
intent.putExtra(Intents.EXTRA_CONFIGURATION_CHANGED_MAP, map);
context.sendBroadcast(intent);
  • This command overrides the current whitelist
  • The persistence level must be set to Reboot

Clear the Whitelist​

Intent intent = new Intent(Intents.ACTION_CONFIGURATION_COMMIT);
HashMap<Integer, String> map = new HashMap<>();
map.put(PropertyID.USB_HOST_WHITELISTING, "[]");
intent.putExtra(Intents.EXTRA_CONFIGURATION_CHANGED_MAP, map);
context.sendBroadcast(intent);

Configure USB Host Whitelisting via the Shell Intent​

The whitelist syntax must be the following:

[["vid","pid","name","description","persistence"],["vid","pid","name","description","persistence"], … ,[…]]

Add one or more devices to a whitelist​

adb shell am broadcast \
-a com.datalogic.device.intent.action.configuration.COMMIT \
--es com.datalogic.device.intent.extra.configuration.CHANGED_MAP \
'USB_HOST_WHITELISTING=[[\"04fb\""\,"\"96a2\""\,"\"mouse\""\,"\"usb" "mouse\""\,"\"REBOOT\"]"\,"[\"06b2\""\,"\"f9a2\""\,"\"keyboard\""\,"\"usb" "keyboard\""\,"\"REBOOT\"]]'
  • This command overrides the current whitelist
  • The persistence level must be set to Reboot

Clear the Whitelist​

adb shell am broadcast \
-a com.datalogic.device.intent.action.configuration.COMMIT \
--es com.datalogic.device.intent.extra.configuration.CHANGED_MAP \
'USB_HOST_WHITELISTING=[]'

Configure USB Host Whitelisting via the User Interface​

Tap Datalogic Settings > USB to open the USB settings main page.

Slide the USB client data toggle to enable/disable the USB client mode. Your device won't be recognized by the Host PC.

Slide the USB host data toggle to enable/disable the USB Host mode. Your device won't detect any peripherals.

Tap Datalogic Settings > USB > USB host whitelisting to open the USB host whitelisting main page.

For USB host mode, you can create a list of approved USB devices that are allowed to connect to your device even if USB host data is set to OFF.

Tap Datalogic Settings > USB > USB host whitelisting to open the USB host whitelisting main page and display or edit this list.

Home

The list in the main page shows the whitelisted devices and the connected devices (if USB host data is enabled).

Tap Filter by to select the filter criteria:

  • Whitelisted only - display only whitelisted devices
  • Not whitelisted - display only connected devices
  • All devices - display both whitelisted and connected devices

Tap the + button at the right bottom of the screen to add a device.

For each device in the list, the following details are shown:

  • ID - device ID, displayed as VID:PID where VID/PID stand for vendor/product ID respectively
  • Name - name of the device
  • Description - description of the device
  • Persistence - indicates the persistence of the device's whitelist in memory
  • Connection icon - shows the connection status (connected/disconnected)

How to add/edit a connected device​

To add a connected device to a whitelist (persistence level: Reboot) tap the + icon. A popup appears where you can enter the Name and the Description of the device you want to add. VID and PID are not editable.

Once a connected device is added to a whitelist, the Usb host whitelisting screen will display the new name and description, the persistence level, the Edit icon and the Delete icon.

Tap the Edit icon to change the Name and the Description of the whitelisted device. VID and PID are not editable.

Tap the Delete icon to remove the device from the whitelist.

tip

Name and Description are merely descriptive and can be changed at any time if the level of persistence is Reboot.

How to add a not connected device​

Tap the + button at the right bottom of the screen to add a device to a whitelist, even if it is not connected.

A popup appears asking to enter valid VID and PID numbers. VID and PID are always in hexadecimal format between 0x0000 and 0xFFFF.

Name and Description are optional.

Once the device is added to a whitelist, its details will be displayed in the Usb host whitelisting screen.

Important

A peripheral device can only be added to one whitelist. To add it to a different whitelist, you need to remove it from the current one. Since devices added to whitelists with persistence levels Enterprise reset, Factory reset or Default cannot be edited, they cannot be moved to a Reboot whitelist via Configuration Manager or Datalogic Settings.