diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 2bc0b863b..b21d1a28d 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -8,4 +8,21 @@ assignees: '' --- +#### Summary + + + +**Device** +- [ ] Amigo +- [ ] M5stickV +- [ ] Dock +- [ ] Bit +- [ ] Yahboom + +**Version** +- [ ] Official release (selfcustody/krux): +- [ ] Beta release (odudex/krux_binaries): + #### Describe the bug + + diff --git a/.github/codecov.yml b/.github/codecov.yml index cd1af3835..8b56d5302 100644 --- a/.github/codecov.yml +++ b/.github/codecov.yml @@ -2,5 +2,9 @@ coverage: status: project: default: - target: 100% - threshold: 15% \ No newline at end of file + target: 95% + threshold: 5% + patch: + default: + target: 95% + threshold: 5% diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 3d94f0b60..598c89ba3 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -11,7 +11,7 @@ jobs: build: strategy: matrix: - device: [maixpy_m5stickv, maixpy_amigo_ips, maixpy_amigo_tft, maixpy_bit, maixpy_dock] + device: [maixpy_m5stickv, maixpy_amigo, maixpy_bit, maixpy_dock] runs-on: ubuntu-latest services: registry: @@ -20,7 +20,7 @@ jobs: - 5000:5000 steps: - name: Checkout - uses: actions/checkout@v3 + uses: actions/checkout@v4 with: submodules: recursive - name: Set up Docker Buildx @@ -59,53 +59,29 @@ jobs: path: ${{ steps.extract-m5stickv.outputs.destination }} name: build-m5stickv - - name: Build for Amigo IPS - if: matrix.device == 'maixpy_amigo_ips' + - name: Build for Amigo + if: matrix.device == 'maixpy_amigo' uses: docker/build-push-action@v4 with: context: . - build-args: DEVICE=maixpy_amigo_ips + build-args: DEVICE=maixpy_amigo push: true - tags: localhost:5000/selfcustody/krux-builder-amigo-ips:latest + tags: localhost:5000/selfcustody/krux-builder-amigo:latest cache-from: type=local,src=/tmp/.buildx-cache cache-to: type=local,dest=/tmp/.buildx-cache-new,mode=max - - name: Extract firmware for Amigo IPS - id: extract-amigo-ips - if: matrix.device == 'maixpy_amigo_ips' + - name: Extract firmware for Amigo + id: extract-amigo + if: matrix.device == 'maixpy_amigo' uses: shrink/actions-docker-extract@v2 with: - image: localhost:5000/selfcustody/krux-builder-amigo-ips:latest + image: localhost:5000/selfcustody/krux-builder-amigo:latest path: /src/firmware/Kboot/build/. - - name: Upload firmware for Amigo IPS - if: matrix.device == 'maixpy_amigo_ips' + - name: Upload firmware for Amigo + if: matrix.device == 'maixpy_amigo' uses: actions/upload-artifact@v3 with: - path: ${{ steps.extract-amigo-ips.outputs.destination }} - name: build-amigo-ips - - - name: Build for Amigo TFT - if: matrix.device == 'maixpy_amigo_tft' - uses: docker/build-push-action@v4 - with: - context: . - build-args: DEVICE=maixpy_amigo_tft - push: true - tags: localhost:5000/selfcustody/krux-builder-amigo-tft:latest - cache-from: type=local,src=/tmp/.buildx-cache - cache-to: type=local,dest=/tmp/.buildx-cache-new,mode=max - - name: Extract firmware for Amigo TFT - id: extract-amigo-tft - if: matrix.device == 'maixpy_amigo_tft' - uses: shrink/actions-docker-extract@v2 - with: - image: localhost:5000/selfcustody/krux-builder-amigo-tft:latest - path: /src/firmware/Kboot/build/. - - name: Upload firmware for Amigo TFT - if: matrix.device == 'maixpy_amigo_tft' - uses: actions/upload-artifact@v3 - with: - path: ${{ steps.extract-amigo-tft.outputs.destination }} - name: build-amigo-tft + path: ${{ steps.extract-amigo.outputs.destination }} + name: build-amigo - name: Build for Bit if: matrix.device == 'maixpy_bit' diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index e8bdbd4dd..87cc1c4af 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -9,11 +9,11 @@ jobs: build-gh-pages: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 with: submodules: recursive - name: Setup Python - uses: actions/setup-python@v4 + uses: actions/setup-python@v5 with: python-version: '3.10' - name: Install dependencies diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 9423d2f77..a23e08e35 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -11,9 +11,9 @@ jobs: lint-black: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - name: Setup Python - uses: actions/setup-python@v4 + uses: actions/setup-python@v5 with: python-version: '3.10' - uses: psf/black@stable @@ -40,9 +40,9 @@ jobs: lint-pylint: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - name: Setup Python - uses: actions/setup-python@v4 + uses: actions/setup-python@v5 with: python-version: '3.10' - name: Install dependencies @@ -59,9 +59,9 @@ jobs: check-translations: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - name: Setup Python - uses: actions/setup-python@v4 + uses: actions/setup-python@v5 with: python-version: '3.10' - name: Validate translations @@ -70,11 +70,11 @@ jobs: run-tests: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 with: submodules: recursive - name: Setup Python - uses: actions/setup-python@v4 + uses: actions/setup-python@v5 with: python-version: '3.10' - name: Install dependencies @@ -89,11 +89,11 @@ jobs: coverage: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 with: submodules: recursive - name: Setup Python - uses: actions/setup-python@v4 + uses: actions/setup-python@v5 with: python-version: '3.10' - name: Install dependencies diff --git a/CHANGELOG.md b/CHANGELOG.md index 9365a790b..3dbb33bf4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,64 @@ +# Changelog 24.04.beta16 - February 10, 2024 + +## Changes + +### Wipe Device +Option on tools to wipe the device, permanently removing settings and stored encrypted mnemonics by erasing every single bit of user's flash space. + +### Better Deletion of Mnemonics Stored on SD card +When deleting an encrypted mnemonic from an SD card, Krux will now overwrite the memory area making it impossible to recover the previously stored data. + +### Save and Load Wallet Output Descriptor from SD card +Create or load from a wallet output descriptor file on an SD card. The backup file format is compatible with most coordinators. + +### Sign Messages at a Derived Bitcoin address +Sign messages from Sparrow and Specter, via QR code, also attesting a Bitcoin address belongs to you. + +### Add Entropy Quality Estimation for Mnemonic Creation. +Entropy quality estimators, like Shannon's entropy, were added to mnemonic generation through dice rolls and camera snapshot. + +### IRQ Interfaces +Button and touch presses are now detected by the application through IO interrupts. Meaning inputs events will be registered and handled even if they happened when other tasks were being executed by the processor, resulting in a better UX. + +### Restore Default Settings +Option to restore the device's settings to its factory state. + +### Optimized Settings Storage +Device's storage is now used more efficiently, data is stored less frequently, only in case a setting is changed from defaults. + +### Amigo's Power Manager Enhancements +Standardize Amigo's shutdown and power on behavior. + +### GUI Enhancements +Icons, information text boxes, and rounded shapes are now present at the GUI. + +### Mnemonic Numbers +To match the input options, export mnemonics as decimal, hexadecimal, or octal numbers. When loading from numbers, a new numbers confirmation screen was added. + +### Optimized QR codes +QR codes rendering is faster and uses less RAM. + +### Export QR Codes as Images to SD Card +Some QR codes can be exported as images to SD card. + +### Screensaver +Optional screensaver to reduce pixels' burn-in and grab the attention of the user when the device is left powered on. + +### Addresses Exploring +More receive and change addresses per page are shown on bigger screens. + +### Update Embit to version 0.7 +Use the latest Embit release. + +### Maix Dock Simulator +Now Krux PC simulator can also run in Maix Dock mode, mimicking appearance and characteristics of the most DIY Krux device. + +### Join Amigo IPS and Amigo TFT firmwares +Users will be able to flash a single firmware and change display settings if their device was shipped with a display different from standard TFT. + +### Other Small Fixes and Code Optimizations +Many other small fixes and optimizations under the hood. + # Version 23.09.1 - November 18, 2023 This release contain bugfixes: diff --git a/Dockerfile b/Dockerfile index 4f7527a7f..8fe50301a 100644 --- a/Dockerfile +++ b/Dockerfile @@ -110,4 +110,5 @@ FROM build-firmware AS build ARG DEVICE="maixpy_m5stickv" WORKDIR /src/firmware/Kboot/build RUN cp /src/firmware/MaixPy/projects/"${DEVICE}"/build/firmware.bin . +RUN sed -i -e 's/\r$//' *.sh RUN ./CLEAN.sh && ./BUILD.sh diff --git a/README.md b/README.md index 5d543fa10..31a890ead 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@

- +

Krux is open-source firmware that enables anyone to build their own Bitcoin signing device via off-the-shelf parts. It runs on Kendryte K210 devices such as the [M5StickV](https://docs.m5stack.com/en/core/m5stickv) and [Maix Amigo](https://www.seeedstudio.com/Sipeed-Maix-Amigo-p-4689.html), converting them into airgapped devices that can sign transactions for multisignature and single-sig wallets. @@ -66,25 +66,25 @@ Note that you can run `poetry install` after making a change to the krux code if ## Format code ```bash -poetry run black ./src -poetry run black ./tests +poetry run poe format ``` ## Run pylint ```bash -poetry run pylint ./src +poetry run poe lint ``` ## Run tests ```bash -poetry run pytest --cache-clear --cov src/krux --cov-report html ./tests +poetry run poe test ``` + This will run all tests and generate a coverage report you can browse to locally in your browser at `file:///path/to/krux/htmlcov/index.html`. For more verbose test output (e.g., to see the output of print statements), run: ```bash -poetry run pytest --cache-clear --cov src/krux --cov-report html --show-capture all --capture tee-sys -r A ./tests +poetry run poe test-verbose ``` To run just a specific test from a specific file, run: @@ -130,7 +130,7 @@ Run the simulator: cd simulator # Run simulator with the touch device amigo, then use mouse to navigate -poetry run python simulator.py --device maixpy_amigo_tft +poetry run python simulator.py --device maixpy_amigo # Run simulator with sd enabled (you need the folder `simulator/sd`) on the small button-only device m5stick, then use keyboard (arrow keys UP or DOWN and ENTER) poetry run python simulator.py --device maixpy_m5stickv --sd @@ -168,7 +168,7 @@ cd simulator poetry run python simulator.py --sequence sequences/about.txt --sd --device maixpy_m5stickv # Sequence screenshots are scaled to fit in docs. Use --no-screenshot-scale to get full size -poetry run python simulator.py --sequence sequences/home-options.txt --device maixpy_amigo_tft --no-screenshot-scale +poetry run python simulator.py --sequence sequences/home-options.txt --device maixpy_amigo --no-screenshot-scale ``` ## Live debug a device @@ -287,7 +287,7 @@ Learn about how to setup fonts [here](firmware/font/README.md) ## Colors -Use [this script](firmware/scripts/krux_colors.py) to generate Maixpy compatible colors from RGB values to customize Krux +Use [this script](firmware/scripts/rgbconv.py) to generate Maixpy compatible colors from RGB values to customize Krux ## Documentation diff --git a/docs/css/custom.css b/docs/css/custom.css index a06dd743a..a4b76c206 100644 --- a/docs/css/custom.css +++ b/docs/css/custom.css @@ -1,3 +1,7 @@ -.md-typeset img { - margin: 0 0 0.4em 0.8em !important; - } \ No newline at end of file +.md-typeset img { + margin: 0 0 0.4em 0.8em !important; +} + +.md-typeset img.twemoji { + margin: 0 !important; +} \ No newline at end of file diff --git a/docs/development.en.md b/docs/development.en.md deleted file mode 100644 index 6e3f32723..000000000 --- a/docs/development.en.md +++ /dev/null @@ -1,15 +0,0 @@ -# Navigation - -Mind map representation of menus under development. - -Click on the circle on the right side of each node to expand and explore the mind map. - -Activate full screen for better visualization on top-right menu. - -## Login Menu - - - -## Home Menu (Loaded Wallet) - - diff --git a/docs/faq.en.md b/docs/faq.en.md index 7a1af5e9a..0af427d47 100644 --- a/docs/faq.en.md +++ b/docs/faq.en.md @@ -1,5 +1,47 @@ +## Why are the buttons on my Maix Amigo in the wrong order? Why is my Amigo screen displaying the wrong colors? +Some Amigo screens have inverted X coordinates while others don’t. If you notice that the buttons on keypad input screens appear to be in the wrong order, please go to `Settings > Hardware > Display` and change the value of `Flipped X Coordinates` which should correct the issue. + +Others have found that there are issues with the colors displayed in the interface and camera preview. To fix this we have two options in `Settings > Hardware > Display`, `BGR Colors` and `Inverted Colors`, test with them until the colors appear to be correct on your device. + +## Why isn't my device charging or being recognized when connected to the computer's USB? +If you have a Maix Amigo, make sure you're using the USB-C port at the bottom of the device, not the one on the left side. + +Different computer hosts have varying hardware, operating systems, and behaviors regarding their USB ports. Below are the expected behaviors: + +### USB-A: +Your device should charge and turn on when connected to a USB-A port, even if it was initially turned off. You can also turn off the device while it continues to charge. However, some hosts' USB-A ports may behave like USB-C ports, as described below. + +### USB-C: + +- If the device is turned off and connected to a USB-C port, it should turn on and start charging. You can turn it off again, and it will continue to charge. + +- If the device is already turned on and connected to a USB-C port, it may not charge or be recognized by the computer. In this case, turn off the device to initiate recognition and charging. Once turned off and reconnected, the device should restart, be recognized by the computer, and charging should be triggered by USB-C hosts. +If your device is not charging or being recognized as expected, try using a different USB port or a different computer to determine if the issue is with the device or the host's USB port. + +## Why isn't my M5stickV device being recognized and charged when connected to the computer's USB-C? +M5stickV's USB-C port lacks pull up resistors required for it to be recognized and powered by host(computer) USB-C ports. If you don't have an USB-A available, you can use a USB hub connected between your computer's USB-C and M5stickV + +## Why does my Krux device randomly freeze or restart when connected to the computer? +Windows is known to have issues with the USB-C devices. If you are experiencing random crashes or even reboots and your device does not have a battery, try using a phone charger or other power source such as a power bank. + +## Why won't my Linux OS list a serial port after connecting my device? +If you get the following error when trying to flash your device: `Failed to find device via USB. Is it connected and powered on?` +Make sure your device is being detected and serial ports are being mounted by running: +```bash +ls /dev/ttyUSB* +``` +Expect one port to be listed for devices like M5stickV and Maix Dock `/dev/ttyUSB0`, and two ports for Maix Amigo and Maix Bit `/dev/ttyUSB0 /dev/ttyUSB1`. + +If you don't see them, your OS may not be loading the correct drivers to create the serial ports to connect to. Ubuntu has a known bug where the `brltty` driver "kidnaps" serial devices. You can solve this problem by removing it: +```bash +sudo apt-get remove brltty +``` + +## What are all the features available? What are the additional features of the Test (Beta) version? Is there an Android app? +For [official releases](https://github.com/selfcustody/krux/releases) you will find all the features detailed here on the [Getting Started page](getting-started/index.md) with a brief summary on the [Navigation Overview page](getting-started/navigation.md). The latest and most experimental features, which we sometimes share on our social media, can be found only in the [test (beta) repository](https://github.com/odudex/krux_binaries/). Only official releases are signed, Test (Beta) is just for trying new things and providing feedback. Krux Android app ia available as an `apk` on the [test (beta) repository](https://github.com/odudex/krux_binaries/). + ## Why does Krux show an xpub for a segwit address? -The xpub that Krux displays follows the [bitcoin core descriptors spec](https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md#key-origin-identification) and includes key origin and derivation info that, in theory, makes zpubs (and ypubs) unnecessary *if the wallet software being shown this extra information can parse it*. +The xpub that Krux displays follows the [bitcoin core descriptors spec](https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md/#key-origin-identification) and includes key origin and derivation info that, in theory, makes zpubs (and ypubs) unnecessary *if the wallet software being shown this extra information can parse it*. From the spec: > Every public key can be prefixed by an 8-character hexadecimal fingerprint plus optional derivation steps (hardened and unhardened) surrounded by brackets, identifying the master and derivation path the key or xpub that follows was derived with. @@ -13,63 +55,42 @@ The level of detail that you see is what Krux sees. If the QR code shown on the If you have adjusted the lens already, the device may be too far away or too close to the code to read it. Start by holding the device as close to the QR code as possible and pulling away slowly until all or most of the QR code is viewable within the screen. If the code on the screen looks crisp, Krux should read it quickly and give you immediate feedback. -If you are in a dark environment, you can hold down the ENTER button of the M5StickV or Maix Amigo to turn on their LED light to potentially increase visibility. M5stickV and Amigo also has an anti-glare mode to better capture images from high brightness screens or with incident light, to enable/disable the anti-glare just press the PAGE button. +If you are in a dark environment, you can hold down the ENTER button of the M5StickV or Maix Amigo to turn on their LED light to potentially increase visibility. M5stickV and Amigo also has an anti-glare mode to better capture images from high brightness screens or with incident light, to enable/disable the anti-glare just press the PAGE button while scanning. ## Why am I getting an error when I try to scan a QR code? -If Krux is recognizing that it sees a QR code but is displaying an error message after reading it, the likely reason is that the QR code is not in a format that Krux understands. +If Krux is recognizing that it sees a QR code but is displaying an error message after reading it, the likely reason is that the QR code is not in a format that Krux works with. We have listed the supported formats below: -For mnemonics, Krux recognizes: +For BIP-39 mnemonics: 1. BIP-39 Plaintext (Used by Krux and [https://iancoleman.io/bip39/](https://iancoleman.io/bip39/)) 2. SeedSigner [SeedQR and CompactSeedQR](https://github.com/SeedSigner/seedsigner/blob/dev/docs/seed_qr/README.md) Formats 3. [UR Type `crypto-bip39`](https://github.com/BlockchainCommons/Research/blob/master/papers/bcr-2020-006-urtypes.md) 4. Encrypted QR Code (Format created by Krux, [more info here](getting-started/features/encrypted-mnemonics.md)) -For loading wallets, Krux recognizes: +For Wallet output descriptor: 1. JSON with at least a `descriptor` key containing an output descriptor string 2. Key-value INI files with at least `Format`, `Policy`, and `Derivation` keys 3. [UR Type `crypto-output`](https://github.com/BlockchainCommons/Research/blob/master/papers/bcr-2020-010-output-desc.md) -For PSBTs, Krux recognizes: +For Partially Signed Bitcoin Transactions (PSBT): 1. Base43, Base58, and Base64-encoded bytes 2. Raw Bytes 3. [UR Type `crypto-psbt`](https://github.com/BlockchainCommons/Research/blob/master/papers/bcr-2020-006-urtypes.md) -Additionally, Krux recognizes animated QR codes that use either the plaintext `pMofN` or binary [`UR`](https://github.com/BlockchainCommons/Research/blob/master/papers/bcr-2020-005-ur.md) encodings. +Additionally, Krux recognizes animated QR codes that use either the plaintext `pMofN` (Specter QR format) or binary [`UR`](https://github.com/BlockchainCommons/Research/blob/master/papers/bcr-2020-005-ur.md) encodings. ## Why can't my computer read the QR code that Krux displays? If you are using an M5StickV, the small screen makes it difficult for laptop webcams to capture enough detail to parse the QR codes it displays. You can toggle brightness of QR codes from public keys and PSBTs by pressing PAGE button. In the future, more work will be done to support displaying lower density QR codes. For now, a workaround you can do is to take a picture or video of the QR code with a better-quality camera (such as your phone), then enlarge and display the photo or video to your webcam. Alternatively, it may be simpler to use a mobile wallet such as BlueWallet with the M5StickV since phone cameras don't seem to have issues reading the small QR codes. You can also save the PSBT on a microSD card for Krux to sign and then save the signed transaction to the microSD card to transfer the file to the computer or phone. -## Why isn't my Amigo device being recognized when connected to the computer USB? -Make sure you’re using the bottom USB-C port, not the one on the left side. It is also possible that there is some incompatibility with the cable used, try a few before investigating further. - -## Why won't my Linux OS list a serial port after connecting my device? -If you get the following error when trying to flash your device: `Failed to find device via USB. Is it connected and powered on?` -Make sure your device is being detected and serial ports are being mounted by running: -```bash -ls /dev/ttyUSB* -``` -Expect one port to be listed for devices like M5stickV and Dock `/dev/ttyUSB0`, and two ports for Amigo and Bit `/dev/ttyUSB0 /dev/ttyUSB1`. - -If you don't see them, your OS may not be loading the correct drivers to create the serial ports to connect to. Ubuntu has a known bug where the `brltty` driver "kidnaps" serial devices. You can solve this problem by removing it: -```bash -sudo apt-get remove brltty -``` - -## Why won't my Apple OS list a serial port after connecting my device? -Some users reported that they were able to make their Apple devices recognize Krux devices only after they connected them through an USB dock instead of connecting them directly. - -## Why are the buttons on my Amigo in the wrong order? -Some Amigo screens have inverted x coordinates while others don’t. - -If after flashing `maixpy_amigo_tft` to your device you notice that the buttons on keypad input screens appear to be in the wrong order, please try flashing `maixpy_amigo_ips` instead (or vice versa) which should correct the issue. - ## Why isn't Krux detecting my microSD card or presenting an error? Starting from version 23.09.0, Krux supports SD card hot plugging. If you are using older versions, it may only detect the SD card at boot, so make sure Krux is turned off when inserting the microSD into it. To test the card compatibility use Krux [Tools>Check SD Card](getting-started/features/tools.md/#check-sd-card). Make sure the SD card is using MBR/DOS partition table and FAT32 format. -Here is some [supported microSD cards](https://github.com/m5stack/m5-docs/blob/master/docs/en/core/m5stickv.md#tf-cardmicrosd-test), and here is the MaixPy FAQ explaining [Why my micro SD card cannot be read](https://wiki.sipeed.com/soft/maixpy/en/others/maixpy_faq.html#Micro-SD-card-cannot-be-read). \ No newline at end of file +Here is some [supported microSD cards](https://github.com/m5stack/m5-docs/blob/master/docs/en/core/m5stickv.md/#tf-cardmicrosd-test), and here is the MaixPy FAQ explaining [Why my micro SD card cannot be read](https://wiki.sipeed.com/soft/maixpy/en/others/maixpy_faq.html#Micro-SD-card-cannot-be-read). + +## Why insert an SD card into my device? What is it for? Does it save something? +SD card use is optional, most people use Krux only with QR codes. But you can use SD card to to upgrade the firmware, save settings, cnc/file, QR codes, XPUBs, encrypted mnemonics, and to save and load PSBTs, messages and wallet output descriptors. \ No newline at end of file diff --git a/docs/getting-started/features/QR-transcript-tools.en.md b/docs/getting-started/features/QR-transcript-tools.en.md index e9d44b2d4..0343037e0 100644 --- a/docs/getting-started/features/QR-transcript-tools.en.md +++ b/docs/getting-started/features/QR-transcript-tools.en.md @@ -2,7 +2,7 @@ When you export a mnemonic, encrypted mnemonic or a generic text QR code, altern ### Standard Mode - + This mode is optimized for scanning, the raw QR code will be displayed @@ -10,7 +10,7 @@ This mode is optimized for scanning, the raw QR code will be displayed ### Lines Mode - + If you are good at transcribing things like handwritten text, with this mode one QR code line will be highlighted at a time. Press `Enter` to highlight the next line. @@ -18,7 +18,7 @@ If you are good at transcribing things like handwritten text, with this mode one ### Zoomed Regions Mode - + QR codes will be split into regions, of 5x5 or 7x7 "blocks". One QR code region will be shown at a time. Press `Enter` to display the next region. @@ -26,7 +26,7 @@ QR codes will be split into regions, of 5x5 or 7x7 "blocks". One QR code region ### Highlighted Regions Mode - + QR codes will be split into regions, of 5x5 or 7x7 "blocks". One QR code region will be highlighted at a time. Press `Enter` to highlight the next region. @@ -34,7 +34,7 @@ QR codes will be split into regions, of 5x5 or 7x7 "blocks". One QR code region ### Grided Mode - + Grids will be added to a standard QR code. In a dark room, if you place a sheet of paper over the device's screen, you'll notice QR code will be visible and it will be possible to copy it directly from above. Be careful to don't damage your screen with pen and markers, use an insulating plastic tape or film to protect the device if you use this method. diff --git a/docs/getting-started/features/encrypted-mnemonics.en.md b/docs/getting-started/features/encrypted-mnemonics.en.md index a6ff68f8c..db909c73f 100644 --- a/docs/getting-started/features/encrypted-mnemonics.en.md +++ b/docs/getting-started/features/encrypted-mnemonics.en.md @@ -1,6 +1,24 @@ ## Introduction -There are many possible security layers one could add to protect a wallet’s private key, adding a passphrase to the mnemonic is the most common. To encrypt a mnemonic would have similar use case as the passphrase, but, depending on how it is done, the user experience could be different. The main difference from passphrases to Krux’s encrypted mnemonic implementation is that when users type the wrong key, instead of loading a different wallet, encrypted mnemonics will return an error. This is not considered an advantage, but a difference, that may be desired or not. The implementation also has the convenience of storing a mnemonic ID together with stored or QR code encrypted mnemonics. Mnemonic encryption, with its own key, can be used together with passphrases as an extra security layer. +There are many possible security layers one could add to protect a wallet’s private key. Adding a BIP-39 passphrase to the mnemonic is the most common method. Encrypting a BIP-39 mnemonic has a similar use case as the BIP-39 passphrase, but the user experience may differ depending on the implementation. The main difference between BIP-39 passphrases and Krux’s encrypted mnemonic implementation is that when users type the wrong key, encrypted mnemonics will return an error instead of loading a different wallet, as BIP-39 passphrases do. This difference may be desired or not. The implementation also has the convenience of storing a mnemonic ID together with the stored or QR code encrypted mnemonics. Mnemonic encryption, with its own key, can be used together with BIP-39 passphrase as an extra security layer. + +We use standard AES encryption modes ECB and CBC: + +### AES-ECB + +ECB (Electronic Codebook) is a simpler method where encryption data blocks are encrypted individually. This mode is faster and simpler to encrypt, resulting in QR codes with lower density and easier to transcribe. It is generally considered less secure than CBC because it does not provide data chaining, meaning identical plaintext blocks will produce identical ciphertext blocks, making it vulnerable to pattern analysis. However, in Krux's implementation, only one or two binary data blocks are encrypted, so there will be no patterns, and the lack of chaining is not as relevant as it would be for larger files, plain text, or media. + +### AES-CBC + +CBC (Cipher-block Chaining) is considered more secure. In the first data block, an initialization vector (IV) is used to add random data to the encryption. The encryption of subsequent blocks depends on the data from previous blocks, characterizing chaining. The tradeoff is that the encryption process will take longer because a snapshot will be needed to generate the IV. This IV will be stored together with encrypted data, making encrypted QR codes denser and harder to transcribe. + +#### CBC Encryption IV + +The Initial Vector (IV) will be generated from a snapshot taken with the camera. The IV is a fixed-size input value used in the first block of the encryption process. It adds randomness to the encryption, ensuring that data encrypted with the same key will produce different ciphertexts each time. The IV is not secret and will be transmitted along with the ciphertext. However, like any nonce, it should not be reused to maintain security. + +### PBKDF2 Iterations +When you enter the encryption key, it is not directly used to encrypt your data. In order to protect against brute force attacks, the key is derived multiple times using hashing functions. PBKDF2 (Password-Based Key Derivation Function) iterations refer to the number of derivations that will be performed over your key prior to encrypting/decrypting your mnemonic. + ## Encrypted QR Codes Data and Parsing In search of efficiency and smaller QR codes, all data is converted to bytes and organized like a Bitcoin transaction, with variable and fixed length fields. The following data is present on the QR code: @@ -23,3 +41,5 @@ In search of efficiency and smaller QR codes, all data is converted to bytes and ## Considerations Storage of encrypted mnemonics on the device or SD cards are meant for convenience only and should not be considered a form of backup. Always make a physical backup of your keys that is independent from electronic devices and test recovering your wallet from this backup before you send funds to it. + +Remember that the stored encrypted mnemonic is protected by the key you defined to encrypt it. If the defined [key is weak](https://www.hivesystems.io/blog/are-your-passwords-in-the-green), your encrypted mnemonic will not be protected. If you have stored a mnemonic with funds in the device's internal flash memory using a [weak key](https://www.hivesystems.io/blog/are-your-passwords-in-the-green), the best way to undo this is to [wipe the device](./tools.md/#wipe-device). \ No newline at end of file diff --git a/docs/getting-started/features/printing.en.md b/docs/getting-started/features/printing.en.md index a37cae57a..aaee4710d 100644 --- a/docs/getting-started/features/printing.en.md +++ b/docs/getting-started/features/printing.en.md @@ -1,6 +1,6 @@ -Krux has the ability to print all QR codes it generates, including mnemonic, xpub, wallet backup, and signed PSBT, via a locally-connected thermal printer over its serial port. Consult the [part list](../../parts.md) page for supported printers. +Krux has the ability to print all QR codes it generates, including mnemonic, xpub, wallet backup, and signed PSBT, via a locally-connected thermal printer over its serial port. Consult the [part list](../../parts.md/#optional-thermal-printer) page for supported printers. - +