The Baochip bootloader assumes an environment where USB is available. The device will enumerate as a USB mass storage device. Firmware is delivered by copying [`UF2`]((https://makecode.com/blog/one-chip-to-flash-them-all)) files into the drive (it is *not* usable as a generic storage device). Be sure to cleanly unmount or `sync` the drive before booting the device.
The bootloader also makes a "serial console" available over USB. This is the primary method for developers to interact with the device. Read more about [serial consoles](./README-consoles.md).
The build idiom is `cargo xtask <target>`, i.e. `cargo xtask dabao`. The build will generate a [`UF2`](https://makecode.com/blog/one-chip-to-flash-them-all) artifact, which can be found in `target/riscv32imac-unknown-[xous|none]-elf/release/`. You will need to copy all three artifacts generated (loader.uf2, xous.uf2, and apps.uf2) initially to ensure that the loader, kernel, and applications are at the same revision. After that point if the loader and kernel are not updated, one can just update apps.uf2.
Holding down the `PROG` button while plugging the device into USB will cause it to enter a bootloader that enumerates a mass storage device. The build artifacts can then be copied onto the device. Pressing `PROG` again will cause the device to run the program. Targets also enumerate a serial port over USB, which will activate a debug console.
Regardless of the board, the `bao1x` chip comes from the factory programmed with `boot0` and `boot1` stages. The code for these can be found in `bao1x-boot/`.
-`boot0` is a permanent root of trust burned onto the chip. Its sole purpose is to validate `boot1`. See [security model](./README-baochip.md#security-model) for details on the trust chain
-`boot1` contains a USB driver, serial-over-USB driver, and serial driver capable of accepting code updates in the form of .u2f files or serial commands. It also contains a small command terminal for managing configurations, keys, and device lifecycle state.
-`PC13` and `PF5` are both briefly driven to 0 and then 1 before USB enumeration. A USB switch such as the EMS4000 will ensure "clean" enumeration as the USB PHY on Baochip has no way to definitively enter the SE0 state on its own. After exiting the bootloader, the pin not corresponding to the board type is set to an input (`PC13` is dabao, `PF5` is baosec).
-`PB14` and `PB13` are `TX` and `RX` pairs of a serial console, set to 1,000,000 baud 8N1.
`boot1` is responsible for managing application loading. As such, updating `boot1` requires an intermediate step, because the actively executing program cannot overwrite its contents safely. The overview for updating `boot1` is as follows:
1. Load `boot1-alt` into the `baremetal` region.
2. Run `boot1-alt`, thus freeing `boot1` to be updated.
3. Copy the updated `boot1` record while in the `boot1-alt` environment.
You can fetch pre-built verions of the .uf2 files from the CI pipeline [here](https://ci.betrusted.io/latest-ci/baochip/bootloader/). Once Baochip hits release status, we'll drop a link for a stable release version here as well.
3. Plug the dabao board into the host. Confirm that the mass storage device has the volume label of `BAOCHIP`.
4. Copy `target/riscv32imac-unknown-none-elf/release/bao1x-alt-boot1.uf2` into the `BAOCHIP` volume.
5. Press `PROG` (the button closest to the USB connector)
6. The board should unmount itself and re-mount as a volume with the label of `ALTCHIP`.
7. Copy `target/riscv32imac-unknown-none-elf/release/bao1x-boot1.uf2` into the `ALTCHIP` volume.
8. Press `RESET` (the button farthest from the USB connector)
9. The device should re-appear as `BAOCHIP`
10. Confirm boot1 update by running the `audit` command on the boot1 console and checking that the reported git revision matches that of the source build.
- [`baremetal`](./baremetal/) is an unsecured, bare-iron environment. It is `no-std`, but comes with `alloc` pre-initialized and a USB serial console.
- [`dabao`](./apps-dabao/) is a Xous environment. It boots a full kernel, supports `std`, and features "detached-apps", i.e., users can develop stand-alone applications that run on the OS without having to touch the kernel image.
- [`baosec`](./apps-baosec/) is a Xous environment. It is like `dabao`, but supports swap memory. As a result it can run much larger, more complicated applications. The on-chip RRAM is reserved for the kernel, while the off-chip swap contains user applications.
Code is delivered via `boot1`. `boot1` is entered by holding down a button while power the device on. The device will show up as a USB mass storage device, at which point a .uf2 file containing the application image is copied to the device, and the update is applied.
For developers that don't need strong security, "out of tree" builds are available. An out of tree build allows just the app to be built on its own, targeting a xous-core revision via a github revision. See this [out of tree demo app](https://github.com/bunnie/dabao-console) for more information on how to set up and run an out of tree build.
Out of tree advantages:
- Just the application code is cloned
- Faster, lighter-weight builds
Out of tree disadvantages:
- Application and kernel can be out of sync
- Features like anti-rollback, version checking, and secure signing don't work
If you're looking to use the Baochip as a lightweight microcontroller for write-once projects, out of tree builds might be a good match for your scenario.
If you're looking to build a more durable application meant to be distributed as a product with firmware signing, you'll want to do an in-tree build.
The default `bao1x` chips come from the factory with four public keys burned into them:
- Two code deployment signing keys
- One beta signing key
- One developer key (anyone can use the [private key](./devkey/README.md) to sign a developer image)
In addition to these public keys, a collection of initial identifiers and secrets are generated on-device which serve as the security root. Each boot stage has a copy of these public keys; thus the key set can be updated/changed for downstream artifacts. boot0/boot1 should be rarely, if ever, updated; meanwhile detached application images running within the OS environment may have more permissive signing policies since memory protection is enforced by the OS.
By default, the `bao1x` will accept and run developer images; however upon encountering a developer image anywhere in the boot chain, all the initial secrets are erased, and a one-way counter is incremented to indicate the device is a developer device. From this point developers can generate new keys, but any device attestation or on-chip secrets programmed into the device are lost.
The developer key can be revoked by running `lockdown` at the `boot1` stage. `baosec` boards have this done at the factory prior to shipment, to prevent tampering in the supply chain.
Baochip cannot be the ultimate guarantor of third party signature integrity. It doesn't have the resources or
risk profile to (for example) sign cryptocurrency wallets. Thus, developers looking to build high-value applications
on Baochip must also manage their own signing keys. To this end, a policy of "mutual distrust" is enforced by `boot0`.
#### Preventing Third Party Access to Baochip Secrets
Boot0 and Boot1 check the public key block presented by the next stage against a set of expected public
keys that should match the Baochip OEM keys. If any of these do not match, most of the Baochip secret
keys are erased before running the next stage. Thus any third party firmware may be free to inspect
Baochip's keyslots, but by the time it runs, those keyslots have been erased.
#### Preventing Baochip Access to Third Party Secrets
An bank of 4x 256-bit keys known as `collateral` keys are provided. These keys are always erased by
the boot0 / boot1 firmware whenever the public key block embedded in the header of the next stage matches Baochip's
expected public keys. The only condition when they are not erased is when key slots 0, 1, and 2 are all
different from Baochip's public keys (key slot 3 is a devkey slot, and anyone can sign an image for
that key slot, so it is not erased).
#### Details of the Mutual-Distrust Mechanism
The Mutual-Distrust mechanism aims to achieve the following goals:
1. Any firmware signed by a third party can't be used to decrypt Baochip secrets
2. Any firmware signed by Baochip can't be used to decrypt third party secrets
Before we get into how the above is implemented, some definitions:
`third party firmware`: Code signed and maintained by a third party. Once a third party has a Baochip-signed `boot1`, they can freely sign further downstream application images using their own signing keys; updates to `boot1` would require a fresh Baochip signature.
`key manifest`: Each stage contains an embedded header which contains a signature for the code in that stage.
Immediately after the signature and within the signed region, there is a `key manifest` that
consists of four ED25519 public keys. The `key manifest` declares what public keys the current
stage intends to use for verifying the next stage's code.
`reference keys`: Baochip's expected signing keys. These are burned into multiple redundant indelible locations. Collectively they are referred to as `reference keys`.
`Baochip secrets`: Baochip stores its secret keys in a block of key slots expressly reserved for Baochip's use. These are erased anytime trust is transferred to a new entity, or if trust is lost (e.g. going into developer mode).
`collateral`: A set of keys used to effect key destruction when crossing trust domains. To accomplish this, third party firmware *must* use at least 256 bits of the `collateral` key set in its master key derivation scheme.
`developer key`: A public key stored in slot 3 of the `key manifest` that corresponds to a well-known private key. Anyone can sign an image with a `developer key`.
Based on the above definitions, here are the mutual-distrust policies enforced by the Baochip bootloader:
1.`boot0` verifies that its `key manifest` matches the `reference keys`. If not, `Baochip secrets` are erased.
2.`boot0` verifies that `boot1`'s `key manifest` matches the `reference keys`. If any keys do not match, `Baochip secrets` are erased.
3.`boot0` checks if any non-`developer key` keys in `key manifest` match the `reference keys`. If any matching keys are found, the `collateral` is erased. Otherwise, `collateral` is preserved.
Let's observe what properties are guaranteed by this arrangement:
- If `boot0` and `boot1`'s `key manifest`s match the `reference keys`, then `Baochip secrets` are intact.
- If any of `boot1`'s `key manifest` non-developer entries match any of the `reference keys`, `collateral` is erased. Thus, any attempt to "downgrade" the firmware by loading a Baochip-signed image would not lead to third-party secret disclosure, because the `collateral` keys are part of the third party firmware's key derivation mechanism.
- If any of `boot1`'s `key manifest` does not match the `reference keys` or if `boot1` is signed by the `developer key`, most of Baochip's secrets are erased. Thus the process of loading third party firmware would also cause any Baochip secrets to be lost.
#### Conditions for Getting Signed Third-Party `boot1`
Baochip will *only* sign third-party `boot1` images after the proposed firmware meets the following tests:
1. The `boot1``key manifest` block is entirely different (except for optionally the developer key) from Baochip's `reference keys`
2. The proposed firmware can demonstrate that it has initialized the `collateral` key slots by revealing the contents of `collateral` slot 3 via an introspection command (slots 0, 1, and 2 are private; each slot is 256 bits in length).
3. The proposed firmware demonstrates permanent loss of access to encrypted data if a Baochip-signed `boot1` is swapped in, and then reverted back to the third-party-signed `boot1`.
4. The same introspection command used in step 2 is run again. The resulting value must be different from the value reported in the original run of step 2.
The above four tests are written such that the test can be run without inspection of the details of the third party firmware, but ideally, Baochip can inspect the firmware to ensure the intended policies are in place.
Note that if the third party firmware developer fails to use the `collateral` keys correctly to derive its master key, it can be subject to exploitation by a Baochip-signed image. Baochip takes no responsibility for any damages that may occur in that event.
Baochip would also entertain giving third parties self-signed `boot0`s with indelible `reference keys` linked to their own keys, *but* this requires a minimum order of around 50,000 chips plus a per-lot engineering fee to retool the wafer probe infrastructure used to burn the keys into the chip (these numbers are just ballpark estimates; contact Baochip to finalize details). Thus for high-volume applications this is a viable option, while the third-party firmware mechanism is an economical option to bootstrap self-managed secure ecosystems.