Add mention of evil maid attacks (#47)

* Add mention of evil maid attacks * doc: improve wording * doc: acc note about decoy devices * fix: use archived link * doc: improve search key format * doc: improve formatting * doc: Use capitalization and repetition for user's attention * doc: some more improvements * doc: add missing period * doc: improve formatting * doc: improve * doc: improve again * fix: broken link syntax
epiccurious · Dec 17, 2023 · 7bd652c · 7bd652c
1 parent 5a6f671
commit 7bd652c
Show file tree

Hide file tree

Showing 2 changed files with 67 additions and 29 deletions.
diff --git a/README.md b/README.md
@@ -6,15 +6,16 @@ This guide is designed for the general user who is not incompetant with computer
 
 - [Background](#background)
   - [What is a Jade?](#what-is-a-jade)
-  - [Motivation](#motivation)
+  - [Motivation (Who Should Follow This Guide?)](#motivation-who-should-follow-this-guide)
   - [Who Should NOT Follow This Guide?](#who-should-not-follow-this-guide)
+  - [MUST READ: Keep Your DIY Jade Secured](#must-read-keep-your-diy-jade-secured)
   - [Current Limitations of Third-Party DIY Hardware](#current-limitations-of-third-party-diy-hardware)
-- [Overview of Hardware Options](#overview-of-hardware-options)
+- [Hardware Options](#hardware-options)
   - [TTGO T-Display](#ttgo-t-display)
   - [M5Stack M5StickC PLUS](#m5stack-m5stickc-plus)
   - [M5Stack Core Basic](#m5stack-core-basic)
   - [M5Stack FIRE v2.6](#m5stack-fire-v26)
-- [Set Up Instructions](#set-up-instructions)
+- [Set-Up Instructions](#set-up-instructions)
   - [Use the Semi-Automated Script](#use-the-semi-automated-script)
   - [Use a Device-Specific Script](#use-a-device-specific-script)
   - [Run the Commands Manually](#run-the-commands-manually)
@@ -28,7 +29,7 @@ This guide is designed for the general user who is not incompetant with computer
 
 The firmware that runs Jade can also run other general purpose hardware that shares the same ESP32 microcontroller.
 
-### Motivation
+### Motivation (Who Should Follow This Guide)
 
 Why Should I Follow This Guide?
 
@@ -46,16 +47,30 @@ You understand that the person who sells you hardware for your bitcoin shouldn't
 2. You want to learn how to use the Jade hardware wallet. Refer to [the Jade's help center documentation](https://help.blockstream.com/hc/en-us/categories/900000061906-Blockstream-Jade/) or [contact Blockstream](https://help.blockstream.com/hc/en-us/requests/new) for software support.
 <!-- markdown-link-check-enable -->
 
-3. You're a normie who can't be bothered to learn how to operate a computer through the command line. We will be using the Terminal console, which some people find scary. It's not hard, I promise.
+3. You can't be bothered to operate a computer through the command line. We will be using the Terminal console, which some people find scary. It's not hard, I promise.
 
-4. You aren't willing to use macOS or [Linux](https://ubuntu.com/tutorials/install-ubuntu-desktop). (This guide only supports macOS and Debian Linux for now but will eventually add support for other Linux distributions.)
+4. You aren't willing to use [Linux](https://ubuntu.com/tutorials/install-ubuntu-desktop), macOS (running modern Arm-based hardware), or ChromOS. (This guide only supports Debian-based Linux, macOS, and ChromeOS for now but will eventually add support for other Linux distributions.)
+
+### MUST READ: Keep Your DIY Jade Secured
+
+tl;dr: ***You need to control physical access to your DIY Jade.***
+
+Evil maid attacks, such as [this one done by hackers for a competitor](https://www.ledger.com/blog/firmware-extraction-evil-maid-attacks-on-blockstream-jade-hardware-wallet), will become easier and cheaper to perform over time.
+
+It's not just a risk of someone hacking or altering YOUR device. An evil maid can also swap your device with a new malicious device.
+
+**You need to control physical access to your DIY Jade** hardware wallet at all times as a countermeasure. Keep your DIY Jade locked up in a safe, lockbox, or some other method of restricting access. Don't let your house cleaner see your DIY Jade.
+
+For further reading, please see [[#1]](https://usa.kaspersky.com/blog/fake-trezor-hardware-crypto-wallet/28299/), [[#2]](https://media.ccc.de/v/35c3-9563-wallet_fail), [[#3]](https://blog.trezor.io/psa-non-genuine-trezor-devices-979b64e359a7), [[#4]](https://web.archive.org/web/20220820031918/https://www.reddit.com/r/ledgerwallet/comments/o154gz/comment/h1zagmk/).
 
 ### Current Limitations of Third-Party DIY Hardware
 
 - No camera support. To build a DIY Jade with camera support, [please refer here](https://www.youtube.com/watch?v=V2yVKag2wlc).
 - Need a documented process for updating firmware.
 
-## Overview of Hardware Options
+[[back to top]](#table-of-contents)
+
+## Hardware Options
 
 You are better off buying the hardware directly from the hardware vendor than through a third-party channel like Amazon or Alibaba. In many cases, it's cheaper to buy direct too.
 
@@ -92,7 +107,9 @@ You are better off buying the hardware directly from the hardware vendor than th
 - **MSRP: [$50](https://shop.m5stack.com/products/m5stack-fire-iot-development-kit-psram-v2-6)**
 - Nice 3-button design, a bigger battery, and a magnetic charging base
 
-## Set Up Instructions
+[[back to top]](#table-of-contents)
+
+## Set-Up Instructions
 
 There are three options for flashing your device:
 - [**Install with the Semi-Automated Script**](#install-with-the-semi-automated-script) (easiest way)
@@ -103,39 +120,45 @@ There are three options for flashing your device:
 
 This option is recommended for the average user who doesn't know how to read and write bash.
 
-1. Open the Terminal.
+1. Read [this section about physically securing your DIY Jade](#must-read-keep-your-diy-jade-secured).
+
+2. Open the Terminal.
     - On Linux, press `Ctrl+Alt+T`.
     - On macOS, press `Command+Space`, type terminal, and press `return`.
+    - on ChromeOS, install Linux under Settings -> Advanced -> Developers. Then press `🔍 (search)` on the keyboard, type terminal and press `enter`.
 
-2. Copy-paste the following full command in Terminal (you might have to scroll right):
+3. Run the following command (via copy-paste) in Terminal.
     ```bash
     /bin/bash -c "$(curl -sSL https://github.com/epiccurious/jade-diy/raw/master/flash_your_device)"
     ```
 
-3. When the script asks, choose your device (#1-#4).
+4. When the script asks, choose your device (#1-#4).
 
 After the script completes, you should see the Jade initialization screen on your device.
 
 ### Use a Device-Specific Script
 
-1. Open the Terminal. On Linux, press `Ctrl+Alt+T`. On macOS, press `Command+Space`, type terminal, and press `return`.
+1. Read [this section about physically securing your DIY Jade](#must-read-keep-your-diy-jade-secured).
 
-2. Connect your device to your computer via USB.
+2. Open the Terminal.
+    - On Linux, press `Ctrl+Alt+T`.
+    - On macOS, press `Command+Space`, type terminal, and press `return`.
+    - on ChromeOS, install Linux under Settings -> Advanced -> Developers. Then press `🔍 (search)` on the keyboard, type terminal and press `enter`.
 
-3. Run one of the following in Terminal:
-    - If you're using the TTGO T-Dispay, run:
+3. Run one of the following commands (via copy-paste) in Terminal.
+    - For the TTGO T-Dispay:
         ```
         /bin/bash -c "$(curl -sSL https://github.com/epiccurious/jade-diy/raw/master/device_specific/flash_the_ttgo_tdisplay)"
         ```
-    - If you're using the M5Stack M5StickC PLUS, run:
+    - For the M5Stack M5StickC PLUS:
         ```
         /bin/bash -c "$(curl -sSL https://github.com/epiccurious/jade-diy/raw/master/device_specific/flash_the_m5stack_m5stickc_plus)"
         ```
-    - If you're using the M5Stack Core Basic, run:
+    - For the M5Stack Core Basic:
         ```
         /bin/bash -c "$(curl -sSL https://github.com/epiccurious/jade-diy/raw/master/device_specific/flash_the_m5stack_core_basic)"
         ```
-    - If you're using the M5Stack FIRE, run:
+    - For the M5Stack FIRE:
         ```
         /bin/bash -c "$(curl -sSL https://github.com/epiccurious/jade-diy/raw/master/device_specific/flash_the_m5stack_fire)"
         ```
@@ -146,9 +169,11 @@ After the script completes, you should see the Jade initialization screen on you
 
 This options is provided for people who want to run the commands themselves.
 
-1. Open the Terminal. On Linux, press `Ctrl+Alt+T`. On macOS, press `Command+Space`, type terminal, and press `return`.
+1. Read [this section about physically securing your DIY Jade](#must-read-keep-your-diy-jade-secured).
 
-2. Install the required software packages. On a slow computer, this step can take over 20 minutes. Copy-and-paste the following lines into Terminal:
+2. Open the Terminal. On Linux, press `Ctrl+Alt+T`. On macOS, press `Command+Space`, type terminal, and press `return`.
+
+3. Install the required software packages. On a slow computer, this step can take over 20 minutes. Copy-and-paste the following lines into Terminal:
     ```bash
     sudo apt update
     sudo apt install -y cmake git python3-pip python3-venv
@@ -160,14 +185,14 @@ This options is provided for people who want to run the commands themselves.
     ```
 TODO: Add instructions for installing macOS dependendies.
 
-3. Download the Jade source code. Copy-and-paste the following lines into Terminal:
+4. Download the Jade source code. Copy-and-paste the following lines into Terminal:
     ```bash
     git clone --recursive https://github.com/blockstream/jade "${HOME}"/jade
     cd "${HOME}"/jade/
     git checkout $(git tag | grep -v miner | sort -V | tail -1)
     ```
 
-4. Load the pre-built configuration file for your DIY hardware.
+5. Load the pre-built configuration file for your DIY hardware.
     - For the TTGO T-Display, run:
         ```bash
         cp configs/sdkconfig_display_ttgo_tdisplay.defaults sdkconfig.defaults
@@ -185,29 +210,42 @@ TODO: Add instructions for installing macOS dependendies.
         cp configs/sdkconfig_display_m5fire.defaults sdkconfig.defaults
         ```
 
-5. Modify the configuration file you just loaded to disable logging in debug mode (a.k.a. "research and development" mode).
+6. Modify the configuration file you just loaded to disable logging in debug mode (a.k.a. "research and development" mode).
     ```bash
     sed -i.bak '/CONFIG_DEBUG_MODE/d' ./sdkconfig.defaults
     sed -i.bak '1s/^/CONFIG_LOG_DEFUALT_LEVEL_NONE=y\n/' sdkconfig.defaults
     rm sdkconfig.defaults.bak
     ```
-
-6. Connect your device to your computer via USB.
 
-7. Enable read-write permissions for your device.
+7. Build the firmware.
+    ```
+    idf.py build
+    ```
+
+8. Connect your device to your computer via USB.
+
+9. Enable read-write permissions for your device.
     ```bash
     [ -f /dev/ttyACM0 ] && sudo chmod o+rw /dev/ttyACM0
-    [ -f /dev/ttyUSB0 ] && sudo chmod a+rw /dev/ttyUSB0
+    [ -f /dev/ttyUSB0 ] && sudo chmod o+rw /dev/ttyUSB0
     ```
 TODO: Add macOS instructions.
 
-8. Flash (install) Jade onto your device. On a slow computer, this step can take over 10 minutes. Run the following command in Terminal:
+10. Flash (install) Jade onto your device. On a slow computer, this step can take over 10 minutes. Run the following command in Terminal:
     ```bash
     idf.py -b 115200 flash
     ```
 
+11. Either disable read-write permissions for your device or disconnect it. (Default permissions will be restored when you re-connect it.)
+    ```bash
+    [ -f /dev/ttyACM0 ] && sudo chmod o-rw /dev/ttyACM0
+    [ -f /dev/ttyUSB0 ] && sudo chmod o-rw /dev/ttyUSB0
+    ```
+
 After the build and flash process completes, you should see the Jade initialization screen on your device.
 
+[[back to top]](#table-of-contents)
+
 ## Acknowledgements
 
 Inspiration for this project came from:

diff --git a/flash_your_device b/flash_your_device
@@ -198,7 +198,7 @@ echo -e "Ready to install Jade ${jade_version} on your ${chosen_device}.\n  (Thi
 read -srn1 -p "  PRESS ANY KEY to continue... " && echo
 
 final_confirmation_sleep_time="10"
-echo -ne "\nJade ${jade_version} installion will begin in ${final_confirmation_sleep_time} seconds.\nPress Ctrl+C to cancel... "
+echo -ne "\nContinuing Jade ${jade_version} installion in ${final_confirmation_sleep_time} seconds.\nPress Ctrl+C to abort ... "
 sleep "${final_confirmation_sleep_time}"
 echo