diff --git a/docs/solo/bootloader-mode.md b/docs/solo/bootloader-mode.md index ff4358a..d69b6dc 100644 --- a/docs/solo/bootloader-mode.md +++ b/docs/solo/bootloader-mode.md @@ -1,16 +1,17 @@ # Booting into bootloader mode -You can put Solo into bootloader mode by holding down the button, and plugging in Solo. After 2 seconds, bootloader mode will activate. -You'll see a yellowish flashing light and you can let go of the button. - -Now Solo is ready to [accept firmware updates](/solo/signed-updates). If the Solo is a secured model, it can only accept signed updates, typically in the `firmware-*.json` format. - -If Solo is running a hacker build, it can be put into bootloader mode on command. This makes it easier for development. +If you have a recent version of Solo, you can put it into bootloader mode by running this command. ```bash solo program aux enter-bootloader ``` +If your Solo is a bit older (<=2.5.3) You can put Solo into bootloader mode by using the button method: +Hold down button while plugging in Solo. After 2 seconds, bootloader mode will activate. +You'll see a yellowish flashing light and you can let go of the button. + +Now Solo is ready to [accept firmware updates](/solo/signed-updates). If the Solo is a secured model, it can only accept signed updates, typically in the `firmware-*.json` format. + # The boot stages of Solo Solo has 3 boot stages. @@ -21,7 +22,8 @@ The first stage is the DFU (Device Firmware Update) which is in a ROM on Solo. This is what allows the entire firmware of Solo to be programmed. **It's not recommended to develop for Solo using the DFU because if you program broken firmware, you could brick your device**. -On hacker devices, you can boot into the DFU by holding down the button for 5 seconds, when Solo is already in bootloader mode. +On hacker/nonverifying-bootloader devices, you can boot into the DFU by holding down the button for 5 seconds, +when Solo is already in bootloader mode. You can also run this command when Solo is in bootloader mode to put it in DFU mode. @@ -29,7 +31,7 @@ You can also run this command when Solo is in bootloader mode to put it in DFU m solo program aux enter-dfu ``` -Note it will stay in DFU mode until to tell it to boot again. You can boot it again by running the following. +Note it will stay in DFU mode until you to tell it to boot again. You can boot it again by running the following. ```bash solo program aux leave-dfu diff --git a/docs/solo/building.md b/docs/solo/building.md index 3fbfb9b..f5752ab 100644 --- a/docs/solo/building.md +++ b/docs/solo/building.md @@ -36,17 +36,21 @@ Enter the `stm32l4xx` target directory. cd targets/stm32l432 ``` -Now build Solo. +Now build the Solo application. ``` -make build-hacker +make firmware ``` -The `build-hacker` recipe does a few things. First it builds the bootloader, with +The `firmware` recipe builds the solo application, and outputs `solo.hex`. You can use this +to reprogram any unlocked/hacker Solo model. Note that it does not include the Solo bootloader, +so it is not a full reprogram. + + If you're just planning to do development, **please don't try to reprogram the bootloader**, as this can be risky if done often. Just use `solo.hex`. @@ -57,13 +61,13 @@ If you're developing, you probably want to see debug messages! Solo has a USB Serial port that it will send debug messages through (from `printf`). You can read them using a normal serial terminal like `picocom` or `putty`. -Just add `DEBUG=1` or `DEBUG=2` to your build recipe, like this. +Just add `-debug-1` or `-debug-2` to your build recipe, like this. ``` -make build-hacker DEBUG=1 +make firmware-debug-1 ``` -If you use `DEBUG=2`, that means Solo will not boot until something starts reading +If you use `debug-2`, that means Solo will not boot until something starts reading its debug messages. So it basically waits to tether to a serial terminal so that you don't miss any debug messages. @@ -78,27 +82,45 @@ solo monitor [See issue 62](https://github.com/solokeys/solo/issues/62). -### Building a Solo release +### Building a complete Solo build (application + bootloader + certificate) -To build Solo +To make a complete Solo build, you need to build the bootloader. We provide +two easy recipes: -If you want to build a release of Solo, we recommend trying a Hacker build first -just to make sure that it's working. Otherwise it may not be as easy or possible to -fix any mistakes. +* `bootloader-nonverifying`: bootloader with no signature checking on updates. I.e. "unlocked". +* `bootloader-verifying`: bootloader with signature checking enforced on updated. I.e. "Locked". -If you're ready to program a full release, run this recipe to build. +To be safe, let's use the `-nonverifying` build. ``` -make build-release-locked +make bootloader-nonverifying ``` -This outputs bootloader.hex, solo.hex, and the combined all.hex. +This outputs `bootloader.hex`. We can then merge the bootloader and application. -Programming `all.hex` will cause the device to permanently lock itself. This means debuggers cannot be used and signature checking -will be enforced on all future updates. +``` +solo mergehex bootloader.hex solo.hex bundle.hex +``` -Note if you program a secured `solo.hex` file onto a Solo Hacker, it will lock the flash, but the bootloader -will still accept unsigned firmware updates. So you can switch it back to being a hacker, but you will -not be able to replace the unlocked bootloader anymore, since the permanently locked flash also disables the DFU. -[Read more on Solo's boot stages](/solo/bootloader-mode). +`bundle.hex` is our complete firmware build. Note it is in this step that you can +include a custom attestation certificate or lock the device from debugging/DFU. +By default the "hacker" attestation certifcate and key is used. + +``` +solo mergehex \ + --attestation-key "0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF" \ + --attestation-cert attestation.der \ + --lock \ + solo.hex \ + bootloader.hex \ + bundle.hex +``` + +See [here for more information on custom attestation](/solo/customization/). + +If you use `--lock`, this will permanently lock the device to this new bootloader. You +won't be able to program the bootloader again or be able to connect a hardware debugger. +The new bootloader may be able to accept (signed) updates still, depending on how you configured it. + +To learn more about normal updates or a "full" update, you should [read more on Solo's boot stages](/solo/bootloader-mode). diff --git a/docs/solo/customization.md b/docs/solo/customization.md index 4826c74..b8f5444 100644 --- a/docs/solo/customization.md +++ b/docs/solo/customization.md @@ -114,28 +114,27 @@ If the checks succeed, you are ready to program the device attestation key and c ### Programming an attestation key and certificate -Convert the DER format of the device attestation certificate to "C" bytes using our utility script. You may first need to -first install prerequisite python modules (`pip install -r tools/requirements.txt`). +First, [Build your solo application and bootloader](/solo/building). -``` -python tools/gencert/cbytes.py device_cert.der -``` - -Copy the byte string portion into the [`attestation.c` source file of Solo](https://github.com/solokeys/solo/blob/master/targets/stm32l432/src/attestation.c). Overwrite the development or "default" certificate that is already there. - -Now [build the Solo firmware](/solo/building), either a secure or hacker build. You will need to produce a `bootloader.hex` file and a `solo.hex` file. - -Print your attestation key in a hex string format. +Print your attestation key in a hex string format. Using our utility script: ``` python tools/print_x_y.py device_key.pem ``` -Merge the `bootloader.hex`, `solo.hex`, and attestion key into one firmware file. +Merge the `bootloader.hex`, `solo.hex`, attestion key, and certificate into one firmware file. ``` -solo mergehex --attestation-key bootloader.hex solo.hex all.hex +solo mergehex \ + --attestation-key "(The 32-byte hex string extracted from device_key.pem)" \ + --attestation-cert device_cert.der \ + --lock \ + solo.hex \ + bootloader.hex \ + bundle.hex ``` -Now you have a newly create `all.hex` file with a custom attestation key. You can [program this `all.hex` file +Now you have a newly created `bundle.hex` file with a custom attestation key and cert. You can [program this `bundle.hex` file with Solo in DFU mode](/solo/programming#procedure). + +Are you interested in customizing in bulk? Contact hello@solokeys.com and we can help. diff --git a/docs/solo/programming.md b/docs/solo/programming.md index a63d39e..424d373 100644 --- a/docs/solo/programming.md +++ b/docs/solo/programming.md @@ -22,12 +22,11 @@ solo key update <--secure | --hacker> You can manually install the [latest release](https://github.com/solokeys/solo/releases), or use a build that you made. ```bash -# If it's a hacker, it will automatically boot into bootloader mode. solo program bootloader ``` Note you won't be able to use `all.hex` or the `bundle-*.hex` builds, as these include the solo bootloader. You shouldn't -risk changing the Solo bootloader unless you want to make it a secure device, or [make other customizations](). +risk changing the Solo bootloader unless you want to make it a secure device, or [make other customizations](/solo/customization/). ## Updating a Hacker to a Secure Solo @@ -38,14 +37,14 @@ You can use a firmware build from the [latest release](https://github.com/soloke a build that you made yourself. You need to use a firmware file that has the combined bootloader and application (or at the very least just the bootloader). -This means using the `bundle-*.hex` file or the `all.hex` from your build. If you overwrite the Solo flash with a missing bootloader, +This means using the `bundle-*.hex` file or the `bundle.hex` from your build. If you overwrite the Solo flash with a missing bootloader, it will be bricked. We provide two types of bundled builds. The `bundle-hacker-*.hex` build is the hacker build. If you update with this, you will update the bootloader and application, but nothing will be secured. The `bundle-secure-non-solokeys.hex` is a secured build that will lock your device and it will behave just like a Secure Solo. The main difference is that it uses a "default" attestation key in the device, rather than the SoloKeys attestation key. There is no security -concern with using our default attestation key, aside from a privacy implication that services can distinguish it from Solo Secure. +concern with using our default attestation key, aside from a small privacy implication that services can distinguish it from Solo Secure. ### Procedure @@ -61,7 +60,7 @@ concern with using our default attestation key, aside from a privacy implication 2. Program the device - solo program dfu + solo program dfu Double check you programmed it with bootloader + application (or just bootloader). If you messed it up, simply don't do the next step and repeat this step correctly.