search

particle-iot / particle-cli

Command Line Interface for Particle Cloud and devices
Apache License 2.0
212 stars 92 forks source link

Device Protection Feature #745

Closed keeramis closed 3 months ago

keeramis commented 4 months ago

Description

This PR introduces the device-protection command to the CLI. Using particle device-protection xxx, users can disable, enable, and get the current protection status of a Particle device.

Status

A Particle device (whether Open / Protected / Protected (Service Mode)) can be queried via control request to get this information. The control request used to get the current protected status is CTRL_REQUEST_GET_PROTECTED_STATE which returns protected and overridden

A Particle device can now be categorized into three types

Source of truth: Device Protection Customer messaging doc

Open Device

An Open Device does not have Device Protection enabled on it. It has an ordinary ("non-protected") bootloader. If this device is in a product that is capable of Device Protection and if this device is not marked as a Development Device in the product, then the cloud could flash a protected bootloader to the device (when the device comes online next time)

state: false, overridden: false

Protected Device

A Protected Device has Device Protection enabled on it. It has a protected version of the bootloader. Devices support this feature on Device-OS 6.0.0 and higher.

state: true

Protected Device (service mode)

A Protected Device in Service Mode acts like an Open Device only temporarily. A Protected Device stays in Service Mode for up to 20 reboots or 24 hours. It's possible to use other CLI commands during this time.

state: true, overridden: true

Diagram

image

How protection is enabled on a device

To enable protection on a device, use the particle device-protection enable command. This command flashes the protected bootloader, either provided via the --file option when working in offline mode or by downloading the Device-OS released bootloader in online mode, and applies protection to it. If the Device-OS version of the binary provided is lesser than 6.0.0 (which is the min version at which Protected Devices are supported), then the CLI rejects it. Additionally, it removes the device from development mode, allowing the cloud to flash the appropriate firmware as needed. Note that the CLI will not protect a device if it is not part of a product that supports device protection.

How protection is removed on a device

A Protected Device cannot be turned into an Open Device via the CLI. A Protected Device can only be put into Service Mode to perform any CLI operations as needed. A Protected Device can be turned to an Open Device only via the cloud.

To keep a Protected Device in Service Mode, use the particle device-protection disable command.

Temporarily disabling protection on a device (service mode device) (Same as above)

To temporarily disable protection and enable access to various functions, use the particle device-protection disable command. This command temporarily provides access to all the interfaces as if the device is an Open Device and places the device back in Protected Mode after 20 reboots or 24 hours, whichever comes first.

How to create a protected bootloader from a Device-OS released bootloader if needed

Run particle binary enable-device-protected argon-bootloader@6.1.1.bin

How to Test

Setup your device and cli

  1. Flash the Device-OS 6.1.1 with the bootloader (if 6.1.1 is not ready, compile and flash Device-OS at this commit) with a blank app or an app of your choice

  2. Check out this branch and run nvm use and npm ci

Commands to use the device protection feature

  1. npm start -- device-protection --help
  2. npm start -- device-protection status
  3. npm start -- device-protection disable
  4. npm start -- device-protection status
  5. npm start -- device-protection enable
  6. npm start -- device-protection status

Related Issues / Discussions

SC Epic: https://app.shortcut.com/particle/epic/127955 SDD: https://www.notion.so/particle/Device-Protection-Tooling-SDD-89983752943a4bc69fc0e611480b8271

Completeness

keeramis commented 4 months ago

The unit tests failing here are logic-function ones and not the ones for device protection. Perhaps something has changed with the cyberdane product. I will look into those now.