From abd2eca3ca1b0c61005e1015a60977ead78609e3 Mon Sep 17 00:00:00 2001 From: Conor Patrick Date: Fri, 16 Aug 2019 13:53:28 +0800 Subject: [PATCH] run through fixes --- docs/solo/bootloader-mode.md | 2 +- docs/solo/building.md | 7 +++++++ docs/solo/customization.md | 23 ++++++++++++----------- 3 files changed, 20 insertions(+), 12 deletions(-) diff --git a/docs/solo/bootloader-mode.md b/docs/solo/bootloader-mode.md index 5979c1b..ff4358a 100644 --- a/docs/solo/bootloader-mode.md +++ b/docs/solo/bootloader-mode.md @@ -3,7 +3,7 @@ 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. If the Solo is a secured model, it can only accept signed updates, typically in the `firmware-*.json` format. +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. diff --git a/docs/solo/building.md b/docs/solo/building.md index 0cc4817..3fbfb9b 100644 --- a/docs/solo/building.md +++ b/docs/solo/building.md @@ -92,6 +92,13 @@ If you're ready to program a full release, run this recipe to build. make build-release-locked ``` +This outputs bootloader.hex, solo.hex, and the combined all.hex. + 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. +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). + diff --git a/docs/solo/customization.md b/docs/solo/customization.md index 08b74da..e7d65b2 100644 --- a/docs/solo/customization.md +++ b/docs/solo/customization.md @@ -5,7 +5,8 @@ If you are interested in customizing parts of your Solo, and you have a Solo Hac ## Custom Attestation key The attestation key is used in the FIDO2 *makeCredential* or U2F *register* requests. It signs -newly generated credentials. The certification associated with the attestation key is output as well. +newly generated credentials. The certificate associated with the attestation key is output with newly created credentials. + Platforms or services can use the attestation feature to enforce specific authenticators to be used. This is typically a use case for organizations and isn't seen in the wild for consumer use cases. @@ -18,11 +19,11 @@ and program it. ### Creating your attestation key pair Since we are generating keys, it's important to use a good entropy source. -You can use your Solo device to generate some good random numbers. +You can use the True RNG on your Solo device to generate some good random numbers. ``` # Run for 1 second, then hit control-c -solo key rng > seed.bin +solo key rng raw > seed.bin ``` First we will create a self signed key pair that acts as the root of trust. This @@ -36,7 +37,7 @@ curve=prime256v1 country=US state=Maine organization=OpenSourceSecurity -unit=Root CA +unit="Root CA" CN=example.com email=example@example.com @@ -73,7 +74,7 @@ Note you must use a prime256v1 curve for this step, and you must leave the unit/ country=US state=Maine organization=OpenSourceSecurity -unit=Authenticator Attestation +unit="Authenticator Attestation" CN=example.com email=example@example.com @@ -81,7 +82,7 @@ email=example@example.com openssl ecparam -genkey -name "$curve" -out device_key.pem -rand seed.bin # generate a "signing request" -openssl req -new -key device_key.pem -out device_key.pem.csr -subj "/C=$country/ST=$state/O=$organization/OU=$unit/CN=example.com/emailAddress=$email +openssl req -new -key device_key.pem -out device_key.pem.csr -subj "/C=$country/ST=$state/O=$organization/OU=$unit/CN=example.com/emailAddress=$email" # sign the request openssl x509 -req -days 18250 -in device_key.pem.csr -extfile v3.ext -CA root_cert.pem -CAkey root_key.pem -set_serial 01 -out device_cert.pem -sha256 @@ -100,13 +101,13 @@ echo 'challenge $RANDOM' > chal.txt # check that they are valid key pairs openssl dgst -sha256 -sign device_key.pem -out sig.txt chal.txt -openssl dgst -sha256 -verify <(openssl x509 -in device_cert.der -pubkey -noout) -signature sig.txt chal.txt +openssl dgst -sha256 -verify <(openssl x509 -in device_cert.pem -pubkey -noout) -signature sig.txt chal.txt openssl dgst -sha256 -sign "root_key.pem" -out sig.txt chal.txt -openssl dgst -sha256 -verify <(openssl x509 -in root_cert.der -pubkey -noout) -signature sig.txt chal.txt +openssl dgst -sha256 -verify <(openssl x509 -in root_cert.pem -pubkey -noout) -signature sig.txt chal.txt # Check they are a chain -openssl verify -verbose -CAfile "$rcert" "$icert" +openssl verify -verbose -CAfile "root_cert.pem" "device_cert.pem" ``` If the checks succeed, you are ready to program the device attestation key and certificate. @@ -127,13 +128,13 @@ Now [build the Solo firmware](/solo/building), either a secure or hacker build. Print your attestation key in a hex string format. ``` -python tools/print_x_y.py +python tools/print_x_y.py device_key.pem ``` Merge the bootloader.hex, solo.hex, and attestion key into one firmware file. ``` -solo merge --attestation-key bootloader.hex solo.hex all.hex +solo mergehex --attestation-key bootloader.hex solo.hex all.hex ``` Now you have a newly create `all.hex` file with a custom attestation key. You can [program this all.hex file