Initializing Root Keys - betrusted-io/betrusted-wiki GitHub Wiki

Precursor has several security keys. Before you can start doing anything, however, you need to initialize a set of "root keys". This should be done only after you're satisfied that you are ready to trust your Precursor device. The threshold for that is up to you -- you can rebuild your own softcore-CPU and OS, and inspect every component on the motherboard; or you can just assume that out of the box everything is cool.

Everyone has a different use case, and there is no one answer to this.

Your device will inform you that there is a security problem by putting a dashed line through the top status bar:

images/dashed_line.png

Anytime you see this, it means something did not check out in the full security path. You will expect to see this on the following occasions:

  • A brand new device, without root keys
  • After installing a firmware update, but before you have self-signed the update

Once you're ready to trust your device, select the "Initialize root keys" option from the main menu on Precursor, which is accessed by pressing the middle of the D-pad button immediately beneath the center of the screen.

images/initialize_root_keys.png

If you don't see this option, but are instead presented with the option to "install gateware update" and "sign xous", this means someone has previously initialized the root keys on your device. Assuming the device has not had its eFuses burned, you should be able to wipe the device to a factory-new state and re-install keys; however, there is no way to recover the root keys without knowing the passwords used to secure them.

You will be required to pick two passwords:

  • The "root" password is a critical password for system security that you will enter only after applying an update to the gateware or OS. This should be hard to guess and long.
  • The "boot PIN" password is a relatively low-impact password that you will enter regularly, on every boot or even every time you unlock the screen. A simple PIN or password should suffice.

The "boot PIN" password is low-impact because you may be forced to disclose the password; for example, at a customs checkpoint, or under force of subpoena. Data which you which to keep in confidence can be protected with further sets of passwords, which are designed to be plausibly deniable: there is no forensic difference between simply forgetting plausibly deniable passwords, and erasing the data from the device. "Device unlock" thus serves primarily as a deterrent to nosy neighbors and petty theft.

The password request dialog boxes will try to briefly remind you of the security impact of your passwords, as shown below:

images/password_request.png

Some things to keep in mind:

  • An authentic password request will only show up as inverted text (white text on a black background, as shown above)
  • You can use the left/right D-pad keys to select the visibility of the password. By default, the last two characters are shown, and the rest are hidden. Toggling left shows all characters, toggling right hides all characters.
  • The pattern of lines in the background will change every time. They are drawn to "deface" any background content and prevent it from attempting to masquerade as a valid password request. If you see random lines drawn over your password request, do not trust the request!

In some cases, you will also be asked to pick a password retention policy (keep until reboot/keep until suspend/use once). By default, the update passwords are erased on suspend, and the unlock passwords are kept until reboot.

There is no way to recover these passwords. We do not have a back-up service, or a recovery method for the root key passwords.

Renode Emulation

Renode comes pre-loaded with an initialized root key box. Both the boot and root passwords are simply the letter 'a'.