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, 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, the best way to undo this is to wipe the device.
+Remember that the stored encrypted mnemonic is protected by the key you defined to encrypt it. If the defined key is weak, 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, the best way to undo this is to erase user's data.
diff --git a/getting-started/features/sd-card-update/index.html b/getting-started/features/sd-card-update/index.html index 61714df9..bbb6790f 100644 --- a/getting-started/features/sd-card-update/index.html +++ b/getting-started/features/sd-card-update/index.html @@ -1467,7 +1467,7 @@To perform an upgrade, simply copy the official release firmware.bin and firmware.bin.sig files to the root of a FAT-32 / MBR formatted microSD card, insert the card into your device, and reboot the device. If it detects the new firmware file and is able to verify the signature, you will be prompted to install it.
Once installation is complete, eject the microSD card and delete the firmware files before reinserting and rebooting. Otherwise you will be prompted to install it again.
-We cannot guarantee that a microSD card is compatible and will work in your device; you'll need to test it on the device to be sure, read the Troubleshooting for more info. +
We cannot guarantee that a microSD card is compatible and will work in your device; you'll need to test it on the device to be sure, read the Troubleshooting for more info. Only official releases are signed and can be installed via microSD card.
diff --git a/getting-started/features/tamper-detection/index.html b/getting-started/features/tamper-detection/index.html index efc0f2df..624e513e 100644 --- a/getting-started/features/tamper-detection/index.html +++ b/getting-started/features/tamper-detection/index.html @@ -1644,7 +1644,7 @@Use SD Card for Updates: After the initial flash through USB, perform subsequent updates via the SD card. This keeps your device air-gapped and allows the existing firmware to verify new updates before installation.
diff --git a/getting-started/installing/from-gui/debian-like/index.html b/getting-started/installing/from-gui/debian-like/index.html index 770a6b36..58e972f1 100644 --- a/getting-started/installing/from-gui/debian-like/index.html +++ b/getting-started/installing/from-gui/debian-like/index.html @@ -1530,7 +1530,6 @@Once installed, you can proceed to firmware installation.
diff --git a/getting-started/installing/from-gui/fedora-like/index.html b/getting-started/installing/from-gui/fedora-like/index.html index c5dfb36d..afc34c39 100644 --- a/getting-started/installing/from-gui/fedora-like/index.html +++ b/getting-started/installing/from-gui/fedora-like/index.html @@ -1548,7 +1548,6 @@Once installed, you can proceed to firmware installation.
diff --git a/getting-started/installing/from-gui/macos-arm64/index.html b/getting-started/installing/from-gui/macos-arm64/index.html index b73ed3ac..58c44250 100644 --- a/getting-started/installing/from-gui/macos-arm64/index.html +++ b/getting-started/installing/from-gui/macos-arm64/index.html @@ -1529,7 +1529,6 @@Once installed, you can proceed to firmware installation.
diff --git a/getting-started/installing/from-gui/macos-intel/index.html b/getting-started/installing/from-gui/macos-intel/index.html index d6dc9e47..54b067fb 100644 --- a/getting-started/installing/from-gui/macos-intel/index.html +++ b/getting-started/installing/from-gui/macos-intel/index.html @@ -1529,7 +1529,6 @@Once installed, you can proceed to firmware installation.
diff --git a/getting-started/installing/from-gui/usage/index.html b/getting-started/installing/from-gui/usage/index.html index b8ec5561..909d70a1 100644 --- a/getting-started/installing/from-gui/usage/index.html +++ b/getting-started/installing/from-gui/usage/index.html @@ -1908,7 +1908,7 @@Now you will be able to select if you do a flash process or need to do an airgap process:
Click on Flash with to install via USB or Air-gapped update with to perform upgrades via a SD card.
+Click on Flash with to install via USB or Air-gapped update with to perform upgrades via a SD card.
When flash starts, it will warn you to not disconnect the device until the process is complete. You'll be able to see the flash progress:
diff --git a/getting-started/installing/from-gui/windows/index.html b/getting-started/installing/from-gui/windows/index.html index dff47913..bfce6303 100644 --- a/getting-started/installing/from-gui/windows/index.html +++ b/getting-started/installing/from-gui/windows/index.html @@ -1554,7 +1554,6 @@Once installed, you can proceed to firmware installation.
diff --git a/getting-started/installing/from-pre-built-release/index.html b/getting-started/installing/from-pre-built-release/index.html index 1ee22159..31d903c2 100644 --- a/getting-started/installing/from-pre-built-release/index.html +++ b/getting-started/installing/from-pre-built-release/index.html @@ -1566,8 +1566,17 @@selfcustody.pem public key found in the root of the krux repository.You can either do this manually or with the krux shell script, which contains helper commands for this:
-
./krux sha256 krux-v24.11.1.zip
+### Using krux script ###
+# Hash checksum
+./krux sha256 krux-v24.11.1.zip
+# Signature
./krux verify krux-v24.11.1.zip selfcustody.pem
+
+### Manually ###
+# Hash checksum
+sha256sum krux-v24.11.1.zip.sha256.txt -c
+#Signature
+openssl sha256 <krux-v24.11.1.zip -binary | openssl pkeyutl -verify -pubin -inkey selfcustody.pem -sigfile krux-v24.11.1.zip.sig
On Mac you may need to install coreutils to be able to use sha256sum
brew install coreutils
diff --git a/getting-started/installing/from-source/index.html b/getting-started/installing/from-source/index.html
index d08615c0..72eb2279 100644
--- a/getting-started/installing/from-source/index.html
+++ b/getting-started/installing/from-source/index.html
@@ -1593,16 +1593,20 @@ Build the firmware (Linux or WSL)
Reproducibility¶
-If you build from the main branch of the source code, you should be able to reproduce the build process used to generate the last release binaries and obtain exact copies of the firmware.bin and kboot.kfpkg files, with matching hash checksums.
-To extract and verify the firmware.bin contained in kboot.kfpkg, you can use the following command:
+If you build from the main branch of the source code, you should be able to reproduce the build process used to generate the latest release binaries and obtain exactly the same copies of the firmware.bin and kboot.kfpkg files, with matching hash checksums (to check for an older version, use the tag instead).
+To check, use the compiled files for the target device. Each command should output the same hash for the two provided files:
+
sha256sum build/firmware.bin krux-v24.11.1/maixpy_DEVICE/firmware.bin
+sha256sum build/kboot.kfpkg krux-v24.11.1/maixpy_DEVICE/kboot.kfpkg
+
+If you want to extract and verify the firmware.binfile contained in kboot.kfpkg, use the following:
unzip kboot.kfpkg -d ./kboot/
Flash the firmware onto the device¶
Connect the device to your computer via USB (for Maix Amigo, make sure you’re using bottom port), power it on, and run the following, replacing DEVICE with either m5stickv, amigo, bit, cube, dock or yahboom:
-
# build firmware for DEVICE
+# flash firmware to DEVICE
./krux flash maixpy_DEVICE
-If the flashing fails try one of the following common solutions listed on FAQ
+If flashing fails try reading Troubleshooting
When the flashing process completes, you should see the Krux logo:
diff --git a/parts/index.html b/parts/index.html
index fab760d6..66db3e61 100644
--- a/parts/index.html
+++ b/parts/index.html
@@ -1766,7 +1766,7 @@ Other PartsUSB-C or Micro USB Charge Cable¶
This will come with the device. It will be necessary to power, charge the device (if it has battery) and to initially flash the firmware.
(Optional) MicroSD Card¶
-We cannot guarantee that a microSD card is compatible and will work in your device; you'll need to test it on the device to be sure, read the Troubleshooting for more info.
+
We cannot guarantee that a microSD card is compatible and will work in your device; you'll need to test it on the device to be sure, read the Troubleshooting for more info.
Yahboom will come with a compatible 32G card. The size of the SD card isn't important; anything over a few megabytes will be plenty.
(Optional) TTL Serial Thermal Printer¶
Warning/Disclaimer: This feature is intended for individuals with experience in electronics tinkering and soldering.
diff --git a/search/search_index.json b/search/search_index.json
index 45a8a070..a1c6fd55 100644
--- a/search/search_index.json
+++ b/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"faq/","title":"FAQ","text":""},{"location":"faq/#is-krux-a-hardware-wallet","title":"Is Krux a hardware wallet?","text":"The term \"hardware wallet\" typically refers to devices dedicated to storing private keys and signing transactions. These devices often feature specific security components like secure element chips.
Krux was initially developed as a signer, operating exclusively in amnesic mode, which requires users to load their keys each time the device is powered on. However, Krux has evolved and now offers the option to store mnemonics, similar to traditional hardware wallets. These mnemonics can be stored in the device's internal memory or on SD cards.
Krux does not include hardware secure elements. The security of stored data relies on encryption.
Note: Due to the inherent fragility of electronic components, never use your Krux device or SD card encrypted storage as your sole backup method. Always maintain a physical backup for added security.
"},{"location":"faq/#what-is-beta-version","title":"What is Beta version?","text":"The Beta version includes the latest and most experimental features, which we occasionally share on our social media. These can be found exclusively in the test (beta) repository. Use and flash the beta firmware if you are curious about new features or want to participate in the development process by hunting bugs, providing feedback, and sharing ideas in our Telegram groups or other social media platforms.
For regular use, flash the official releases, which are signed, thoroughly tested, and well-documented.
"},{"location":"faq/#what-is-krux-android-app","title":"What is Krux Android app?","text":""},{"location":"faq/#how-can-i-find-it","title":"How can I find it?","text":"The Krux Android app is available as an APK in the test (beta) repository. It requires Android 6.0 or above.
"},{"location":"faq/#how-can-i-install-it","title":"How can I install it?","text":"The APK is not available on the Play Store. You can download the APK directly or transfer it to your Android device via SD card or USB cable. To install it, you may need to configure your Android device to allow installations from unknown sources.
"},{"location":"faq/#is-it-safe-to-use","title":"Is it safe to use?","text":"The Krux Android app is designed for learning about Krux and Bitcoin air-gapped transactions. Due to the numerous potential vulnerabilities inherent in smartphones, such as the lack of control over the operating system, libraries, and hardware peripherals, the Krux app should NOT be used to manage wallets containing savings or important keys and mnemonics. For secure management of your keys, a dedicated device is recommended.
"},{"location":"","title":"Krux","text":"Krux is an open-source firmware that transforms off-the-shelf Kendryte K210 devices, such as the Maix Amigo, M5StickV and more, into versatile bitcoin transaction signers. Beyond its core functionality, Krux is a flexible platform that can adapt to devices with different form factors, providing a suite of tools to assist with the creation and recovery of mnemonic backups, some of which include encryption options for enhanced security.
Devices like the Maix Amigo and Yahboom come ready to use, with large touchscreens that make it easy and user-friendly to operate. These devices are ideal for those looking for a plug-and-play solution. On the other hand, Krux also supports development board kits, which are perfect for DIY enthusiasts who enjoy customizing and building their own hardware setups.
Interacting seamlessly with leading coordinator wallets through QR codes, SD cards, and even thermal printers, the user-friendly firmware offers unique features to support transactions and mnemonic backups in an offline environment.
To learn more about Krux, check out Getting Started.
"},{"location":"parts/","title":"Devices and Parts List","text":""},{"location":"parts/#krux-compatible-devices","title":"Krux Compatible Devices","text":""},{"location":"parts/#comparative-table","title":"Comparative Table","text":"Device M5StickV Maix Amigo Maix Dock Maix Bit Yahboom k210 module Maix Cube WonderMV Price range US$ 50-55 US$ 50-85 US$ 27-35 US$ 32-42 US$ 45-61 US$ 34-49 US$ 58-86 Screen size / resolution 1.14\" / 135*240 3.5\" / 320*480 2.4\" / 240*320 2.4\" / 240*320 2\" / 240*320 1.3\" / 240*240 2\" / 240*320 Brightness control Device size 48*24*22mm 104*63*17mm 98*59*18mm 69*84*41mm 57*41*17mm 40*40*16mm 59*41*17mm Touchscreen Capacitive Capacitive Capacitive Camera OV7740 OV7740 rearGC0328 front GC0328 OV2640 orOV5642 OV2640 (VER:1.0) orGC2145 (VER:1.1) OV7740 GC2145 Battery 200mAh 520mAh 200mAh Requirements None None Rotary encoder 3D printed case SolderingAssembly Buttons 3D printed case SolderingAssembly None None None Warnings Camera has lens distortion Micro USB 3-Way button None : Only OV7740, OV2640 and GC2145 have an anti-glare mode to better capture images from high brightness screens or with incident light.
: 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.
: Some Amigo screens have inverted X coordinates, others display colors differently. For more info see Troubleshooting.
: Some stores ship the Maix Dock with soldered pin connectors that do not fit into the 3D printed case.
All devices feature Kendryte K210 chip: 28nm process, dual-core RISC-V 64bit @400MHz, 8 MB high-speed SRAM, DVP camera and MCU LCD interface, AES Accelerator, SHA256 Accelerator, FFT Accelerator.
"},{"location":"parts/#m5stickv","title":"M5StickV","text":"Below is a list of some distributors where you can find this device:
- M5Stack
- Mouser
- Digi-Key
- Electromaker
- Lee's Electronic
- AliExpress
- ABRA
- Adafruit
- Cytron
"},{"location":"parts/#maix-amigo","title":"Maix Amigo","text":"Below is a list of some distributors where you can find this device:
- AliExpress
- Seeed Studio
- Digi-Key
- Mouser
- Electromaker
"},{"location":"parts/#yahboom-k210-module","title":"Yahboom k210 module","text":"It comes with a compatible 32G card, an USB card reader, one PH2.0 4Pin male-to-male connector and one PH2.0 female adapter (to connect to a thermal printer). Below is a list of some distributors where you can find this device:
- AliExpress
- Amazon
- Yahboom Store
- ETC HK Shop
"},{"location":"parts/#maix-cube","title":"Maix Cube","text":"Below is a list of some distributors where you can find this device:
- Seeed Studio
- Mouser
- Electromaker
- Digi-Key
- AliExpress
- Amazon
"},{"location":"parts/#maix-dock-and-maix-bit","title":"Maix Dock and Maix Bit","text":"For the DIYers, the Maix Dock and Maix Bit are also supported but will require sourcing the parts individually and building the device yourself.
Below are example implementations with instructions on how to recreate them:
- https://github.com/selfcustody/DockEncoderCase
- https://github.com/selfcustody/MaixBitCase
Below is a list of some distributors where you can find these devices:
- Mouser
- Electromaker
- Digi-Key
- AliExpress
- Amazon
"},{"location":"parts/#other-parts","title":"Other Parts","text":""},{"location":"parts/#usb-c-or-micro-usb-charge-cable","title":"USB-C or Micro USB Charge Cable","text":"This will come with the device. It will be necessary to power, charge the device (if it has battery) and to initially flash the firmware.
"},{"location":"parts/#optional-microsd-card","title":"(Optional) MicroSD Card","text":"We cannot guarantee that a microSD card is compatible and will work in your device; you'll need to test it on the device to be sure, read the Troubleshooting for more info. Yahboom will come with a compatible 32G card. The size of the SD card isn't important; anything over a few megabytes will be plenty.
"},{"location":"parts/#optional-ttl-serial-thermal-printer","title":"(Optional) TTL Serial Thermal Printer","text":"Warning/Disclaimer: This feature is intended for individuals with experience in electronics tinkering and soldering.
Krux has the capability to print all QR codes it generates, including those for mnemonics, xpubs, wallet backups, and signed PSBTs, using a locally-connected thermal printer via its serial port.
Many TTL serial thermal printers may be compatible, but currently, the Goojprt QR203 has the best support (except this printer only supports ASCII or Chinese characters, non-ASCII characters will be printed as Chinese). The Adafruit printer starter pack can also be a convenient option to get started, as it includes all the necessary components for printing (except the conversion cable). To ensure proper functionality, enable the printer driver in the Krux settings, set the Tx pin and baud rate value to either 19200 or 9600 (depends on the printer), as explained in this Adafruit printer tutorial. You will need to connect the device's Tx to the printer's Rx and device's ground to the printer's ground, do not connect any other pins because a wrong connection may damage your device. The printer requires a dedicated power supply, typically with an output of 5 to 9V (or 12V) and capable of supplying at least 2A. For more information, see this discussion.
"},{"location":"parts/#optional-conversion-cable-for-thermal-printer","title":"(Optional) Conversion Cable for Thermal Printer","text":"To connect the printer to M5StickV, Amigo or Cube, you will need a grove conversion cable with a 4-pin male Grove connector on one end (to connect to the device) and 4-pin male jumpers on the other end (to connect to the printer). Check your device and printer model connection first, Yahboom comes with PH2.0 4Pin female connector; Dock and Bit doesn't have a connector. For a more reliable connection, it is recommended to cut and solder the wires of your custom cables instead of using jumpers.
"},{"location":"support/","title":"Support the Project","text":""},{"location":"support/#ways-you-can-help","title":"Ways you can help","text":""},{"location":"support/#development","title":"Development","text":"Audit the code, file an issue, make a pull request, or do all three. :)
"},{"location":"support/#documentation","title":"Documentation","text":"\"I'd like to see Krux help as many people as possible, and to do that, good documentation is needed. If you identify a better way to say something, please make a PR, any help is appreciated.\" - Jeff
"},{"location":"support/#translation","title":"Translation","text":"Krux supports different languages. If you missed a language or saw an awkward translation, open an issue or make a PR! You can also make a difference by translating this documentation! For information on how to translate, see here
"},{"location":"support/#social","title":"Social","text":"Reach out via our Telegram group or X profile (Twitter) for faster help, share ideas and join the Krux community. Help others get to know Krux.
\"I'm an engineer, not a marketer. If you like Krux, help spread the word!\" - Jeff
"},{"location":"support/#krux-ethos","title":"Krux Ethos","text":"The purpose of this ethos is not to virtue signal, but to introduce newcomers to Krux's philosophy and provide a guiding reference for decision-making and the long-term mission for dedicated Krux users.
"},{"location":"support/#mission","title":"Mission","text":"To implement ideas that make self-custody more powerful, accessible, and user-friendly.
"},{"location":"support/#dont-trust-verify","title":"Don't Trust, Verify","text":"Do not trust developers\u2019 intentions or competence. Krux is a DIY, use-at-your-own-risk project. We are committed to continuously improving security, but will not make claims or create marketing narratives about it. It is up to the users verify their hardware, the firmware and Krux-Installer
"},{"location":"support/#donations","title":"Donations","text":"Krux will not solicit, receive, manage, or distribute donations. Therefore, Krux has no budget for publicity, audits, or similar activities. Contributors to Krux will fund their own work\u2014whether by promoting their efforts, applying for grants, or seeking direct individual donations.
"},{"location":"support/#krux-is-public-domain","title":"Krux is Public Domain","text":"Krux users should feel completely free from any obligation to donate or support developers. Use Krux without guilt or expectation.
The same applies to any company profiting from Krux-based products or services, such as educational content, custom hardware, or accessories. The \"don't trust\" principle clearly extends here as well\u2014it is the users\u2019 responsibility to determine if these products align with the Krux ethos and their personal values.
"},{"location":"troubleshooting/","title":"Troubleshooting","text":""},{"location":"troubleshooting/#before-installing","title":"Before Installing","text":""},{"location":"troubleshooting/#linux-os-not-listing-serial-port","title":"Linux OS not listing serial port?","text":"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:
ls /dev/ttyUSB*\n
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:
sudo apt-get remove brltty\n
"},{"location":"troubleshooting/#m5stickv-device-not-being-recognized-and-charged","title":"M5StickV device not being recognized and charged?","text":"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.
"},{"location":"troubleshooting/#device-not-charging-or-being-recognized","title":"Device not charging or being recognized?","text":"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 connecting to 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.
"},{"location":"troubleshooting/#device-randomly-freezes-or-restarts","title":"Device randomly freezes or restarts?","text":"If the device behaves this way when connected to the computer, Windows is known to have issues with 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.
"},{"location":"troubleshooting/#after-installing","title":"After Installing","text":""},{"location":"troubleshooting/#maix-amigo-touchscreen-doesnt-work-with-v24030-but-worked-okay-with-v23091","title":"Maix Amigo touchscreen doesn't work with v24.03.0 but worked okay with v23.09.1?","text":"We added a hardware IRQ (interrupt request) to the firmware, so when you open your Maix Amigo, you will see a switch in the middle of the device board, it must be in the upper position for the touchscreen to work with v24.03.0 and later.
"},{"location":"troubleshooting/#troubleshooting-lcd-settings-on-maix-amigo","title":"Troubleshooting LCD Settings on Maix Amigo","text":"Buttons in the Wrong Order
If the buttons on keypad input screens appear to be in the wrong order, this might be due to inverted X coordinates. To correct this:
- Go to Settings > Hardware > Display.
- Change the value of
Flipped X Coordinates.
Incorrect Colors
If the colors displayed on the interface or camera preview are incorrect, you can try the following options:
Inverted Colors
If, for example, the background color is white when it should be black, go to Settings > Hardware > Display and toggle Inverted Colors .
BGR Colors
If, for example, you are using the Orange theme, and instead of orange the colors appear bluish, toggle BGR Colors in the display settings.
LCD Type
WARNING! Only try changing this setting if you failed to fix colors with previous ones.
If adjusting BGR Colors and Inverted Colors doesn't fix the color issue, try changing the LCD Type:
- After changing this setting, you will be warned that the device will reboot automatically if this change does not resolve the issue (if it fails, the screen will turn black, and you'll not see anything).
- After proceeding with the warning, if you see a message prompting you to press the
PREVIOUS (UP) button, it means that the new setting worked. Follow the instructions and press UP. - If you notice menu options but the colors are still wrong, try again with different combinations of
Inverted Colors and BGR Colors. This time, it is likely you will find a combination that correctly displays the colors of themes and the camera feed.
If, after the warning in step 1, the screen turns black and you don't see anything, don't panic or press any buttons. Just wait 5 seconds, and the device will automatically reboot with the previous display settings. This means you should keep the default LCD Type setting and maybe try again with Inverted Colors and BGR Colors.
If you accidentally pressed PREVIOUS (UP) and saved the wrong setting, you will have to perform a wipe to remove all stored settings to be able to see the screen working again. On Linux, go to the folder where you downloaded the Krux firmware and use Ktool to fully wipe your device:
./ktool-linux -B goE -b 1500000 -E
(Soon Krux-Installer will have a full wipe button too)
Then flash the firmware again.
./ktool-linux -B goE -b 1500000 maixpy_amigo/kboot.kfpkg
"},{"location":"troubleshooting/#device-didnt-reboot-and-screen-is-blank","title":"Device didn't reboot, and screen is blank","text":"If the device didn't reboot after successfully flashing the firmware, and the screen is blank after turning it off and on, check if the downloaded file matches the device (this can also occur due to data corruption). Try downloading binaries again.
You can also install MaixPy IDE to help with debugging, Tools > Open Terminal > New Terminal > Connect to serial port > Select a COM port available (if it doesn't work, try another COM port). It will show the terminal and some messages, a message about an empty device or with corrupted firmware appears like: \"interesting, something's wrong, boot failed with exit code 233, go to find your vendor.\"
"},{"location":"troubleshooting/#usage","title":"Usage","text":""},{"location":"troubleshooting/#why-isnt-krux-scanning-the-qr-code","title":"Why isn't Krux scanning the QR code?","text":"The level of detail that you see is what Krux sees. If the QR code shown on the device's screen is blurry, the camera lens of the device may be out of focus. It can be adjusted by rotating it clockwise or counter-clockwise to achieve a clearer result. The lenses usually comes with a drop of glue that makes id harder to adjust for the first time. You can use your fingertip, tweezers or small precision pliers to help, being careful to don't damage the fragile lenses.
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. Some cameras (OV7740, OV2640 and GC2145) have an anti-glare mode to better capture images from high brightness screens or with incident light, they are present on M5StickV, Amigo, Cube and Yahboom. To enable/disable the anti-glare mode on a supported device just press the PAGE button while scanning.
"},{"location":"troubleshooting/#error-when-scanning-qr-code","title":"Error when scanning QR code?","text":"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 BIP-39 mnemonics:
- BIP-39 Plaintext (Used by Krux and https://iancoleman.io/bip39/)
- SeedSigner SeedQR and CompactSeedQR Formats
- UR Type
crypto-bip39 - Encrypted QR Code (Format created by Krux, more information here)
For Wallet output descriptor:
- JSON with at least a
descriptor key containing an output descriptor string - Key-value INI files with at least
Format, Policy, and Derivation keys - UR Type
crypto-output
For PSBT (Partially Signed Bitcoin Transactions):
- Base43, Base58, and Base64-encoded bytes
- Raw Bytes
- UR Type
crypto-psbt
Additionally, Krux recognizes animated QR codes that use either the plaintext pMofN (the Specter QR format) or binary UR encodings.
"},{"location":"troubleshooting/#computer-not-reading-qr-code-that-krux-displays","title":"Computer not reading QR code that Krux displays?","text":"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. 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.
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.
"},{"location":"troubleshooting/#why-does-krux-say-the-entropy-of-my-fifty-dice-rolls-does-not-contain-128-bits-of-entropy","title":"Why Does Krux Say the Entropy of My Fifty Dice Rolls Does Not Contain 128 Bits of Entropy?","text":"Please check how entropy measurement works.
"},{"location":"troubleshooting/#why-isnt-krux-detecting-my-microsd-card-or-presenting-an-error","title":"Why isn't Krux detecting my microSD card or presenting an error?","text":"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. Make sure the SD card is using MBR/DOS partition table and FAT32 format.
"},{"location":"uncommon-questions/","title":"Uncommon Questions","text":""},{"location":"uncommon-questions/#what-are-all-the-features-available","title":"What are all the features available?","text":"On the official releases page you will find all the features listed, with details on the Getting Started page with a brief summary on the Navigation Overview page.
"},{"location":"uncommon-questions/#what-is-the-purpose-of-using-an-sd-card-with-the-device","title":"What is the purpose of using an SD card with the device?","text":"SD card use is optional, but can be used to upgrade the firmware, save settings, cnc/file, QR codes, XPUBs, encrypted mnemonics, and also to save and load PSBTs, messages and wallet output descriptors.
"},{"location":"getting-started/","title":"Getting Started","text":"Krux is open-source Bitcoin signing firmware for devices with the K210 chipset; also known as a hardware signer.
Signing operations in Krux are done offline via QR code or via SD card using the PSBT functionality. You can create/load your BIP-39 mnemonic, or import a wallet descriptor, and sign transactions all without having to plug the device into your computer (except to initially install the firmware). It reads QR codes with its camera and outputs QR codes to its screen, or to paper via an optional thermal printer attachment.
Krux runs offline, and therefore never handles the broadcasting part of the PSBT transaction. Instead, you can use Krux with third-party wallet coordinators to broadcast transactions from your online computer or mobile device while keeping your keys offline. Krux was built to be vendor agnostic and works with many popular wallet coordinators, including:
- Sparrow Wallet (desktop)
- Specter Desktop (desktop)
- Nunchuk (mobile)
- BlueWallet (mobile)
"},{"location":"getting-started/navigation/","title":"Navigation Overview","text":"Below is the mind map representation of the currently menus available. Click the circle with a number (Ex.: ) to the right of each node to expand and explore. Also, enable full screen in the top right menu for better viewing .
"},{"location":"getting-started/navigation/#login-menu","title":"Login Menu","text":""},{"location":"getting-started/navigation/#home-menu-loaded-a-mnemonic","title":"Home Menu (Loaded a mnemonic)","text":""},{"location":"getting-started/settings/","title":"Settings","text":"In the Krux home menu, there is a Settings entry. Some submenu entries have too many options to fit on one screen, swipe up or down to navigate between the screens if your device has a touchscreen. Below is a breakdown of the options you can change:
"},{"location":"getting-started/settings/#default-wallet","title":"Default Wallet","text":"Set the default attributes for wallet loading.
"},{"location":"getting-started/settings/#multisig","title":"Multisig","text":"Set this to true if you are more likely to use Krux for multisig setups. This way, you won't need to \"Customize\" your wallet attributes every time you load a key.
"},{"location":"getting-started/settings/#network","title":"Network","text":"This option allows you to switch between mainnet (the default) and testnet. Testnet can be used to try out different wallet coordinators or for development.
"},{"location":"getting-started/settings/#encryption","title":"Encryption","text":"Modify the encryption method and parameters to fit your needs. This will be used when storing encrypted mnemonics or creating encrypted QR codes. For more info see Krux Encrypted Mnemonics.
"},{"location":"getting-started/settings/#pbkdf2-iter-iterations","title":"PBKDF2 Iter. (Iterations)","text":"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 stands for the amount of derivations that will be performed over your key prior to encrypt/decrypt your mnemonic.
If you increase this value it will make the encryption harder, at the cost of taking longer to encrypt/decrypt your mnemonics.
Values must be multiple of 10,000. This was done to save data space on QR codes.
"},{"location":"getting-started/settings/#encryption-mode","title":"Encryption Mode","text":"Choose between well known and widely used AES (Advanced Encryption Standard) modes:
"},{"location":"getting-started/settings/#aes-ecb","title":"AES-ECB","text":"ECB (Electronic Codebook) is a simpler method where data blocks are encrypted individually. Compared to CBC, it will be faster and simpler to encrypt, QR codes will have a lower density and will be easier to transcribe.
"},{"location":"getting-started/settings/#aes-cbc","title":"AES-CBC","text":"CBC (Cipher-block Chaining) is considered more secure than ECB. 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, ensuring chaining.
Encryption will take longer because a snapshot will be needed to generate the IV. This IV will be stored together with the encrypted data, making encrypted QR codes denser and harder to transcribe.
"},{"location":"getting-started/settings/#hardware","title":"Hardware","text":"Customize the parameters available for your device and change printer settings.
"},{"location":"getting-started/settings/#encoder-maix-dock-only","title":"Encoder (Maix Dock only)","text":"If your device has a rotary encoder, you can change the debounce threshold in milliseconds. With lower values, faster movements and navigation will be allowed.
The caveat is low values can cause issues, such as double step and unexpected movements, especially with lower quality encoders. If this is the case increase the value to make navigation more stable.
"},{"location":"getting-started/settings/#display-maix-amigo-only","title":"Display (Maix Amigo only)","text":"Some Maix Amigo screens are different, here you can customize the BGR Colors, Flipped X Coordinates, Inverted Colors and LCD Type. For more info see Troubleshooting
"},{"location":"getting-started/settings/#printer","title":"Printer","text":"You can set up a TTL serial thermal printer or tell Krux to store a GRBL CNC instructions file on a SD card to machine QR codes.
"},{"location":"getting-started/settings/#cnc","title":"CNC","text":"Define several machining parameters according to the desired size, material you'll use, and your CNC characteristics and capabilities.
"},{"location":"getting-started/settings/#thermal","title":"Thermal","text":"Printers can come with different baudrates from the manufacturer. By default, Krux assumes the connected printer will have a baudrate of 9600. If yours is different, you can change it here.
Also setup the TX Pin you'll use (e.g. 35 for M5StickV and 7 for Maix Amigo) and tweak other parameters according to your printer recommendations. For most printers you will only need to connect 2 cables, the device TX to the printer RX and ground. Current uses of printing are listed here. Consult the parts list for supported printers.
"},{"location":"getting-started/settings/#driver","title":"Driver","text":"Here you choose between Thermal, CNC or none (default). Leave this setting to \"none\" if you won't use a printer and don't want to be bothered by print prompts.
"},{"location":"getting-started/settings/#touchscreen-maix-amigo-and-yahboom-only","title":"Touchscreen (Maix Amigo and Yahboom only)","text":"If your device has touchscreen you can change the touch detection threshold. If it is being too sensitive or detecting false or ghost touches, you should increase the threshold value, making it less sensitive. The other way is also valid, reduce the threshold to make the screen more sensitive to touches.
"},{"location":"getting-started/settings/#language-locale","title":"Language - Locale","text":"Here you can change Krux to your desired language.
"},{"location":"getting-started/settings/#persist","title":"Persist","text":"Choose between flash (device's internal memory) or SD card for the place where your settings will be stored.
"},{"location":"getting-started/settings/#security","title":"Security","text":"Adjust settings that may impact your security protocols.
"},{"location":"getting-started/settings/#shutdown-time","title":"Shutdown Time","text":"Set the time it takes for Krux to automatically shut down. This feature not only conserves your device's battery, if it has one, but also serves as an important security measure. If you forget your device with private keys loaded, it will shut down automatically after the set time.
Please note that devices without batteries and power management will not shut down but will reboot instead, which is sufficient to unload private keys.
"},{"location":"getting-started/settings/#tc-flash-hash-at-boot","title":"TC Flash Hash at Boot","text":"Chose if you would like to run Tamper Check Flash Hash every time the device is powered on.
Activating TC Flash Hash at boot helps prevent unauthorized use by requiring the TC Code. But is important to note, unlike a PIN, the TC Code does not provide access control over USB. This means that the device's memory remains accessible for reading and writing via USB, allowing it to be flashed with firmware that does not require the TC Code, which could then allow unauthorized use through its human interface.
"},{"location":"getting-started/settings/#hide-mnemonics","title":"Hide Mnemonics","text":"When \"Hide Mnemonics\" mode is set to \"True\", your device will not display private key data or backup tools when a key is loaded. It will only show public key information and allow signing operations.
"},{"location":"getting-started/settings/#tamper-check-code","title":"Tamper Check Code","text":"Create or modify a Tamper Check Code. This code will be required every time Tamper Check Flash Hash is executed.
After creating the code, you will be prompted to fill the empty memory spaces with random entropy from the camera. This step is important to make TC Flash Hash more resilient to data manipulation by eliminating empty memory spaces that could be exploited in a sophisticated tamper attempt.
The filling process requires good entropy images. If, for any reason, such as starting the process in a dark room, you fail to capture good entropy images, you can restart the filling process by resetting your TC Code.
The TC Code will be deleted if the device is wiped or user data is erased, which will consequently disable TC Flash Hash.
"},{"location":"getting-started/settings/#appearance","title":"Appearance","text":"Configure screensaver time and change Krux to your desired theme.
"},{"location":"getting-started/settings/#screensaver-time","title":"Screensaver time","text":"Set how long to wait idle before the screensaver appears. Enter 0 to disable the screensaver.
"},{"location":"getting-started/settings/#theme","title":"Theme","text":"Choose your color theme according to your preference. Some themes may be more suitable for some devices, coordinator cameras and environments. As an example, it may be easier to scan QR codes from Krux devices using light theme in brighter environments.
"},{"location":"getting-started/settings/#factory-settings","title":"Factory Settings","text":"Restore device to factory settings and reboot.
"},{"location":"getting-started/features/QR-transcript-tools/","title":"Transcribing QR Codes","text":"When you export a mnemonic, encrypted mnemonic or a generic text QR code, alternative visualization modes will be available. Swipe left or right to change modes, or if your device doesn't have a touchscreen, press the PAGE buttons. Find transcribe templates here.
"},{"location":"getting-started/features/QR-transcript-tools/#standard-mode","title":"Standard Mode","text":"This mode is optimized for scanning, the raw QR code will be displayed
"},{"location":"getting-started/features/QR-transcript-tools/#lines-mode","title":"Lines Mode","text":"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.
"},{"location":"getting-started/features/QR-transcript-tools/#zoomed-regions-mode","title":"Zoomed Regions Mode","text":"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.
"},{"location":"getting-started/features/QR-transcript-tools/#highlighted-regions-mode","title":"Highlighted Regions Mode","text":"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.
"},{"location":"getting-started/features/QR-transcript-tools/#grided-mode","title":"Grided Mode","text":"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 (tracing). Be careful not to damage your screen with pen and markers, use an insulating plastic tape or film to protect the device when using this method.
"},{"location":"getting-started/features/encrypted-mnemonics/","title":"Encrypted Mnemonics","text":""},{"location":"getting-started/features/encrypted-mnemonics/#introduction","title":"Introduction","text":"There are many possible security layers one could add to protect a wallet\u2019s 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\u2019s 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:
"},{"location":"getting-started/features/encrypted-mnemonics/#aes-ecb","title":"AES-ECB","text":"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.
"},{"location":"getting-started/features/encrypted-mnemonics/#aes-cbc","title":"AES-CBC","text":"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.
"},{"location":"getting-started/features/encrypted-mnemonics/#cbc-encryption-iv","title":"CBC Encryption IV","text":"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.
"},{"location":"getting-started/features/encrypted-mnemonics/#pbkdf2-iterations","title":"PBKDF2 Iterations","text":"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.
"},{"location":"getting-started/features/encrypted-mnemonics/#encrypted-qr-codes-data-and-parsing","title":"Encrypted QR Codes Data and Parsing","text":"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:
ID length (1) ID (2) Version (3) Key Derivations (4) IV (5) Encrypted Mnemonic (6) Validation Block (7) 1 Byte Variable 1 Byte 3 Bytes 16 Bytes (optional) 16 Bytes (12 words) 32 Bytes (24 words) 16 Bytes - Visible data (1 to 4):
- (1) Mnemonic ID length (1 Byte).
- (2) Mnemonic ID (variable lenght): Custom ID or wallet fingerprint.
- (3) Version (1 Byte): Version of encryption method, currently two are available:
- 0: AES-ECB-PBKDF2: Electronic Codebook with PBKDF2 key derivation.
- 1: AES-CBC-PBKDF2: Cypher Block Chaining with PBKDF2 key derivation.
- (4) Key derivation iterations (3 Bytes): Number of PBKDF2 key derivations times 10,000.
- Cipher data (5 to 7):
- (5) IV (16 Bytes-optional): Initial vector for AES-CBC encryption, possibility to be nonce for future AES-CTR or other encryption methods.
- (6) Encrypted Mnemonic (16 Bytes - 12 words, 32 Bytes - 24 words): Mnemonic ciphertext.
- (7) Validation block (16 Bytes): Currently using first 16 bytes of sha256 of the mnemonic bytes as checksum, could be used in future to store AES-AEX validation tag.
"},{"location":"getting-started/features/encrypted-mnemonics/#considerations","title":"Considerations","text":"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, 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, the best way to undo this is to wipe the device.
"},{"location":"getting-started/features/entropy/","title":"Empirical Entropy Measurement","text":""},{"location":"getting-started/features/entropy/#why-does-krux-say-the-entropy-of-my-fifty-dice-rolls-does-not-contain-128-bits-of-entropy","title":"Why Does Krux Say the Entropy of My Fifty Dice Rolls Does Not Contain 128 Bits of Entropy?","text":"This question, frequently raised in Krux chat groups, highlights the need to clarify the concepts and tools used by Krux to help users detect possible issues in the mnemonic creation procedure. Tools in Krux were designed to help users understand the concepts involved in the process, present statistics and indicators, and encourage users to experiment and evaluate results. This way, users learn about best practices in key generation. Below, we will dive deeper into entropy concepts to better support users in the fundamental requirement for sovereign self-custody, which is to build up knowledge.
"},{"location":"getting-started/features/entropy/#entropy-in-dice-rolls","title":"Entropy in Dice Rolls","text":"Rolling dice and collecting the resulting values can be an effective method for generating cryptographic keys due to the inherent randomness and unpredictability of each roll. Each roll of a die produces a random number within a specific range, and when multiple rolls are combined, they create a sequence that is difficult to predict or reproduce. This sequence can be used to generate cryptographic keys that are robust against attacks. By ensuring that the dice rolls are conducted in a controlled and secure environment, and by using a sufficient number of rolls to achieve the desired level of randomness, one can create cryptographic keys that are highly secure and resistant to brute-force attacks or other forms of cryptanalysis.
"},{"location":"getting-started/features/entropy/#entropy-definitions","title":"Entropy Definitions","text":"Entropy, a fundamental concept in various scientific disciplines, measures the degree of disorder or uncertainty within a system. This notion is interpreted differently across fields, leading to distinct types of entropy: mechanical entropy, Shannon's entropy, and cryptographic entropy.
Mechanical entropy, rooted in thermodynamics and statistical mechanics, quantifies the disorder in a physical system. It describes how energy is distributed among the particles in a system, reflecting the system's tendency towards equilibrium and maximum disorder.
Shannon's entropy, from information theory, measures the uncertainty or information content in a message or data source. Introduced by Claude Shannon, it quantifies the average amount of information produced by a stochastic source of data, indicating how unpredictable the data is.
Cryptographic entropy, crucial in security, refers to the unpredictability and randomness required for secure cryptographic keys and processes. High cryptographic entropy ensures that keys are difficult to predict or reproduce, providing robustness against attacks.
While mechanical entropy deals with physical systems, Shannon's entropy focuses on information content, and cryptographic entropy emphasizes security through randomness.
"},{"location":"getting-started/features/entropy/#measuring-dice-rolls-entropy","title":"Measuring Dice Rolls Entropy","text":"Entropy is a theoretical measure and is not directly measurable from a single roll but rather from the probability distribution of outcomes over many rolls. We can use Shannon's formula for theoretical and empirical calculations. Entropy S can be quantified with:
S = -\\sum_{i=1}^{n} p_i \\log(p_i) - Empirical Measurement:
- Roll the dice a large number of times to observe the frequency of each outcome.
-
Estimate the probabilities p_i based on observed frequencies.
-
Theoretical Calculation:
- Use the uniform distribution assumption (equal probability for all outcomes).
where: - p_i is the probability of each possible outcome (or state) of the system. - n is the number of possible outcomes.
"},{"location":"getting-started/features/entropy/#empirical-real-vs-theoretical-entropy-in-dice-rolls","title":"Empirical (Real) vs. Theoretical Entropy in Dice Rolls","text":"When calculating the entropy of dice rolls, the difference between real and theoretical results arises from the assumption of perfect fairness and uniformity versus the inherent imperfections in real-world experiments.
"},{"location":"getting-started/features/entropy/#theoretical-entropy","title":"Theoretical Entropy","text":"The theoretical entropy calculation assumes that the dice are perfectly fair, meaning each face has an equal probability of landing face up.
Consider a fair six-sided die. The possible outcomes when rolling one die are {1, 2, 3, 4, 5, 6}, each with an equal probability of \\frac{1}{6}.
- Single Die Roll:
- Each outcome has a probability p_i = \\frac{1}{6}.
- The entropy S for one die roll is calculated as:
S = - \\sum_{i=1}^{6} \\left( \\frac{1}{6} \\log_2 \\left( \\frac{1}{6} \\right) \\right) Since \\log_2(1/6) = -\\log_2(6) :
S = -6 \\left( \\frac{1}{6} \\times -\\log_2(6) \\right) = \\log_2(6) \\approx 2.585 \\text{ bits} - Multiple Dice Rolls:
- For multiple dice, the entropy increases as the number of possible outcomes increases. For k fair dice, the number of possible outcomes is 6^k.
-
The entropy S for k dice is:
S = \\log_2(6^k) = k \\log_2(6) \\approx 2.585k \\text{ bits}
-
For example, entropy for the roll of 50 fair dice is calculated as:
S = \\log_2(6^{50}) = 50 \\log_2(6) \\approx 2.585 \\times 50 \\approx 129.25 \\text{ bits}
This calculation assumes that every outcome (each face of the die) has an equal likelihood, leading to a uniform distribution.
"},{"location":"getting-started/features/entropy/#empirical-entropy","title":"Empirical Entropy","text":"In a real sample of dice rolls, several factors can cause deviations from the perfect uniform distribution:
- Imperfect Dice: Real dice may not be perfectly balanced. Small manufacturing defects can make certain faces slightly heavier or lighter, causing biases.
- Rolling Conditions: The way the dice are rolled, the surface they land on, and even air currents can introduce slight biases.
- Finite Sample Size: When rolling dice a finite number of times, the observed frequencies of each face will naturally deviate from the expected uniform distribution due to random variations. This phenomenon is more pronounced with smaller sample sizes.
When you roll a die multiple times and observe the outcomes, you can calculate the empirical probabilities p_i of each face. Using these probabilities, the entropy is calculated as:
S = - \\sum_{i=1}^{6} p_i \\log_2(p_i)"},{"location":"getting-started/features/entropy/#example","title":"Example","text":"Suppose you roll a six-sided die 50 times and get the following results:
- 1: 4 times
- 2: 9 times
- 3: 7 times
- 4: 10 times
- 5: 12 times
- 6: 8 times
We can calculate Shannon's entropy as follows:
"},{"location":"getting-started/features/entropy/#step-1-calculate-probabilities","title":"Step 1: Calculate Probabilities","text":"Total number of rolls:
N = 4 + 9 + 7 + 10 + 12 + 8 = 50 Probabilities for each outcome:
p_1 = \\frac{4}{50} = 0.08 p_2 = \\frac{9}{50} = 0.18 p_3 = \\frac{7}{50} = 0.14 p_4 = \\frac{10}{50} = 0.2 p_5 = \\frac{12}{50} = 0.24 p_6 = \\frac{8}{50} = 0.16"},{"location":"getting-started/features/entropy/#step-2-compute-entropy","title":"Step 2: Compute Entropy","text":"Using Shannon's entropy formula:
S = -\\sum_{i=1}^{n} p_i \\log_2(p_i) Calculate each term:
S_1 = -p_1 \\log_2(p_1) = -0.08 \\log_2(0.08) = -0.08 \\times (-3.64386) = 0.291509 S_2 = -p_2 \\log_2(p_2) = -0.18 \\log_2(0.18) = -0.18 \\times (-2.47393) = 0.445307 S_3 = -p_3 \\log_2(p_3) = -0.14 \\log_2(0.14) = -0.14 \\times (-2.8365) = 0.39711 S_4 = -p_4 \\log_2(p_4) = -0.2 \\log_2(0.2) = -0.2 \\times (-2.32193) = 0.464386 S_5 = -p_5 \\log_2(p_5) = -0.24 \\log_2(0.24) = -0.24 \\times (-2.05889) = 0.494132 S_6 = -p_6 \\log_2(p_6) = -0.16 \\log_2(0.16) = -0.16 \\times (-2.64386) = 0.423018 Sum the contributions:
S = S_1 + S_2 + S_3 + S_4 + S_5 + S_6 S = 0.291509 + 0.445307 + 0.39711 + 0.464386 + 0.494132 + 0.423018 = 2.515462 Thus, the Shannon's entropy for the given distribution of dice rolls is approximately 2.52 bits per roll.
This will give you a different value than \\log_2(6) due to the deviations in the empirical probabilities.
The total entropy for the N = 50 rolls is:
S_{total} = S \\times N = 2.515 + 50 \\approx 125.8 \\text{ bits}"},{"location":"getting-started/features/entropy/#shannons-entropy-in-practice","title":"Shannon's Entropy in Practice","text":"Calculating Shannon's entropy on a real sample of dice rolls provides insights into the actual randomness and fairness of the dice and rolling conditions. Deviations from the theoretical entropy reflect the natural imperfections and variances inherent in real-world scenarios. This understanding helps in evaluating and improving the fairness and randomness of dice or similar systems.
Shannon's entropy evaluates the statistical probability distribution of samples of a dice roll. An even distribution results in higher entropy, closer to the theoretical maximum entropy, which assumes perfectly distributed rolls. An uneven distribution, created, for example, by a biased die, will result in lower Shannon's entropy. In an extreme case, with a terribly biased die that always lands on the same side, Shannon's entropy will be zero.
"},{"location":"getting-started/features/entropy/#cryptographic-entropy","title":"Cryptographic Entropy","text":"Shannon's entropy, while a powerful measure of information content and uncertainty in a statistical distribution for natural samples, is not considered cryptographic entropy due to its inability to detect patterns or other sources of predictability within data. Shannon's formula quantifies the average information produced by a stochastic process, essentially measuring the expected surprise in a sequence of symbols based on their probabilities. However, it does not account for potential structure, correlations, or regularities within the data that could be inserted by a user and exploited by an attacker.
Cryptographic entropy, on the other hand, requires a higher standard of unpredictability. It must ensure that every bit of the cryptographic key is as random and independent as possible, making it resilient against any form of analysis that could reveal patterns or reduce the effective randomness. While Shannon's entropy can evaluate the statistical distribution of symbols, it falls short in guaranteeing the absence of patterns or dependencies, which are crucial for maintaining the security of cryptographic systems. Thus, cryptographic entropy encompasses a broader concept of randomness, ensuring that the generated keys are not only statistically random but also free from any detectable structure or predictability.
"},{"location":"getting-started/features/entropy/#pattern-detection","title":"Pattern Detection","text":"It is possible to have dice rolls with an even distribution but poor cryptographic entropy. This issue arises when patterns are present in the sequences. Examples include sequences like 123456123456123..., 111122223333..., and 654321654321..., which exhibit poor cryptographic entropy despite having even distribution and high Shannon's entropy.
To mitigate this issue, Krux has implemented a pattern detection algorithm that evaluates the Shannon's entropy of the rolls' derivatives. In practice, this algorithm detects arithmetic progression components in the dice rolls and raises a warning if a certain threshold is crossed.
"},{"location":"getting-started/features/entropy/#what-krux-does","title":"What Krux Does?","text":" - Krux requires a minimum number of rolls based on theoretical entropy.
- Krux warns the user if low Shannon's entropy, calculated with the actual rolls, is detected.
- Krux warns the user if it suspects there are patterns within the actual rolls.
"},{"location":"getting-started/features/entropy/#conclusion","title":"Conclusion","text":"While Krux cannot ensure rolls have good or bad cryptographic entropy, it does provide indicators to help users detect issues and learn about the concepts involved in mnemonic generation.
"},{"location":"getting-started/features/printing/","title":"Printing","text":"Warning/Disclaimer: This feature is intended for individuals with experience in electronics tinkering and soldering.
Krux has the ability to print mnemonic backup (Words, Numbers, Tiny Seed template; but not Stackbit 1248) and any QR code (SeedQR, signed PSBT, Address, XPUB, Wallet output descriptor, ...) via a locally-connected TTL serial thermal printer. Consult the parts list page for supported printers.
Once a thermal printer and driver have been enabled in Krux settings, all screens that display a QR code will offer the option to Print to QR. Other formats of mnemonic backup will also ask if you want to Print to QR?.
There are many ways you can use this functionality, including:
- Printing backups of your mnemonics and multisig wallet output descriptor
- Printing your xpubs and receive addresses to share
- Printing signed messages and PSBTs
Since printed thermal paper fades quickly, you can also print your backups on sticker thermal paper to use as templates for punching into more resilient materials like steel.
We also have plans to add support for other kinds of QR \"printers\" in the future, including CNC machines. In this case, gcode will be generated that can be sent directly to a GRBL controller to cut your QRs out of wood or metal!
Just be careful what you do with the printed codes, since most smartphones can now quickly and easily read QR codes. Treat your QR mnemonic the same way you would treat a plaintext copy of it.
"},{"location":"getting-started/features/sd-card-update/","title":"SD Card Updates","text":""},{"location":"getting-started/features/sd-card-update/#upgrade-via-microsd-card","title":"Upgrade via microSD card","text":"Once you've installed the initial firmware on your device via USB, you can either continue updating the device by flashing via USB or you can perform upgrades via microSD card to keep the device airgapped.
To perform an upgrade, simply copy the official release firmware.bin and firmware.bin.sig files to the root of a FAT-32 / MBR formatted microSD card, insert the card into your device, and reboot the device. If it detects the new firmware file and is able to verify the signature, you will be prompted to install it.
Once installation is complete, eject the microSD card and delete the firmware files before reinserting and rebooting. Otherwise you will be prompted to install it again.
We cannot guarantee that a microSD card is compatible and will work in your device; you'll need to test it on the device to be sure, read the Troubleshooting for more info. Only official releases are signed and can be installed via microSD card.
"},{"location":"getting-started/features/tamper-detection/","title":"Tamper Detection Mechanism (Experimental)","text":"Krux's tamper detection tool combines cryptographic hashes, a Tamper Check Code, and camera-generated entropy to create a tamper indicator that is unique to each device, represented by a memorable image and four words.
Before we get into details, let's start with some limitations and necessary prerequisites to allow the feature to work.
"},{"location":"getting-started/features/tamper-detection/#krux-security-model-good-practices-and-limitations","title":"Krux Security Model - Good Practices and Limitations","text":"To secure your Krux device, always verify firmware authenticity before installation, particularly when flashing via USB.
"},{"location":"getting-started/features/tamper-detection/#firmware-verification-methods","title":"Firmware Verification Methods","text":" -
Using OpenSSL Command-Line Tool: Follow the Krux documentation to verify the firmware's signature manually. This method provides a high level of assurance but requires familiarity with command-line operations.
-
Using Krux-Installer: For a more user-friendly experience, verify the Krux-Installer's signature using GPG. Graphical interfaces like Sparrow Wallet can facilitate this process. Krux-Installer automatically downloads the firmware from Github, verifies the firmware signature, informs you of the results, and guides you through manual verification if desired.
"},{"location":"getting-started/features/tamper-detection/#recommendations","title":"Recommendations","text":" -
Learn Verification Tools: Familiarize yourself with verification methods and tools to maintain control over your device's security.
-
Build from Source: Consider building the firmware from source code and verifying its reproducibility for maximum assurance.
-
Use SD Card for Updates: After the initial flash through USB, perform subsequent updates via the SD card. This keeps your device air-gapped and allows the existing firmware to verify new updates before installation.
Note: The effectiveness of the TC Flash Hash tamper detection feature relies on running legitimate, uncompromised firmware and safely protecting your Tamper Check Code.
"},{"location":"getting-started/features/tamper-detection/#tamper-check-code-tc-code","title":"Tamper Check Code (TC Code)","text":"A Tamper Check Code, composed of numbers, letters and special characters, with a minimum length of six characters, can be stored and required to execute Tamper Check (TC) Flash Hash tamper verification before Krux boots at the main application, or optionally as a feature available in Tools -> Flash Tools.
Before being stored in the device\u2019s flash, the TC Code is hashed together with the K210 chip\u2019s unique ID and stretched using PBKDF2. This ensures the TC Code is not retrievable via a flash dump and can only be brute-forced outside the device if the attacker also has access to the device\u2019s unique ID. By allowing letters, special characters, and running 100k iterations of PBKDF2, brute-forcing the TC Code from dumped data becomes more time-consuming and resource-intensive.
"},{"location":"getting-started/features/tamper-detection/#enhancing-tamper-detection","title":"Enhancing Tamper Detection","text":"After setting the TC Code, you are prompted to fill empty flash memory blocks with random entropy from the camera. This process ensures that attackers cannot exploit unused memory space.
"},{"location":"getting-started/features/tamper-detection/#tamper-check-tc-flash-hash-a-tamper-detection-tool","title":"Tamper Check (TC) Flash Hash - A Tamper Detection Tool","text":""},{"location":"getting-started/features/tamper-detection/#introduction","title":"Introduction","text":"The \"TC Flash Hash\" tool enables you to verify if the flash memory content has been altered.
"},{"location":"getting-started/features/tamper-detection/#how-it-works","title":"How It Works","text":"The tool generates a unique image and four tamper detection words based on a hash of your TC Code, the device's UID, and the flash content. The flash memory is divided into two regions:
-
Firmware Region: Generates the image and the first two words.
-
User's Region: Generates the last two words.
Example: The blue symbol and words 'tail monkey' represent the firmware region, while 'wrestle over' reflects the user region.
Any change in the flash content results in a different image or words:
-
Firmware Changes: Alterations in the firmware region, including the bootloader, change the image and the first two words.
-
User's Data Changes: Modifications in the user's region, such as new settings or stored mnemonics, change the last two words.
-
TC Code Changes: Replacing the TC Code alters the image and all four words.
"},{"location":"getting-started/features/tamper-detection/#filling-empty-flash-blocks","title":"Filling Empty Flash Blocks","text":"Krux performs a memory sweep while simultaneously capturing a live feed from the camera. Whenever an empty block is found in the flash memory, Krux estimates the image's entropy by evaluating its color variance. Krux waits until minimum threshold is met, then uses the data from the image to fill these empty spaces with rich, random entropy.
"},{"location":"getting-started/features/tamper-detection/#ensuring-tamper-detection","title":"Ensuring Tamper Detection","text":"The TC Flash Hash function securely hashes the combination of the TC Code, UID, and flash content:
hash(TC Code,UID,Flash content) -> Image + Words
Hash properties ensure that without knowing the TC Code, UID, and flash content, an attacker cannot reproduce the TC Flash Hash results.
"},{"location":"getting-started/features/tamper-detection/#executing-tc-flash-hash","title":"Executing TC Flash Hash","text":"After setting a TC Code user can use the TC Flash Hash feature, available in Tools -> Flash Tools -> TC Flash Hash.
By navigating to Settings -> Security -> TC Flash Hash at Boot, you can set Krux to always require TC Flash Hash verification after device is turned on.
If a wrong TC Code is typed at boot, the device will turn off. As storing code typing attempts count on flash would change its contents, there will be no consequences if wrong TC Code is typed multiple times.
As TC Code verification data is stored in the user's region of memory, TC Flash Hash and TC Code requirement is disabled if the user wipes the device. Flashing an older firmware version will also disable the feature.
"},{"location":"getting-started/features/tamper-detection/#potential-attack-scenarios-and-their-mitigation","title":"Potential Attack Scenarios and Their Mitigation","text":""},{"location":"getting-started/features/tamper-detection/#challenge-for-an-attacker","title":"Challenge for an Attacker","text":"An attacker faces major challenges in replacing the firmware:
-
Lack of Original Flash Data: Without the exact original flash content, the attacker cannot reproduce the correct hash.
-
Sequential Hash Dependency: The hash function processes data sequentially (TC Code, UID, flash content), preventing the attacker from injecting or rearranging data to produce the same hash.
-
One-Way Hash Functions: Cryptographic hash functions like SHA-256 are one-way, making it infeasible to reverse-engineer or manipulate the hash without the original inputs.
"},{"location":"getting-started/features/tamper-detection/#why-tampered-firmware-cannot-bypass-verification","title":"Why Tampered Firmware Cannot Bypass Verification","text":" -
Cannot Reconstruct the Hash: Without the original flash data, the attacker cannot generate the correct hash, even if they know the UID and TC Code after the user enters it.
-
Hash Sensitivity: Any alteration in the flash content changes the hash output, which will be evident through a different image or tamper detection words.
-
Entropy Filling: Filling empty flash blocks with camera-generated entropy leaves no space for malicious code and any changes to these blocks will alter the hash.
"},{"location":"getting-started/features/tamper-detection/#possible-attack-strategies-and-failures","title":"Possible Attack Strategies and Failures","text":" -
Precomputing Hashes: The attacker cannot precompute the correct hash without the TC Code, UID, and exact flash content.
-
Storing Hashes: Storing hash(flash content) is ineffective because the overall hash depends on the sequential combination of TC Code, UID, and flash data.
-
Inserting Malicious Code: Attempting to insert code into empty spaces fails because the entropy filling process and hash verification will detect any changes.
-
Using an SD Card to Store a Copy of Original Flash Content: An attacker could extract an exact copy of the flash contents to an SD card and subsequently install malicious firmware. This firmware could capture the chip's UID and the user's TC Code, then hash the content of the SD card instead of the flash memory. Although this would make the verification process slower, it introduces a potential security risk. To mitigate this vulnerability, it is advisable to avoid performing verifications while an SD card is inserted.
"},{"location":"getting-started/features/tamper-detection/#conclusion","title":"Conclusion","text":"The TC Flash Hash tool significantly enhances security by making it infeasible for attackers to tamper with the firmware without detection. By combining TC Code hashing, filling empty memory with random entropy, and verifying flash integrity through unique images and words, Krux significantly enhances the detection of any tamper attempts.
Note: The strength of this defense strategy depends on maintaining a strong, confidential TC Code and following secure practices when unlocking the device.
"},{"location":"getting-started/features/tinyseed/","title":"Tiny Seed and other metal plates","text":""},{"location":"getting-started/features/tinyseed/#background","title":"Background","text":"The examples below have been created so that you can test the workflow for scanning both 12 and 24 word mnemonics. (Scanning the left plate for a 12 word mnemonic and both plates for 24) The resulting fingerprint from an successful scan is also incldued in the image.
"},{"location":"getting-started/features/tinyseed/#tinyseed","title":"TinySeed","text":""},{"location":"getting-started/features/tinyseed/#onekey-keytag","title":"OneKey KeyTag","text":""},{"location":"getting-started/features/tinyseed/#binary-grid","title":"Binary Grid","text":""},{"location":"getting-started/features/tinyseed/#size-offset-and-padding-reference","title":"Size, Offset and Padding Reference","text":"The general logic for how these are processed is:
- Krux first looks for a square (Which works best if with a well lit square, with clean edges, on a dark background)
- This square is checked and if the ratio of length to height is within a defined range for the given seed type, the square is further processed. (Uses the aspect_high and aspect_low variables)
- An X and Y offset are applied to work out the corner of the seed grid within the seed plate. Some devices like the Maix Amigo use a mirrored coordinate system and some seed types will have a slightly different layout on the front and back of the plate. (Uses the x_offset and y_offset variables, p0 for the front face and p1 for the reverse face)
- The location of each cell within the 12x12 grid is calculated. (This uses the xpad and ypad variables)
- Krux uses the grid created in 4 to evaluate which cells are marked and which are blank, once a seed with a valid checksum is detected, the user can then confirm the dots.
If you have a different type of grid that you want to use, you will need to edit the offsets and padding numbers in tiny_seed.py. (All of the sizes are scaled based on the size of the square detected in step 1...)
You can match the pre-sets for supported key-types to the physical dimensions of the tag as shown below. (The numbers for these offsets are in 1/10th of a millimeter)
"},{"location":"getting-started/features/tools/","title":"Tools","text":"Here are some useful tools that are available as soon as Krux starts! These are offered as a complement to managing your device and wallets.
"},{"location":"getting-started/features/tools/#check-sd-card","title":"Check SD Card","text":"You can check if a SD card can be detected and read by your device and explore its content. If there are too many files to fit on one screen, swipe up or down to navigate between the screens if your device has a touchscreen.
"},{"location":"getting-started/features/tools/#print-test-qr","title":"Print Test QR","text":"Quickly print a test QR code to check and optimize your printer setup.
"},{"location":"getting-started/features/tools/#create-qr-code","title":"Create QR Code","text":"Enter text to create, print or transcribe a QR code that can later be used as an encryption key or passphrase. Swipe left or right to change modes if your device has a touchscreen.
"},{"location":"getting-started/features/tools/#descriptor-addresses","title":"Descriptor Addresses","text":"Verify if an address or list of addresses belong to a wallet without needing to load private keys. Simply load a trusted wallet descriptor from a QR code or SD card.
"},{"location":"getting-started/features/tools/#flash-tools","title":"Flash Tools","text":"Tools to inspect the content of device's flash memory and clear user's area
"},{"location":"getting-started/features/tools/#flash-map","title":"Flash Map","text":"Flash map indicates which memory blocks (4086 Bytes each) are empty. Memory is separated in two regions: Firmware and User's Data. White or colored blocks contain data, while grey blocks are empty.
This is an interesting tool to visualize the effects of filling the memory with ramdom entropy, what is done during the setup of a new TC Code, used with TC Flash Hash tool, described below.
"},{"location":"getting-started/features/tools/#tc-flash-hash","title":"TC Flash Hash","text":"Tamper Check Flash Hash is a tamper detection mechanism that enables you to verify if the flash memory content has been altered. To use it first, need to create a TC Code on Settings -> Security -> Tamper Check Code. TC Flash Hash will hash this code, K210 chip's unique ID and the content of the whole flash memory together and produce an image. The tool generates a unique image and four tamper detection words based on a hash of your TC Code, the device's UID, and the flash content. The flash memory is divided into two regions:
-
Firmware Region: Generates the image and the first two words.
-
User's Region: Generates the last two words.
Learn more about Tamper Check Flash Hash on Tamper Detection
"},{"location":"getting-started/features/tools/#erase-users-data","title":"Erase User's Data","text":"This option permanently removes all stored encrypted mnemonics, settings and TC Code from the device's internal flash memory. It ensures that the data is irrecoverable, making it an adequate measure to take if any important mnemonics were stored with a weak encryption key.
"},{"location":"getting-started/features/tools/#remove-mnemonic","title":"Remove Mnemonic","text":"This option allows you to remove any stored encrypted mnemonic from the device's internal memory or an SD card. For more information, see Krux Encrypted Mnemonics.
When mnemonics are removed from the device's flash memory, Krux will no longer be able to access them. However, as with most operating systems, the data may still be recoverable using specialized tools. If you stored any important keys with a weak encryption key, it is recommended to use the \"Wipe Device\" feature below to ensure that the data is irrecoverable.
When mnemonics are removed from an SD card, Krux will overwrite the region where the encrypted mnemonic was stored with empty data. This makes it more secure to delete mnemonics from SD cards using Krux rather than a PC or another device. However, Krux does not have a \"Wipe\" feature for SD cards; you can find this feature in third-party applications.
"},{"location":"getting-started/installing/from-pre-built-release/","title":"From pre-built official release","text":"This page explains how to install Krux from an official, pre-built release.
"},{"location":"getting-started/installing/from-pre-built-release/#download-the-latest-release","title":"Download the latest release","text":"Head over to the releases page and download the latest signed release.
"},{"location":"getting-started/installing/from-pre-built-release/#verify-the-files","title":"Verify the files","text":"Before installing the release, it's a good idea to check that:
- The SHA256 hash of
krux-v24.11.1.zip matches the hash in krux-v24.11.1.zip.sha256.txt - The signature file
krux-v24.11.1.zip.sig can be verified with the selfcustody.pem public key found in the root of the krux repository.
You can either do this manually or with the krux shell script, which contains helper commands for this:
./krux sha256 krux-v24.11.1.zip\n./krux verify krux-v24.11.1.zip selfcustody.pem\n
On Mac you may need to install coreutils to be able to use sha256sum
brew install coreutils\n
Fun fact: Each Krux release is signed with Krux!
"},{"location":"getting-started/installing/from-pre-built-release/#flash-the-firmware-onto-the-device","title":"Flash the firmware onto the device","text":"Extract the latest version of Krux you downloaded and enter the folder:
unzip krux-v24.11.1.zip && cd krux-v24.11.1\n
Connect the device to your computer via USB (for Maix Amigo, make sure you\u2019re using bottom port), power it on, and run the following, replacing DEVICE with either m5stickv, amigo, bit, cube, dock or yahboom (to yahboom you may need to manually specify the port, for example /dev/ttyUSB0 on Linux or COM6 on Windows):
./ktool -B goE -b 1500000 maixpy_DEVICE/kboot.kfpkg\n
For dock use the -B dan parameter:
./ktool -B dan -b 1500000 maixpy_dock/kboot.kfpkg\n
When the flashing process completes, you should see the Krux logo:
If it doesn't, try turning your device off and on by holding down the power button for six seconds.
Congrats, you're now running Krux!
"},{"location":"getting-started/installing/from-pre-built-release/#a-note-about-the-maix-amigo","title":"A note about the Maix Amigo","text":"Some Amigo screens have inverted X coordinates, others display colors differently. For more info see Troubleshooting.
"},{"location":"getting-started/installing/from-pre-built-release/#troubleshooting","title":"Troubleshooting","text":"If ktool fails to run, you may need to give it executable permissions with chmod +x ./ktool, or you might need to use \"sudo\" if your user don't have access to serial port. In Windows or Mac you may need to explicitly allow the tool to run by adding an exception for it.
If the flashing process fails midway through, check the connection, restart the device, and try the command again.
Two serial ports are created when Amigo and Bit are connected to a PC. Sometimes Ktool will pick the wrong port and flashing will fail. Manually specify the serial port to overcome this issue using -p argument:
"},{"location":"getting-started/installing/from-pre-built-release/#linux","title":"Linux","text":"See the correct port using ls /dev/ttyUSB*, in the example below we use /dev/ttyUSB0:
./ktool-linux -B goE -b 1500000 maixpy_amigo/kboot.kfpkg -p /dev/ttyUSB1\n
"},{"location":"getting-started/installing/from-pre-built-release/#windows","title":"Windows","text":"See the correct port at Device Manager > Ports (COM & LPT), in the example below we use COM6:
.\\ktool-win.exe -B goE -b 1500000 maixpy_amigo\\kboot.kfpkg -p COM6\n
"},{"location":"getting-started/installing/from-pre-built-release/#mac","title":"Mac","text":"Remove the Gatekeeper quarantine extended attribute from ktool-mac:
xattr -d com.apple.quarantine ktool-mac\n
See the correct port using the command line: ls /dev/cu.usbserial*, in the example below we use /dev/cu.usbserial-10 (If the output isn't what you expect try a different cable, preferably a smartphone usb-c charger cable):
./ktool-mac -B goE -b 1500000 maixpy_amigo/kboot.kfpkg -p /dev/cu.usbserial-10\n
Different OS versions may have different port names, and the absence of ports may indicate a connection, driver or hardware related issue. See Troubleshooting for more info.
"},{"location":"getting-started/installing/from-pre-built-release/#multilingual-support","title":"Multilingual support","text":"Prefer a different language? Krux has support for multiple languages. Once at the start screen, go to Settings, followed by Locale, and select the locale you wish to use.
"},{"location":"getting-started/installing/from-pre-built-release/#upgrade-via-microsd-card","title":"Upgrade via microSD card","text":"Once you've installed the initial firmware on your device via USB, you can either continue updating the device by flashing or you can perform upgrades via microSD card to keep the device airgapped.
"},{"location":"getting-started/installing/from-source/","title":"From source","text":"This page explains how to install Krux from source. You can check a simplified version of these instructions in our README too.
"},{"location":"getting-started/installing/from-source/#fetch-the-code","title":"Fetch the code","text":"This will download the source code of Krux as well as the code of all its dependencies inside a new folder called krux (needs git):
git clone --recurse-submodules https://github.com/selfcustody/krux\n
Note: When you wish to pull updates (to all submodules, their submodules, ...) to this repo, use:
git pull origin main && git submodule update --init --recursive\n
"},{"location":"getting-started/installing/from-source/#prerequisite-for-upgrading-via-microsd","title":"Prerequisite for upgrading via microSD","text":"If you wish to perform airgapped upgrades via microSD card later, you will need to have a private and public key pair to sign your builds and verify the signatures. If you do not want to perform further airgapped upgrades, jump to build section.
You can use an existing Krux installation and mnemonic to sign your builds with, or you can generate a keypair and sign from the openssl CLI. Commands have been added to the krux shell script to make this easier.
In either case, you will need to update the SIGNER_PUBKEY field in src/krux/metadata.py to store your public key so that Krux can verify future builds before installing.
To generate a keypair:
./krux generate-keypair\n./krux pem-to-pubkey pubkey.pem\n
The first command will create privkey.pem and pubkey.pem files you can use with openssl, and the second command will output your public key in the form expected by Krux.
Once you've updated the SIGNER_PUBKEY with this value, you can proceed with the regular build process.
"},{"location":"getting-started/installing/from-source/#build-the-firmware-linux-or-wsl","title":"Build the firmware (Linux or WSL)","text":"The krux bash script contains commands for common development tasks. It assumes a Linux host, you will need to have Docker Desktop or Docker Engine, openssl, and wget installed at a minimum for the commands to work as expected. It works on Windows using WSL. The channel Crypto Guide from Youtube made a step-by-step video - Krux DIY Bitcoin Signer: Build From Source & Verify (With Windows + WSL2 + Docker)
To build and flash the firmware:
# build firmware for Maix Amigo\n./krux build maixpy_amigo\n
The first time, the build can take around an hour or so to complete. Subsequent builds should take only a few minutes. If all goes well, you should see a new build folder containing firmware.bin and kboot.kfpkg files when the build completes.
Note: if you encounter any of these errors while building, it is a problem connecting to github, try again (if the error persists, try changing the DNS/VPN or correcting the hostname resolution of github.com to an IP that is working for you):
error: RPC failed; curl 92 HTTP/2 stream 0 was not closed cleanly: CANCEL (err8)\nfatal: the remote end hung up unexpectedly\nfatal: early EOF\nfatal: index-pack failed\nfatal: clone of ... failed\nFailed to clone ...\n
"},{"location":"getting-started/installing/from-source/#reproducibility","title":"Reproducibility","text":"If you build from the main branch of the source code, you should be able to reproduce the build process used to generate the last release binaries and obtain exact copies of the firmware.bin and kboot.kfpkg files, with matching hash checksums.
To extract and verify the firmware.bin contained in kboot.kfpkg, you can use the following command:
unzip kboot.kfpkg -d ./kboot/\n
"},{"location":"getting-started/installing/from-source/#flash-the-firmware-onto-the-device","title":"Flash the firmware onto the device","text":"Connect the device to your computer via USB (for Maix Amigo, make sure you\u2019re using bottom port), power it on, and run the following, replacing DEVICE with either m5stickv, amigo, bit, cube, dock or yahboom:
# build firmware for DEVICE\n./krux flash maixpy_DEVICE\n
If the flashing fails try one of the following common solutions listed on FAQ When the flashing process completes, you should see the Krux logo:
If it doesn't, try turning your device off and on by holding down the power button for six seconds.
Congrats, you're now running Krux!
"},{"location":"getting-started/installing/from-source/#a-note-about-the-maix-amigo","title":"A note about the Maix Amigo","text":"Some Amigo screens have inverted X coordinates, others display colors differently. For more info see Troubleshooting.
"},{"location":"getting-started/installing/from-source/#signing-the-firmware","title":"Signing the firmware","text":"You can sign the firmware to perform airgapped upgrades using one of the two methods listed below:
"},{"location":"getting-started/installing/from-source/#method-1-signing-from-krux","title":"Method 1: Signing from Krux","text":"First, calculate the SHA256 hash of the new firmware by running:
./krux sha256 build/firmware.bin\n
Copy this hex string and turn it into a QR code using whichever QR code generator you'd like.
In Krux, enter the mnemonic of your private key that will be used for signing, and go to Sign > Message. Scan the QR code you generated, and you will be asked if you wish to sign the hash. Proceed, and you will be presented with a base64-encoded string containing the signature, as text and as a QR code.
Take this string and create a signature file by running:
./krux b64decode \"signature-in-base64\" > build/firmware.bin.sig\n
This will generate a firmware.bin.sig file containing a signature of the firmware's SHA256 hash.
"},{"location":"getting-started/installing/from-source/#method-2-signing-from-your-computer-with-openssl","title":"Method 2: Signing from your computer with OpenSSL","text":"With the keypair you generated before, you can now run:
./krux sign build/firmware.bin privkey.pem\n
This will generate a firmware.bin.sig file containing a signature of the firmware's SHA256 hash.
"},{"location":"getting-started/installing/from-test-release/","title":"From pre-built test release","text":"This page explains how to install Krux from a test (beta), pre-built release.
"},{"location":"getting-started/installing/from-test-release/#warning","title":"Warning","text":"Keep in mind that these are unsigned binaries.
"},{"location":"getting-started/installing/from-test-release/#download","title":"Download","text":"Download experimental compiled firmware or the Android app apk from our test (beta) repository.
"},{"location":"getting-started/installing/from-test-release/#android","title":"Android","text":"The Krux Android app is designed for learning about Krux and Bitcoin air-gapped transactions. Due to the numerous potential vulnerabilities inherent in smartphones, such as the lack of control over the operating system, libraries, and hardware peripherals, the Krux app should NOT be used to manage wallets containing savings or important keys and mnemonics. For secure management of your keys, a dedicated device is recommended.
"},{"location":"getting-started/installing/from-test-release/#compiled-firmware-for-kendryte-k210-devices","title":"Compiled firmware for Kendryte K210 devices","text":""},{"location":"getting-started/installing/from-test-release/#m5stickv","title":"M5StickV","text":"To Flash M5StickV run the following.
"},{"location":"getting-started/installing/from-test-release/#linux","title":"Linux","text":"./ktool-linux -B goE -b 1500000 maixpy_m5stickv/kboot.kfpkg\n
"},{"location":"getting-started/installing/from-test-release/#mac","title":"Mac","text":"./ktool-mac -B goE -b 1500000 maixpy_m5stickv/kboot.kfpkg\n
"},{"location":"getting-started/installing/from-test-release/#windows","title":"Windows","text":".\\ktool-win.exe -B goE -b 1500000 maixpy_m5stickv\\kboot.kfpkg\n
"},{"location":"getting-started/installing/from-test-release/#sipeed-maix-amigo","title":"Sipeed Maix Amigo","text":"To Flash Maix Amigo run the following.
"},{"location":"getting-started/installing/from-test-release/#linux_1","title":"Linux","text":"./ktool-linux -B goE -b 1500000 maixpy_amigo/kboot.kfpkg\n
"},{"location":"getting-started/installing/from-test-release/#mac_1","title":"Mac","text":"./ktool-mac -B goE -b 1500000 maixpy_amigo/kboot.kfpkg\n
"},{"location":"getting-started/installing/from-test-release/#windows_1","title":"Windows","text":".\\ktool-win.exe -B goE -b 1500000 maixpy_amigo\\kboot.kfpkg\n
"},{"location":"getting-started/installing/from-test-release/#a-note-about-the-maix-amigo","title":"A note about the Maix Amigo","text":"Some Amigo screens have inverted X coordinates, others display colors differently. For more info see Troubleshooting.
"},{"location":"getting-started/installing/from-test-release/#sipeed-maix-bit","title":"Sipeed Maix Bit","text":"To Flash Maix Bit run the following.
"},{"location":"getting-started/installing/from-test-release/#linux_2","title":"Linux","text":"./ktool-linux -B goE -b 1500000 maixpy_bit/kboot.kfpkg\n
"},{"location":"getting-started/installing/from-test-release/#mac_2","title":"Mac","text":"./ktool-mac -B goE -b 1500000 maixpy_bit/kboot.kfpkg\n
"},{"location":"getting-started/installing/from-test-release/#windows_2","title":"Windows","text":".\\ktool-win.exe -B goE -b 1500000 maixpy_bit\\kboot.kfpkg\n
"},{"location":"getting-started/installing/from-test-release/#sipeed-maix-cube","title":"Sipeed Maix Cube","text":"To Flash Maix Cube run the following.
"},{"location":"getting-started/installing/from-test-release/#linux_3","title":"Linux","text":"./ktool-linux -B goE -b 1500000 maixpy_cube/kboot.kfpkg\n
"},{"location":"getting-started/installing/from-test-release/#mac_3","title":"Mac","text":"./ktool-mac -B goE -b 1500000 maixpy_cube/kboot.kfpkg\n
"},{"location":"getting-started/installing/from-test-release/#windows_3","title":"Windows","text":".\\ktool-win.exe -B goE -b 1500000 maixpy_cube\\kboot.kfpkg\n
"},{"location":"getting-started/installing/from-test-release/#sipeed-maix-dock","title":"Sipeed Maix Dock","text":"To Flash Maix Dock you need to pass the -B dan parameter.
"},{"location":"getting-started/installing/from-test-release/#linux_4","title":"Linux","text":"./ktool-linux -B dan -b 1500000 maixpy_dock/kboot.kfpkg\n
"},{"location":"getting-started/installing/from-test-release/#mac_4","title":"Mac","text":"./ktool-mac -B dan -b 1500000 maixpy_dock/kboot.kfpkg\n
"},{"location":"getting-started/installing/from-test-release/#windows_4","title":"Windows","text":".\\ktool-win.exe -B dan -b 1500000 maixpy_dock\\kboot.kfpkg\n
"},{"location":"getting-started/installing/from-test-release/#aimotion-yahboom-k210-module","title":"Aimotion Yahboom k210 module","text":"To Flash Yahboom k210 module you'll have to manually specify the port.
"},{"location":"getting-started/installing/from-test-release/#linux_5","title":"Linux","text":"See the correct port using ls /dev/ttyUSB*, in the example below we use /dev/ttyUSB0:
./ktool-linux -B goE -b 1500000 -p /dev/ttyUSB0 maixpy_yahboom/kboot.kfpkg\n
"},{"location":"getting-started/installing/from-test-release/#mac_5","title":"Mac","text":"See the correct port using the command line: ls /dev/cu.usbserial*, in the example below we use /dev/cu.usbserial-10:
./ktool-mac -B goE -b 1500000 -p /dev/cu.usbserial-10 maixpy_yahboom/kboot.kfpkg\n
"},{"location":"getting-started/installing/from-test-release/#windows_5","title":"Windows","text":"See the correct port at Device Manager > Ports (COM & LPT), in the example below we use COM6:
.\\ktool-win.exe -B goE -b 1500000 -p COM6 maixpy_yahboom\\kboot.kfpkg\n
"},{"location":"getting-started/installing/","title":"Installing","text":"You can install Krux in four different ways:
- From GUI application
- From pre-built official release
- From pre-built test (beta) release
- From source
"},{"location":"getting-started/installing/#requirements","title":"Requirements","text":"Please, check the parts list for the compatible devices and requirements.
After the first firmware install, you can use a microSD card if you wish to perform further airgapped updates.
"},{"location":"getting-started/installing/from-gui/debian-like/","title":"Download assets","text":" krux-installer_0.0.20-beta_amd64.debkrux-installer_0.0.20-beta_amd64.deb.sha256.txtkrux-installer_0.0.20-beta_amd64.deb.sig
"},{"location":"getting-started/installing/from-gui/debian-like/#verify-the-integrity","title":"Verify the integrity","text":"Open your terminal and type the command below:
sha256sum --check ./krux-installer_0.0.20-beta_amd64.deb.sha256.txt\n
"},{"location":"getting-started/installing/from-gui/debian-like/#verify-the-authenticity","title":"Verify the authenticity","text":"The first step is import the developer's key:
gpg --keyserver hkps://keys.openpgp.org --recv-keys B4281DDDFBBD207BFA4113138974C90299326322\n
Then, to verify yourself, run this command on your terminal:
gpg --verify ./krux-installer_0.0.20-beta_amd64.deb.sig\n
\u26a0\ufe0f TIP: If the verification was successful, you may get a message similar to: Good signature from \"qlrddev <qlrddev@gmail.com>\"
"},{"location":"getting-started/installing/from-gui/debian-like/#install","title":"Install","text":"krux-installer isn't available on Debian or Ubuntu repositories. Therefore, only the apt-get install command will not work. To install, it'll be necessary two steps:
- Install the .deb package itself:
sudo dpkg -i krux-installer_0.0.20-beta_amd64.deb\n
- Update the installed package:
sudo apt-get install -f\n
It will warn you that your system user was added to dialout group and maybe you need to reboot to activate the sudoless flash procedure.
"},{"location":"getting-started/installing/from-gui/debian-like/#after-install","title":"After install","text":"Once installed, you can proceed to firmware installation.
"},{"location":"getting-started/installing/from-gui/fedora-like/","title":"Download assets","text":" krux-installer-0.0.20_beta-1.x86_64.rpmkrux-installer-0.0.20_beta-1.x86_64.rpm.sha256.txtkrux-installer-0.0.20_beta-1.x86_64.rpm.sig
"},{"location":"getting-started/installing/from-gui/fedora-like/#verify-the-integrity","title":"Verify the integrity","text":"Open your terminal and type the command below:
sha256sum --check ./krux-installer-0.0.20_beta-1.x86_64.rpm.sha256.txt\n
"},{"location":"getting-started/installing/from-gui/fedora-like/#verify-the-authenticity","title":"Verify the authenticity","text":"The first step is import the developer's key:
gpg --keyserver hkps://keys.openpgp.org --recv-keys B4281DDDFBBD207BFA4113138974C90299326322\n
Then, to verify yourself, run this command on your terminal:
gpg --verify ./krux-installer-0.0.20_beta-1.x86_64.rpm.sig\n
\u26a0\ufe0f TIP: If the verification was successful, you may get a message similar to: Good signature from \"qlrddev <qlrddev@gmail.com>\"
"},{"location":"getting-started/installing/from-gui/fedora-like/#install","title":"Install","text":"krux-installer isn't available on Fedora or RedHat repositories. You'll need to add it manually:
"},{"location":"getting-started/installing/from-gui/fedora-like/#fedora","title":"Fedora","text":"sudo dnf install krux-installer-0.0.20_beta-1.x86_64.rpm\n
"},{"location":"getting-started/installing/from-gui/fedora-like/#other-redhat-based-distros","title":"Other RedHat based distros:","text":"sudo yum localinstall krux-installer-0.0.20_beta-1.x86_64.rpm\n
It will warn you that your system user was added to dialout group and maybe you need to reboot to activate the sudoless flash procedure.
"},{"location":"getting-started/installing/from-gui/fedora-like/#after-install","title":"After install","text":"Once installed, you can proceed to firmware installation.
"},{"location":"getting-started/installing/from-gui/","title":"From GUI application","text":"You can install Krux (both official or beta releases) onto your K210-based device using our official desktop application, KruxInstaller, available for:
\u26a0\ufe0f WARNING: Krux-Installer latest version is in it's alpha version. Maybe you can experience bugs or don't like something. If it is the case, please submit a issue.
- Windows
- MacOS Intel
- MacOS M1/M2/M3
- Debian and like
- Fedora and like
- Other linux distros
"},{"location":"getting-started/installing/from-gui/macos-arm64/","title":"Download assets","text":" krux-installer_0.0.20-beta_arm64.dmgkrux-installer_0.0.20-beta_arm64.dmg.sha256.txtkrux-installer_0.0.20-beta_arm64.dmg.sig
"},{"location":"getting-started/installing/from-gui/macos-arm64/#verify-the-integrity","title":"Verify the integrity","text":"Open your terminal and type the command below:
sha256sum --check ./krux-installer_0.0.20-beta_arm64.dmg.sha256.txt\n
"},{"location":"getting-started/installing/from-gui/macos-arm64/#verify-the-authenticity","title":"Verify the authenticity","text":"The first step is import the developer's key:
gpg --keyserver hkps://keys.openpgp.org --recv-keys B4281DDDFBBD207BFA4113138974C90299326322\n
Then, to verify yourself, run this command on your terminal:
gpg --verify ./krux-installer_0.0.20-beta_arm64.dmg.sig\n
\u26a0\ufe0f TIP: If the verification was successful, you may get a message similar to: Good signature from \"qlrddev <qlrddev@gmail.com>\"
"},{"location":"getting-started/installing/from-gui/macos-arm64/#install","title":"Install","text":"Open the dmg file and a new volume will be presented; drag'n'drop the krux-installer to the Applications folder:
Before run, you'll need to remove the quarantine flag from application. This occurs because we don't added the Apple's code signing and notarization.
To fix this, open your terminal and execute the following command:
xattr -d com.apple.quarantine -r /Applications/krux-installer.app\n
\ud83d\udee1\ufe0f TIP: If you followed the steps presented in authenticity section, you already have the assurance that the software is from a verified and genuine software publisher. This will also help establish a chain of trust when you perform the firmware verification step before flashing.
"},{"location":"getting-started/installing/from-gui/macos-arm64/#after-install","title":"After install","text":"Once installed, you can proceed to firmware installation.
"},{"location":"getting-started/installing/from-gui/macos-intel/","title":"Download assets","text":" krux-installer_0.0.20-beta_x86_64.dmgkrux-installer_0.0.20-beta_x86_64.dmg.sha256.txtkrux-installer_0.0.20-beta_x86_64.dmg.sig
"},{"location":"getting-started/installing/from-gui/macos-intel/#verify-the-integrity","title":"Verify the integrity","text":"Open your terminal and type the command below:
sha256sum --check ./krux-installer_0.0.20-beta_x86_64.dmg.sha256.txt\n
"},{"location":"getting-started/installing/from-gui/macos-intel/#verify-the-authenticity","title":"Verify the authenticity","text":"The first step is import the developer's key:
gpg --keyserver hkps://keys.openpgp.org --recv-keys B4281DDDFBBD207BFA4113138974C90299326322\n
Then, to verify yourself, run this command on your terminal:
gpg --verify ./krux-installer_0.0.20-beta_x86_64.dmg.sig\n
\u26a0\ufe0f TIP: If the verification was successful, you may get a message similar to: Good signature from \"qlrddev <qlrddev@gmail.com>\"
"},{"location":"getting-started/installing/from-gui/macos-intel/#install","title":"Install","text":"Open the dmg file and a new volume will be presented; drag'n'drop the krux-installer to the Applications folder:
Before run, you'll need to remove the quarantine flag from application. This occurs because we don't added the Apple's code signing and notarization.
To fix this, open your terminal and execute the following command:
xattr -d com.apple.quarantine -r /Applications/krux-installer.app\n
\ud83d\udee1\ufe0f TIP: If you followed the steps presented in authenticity section, you already have the assurance that the software is from a verified and genuine software publisher. This will also help establish a chain of trust when you perform the firmware verification step before flashing.
"},{"location":"getting-started/installing/from-gui/macos-intel/#after-install","title":"After install","text":"Once installed, you can proceed to firmware installation.
"},{"location":"getting-started/installing/from-gui/other-linux-distro/","title":"Download assets","text":"For this installation, we'll use the .deb sources:
krux-installer_0.0.20-beta_amd64.debkrux-installer_0.0.20-beta_amd64.deb.sha256.txtkrux-installer_0.0.20-beta_amd64.deb.sig
"},{"location":"getting-started/installing/from-gui/other-linux-distro/#verify-the-integrity","title":"Verify the integrity","text":"Open your terminal and type the command below:
sha256sum --check ./krux-installer_0.0.20-beta_amd64.deb.sha256.txt\n
"},{"location":"getting-started/installing/from-gui/other-linux-distro/#verify-the-authenticity","title":"Verify the authenticity","text":"The first step is import the developer's key:
gpg --keyserver hkps://keys.openpgp.org --recv-keys B4281DDDFBBD207BFA4113138974C90299326322\n
Then, to verify yourself, run this command on your terminal:
gpg --verify ./krux-installer_0.0.20-beta_amd64.deb.sig\n
\u26a0\ufe0f TIP: If the verification was successful, you may get a message similar to: Good signature from \"qlrddev <qlrddev@gmail.com>\"
"},{"location":"getting-started/installing/from-gui/other-linux-distro/#install","title":"Install","text":"This step it's not really an installation. At least it will make the program's binary available somewhere on your computer; it can be useful if you want to develop a package for your distro.
To do this you'll need two tools:
ar;bsdtar.
"},{"location":"getting-started/installing/from-gui/other-linux-distro/#extract-contents","title":"Extract contents","text":" - Extract the
.deb contents:
ar xv krux-installer_0.0.20-beta_amd64.deb\n
- Extract the
data.tar.zst contents:
bsdtar -xvf data.tar.zst\n
The binary will be located at ./usr/local/bin/krux-installer.
"},{"location":"getting-started/installing/from-gui/usage/","title":"Usage","text":"This guide will walk through the basic use of the installer. At startup, it can differ in some operational systems. In the rest, the procedures will be similar.
"},{"location":"getting-started/installing/from-gui/usage/#main-menu","title":"Main Menu","text":"When executing the Krux Installer, you will be presented with a menu of 4 enabled buttons and two disabled buttons:
-
Enabled buttons:
-
Version: select a firmware version;
-
Device: select a supported device for the selected version;
-
Settings: change some application settings;
-
About: just show some information about the application.
-
Disabled buttons:
-
Flash firmware: This button will start the flash firmware procedure;
- It will be enabled when user select both version and device;
-
Wipe device: This button will start the wipe device procedure.
- It will be enabled when user select the device.
"},{"location":"getting-started/installing/from-gui/usage/#select-version","title":"Select version","text":"At startup, the application will setup it to the latest one, krux-v24.11.1. But you can select even a beta release or older versions:
-
Click in the button that show the text Version: krux-v24.11.1;
-
To select a beta release, click on button that show the text odudex/krux_binaries;
-
To select an older version, click on button that show the text Old versions;
"},{"location":"getting-started/installing/from-gui/usage/#beta-release","title":"Beta release","text":"After choose odudex/krux_binaries, you'll be warned with a message:
"},{"location":"getting-started/installing/from-gui/usage/#older-versions","title":"Older versions","text":" - We put this option in case you have any interest in the history of firmware development;
-
Each version supports one device or the other;
-
For example: the version v22.03.0 has support only for m5stickv.
"},{"location":"getting-started/installing/from-gui/usage/#settings","title":"Settings","text":"krux-Installer will give to you some freedom of choices for:
-
Krux-Installer settings;
-
General settings;
"},{"location":"getting-started/installing/from-gui/usage/#krux-installer-specific-settings","title":"krux-installer specific settings","text":"Here you can configure some of the specifics of krux firmare, like:
-
Where you'll save downloaded assets;
-
The flash baudrate
-
The natural language that will be used in the application (system locale).
"},{"location":"getting-started/installing/from-gui/usage/#flash-baudrate","title":"Flash baudrate","text":"The flash baudrate is how quickly the firmware will be written to the device.
But not any value can be used. The valid ones are: 9600, 19200, 28800, 38400, 57600, 76800, 115200, 230400, 460800, 576000, 921600, 1500000.
"},{"location":"getting-started/installing/from-gui/usage/#system-locale","title":"System locale","text":"At startup, krux-installer recognize the locale used in your system. If your language isn't supported, it will defaults to en_US.
"},{"location":"getting-started/installing/from-gui/usage/#select-device","title":"Select Device","text":"Everytime you select a new version, you'll see that the device button will be reseted to Device: select a new one state. Once a version is selected you can choose a device on which the firmware will be written.
First, select the device we want to flash. After that the menu will shown three items:
Note that some devices may be disabled if they are not supported by the chosen version
"},{"location":"getting-started/installing/from-gui/usage/#flash-device","title":"Flash device","text":"Once you choose the device and version, it enables the \"flash device\" button. It will start an automatic process of:
-
For official firmware's releases:
-
Warning;
-
Download;
-
Verification:
-
Unzip the correct firmware;
-
Flash:
-
The flash itself via USB;
-
Air-gapped update via SD card;
-
For beta releases:
-
Download asset;
-
The flash itself;
"},{"location":"getting-started/installing/from-gui/usage/#warning","title":"Warning","text":"If you already downloaded assets, you'll be warned about this and will be offered the possibility to download again or continue without downloading:
"},{"location":"getting-started/installing/from-gui/usage/#download","title":"Download","text":"Krux-installer download can download four assets for official releases or one for beta releases.
"},{"location":"getting-started/installing/from-gui/usage/#official-releases","title":"Official releases","text":" -
A zip file containing all firmwares for each device;
-
Download a zip.sha256.txt file containing a zip's digital fingerprint;
-
Download a zip.sig file containing a zip's digital signature;
-
Download the selfcustody.pem file containing a public key certificate, signed by odudex;
"},{"location":"getting-started/installing/from-gui/usage/#beta-releases","title":"Beta releases","text":" - A
kfpkg file containing the specific firmware for choosen device;
"},{"location":"getting-started/installing/from-gui/usage/#verification","title":"Verification","text":" -
Integrity verification compares the computed hash of zip against thei provided zip.sha256.txt;
-
Authenticity verification check if the zip file was really signed by odudex, using the zip.sig and selfcustody.pem.
"},{"location":"getting-started/installing/from-gui/usage/#unzip","title":"Unzip","text":"Now you will be able to select if you do a flash process or need to do an airgap process:
Click on Flash with to install via USB or Air-gapped update with to perform upgrades via a SD card.
"},{"location":"getting-started/installing/from-gui/usage/#flash-with","title":"Flash with","text":"When flash starts, it will warn you to not disconnect the device until the process is complete. You'll be able to see the flash progress:
\u26a0\ufe0f TIP: You must connect and turn on your device before click extract and flashing starts!.
As well a done icon:
\u26a0\ufe0f TIP: When the flashing process completes, you should see the Krux logo:
If it doesn't, try turning your device off and on by holding down the power button for six seconds.
Congrats, you're now running Krux!
"},{"location":"getting-started/installing/from-gui/usage/#air-gapped-update-with","title":"Air-gapped update with","text":"Once you've installed the initial firmware on your device via USB, you can perform upgrades via SD card to keep the device airgapped.
\u26a0\ufe0f Click on \"Air-gapped update with\"
Once the firmware.bin and firmware.bin.sig are extracted, you'll see a warning message.
Insert the SD card and click 'Proceed' to allow the installer to detect it.
\u26a0\ufe0f If a single SD card is inserted, the screen will display a large button. If multiple removable drives are detected, both SD cards and other drives will be listed.
Select the desired removable drive to copy both firmware.bin and firmware.bin.sig. The first is the Krux firmware, and the second is a signature file that verifies the firmware\u2019s integrity and authenticity.
Now you can compare the firmware's hash computed by installer with the firmware's hash computed by the device.
\u26a0\ufe0f Once files are copied, remove the SD card from computer, connect to device and compare the hashes
"},{"location":"getting-started/installing/from-gui/usage/#wipe-device","title":"Wipe device","text":"This is two step process:
-
Warning
-
Wipe
"},{"location":"getting-started/installing/from-gui/usage/#warning_1","title":"Warning","text":"Before the wipe starts, it will show to you a message:
\u26a0\ufe0f TIP: It's useful when your device is not working or for security reasons. To use Krux again, you'll need to re-flash the firmware.
"},{"location":"getting-started/installing/from-gui/usage/#wipe","title":"Wipe","text":"Once the process starts, the screen will appear frozen and a spinner will keep moving. When it's done, you can scroll down you will see a check icon.
\u26a0\ufe0f TIP: Do not unplug or poweroff your device or computer. Wait until the process finishes.
"},{"location":"getting-started/installing/from-gui/usage/#tips-after-install","title":"Tips after install","text":""},{"location":"getting-started/installing/from-gui/usage/#multilingual-support","title":"Multilingual support","text":"Prefer a different language? Krux has support for multiple languages. Once at the start screen, go to Settings, followed by Locale, and select the locale you wish to use.
"},{"location":"getting-started/installing/from-gui/usage/#upgrade-via-microsd-card","title":"Upgrade via microSD card","text":"Once you've installed the initial firmware on your device via USB, you can either continue updating the device by flashing or you can perform upgrades via microSD card to keep the device airgapped.
"},{"location":"getting-started/installing/from-gui/windows/","title":"Download assets","text":" krux-installer_v0.0.20-beta.Setup.exekrux-installer_v0.0.20-beta.Setup.exe.sha256.txtkrux-installer_v0.0.20-beta.Setup.exe.sig
"},{"location":"getting-started/installing/from-gui/windows/#verify-the-integrity","title":"Verify the integrity","text":"Open your terminal and type the command below:
(Get-FileHash '.\\krux-installer_v0.0.20-beta.Setup.exe').Hash.ToLower() -eq (Get-Content '.\\krux-installer_v0.0.20-beta.Setup.exe.sha256.txt').split(\" \")[0]\n
The result in prompt should be True.
Alternatively, you can check more closely in two steps:
- Compute the binary sha256sum hash:
# Option 1: Compute in default way\nGet-FileHash '.\\krux-installer_v0.0.20-beta.Setup.exe'\n\n# Option 2: Compute and filter the necessary information\n(Get-FileHash '.\\krux-installer_v0.0.20-beta.Setup.exe').Hash\n\n# Option 3: Compute, filter and process the Hash for lowercase letters\n(Get-FileHash '.\\krux-installer_v0.0.20-beta.Setup.exe').Hash.ToLower()\n
- Compare with provided hash:
# Option 1: Get content \nGet-Content '.\\krux-installer_v0.0.20-beta.Setup.exe.sha256.txt'\n\n# Option 2: Get content and filter the necessary information\n(Get-Content '.\\krux-installer_v0.0.20-beta.Setup.exe.sha256.txt').split(\" \")[0]\n
"},{"location":"getting-started/installing/from-gui/windows/#verify-the-authenticity","title":"Verify the authenticity","text":" - You'll need have GPG installed;
- We recommend installing GPG4Win.
The first step is import the developer's key:
gpg --keyserver hkps://keys.openpgp.org --recv-keys B4281DDDFBBD207BFA4113138974C90299326322\n
Then, to verify yourself, run this command on your terminal:
gpg --verify ./krux-installer_v0.0.20-beta.Setup.exe.sig\n
\u26a0\ufe0f TIP: If the verification was successful, you may get a message similar to: Good signature from \"qlrddev <qlrddev@gmail.com>\"
"},{"location":"getting-started/installing/from-gui/windows/#install","title":"Install","text":"Execute the krux-installer_v0.0.20-beta.Setup.exe. You'll be faced with a blue window saying \"Windows protected your PC\". This occurs because we don't have a code signing certificate:
\ud83d\udee1\ufe0f TIP: If you followed the steps presented in authenticity section, you already have the assurance that the software is from a verified and genuine software publisher. This will also help establish a chain of trust when you perform the firmware verification step before flashing.
Follow the installer's instructions to complete the installation. At the end, click on \"Create desktop icon\":
"},{"location":"getting-started/installing/from-gui/windows/#after-install","title":"After install","text":"Once installed, you can proceed to firmware installation.
"},{"location":"getting-started/templates/templates/","title":"Templates","text":""},{"location":"getting-started/templates/templates/#templates","title":"Templates","text":"Here we offer a few templates to transcribe QR codes, TinySeed or Binary Grid backups.
"},{"location":"getting-started/templates/templates/#qr-code-templates","title":"QR Code Templates","text":"Print the templates in standard, wax or slide paper, make sure the scale is set to 1:1 in printer setup. You can manually copy compact SeedQR codes or place a proper sized template over the device screen. Protect the template backside with a transparent tape so you won't bleed ink through the paper to your device's screen. Then, using a marker, paint the QR code.
Transcribe Templates - pdf
Transcribe Templates - svg
"},{"location":"getting-started/templates/templates/#tinyseed-templates","title":"TinySeed Templates","text":"TinySeed background of blank templates to be manually filled.
"},{"location":"getting-started/templates/templates/#binary-grid-templates","title":"Binary Grid Templates","text":"Binary Grid labeled and and \"stealth\" clean templates
Binary Grid svg source
Binary Grid Clean svg source
"},{"location":"getting-started/templates/templates/#edit-templates","title":"Edit Templates","text":"To edit the source file (.svg) it is recommended to use Inkscape and set it to use mm unit. \"Unscaled models\" from QR code templates have the 21x21 or 25x25mm size for 12 or 24 respectively, this way making them easier to edit.
"},{"location":"getting-started/usage/generating-a-mnemonic/","title":"Generating a Mnemonic","text":"Krux supports creating 12 and 24-word BIP-39 mnemonic seed phrases. Since generating true entropy is challenging, especially with an embedded device, we recommend outsourcing entropy generation using dice rolls. However, it is also possible to randomly pick words (e.g., SeedPicker) or use the camera as a source of entropy to quickly create a mnemonic.
At the start screen, after selecting New Mnemonic, you will be taken to a second menu where you can choose to create a mnemonic via the camera, words, rolls of a D6 (standard six-sided die), or a D20 (20-sided die).
"},{"location":"getting-started/usage/generating-a-mnemonic/#camera","title":"Camera","text":"(Experimental!) Choose between 12, 24 words or double mnemonic, then take a random picture and Krux will generate a mnemonic from the hash of the image bytes.
"},{"location":"getting-started/usage/generating-a-mnemonic/#image-entropy-quality-estimation","title":"Image Entropy Quality Estimation","text":"During image capture, entropy quality estimation is displayed to assist you in obtaining a high-quality image source for your key. After a snapshot is taken, Shannon's entropy and pixel deviation indices are presented. Minimum thresholds are established to prevent the use of poor-quality images with low entropy for key generation. It's important to note that these values serve as indicators or estimations of entropy quality, but they are not absolute entropy values in a cryptographic context.
"},{"location":"getting-started/usage/generating-a-mnemonic/#double-mnemonic","title":"Double mnemonic","text":"It is the combination of two 12-word mnemonics that also forms a valid 24-word BIP-39 mnemonic. This is achieved by using the first 16 bytes (128 bits) of the image's entropy to generate the first 12-word, then using the next 16 bytes to generate the second 12-word and checking if these two 12-word together forms a valid 24-word, if not, we iterate over the second 12-word incrementing its entropy bytes until the two 12-word forms a valid 24-word.
Some might say that the name double mnemonic is incorrect because we end up with two 12-word plus a 24-word mnemonic (12 + 12 + 24), so it's a triple mnemonic! But we only use entropy for the two 12-word ones, hence the name double mnemonic. Also, this name has already been used in this double mnemonic generator since July 2023.
Some may wonder what is the use of this, it may be useful to some plausible deniability or even a way to improve your OPSEC.
"},{"location":"getting-started/usage/generating-a-mnemonic/#words","title":"Words","text":"Print the BIP39 word list in 3D or on paper, then cut out the words and place them in a bucket. Manually draw 11 or 23 words from the bucket. For the final word, Krux will assist you in picking a valid 12th or 24th word by adjusting its smart keypad to only allow typing words with a valid checksum. Alternatively, you can leave it empty, and Krux will select a final, valid checksum word for you.
"},{"location":"getting-started/usage/generating-a-mnemonic/#dice-rolls","title":"Dice Rolls","text":""},{"location":"getting-started/usage/generating-a-mnemonic/#via-d6","title":"Via D6","text":"Choose between 12 or 24 words. The entropy in a single roll of a D6 is 2.585 bits ( log2(6) ); therefore a minimum of a 50 rolls will be required for 128 bits of entropy, enough to generate a 12-word mnemonic. For 24-word, or an entropy of 256 bits, a minimum of 99 rolls will be required.
"},{"location":"getting-started/usage/generating-a-mnemonic/#via-d20","title":"Via D20","text":"Since a D20 has more possible outcomes, the entropy is increased per roll to 4.322 bits ( log2(20) ). This means that only 30 rolls are necessary to create a 12-word mnemonic and 60 rolls for a 24-word mnemonic.
"},{"location":"getting-started/usage/generating-a-mnemonic/#dice-rolls-entropy-quality-estimation","title":"Dice Rolls Entropy Quality Estimation","text":"When you input your dice rolls, you'll see two progress bars filling up. The top progress bar shows how many rolls you've entered compared to the minimum number needed. The bottom progress bar shows the real-time calculated Shannon's entropy compared to the required minimum (128 bits for 12 words and 256 bits for 24 words). When the Shannon's entropy estimation reaches the recommended level, the progress bar will be full, and its frame will change color. If you've met the minimum number of rolls but the entropy estimation is still below the recommended level, a warning will appear, suggesting you add more rolls to increase entropy. Note: Similar to image entropy quality estimation, dice rolls Shannon's entropy serves as an indicator and should not be considered an absolute measure of cryptographic entropy.
Learn more about Krux Entropy Quality Estimation.
"},{"location":"getting-started/usage/generating-a-mnemonic/#stats-for-nerds","title":"Stats for Nerds","text":"A low Shannon's entropy value could suggest that your dice are biased or that there's a problem with how you're gathering entropy. To investigate further, examine the \"Stats for Nerds\" section to check the distribution of your rolls and look for any abnormalities.
"},{"location":"getting-started/usage/generating-a-mnemonic/#editing-a-new-mnemonic-optional","title":"Editing a New Mnemonic - Optional","text":"After entering dice rolls, random words, or captured entropy through the camera, you can manually add custom entropy by editing some of the words. Edited words will be highlighted, and the final word will automatically update to ensure a valid checksum. However, proceed with caution, modifying words can negatively impact the natural entropy previously captured.
"},{"location":"getting-started/usage/generating-a-mnemonic/#how-entropy-capture-works","title":"How Entropy Capture Works","text":"For dice rolls, Krux keeps track of every roll you enter and displays the cumulative string of outcomes after each roll.
When you have entered your final roll, Krux will hash this string using SHA256 and output the resulting hash to the screen so that you can verify it for yourself.
In case a camera snapshot is used as a source, the image bytes, which contain pixels data in RGB565 format, will be hashed in the same way as the dice rolls.
Krux then takes this hash, runs unhexlify on it to encode it as bytes, and deterministically converts it into a mnemonic according to the BIP-39 Reference Implementation.
Note: For 12-word mnemonics, only the first half of the SHA256 hash is used (128 bits), while 24-word mnemonics use the full hash (256 bits).
"},{"location":"getting-started/usage/generating-a-mnemonic/#how-to-verify","title":"How to Verify","text":"Don't trust, verify. We encourage you not to trust any claim you cannot verify yourself. Therefore, there are wallets that use compatible algorithms to calculate the entropy derived from dice rolls. You can use the SeedSigner or Coldcard hardware wallets, or even the Bitcoiner Guide website, they share the same logic that Krux uses and will give the same mnemonic for the dice roll method.
"},{"location":"getting-started/usage/loading-a-mnemonic/","title":"Loading a Mnemonic","text":"Once you have either a 12 or 24-word BIP-39 mnemonic, choose Load Mnemonic on Krux's start menu (aka login menu), and you will be presented with several input methods:
"},{"location":"getting-started/usage/loading-a-mnemonic/#input-methods","title":"Input Methods","text":""},{"location":"getting-started/usage/loading-a-mnemonic/#via-camera","title":"Via Camera","text":"You can choose to use the camera to scan a QR code, Tiny Seed, OneKey KeyTag or a Binary Grid.
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. Some cameras (OV7740, OV2640 and GC2145) have an anti-glare mode to better capture images from high brightness screens or with incident light, they are present on M5StickV, Amigo, Cube and Yahboom. To enable/disable the anti-glare mode on a supported device just press the PAGE button while scanning.
"},{"location":"getting-started/usage/loading-a-mnemonic/#qr-code","title":"QR Code","text":"It's unpleasant having to manually enter 12 or 24 words every time you want to use Krux. To remedy this you can instead use the device's camera to read a QR code containing the words. Krux will decode QR codes of four types:
- Plain text QR: The mnemonic words encoded as text, with words separated by spaces.
- SeedQR: Basically, it is the mnemonic words of the respective BIP-39 numbers concatenated, encoded as text.
- Compact SeedQR: Basically, it is the mnemonic words bits concatenated as bytes.
- Encrypted Mnemonic: A specification created by Krux that encrypts the mnemonic words bits and adds some information about the encryption used.
After opening a wallet via one of the methods available you can use Krux to backup the mnemonic as QR code, transcribe them to paper or metal using the transcription helpers or attach a thermal printer to your Krux and print out the mnemonic as QR. Check out the printing section for more information. You can also use an offline QR code generator for this (ideally on an airgapped device).
"},{"location":"getting-started/usage/loading-a-mnemonic/#tiny-seed-onekey-keytag-or-binary-grid","title":"Tiny Seed, OneKey KeyTag or Binary Grid","text":"Tiny Seed, Onekey KeyTag and others directly encode a seed as binary, allowing for a very compact mnemonic storage. Krux devices have machine vision capabilities that allow users to scan these metal plates and instantly load mnemonics engraved on them (this feature is not available in Krux Android app).
To properly scan, place the backup plate over a black background and paint the punched bits black to increase contrast. You can also scan the thermally printed version, or a filled template. You can find some examples of mnemonics encoded here. Alternatively, you can find templates to scan or print here.
"},{"location":"getting-started/usage/loading-a-mnemonic/#via-manual-input","title":"Via Manual Input","text":"Manually type Words, Word Numbers, Tiny Seed (toggle the bits or punches) or Stackbit 1248.
"},{"location":"getting-started/usage/loading-a-mnemonic/#words","title":"Words","text":"Enter each word of your BIP-39 mnemonic one at a time. Krux will disable impossible-to-reach letters as you type and will attempt to autocomplete your words to speed up the process.
"},{"location":"getting-started/usage/loading-a-mnemonic/#word-numbers","title":"Word Numbers","text":""},{"location":"getting-started/usage/loading-a-mnemonic/#decimal","title":"Decimal","text":"Enter each word of your BIP-39 mnemonic as a number (1-2048) one at a time. You can use this list for reference.
"},{"location":"getting-started/usage/loading-a-mnemonic/#hexadecimal-and-octal","title":"Hexadecimal and Octal","text":"You can also enter your BIP-39 mnemonic word's numbers (1-2048) in hexadecimal format, with values ranging from 0x1 to 0x800, or in octal format, with values ranging from 01 to 04000. This is useful with some metal plate backups that uses those formats.
"},{"location":"getting-started/usage/loading-a-mnemonic/#tiny-seed-bits","title":"Tiny Seed (Bits)","text":"Enter the BIP-39 mnemonic word's numbers (1-2048) in binary format, toggling necessary bits to recreate each of the word's respective number. The last word will have checksum bits dynamically toggled while you fill the bits.
"},{"location":"getting-started/usage/loading-a-mnemonic/#stackbit-1248","title":"Stackbit 1248","text":"Enter the BIP-39 mnemonic word's numbers (1-2048) using the Stackbit 1248 metal plate backup method, where each of the four digits of the word's number is a sum of the numbers marked (punched) 1, 2, 4, or 8. For example, to enter the word \"oyster\", number 1268, you must punch (1)(2)(2,4)(8).
"},{"location":"getting-started/usage/loading-a-mnemonic/#from-storage","title":"From Storage","text":"You can retrieve mnemonics previously stored on device's internal flash or external (SD card). All stored mnemonics are encrypted, to load them you'll have to enter the same key you used to encrypt them.
"},{"location":"getting-started/usage/loading-a-mnemonic/#wallet-loading","title":"Wallet Loading","text":""},{"location":"getting-started/usage/loading-a-mnemonic/#confirm-mnemonic-words","title":"Confirm Mnemonic Words","text":"Once you have entered your mnemonic, you will be presented with the full list of words to confirm.
If you see an asterisk (*) in the header, it means this is a double mnemonic.
"},{"location":"getting-started/usage/loading-a-mnemonic/#edit-mnemonic-optional","title":"Edit Mnemonic - Optional","text":"If you make a mistake while loading a mnemonic, you can easily edit it. Simply touch or navigate to the word you want to change and replace it. Edited words will be highlighted in a different color. If the final word contains an invalid checksum, it will appear in red. If your checksum word is red, please review your mnemonic carefully, as there may be an error.
"},{"location":"getting-started/usage/loading-a-mnemonic/#confirm-wallet-attributes","title":"Confirm Wallet Attributes","text":"You will be presented with a screen containing wallet attributes, if they are as expected just press Load Wallet and you'll be ready to use your loaded key.
"},{"location":"getting-started/usage/loading-a-mnemonic/#fingerprint","title":"Fingerprint","text":" -
73c5da0a: The BIP-32 master wallet's fingerprint, if you have it noted down, will help you make sure you entered the correct mnemonic and passphrase (optional) and will load the expected wallet.
"},{"location":"getting-started/usage/loading-a-mnemonic/#network","title":"Network","text":" Mainnet: Check if you are loading a Testnet or Mainnet wallet.
"},{"location":"getting-started/usage/loading-a-mnemonic/#single-multisig","title":"Single / Multisig","text":" Single-sig: Check if you are loading a Single-sig or Multisig wallet.
"},{"location":"getting-started/usage/loading-a-mnemonic/#derivation-path","title":"Derivation Path","text":" m/84'/0'/0': The derivation path is a sequence of numbers, or \"nodes\", that define the script type, network, and account index of your wallet. - Script Type
84': The first number defines the script type. The default is 84', corresponding to a Native Segwit wallet. Other values include: 44' for Legacy49' for Nested Segwit86' for Taproot48' for Multisig
- Network
0': The second number defines the network: 0' for Mainnet1' for Testnet
- Account Index
0': The third number is the account index, with 0' being the default. - Additional: For multisig wallets, a fourth node with the value
2' is added to the derivation path.
"},{"location":"getting-started/usage/loading-a-mnemonic/#passphrase","title":"Passphrase","text":" No Passphrase: Informs if the wallet has a loaded passphrase.
"},{"location":"getting-started/usage/loading-a-mnemonic/#customize","title":"Customize","text":"You can change any of the attributes before and after loading a wallet. It is also possible to change default settings for Network and Single/Multisig on settings.
"},{"location":"getting-started/usage/loading-a-mnemonic/#passphrase_1","title":"Passphrase","text":"You can type or scan a BIP-39 passphrase. When typing, swipe left or right to change keypads if your device has a touchscreen. You can also hold the button PAGE or PAGE_PREV when navigating among letters while typing text to fast forward or backward. For scanning, you can also create a QR code from your offline passphrase using the create QR code tool.
"},{"location":"getting-started/usage/loading-a-mnemonic/#customize_1","title":"Customize","text":"Press Customize to open a menu where you can change the Network, Single/Multisig, Script Type and Account.
Now, onto the main menu...
"},{"location":"getting-started/usage/navigating-the-main-menu/","title":"Navigating the Main Menu","text":"After entering your mnemonic, and loading a wallet, you will find yourself on Krux's main menu. Below is a breakdown of the entries available:
"},{"location":"getting-started/usage/navigating-the-main-menu/#backup-mnemonic","title":"Backup Mnemonic","text":"This will open a new submenu with different types of backups. QR Code based, Encrypted and Other Formats
If you set a printer, it will also give the option to print them!
"},{"location":"getting-started/usage/navigating-the-main-menu/#qr-code","title":"QR Code","text":" - Plaintext QR
Generate a QR containing the mnemonic words as regular text, where words are separated by spaces. Any QR code can be printed if a thermal printer driver is set.
- Compact SeedQR
A QR code is created from a binary representation of mnemonic words. Format created by SeedSigner, more info here.
- SeedQR
Words are converted to their BIP-39 numeric indexes, those numbers are then concatenated as a string and finally converted to a QR code. Format created by SeedSigner, more info here.
- Encrypted QR Code
This option converts the encrypted mnemonic into a QR code. Enter an encryption key and, optionally, a custom ID. When you scan this QR code through \"Load Mnemonic\" -> \"Via Camera\" -> \"QR Code,\" you will be prompted to enter the decryption key to load the mnemonic stored in it. Like any QR code, it can be printed if a thermal printer driver is set up.
"},{"location":"getting-started/usage/navigating-the-main-menu/#encrypted","title":"Encrypted","text":"This feature allows you to back up your mnemonic by encrypting it and storing it on the device's flash memory, an SD card, or in QR code format. You can customize the encryption method and parameters in the settings.
For convenience, you may choose to store the encrypted mnemonic on flash memory or an SD card, but it is advisable not to rely solely on these methods for backup. Flash storage can degrade over time and may be subject to permanent damage, resulting in the loss of stored information.
When using any of the encryption methods, you will be prompted to enter an encryption key. This key can be provided in text or QR code format. Additionally, you have the option to set a custom ID for easier management of your mnemonics. If a custom key is not specified, the device's current loaded wallet fingerprint will be used as the ID.
See this page to find out more about: Krux Mnemonics Encryption.
- Store on Flash
This option stores the encrypted mnemonic in the device's flash memory. You can decrypt and load it later through the \"Load Mnemonic\" -> \"From Storage\" option.
- Store on SD Card
If an SD card is available, this option stores the encrypted mnemonic on it. You can decrypt and load it later through the \"Load Mnemonic\" -> \"From Storage\" option.
- Encrypted QR Code It's another path for the same functionality present on QR Code backups, described above.
"},{"location":"getting-started/usage/navigating-the-main-menu/#other-formats","title":"Other Formats","text":" - Words
Display the BIP-39 mnemonic words as text so you can write them down.
- Numbers
Display the BIP-39 mnemonic word numbers (1-2048) in decimal, hex, or octal format.
- Stackbit 1248
This metal backup format represents the BIP-39 mnemonic word's numbers (1-2048). Each of the four digits is converted to a sum of 1, 2, 4 or 8. This option does not print even if a printer driver is set.
- Tiny Seed
This metal backup format represents the BIP-39 mnemonic word's numbers (1-2048) in binary format on a metal plate, where the 1's are marked (punched) and the 0's are left intact. You can also print your mnemonic in this format if a thermal printer driver is set.
"},{"location":"getting-started/usage/navigating-the-main-menu/#extended-public-key","title":"Extended Public Key","text":"A menu will be presented with options to display your master extended public key (xpub) as text and as a QR code. Depending on the script type or whether a single-sig or multisig wallet was loaded, the options shown will be xpub, ypub, zpub, or Zpub. When displayed as text, the extended public key can be stored on an SD card if available. If you choose to export a QR code, you can not only scan it but also save it as an image on an SD card or print it if a thermal printer is attached.
All QR codes will contain key origin information in key expressions. If your coordinator cannot parse this information, it will not be capable of importing the wallet's fingerprint. As a result, Krux will not perform important verifications when signing transactions created by it unless you manually add the fingerprint so that it can be used to create Krux-compatible PSBTs.
Always prefer to import extended public keys directly from Krux when setting up a coordinator instead of copying it (or parts of it) from other sources.
"},{"location":"getting-started/usage/navigating-the-main-menu/#wallet","title":"Wallet","text":"Here you can load view and save wallet descriptors, add or change passphrases, customize wallet's attributes, derive BIP85 mnemonics and passwords.
"},{"location":"getting-started/usage/navigating-the-main-menu/#wallet-descriptor","title":"Wallet Descriptor","text":"A Bitcoin Wallet Output Script Descriptor defines a set of addresses in a wallet. It includes the following information: - Script Type: Specifies the type of script (e.g., P2PKH, P2SH, P2WPKH). - Origin Info: Defines the master fingerprint and derivation path used to derive keys. - Extended Public Keys: usually represented as an xpub, but could be ypub, zpub, etc.
Output descriptors standardize how wallets generate addresses, ensuring compatibility and security. They help wallets and other software understand how to derive and verify the addresses used in transactions.
For multisig wallets, it is essential to load a descriptor to check addresses and perform full PSBT verification. For single-sig wallets, loading a descriptor is optional and serves as a redundancy check of the coordinator's wallet attributes.
When you select the \"Wallet Descriptor\" option for the first time, you will be prompted to load a wallet descriptor via QR code or SD card. After loading, a preview of the wallet attributes will be displayed for confirmation.
If you access the \"Wallet Descriptor\" option again after loading your wallet, you will see the wallet's name, fingerprints, and the abbreviated XPUBs of all cosigners, along with a QR code containing the exact data that was initially loaded. If an SD card is inserted, you can save the descriptor to it for later use without the assistance of a coordinator. Additionally, if you have a thermal printer attached, you can print this QR code.
Krux also allows you to verify a descriptor's receive and change addresses without the need to load private keys. Simply turn on your Krux, access \"Tools\" -> \"Descriptor Addresses,\" and load a trusted descriptor from a QR code or SD card.
Please note that if you customize the wallet parameters or restart the device, the descriptor will be unloaded, and you may need to load it again to check addresses.
"},{"location":"getting-started/usage/navigating-the-main-menu/#passphrase","title":"Passphrase","text":"If you forgot to load a passphrase while loading your wallet, or if you use multiple passphrases with the same mnemonic, you can add, replace, or remove a passphrase here. Simply choose between typing or scanning it.
To remove a passphrase, select \"Type BIP39 Passphrase,\" leave the field blank, and press \"Go.\"
Don't forget to verify the resulting fingerprint in the status bar to ensure you've loaded the correct key.
"},{"location":"getting-started/usage/navigating-the-main-menu/#customize","title":"Customize","text":"Here you are presented to the exact same customization options you have while loading a key and wallet. You can change the Network, Single/Multisig, Script Type and Account. More about wallet attributes
"},{"location":"getting-started/usage/navigating-the-main-menu/#bip85","title":"BIP85","text":"Bitcoin BIP85, also known as Deterministic Entropy From BIP32 Keychains, allows for the generation of deterministic entropy using a BIP32 master key. This entropy can then be used to create various cryptographic keys and mnemonics (e.g., BIP39 seed phrases). BIP85 ensures that all derived keys and mnemonics are deterministic and reproducible, meaning they can be recreated from the same master key. This feature is useful for securely managing multiple child keys from a single master key without the need to store each one separately.
BIP39 Mnemonic
Choose between 12 or 24 words, then type the desired index to export a child mnemonic. After being presented with the new mnemonic, you can choose to load and use it right away.
Please note that any passphrase from the parent mnemonic will be removed when loading a BIP85 child mnemonic.
Base64 Password
To create a Base64 password, which can be used in a variety of logins, from email to social media accounts, choose an index and then a length of at least 20 characters.
The resulting password will be displayed on the screen and can also be exported to an SD Card or as a QR code.
"},{"location":"getting-started/usage/navigating-the-main-menu/#address","title":"Address","text":"Scan, verify, export or print your wallet addresses.
"},{"location":"getting-started/usage/navigating-the-main-menu/#scan-address","title":"Scan Address","text":"This option turns on the camera and allows you to scan in a QR code of a receive address. Upon scanning, it will render its own QR code of the address back to the display along with the (text) address below it. You could use this feature to scan the address of someone you want to send coins to and display the QR back to your wallet coordinator rather than copy-pasting an address. If you have a thermal printer attached, you can also print this QR code.
After proceeding through this screen, you will be asked if you want to check that the address belongs to your wallet. If you confirm, it will exhaustively search through as many addresses derived from your wallet as you want in order to find a match.
This option exists as an extra security check to verify that the address your wallet coordinator has generated is authentic and belongs to your wallet.
"},{"location":"getting-started/usage/navigating-the-main-menu/#receive-addresses","title":"Receive Addresses","text":"List your wallet receiving addresses, you can browse to select an arbitrary address to show your QR code and print if you want.
"},{"location":"getting-started/usage/navigating-the-main-menu/#change-addresses","title":"Change Addresses","text":"List your wallet change addresses, you can browse to select an arbitrary address to show your QR code and print if you want.
"},{"location":"getting-started/usage/navigating-the-main-menu/#sign","title":"Sign","text":"Under Sign, you can choose to sign a PSBT or a message. You can load both PSBTs and messages scanning QR codes or loading from files on a SD card.
"},{"location":"getting-started/usage/navigating-the-main-menu/#psbt","title":"PSBT","text":"To sign a Bitcoin PSBT, you have the following options:
- Scan an Animated QR Code: Turn on the camera and scan an animated QR code of a PSBT generated by your wallet coordinator software. If you have any issues, see Troubleshooting.
- Load from SD Card: Load an unsigned PSBT file from your SD card.
Upon loading the PSBT, you will be presented with a preview showing the amount of BTC being sent, the recipient's address, and the transaction fee. Amounts are displayed according to your locale and the International Bureau of Weights and Measures, while still adhering to the concept of the Satcomma standard format.
If you choose to proceed and sign the transaction, the signed PSBT can be exported in two ways:
- As an animated QR code, which can be scanned back into your coordinator wallet.
- As a signed PSBT file, which can be saved to your SD card and then loaded back into your coordinator wallet for broadcasting.
If a thermal printer is attached to your device, you can also print the PSBT QR codes for record-keeping or further processing.
"},{"location":"getting-started/usage/navigating-the-main-menu/#message","title":"Message","text":"Similar to PSBTs, Krux can load, sign, and export signatures for messages. This feature allows you to attest not only to the ownership of the messages themselves but also to the ownership of Bitcoin addresses and the authorship of documents and files.
"},{"location":"getting-started/usage/navigating-the-main-menu/#standard-messages-and-files","title":"Standard Messages and Files","text":"You can scan or load a file from an SD card, the content can be plaintext or the SHA-256 hash of a message. Upon loading, you will be shown a preview of the message's SHA-256 hash for confirmation before signing.
If you confirm, a signature will be generated, and you will see a base64-encoded version of it. You can then choose to export it as a QR code or save it to an SD card. If a thermal printer is attached, you can also print the QR code.
Following this, you will see and be allowed to export your raw (master) public key in hexadecimal form, which can be used by others to verify your signature. If a thermal printer is attached, you can also print this QR code.
This feature is used to sign Krux releases, airgapped, using a Krux device.
"},{"location":"getting-started/usage/navigating-the-main-menu/#messages-at-address","title":"Messages at Address","text":"Coordinators like Sparrow and Specter offer the possibility to sign messages at a Bitcoin receive address, allowing you to attest ownership of that address. Krux will detect if the message is of this type and present a similar workflow for signing. The main difference is that the address will be displayed along with the raw message, and since the message is signed with a derived address instead of the master public key, Krux won't offer the option to export the raw public key after the signature.
"},{"location":"getting-started/usage/setting-a-coordinator-and-signing/","title":"Setting a Coordinator and Signing","text":"After creating a mnemonic, making a safe backup, and testing to recover your mnemonic, it's time to set up a coordinator.
Krux can work with multiple coordinator wallets. Popular options include:
-
Sparrow Wallet (desktop)
-
Specter Desktop (desktop)
-
Nunchuk (mobile)
-
BlueWallet (mobile)
"},{"location":"getting-started/usage/setting-a-coordinator-and-signing/#step-1-install-the-coordinator-wallet","title":"Step 1: Install the Coordinator Wallet","text":"Download and install the appropriate version of your chosen coordinator wallet for your device and operating system.
"},{"location":"getting-started/usage/setting-a-coordinator-and-signing/#step-2-create-a-new-wallet-with-krux-as-a-signer","title":"Step 2: Create a New Wallet with Krux as a Signer","text":"Depending on the coordinator, the steps to add Krux as a signer may vary slightly:
Specter and Nunchuk Single-sig: Add Krux as signer device, then create a wallet that uses it.
Specter and Nunchuk Multisig: Add Krux as signer device, add other devices, then create a wallet that uses them.
Sparrow and BlueWallet: Create a wallet (or vault in Blue Wallet) first, then add signer device(s).
- Load a mnemonic and wallet in Krux.
-
On your coordinator, when presented with possible signer devices to add, choose Krux if available, otherwise choose \"other\" or even another QR code compatible signer. As Krux is compatible with many QR code formats, most of available alternatives should work.
-
When prompted by your coordinator to import signer's public key, access the \"Extended Public Key\" on Krux.
- Export an XPUB (or YPUB, ZPUB, etc., based on the script type) as a QR code.
-
Scan this QR code with your coordinator.
-
Ensure the coordinator\u2019s wallet attributes (policy type, script type, fingerprint, and derivation) match those in Krux.
"},{"location":"getting-started/usage/setting-a-coordinator-and-signing/#step-3-load-and-backup-wallet-descriptor-multisig-only","title":"Step 3: Load and Backup Wallet Descriptor (Multisig Only)","text":" - In your coordinator, export the wallet descriptor containing information about the wallet and all cosigners:
- Sparrow: \"Descriptor\"
- Specter: \"Export Wallet\"
- Nunchuk: \"Export Wallet Configuration\"
- BlueWallet: \"Export Coordination Setup\"
- Export the descriptor as a QR code or file.
- On Krux, go to \"Wallet\" -> \"Wallet Descriptor\" to scan the descriptor QR code or load it via SD card.
-
If you access \"Wallet\" -> \"Wallet Descriptor\" again, you will be able to:
- Check the wallet cosigners.
- Save the descriptor on an SD card (useful if you initially loaded it from QR codes).
It is crucial to have a backup of this descriptor to recover your wallet in case one of the cosigners is lost.
"},{"location":"getting-started/usage/setting-a-coordinator-and-signing/#step-4-verify-addresses","title":"Step 4: Verify Addresses","text":"For single-sig or multisig (after loading a descriptor):
-
Go to \"Address\" on Krux.
-
List \"Receive Addresses\" and \"Change Addresses\" or use \"Scan Address\" to verify if addresses from your coordinator are matched by Krux.
"},{"location":"getting-started/usage/setting-a-coordinator-and-signing/#step-5-funding-your-wallet","title":"Step 5: Funding your Wallet","text":"Once addresses are verified, send a small test amount to your wallet. Test signing and sending a transaction before adding more funds.
"},{"location":"getting-started/usage/setting-a-coordinator-and-signing/#step-6-sign-psbts-and-messages","title":"Step 6: Sign PSBTs and Messages","text":""},{"location":"getting-started/usage/setting-a-coordinator-and-signing/#psbts","title":"PSBTs","text":" -
Create a transaction in your coordinator.
-
Export the transaction as a QR code.
-
On Krux, go to \"Sign\" -> \"PSBT\" -> \"Load from camera\".
-
Scan the animated QR code.
-
Verify the transaction details.
-
If correct, press \"Sign to QR code\".
-
Scan the signed transaction QR code back into the coordinator to broadcast it.
Alternatively, you can use an SD card:
Save the transaction as a file on an SD card. On Krux, go to \"Sign\" -> \"PSBT\" -> \"Load from SD card\" and \"Sign to SD card\". Load the signed transaction on the coordinator and broadcast it.
"},{"location":"getting-started/usage/setting-a-coordinator-and-signing/#messages","title":"Messages","text":"Some coordinators, like Sparrow, allow you to sign messages linked to your wallet's addresses. Signing and verifying a message signature attests to the ownership of an address and serves as an additional test for your setup.
"},{"location":"getting-started/usage/video-tutorials/","title":"Video Tutorials","text":""},{"location":"getting-started/usage/video-tutorials/#krux-video-tutorials","title":"Krux Video Tutorials","text":"Most people prefer to learn by watching videos, and we are fortunate to have excellent content creators in the Bitcoin space, here are some examples of Krux related content and tutorials.
"},{"location":"getting-started/usage/video-tutorials/#english","title":"English","text":""},{"location":"getting-started/usage/video-tutorials/#krux-on-m5stickv-sparrow","title":"Krux on M5StickV + Sparrow","text":"Krux on M5StickV + Sparrow Wallet by Crypto Guide
"},{"location":"getting-started/usage/video-tutorials/#krux-on-maix-amigo-blue","title":"Krux on Maix Amigo + Blue","text":"Krux on Maix Amigo + Blue Wallet by Crypto Guide
"},{"location":"getting-started/usage/video-tutorials/#diy-only-multisig","title":"DIY-Only MultiSig","text":"DIY-Only Multivendor Hardware Wallet MultiSig: SeedSigner, Jade, Krux, Satochip + Sparrow & Electrum by Crypto Guide
"},{"location":"getting-started/usage/video-tutorials/#build-from-source-verify","title":"Build From Source & Verify","text":"Krux DIY Bitcoin Signer: Build From Source & Verify (With Windows + WSL2 + Docker) by Crypto Guide
"},{"location":"getting-started/usage/video-tutorials/#portuguese","title":"Portuguese","text":""},{"location":"getting-started/usage/video-tutorials/#krux-facil-de-instalar","title":"Krux f\u00e1cil de instalar","text":"Hardwallet Krux f\u00e1cil de instalar + QRs criptografados - por Bitdov
"},{"location":"getting-started/usage/video-tutorials/#multisig-com-krux","title":"Multisig com Krux","text":"Multisig com Krux e Nunchuk no celular - por Bitdov
"},{"location":"getting-started/usage/video-tutorials/#krux-com-impressora-termica","title":"Krux com impressora t\u00e9rmica","text":"Usando a Krux com impressora t\u00e9rmica - por Bitdov
"},{"location":"getting-started/usage/video-tutorials/#krux-no-celular","title":"Krux no celular","text":"Carteira Bitcoin com celular OFFLINE - Krux mobile APK - por Dig
"},{"location":"getting-started/usage/video-tutorials/#krux-no-celular-ii","title":"Krux no celular II","text":"Como utilizar a carteira Krux no celular - por Jo\u00e3o Trein
"},{"location":"getting-started/usage/video-tutorials/#faca-sua-krux","title":"Fa\u00e7a sua Krux","text":"Fa\u00e7a sua hardware wallet em casa com a KRUX! - por Caiovski
"},{"location":"getting-started/usage/video-tutorials/#korean","title":"Korean","text":"Krux \uc6d4\ub81b \uc124\uce58 \ubc0f \uac80\uc99d \ubc29\ubc95
\uc548\uc0ac\uba74 \uc190\ud574? \uc138\uc0c1\uc5d0\uc11c \uac00\uc7a5 \ud22c\uba85\ud55c \ube44\ud2b8\ucf54\uc778 \uc804\uc6a9 \uc9c0\uac11
"},{"location":"snippets/after-install-installer/","title":"After install installer","text":"Once installed, you can proceed to firmware installation.
"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"faq/","title":"FAQ","text":""},{"location":"faq/#is-krux-a-hardware-wallet","title":"Is Krux a hardware wallet?","text":"The term \"hardware wallet\" typically refers to devices dedicated to storing private keys and signing transactions. These devices often feature specific security components like secure element chips.
Krux was initially developed as a signer, operating exclusively in amnesic mode, which requires users to load their keys each time the device is powered on. However, Krux has evolved and now offers the option to store mnemonics, similar to traditional hardware wallets. These mnemonics can be stored in the device's internal memory or on SD cards.
Krux does not include hardware secure elements. The security of stored data relies on encryption.
Note: Due to the inherent fragility of electronic components, never use your Krux device or SD card encrypted storage as your sole backup method. Always maintain a physical backup for added security.
"},{"location":"faq/#what-is-beta-version","title":"What is Beta version?","text":"The Beta version includes the latest and most experimental features, which we occasionally share on our social media. These can be found exclusively in the test (beta) repository. Use and flash the beta firmware if you are curious about new features or want to participate in the development process by hunting bugs, providing feedback, and sharing ideas in our Telegram groups or other social media platforms.
For regular use, flash the official releases, which are signed, thoroughly tested, and well-documented.
"},{"location":"faq/#what-is-krux-android-app","title":"What is Krux Android app?","text":""},{"location":"faq/#how-can-i-find-it","title":"How can I find it?","text":"The Krux Android app is available as an APK in the test (beta) repository. It requires Android 6.0 or above.
"},{"location":"faq/#how-can-i-install-it","title":"How can I install it?","text":"The APK is not available on the Play Store. You can download the APK directly or transfer it to your Android device via SD card or USB cable. To install it, you may need to configure your Android device to allow installations from unknown sources.
"},{"location":"faq/#is-it-safe-to-use","title":"Is it safe to use?","text":"The Krux Android app is designed for learning about Krux and Bitcoin air-gapped transactions. Due to the numerous potential vulnerabilities inherent in smartphones, such as the lack of control over the operating system, libraries, and hardware peripherals, the Krux app should NOT be used to manage wallets containing savings or important keys and mnemonics. For secure management of your keys, a dedicated device is recommended.
"},{"location":"","title":"Krux","text":"Krux is an open-source firmware that transforms off-the-shelf Kendryte K210 devices, such as the Maix Amigo, M5StickV and more, into versatile bitcoin transaction signers. Beyond its core functionality, Krux is a flexible platform that can adapt to devices with different form factors, providing a suite of tools to assist with the creation and recovery of mnemonic backups, some of which include encryption options for enhanced security.
Devices like the Maix Amigo and Yahboom come ready to use, with large touchscreens that make it easy and user-friendly to operate. These devices are ideal for those looking for a plug-and-play solution. On the other hand, Krux also supports development board kits, which are perfect for DIY enthusiasts who enjoy customizing and building their own hardware setups.
Interacting seamlessly with leading coordinator wallets through QR codes, SD cards, and even thermal printers, the user-friendly firmware offers unique features to support transactions and mnemonic backups in an offline environment.
To learn more about Krux, check out Getting Started.
"},{"location":"parts/","title":"Devices and Parts List","text":""},{"location":"parts/#krux-compatible-devices","title":"Krux Compatible Devices","text":""},{"location":"parts/#comparative-table","title":"Comparative Table","text":"Device M5StickV Maix Amigo Maix Dock Maix Bit Yahboom k210 module Maix Cube WonderMV Price range US$ 50-55 US$ 50-85 US$ 27-35 US$ 32-42 US$ 45-61 US$ 34-49 US$ 58-86 Screen size / resolution 1.14\" / 135*240 3.5\" / 320*480 2.4\" / 240*320 2.4\" / 240*320 2\" / 240*320 1.3\" / 240*240 2\" / 240*320 Brightness control Device size 48*24*22mm 104*63*17mm 98*59*18mm 69*84*41mm 57*41*17mm 40*40*16mm 59*41*17mm Touchscreen Capacitive Capacitive Capacitive Camera OV7740 OV7740 rearGC0328 front GC0328 OV2640 orOV5642 OV2640 (VER:1.0) orGC2145 (VER:1.1) OV7740 GC2145 Battery 200mAh 520mAh 200mAh Requirements None None Rotary encoder 3D printed case SolderingAssembly Buttons 3D printed case SolderingAssembly None None None Warnings Camera has lens distortion Micro USB 3-Way button None : Only OV7740, OV2640 and GC2145 have an anti-glare mode to better capture images from high brightness screens or with incident light.
: 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.
: Some Amigo screens have inverted X coordinates, others display colors differently. For more info see Troubleshooting.
: Some stores ship the Maix Dock with soldered pin connectors that do not fit into the 3D printed case.
All devices feature Kendryte K210 chip: 28nm process, dual-core RISC-V 64bit @400MHz, 8 MB high-speed SRAM, DVP camera and MCU LCD interface, AES Accelerator, SHA256 Accelerator, FFT Accelerator.
"},{"location":"parts/#m5stickv","title":"M5StickV","text":"Below is a list of some distributors where you can find this device:
- M5Stack
- Mouser
- Digi-Key
- Electromaker
- Lee's Electronic
- AliExpress
- ABRA
- Adafruit
- Cytron
"},{"location":"parts/#maix-amigo","title":"Maix Amigo","text":"Below is a list of some distributors where you can find this device:
- AliExpress
- Seeed Studio
- Digi-Key
- Mouser
- Electromaker
"},{"location":"parts/#yahboom-k210-module","title":"Yahboom k210 module","text":"It comes with a compatible 32G card, an USB card reader, one PH2.0 4Pin male-to-male connector and one PH2.0 female adapter (to connect to a thermal printer). Below is a list of some distributors where you can find this device:
- AliExpress
- Amazon
- Yahboom Store
- ETC HK Shop
"},{"location":"parts/#maix-cube","title":"Maix Cube","text":"Below is a list of some distributors where you can find this device:
- Seeed Studio
- Mouser
- Electromaker
- Digi-Key
- AliExpress
- Amazon
"},{"location":"parts/#maix-dock-and-maix-bit","title":"Maix Dock and Maix Bit","text":"For the DIYers, the Maix Dock and Maix Bit are also supported but will require sourcing the parts individually and building the device yourself.
Below are example implementations with instructions on how to recreate them:
- https://github.com/selfcustody/DockEncoderCase
- https://github.com/selfcustody/MaixBitCase
Below is a list of some distributors where you can find these devices:
- Mouser
- Electromaker
- Digi-Key
- AliExpress
- Amazon
"},{"location":"parts/#other-parts","title":"Other Parts","text":""},{"location":"parts/#usb-c-or-micro-usb-charge-cable","title":"USB-C or Micro USB Charge Cable","text":"This will come with the device. It will be necessary to power, charge the device (if it has battery) and to initially flash the firmware.
"},{"location":"parts/#optional-microsd-card","title":"(Optional) MicroSD Card","text":"We cannot guarantee that a microSD card is compatible and will work in your device; you'll need to test it on the device to be sure, read the Troubleshooting for more info. Yahboom will come with a compatible 32G card. The size of the SD card isn't important; anything over a few megabytes will be plenty.
"},{"location":"parts/#optional-ttl-serial-thermal-printer","title":"(Optional) TTL Serial Thermal Printer","text":"Warning/Disclaimer: This feature is intended for individuals with experience in electronics tinkering and soldering.
Krux has the capability to print all QR codes it generates, including those for mnemonics, xpubs, wallet backups, and signed PSBTs, using a locally-connected thermal printer via its serial port.
Many TTL serial thermal printers may be compatible, but currently, the Goojprt QR203 has the best support (except this printer only supports ASCII or Chinese characters, non-ASCII characters will be printed as Chinese). The Adafruit printer starter pack can also be a convenient option to get started, as it includes all the necessary components for printing (except the conversion cable). To ensure proper functionality, enable the printer driver in the Krux settings, set the Tx pin and baud rate value to either 19200 or 9600 (depends on the printer), as explained in this Adafruit printer tutorial. You will need to connect the device's Tx to the printer's Rx and device's ground to the printer's ground, do not connect any other pins because a wrong connection may damage your device. The printer requires a dedicated power supply, typically with an output of 5 to 9V (or 12V) and capable of supplying at least 2A. For more information, see this discussion.
"},{"location":"parts/#optional-conversion-cable-for-thermal-printer","title":"(Optional) Conversion Cable for Thermal Printer","text":"To connect the printer to M5StickV, Amigo or Cube, you will need a grove conversion cable with a 4-pin male Grove connector on one end (to connect to the device) and 4-pin male jumpers on the other end (to connect to the printer). Check your device and printer model connection first, Yahboom comes with PH2.0 4Pin female connector; Dock and Bit doesn't have a connector. For a more reliable connection, it is recommended to cut and solder the wires of your custom cables instead of using jumpers.
"},{"location":"support/","title":"Support the Project","text":""},{"location":"support/#ways-you-can-help","title":"Ways you can help","text":""},{"location":"support/#development","title":"Development","text":"Audit the code, file an issue, make a pull request, or do all three. :)
"},{"location":"support/#documentation","title":"Documentation","text":"\"I'd like to see Krux help as many people as possible, and to do that, good documentation is needed. If you identify a better way to say something, please make a PR, any help is appreciated.\" - Jeff
"},{"location":"support/#translation","title":"Translation","text":"Krux supports different languages. If you missed a language or saw an awkward translation, open an issue or make a PR! You can also make a difference by translating this documentation! For information on how to translate, see here
"},{"location":"support/#social","title":"Social","text":"Reach out via our Telegram group or X profile (Twitter) for faster help, share ideas and join the Krux community. Help others get to know Krux.
\"I'm an engineer, not a marketer. If you like Krux, help spread the word!\" - Jeff
"},{"location":"support/#krux-ethos","title":"Krux Ethos","text":"The purpose of this ethos is not to virtue signal, but to introduce newcomers to Krux's philosophy and provide a guiding reference for decision-making and the long-term mission for dedicated Krux users.
"},{"location":"support/#mission","title":"Mission","text":"To implement ideas that make self-custody more powerful, accessible, and user-friendly.
"},{"location":"support/#dont-trust-verify","title":"Don't Trust, Verify","text":"Do not trust developers\u2019 intentions or competence. Krux is a DIY, use-at-your-own-risk project. We are committed to continuously improving security, but will not make claims or create marketing narratives about it. It is up to the users verify their hardware, the firmware and Krux-Installer
"},{"location":"support/#donations","title":"Donations","text":"Krux will not solicit, receive, manage, or distribute donations. Therefore, Krux has no budget for publicity, audits, or similar activities. Contributors to Krux will fund their own work\u2014whether by promoting their efforts, applying for grants, or seeking direct individual donations.
"},{"location":"support/#krux-is-public-domain","title":"Krux is Public Domain","text":"Krux users should feel completely free from any obligation to donate or support developers. Use Krux without guilt or expectation.
The same applies to any company profiting from Krux-based products or services, such as educational content, custom hardware, or accessories. The \"don't trust\" principle clearly extends here as well\u2014it is the users\u2019 responsibility to determine if these products align with the Krux ethos and their personal values.
"},{"location":"troubleshooting/","title":"Troubleshooting","text":""},{"location":"troubleshooting/#before-installing","title":"Before Installing","text":""},{"location":"troubleshooting/#linux-os-not-listing-serial-port","title":"Linux OS not listing serial port?","text":"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:
ls /dev/ttyUSB*\n
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:
sudo apt-get remove brltty\n
"},{"location":"troubleshooting/#m5stickv-device-not-being-recognized-and-charged","title":"M5StickV device not being recognized and charged?","text":"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.
"},{"location":"troubleshooting/#device-not-charging-or-being-recognized","title":"Device not charging or being recognized?","text":"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 connecting to 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.
"},{"location":"troubleshooting/#device-randomly-freezes-or-restarts","title":"Device randomly freezes or restarts?","text":"If the device behaves this way when connected to the computer, Windows is known to have issues with 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.
"},{"location":"troubleshooting/#after-installing","title":"After Installing","text":""},{"location":"troubleshooting/#maix-amigo-touchscreen-doesnt-work-with-v24030-but-worked-okay-with-v23091","title":"Maix Amigo touchscreen doesn't work with v24.03.0 but worked okay with v23.09.1?","text":"We added a hardware IRQ (interrupt request) to the firmware, so when you open your Maix Amigo, you will see a switch in the middle of the device board, it must be in the upper position for the touchscreen to work with v24.03.0 and later.
"},{"location":"troubleshooting/#troubleshooting-lcd-settings-on-maix-amigo","title":"Troubleshooting LCD Settings on Maix Amigo","text":"Buttons in the Wrong Order
If the buttons on keypad input screens appear to be in the wrong order, this might be due to inverted X coordinates. To correct this:
- Go to Settings > Hardware > Display.
- Change the value of
Flipped X Coordinates.
Incorrect Colors
If the colors displayed on the interface or camera preview are incorrect, you can try the following options:
Inverted Colors
If, for example, the background color is white when it should be black, go to Settings > Hardware > Display and toggle Inverted Colors .
BGR Colors
If, for example, you are using the Orange theme, and instead of orange the colors appear bluish, toggle BGR Colors in the display settings.
LCD Type
WARNING! Only try changing this setting if you failed to fix colors with previous ones.
If adjusting BGR Colors and Inverted Colors doesn't fix the color issue, try changing the LCD Type:
- After changing this setting, you will be warned that the device will reboot automatically if this change does not resolve the issue (if it fails, the screen will turn black, and you'll not see anything).
- After proceeding with the warning, if you see a message prompting you to press the
PREVIOUS (UP) button, it means that the new setting worked. Follow the instructions and press UP. - If you notice menu options but the colors are still wrong, try again with different combinations of
Inverted Colors and BGR Colors. This time, it is likely you will find a combination that correctly displays the colors of themes and the camera feed.
If, after the warning in step 1, the screen turns black and you don't see anything, don't panic or press any buttons. Just wait 5 seconds, and the device will automatically reboot with the previous display settings. This means you should keep the default LCD Type setting and maybe try again with Inverted Colors and BGR Colors.
If you accidentally pressed PREVIOUS (UP) and saved the wrong setting, you will have to perform a wipe to remove all stored settings to be able to see the screen working again. On Linux, go to the folder where you downloaded the Krux firmware and use Ktool to fully wipe your device:
./ktool-linux -B goE -b 1500000 -E
(Soon Krux-Installer will have a full wipe button too)
Then flash the firmware again.
./ktool-linux -B goE -b 1500000 maixpy_amigo/kboot.kfpkg
"},{"location":"troubleshooting/#device-didnt-reboot-and-screen-is-blank","title":"Device didn't reboot, and screen is blank","text":"If the device didn't reboot after successfully flashing the firmware, and the screen is blank after turning it off and on, check if the downloaded file matches the device (this can also occur due to data corruption). Try downloading binaries again.
You can also install MaixPy IDE to help with debugging, Tools > Open Terminal > New Terminal > Connect to serial port > Select a COM port available (if it doesn't work, try another COM port). It will show the terminal and some messages, a message about an empty device or with corrupted firmware appears like: \"interesting, something's wrong, boot failed with exit code 233, go to find your vendor.\"
"},{"location":"troubleshooting/#usage","title":"Usage","text":""},{"location":"troubleshooting/#why-isnt-krux-scanning-the-qr-code","title":"Why isn't Krux scanning the QR code?","text":"The level of detail that you see is what Krux sees. If the QR code shown on the device's screen is blurry, the camera lens of the device may be out of focus. It can be adjusted by rotating it clockwise or counter-clockwise to achieve a clearer result. The lenses usually comes with a drop of glue that makes id harder to adjust for the first time. You can use your fingertip, tweezers or small precision pliers to help, being careful to don't damage the fragile lenses.
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. Some cameras (OV7740, OV2640 and GC2145) have an anti-glare mode to better capture images from high brightness screens or with incident light, they are present on M5StickV, Amigo, Cube and Yahboom. To enable/disable the anti-glare mode on a supported device just press the PAGE button while scanning.
"},{"location":"troubleshooting/#error-when-scanning-qr-code","title":"Error when scanning QR code?","text":"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 BIP-39 mnemonics:
- BIP-39 Plaintext (Used by Krux and https://iancoleman.io/bip39/)
- SeedSigner SeedQR and CompactSeedQR Formats
- UR Type
crypto-bip39 - Encrypted QR Code (Format created by Krux, more information here)
For Wallet output descriptor:
- JSON with at least a
descriptor key containing an output descriptor string - Key-value INI files with at least
Format, Policy, and Derivation keys - UR Type
crypto-output
For PSBT (Partially Signed Bitcoin Transactions):
- Base43, Base58, and Base64-encoded bytes
- Raw Bytes
- UR Type
crypto-psbt
Additionally, Krux recognizes animated QR codes that use either the plaintext pMofN (the Specter QR format) or binary UR encodings.
"},{"location":"troubleshooting/#computer-not-reading-qr-code-that-krux-displays","title":"Computer not reading QR code that Krux displays?","text":"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. 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.
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.
"},{"location":"troubleshooting/#why-does-krux-say-the-entropy-of-my-fifty-dice-rolls-does-not-contain-128-bits-of-entropy","title":"Why Does Krux Say the Entropy of My Fifty Dice Rolls Does Not Contain 128 Bits of Entropy?","text":"Please check how entropy measurement works.
"},{"location":"troubleshooting/#why-isnt-krux-detecting-my-microsd-card-or-presenting-an-error","title":"Why isn't Krux detecting my microSD card or presenting an error?","text":"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. Make sure the SD card is using MBR/DOS partition table and FAT32 format.
"},{"location":"uncommon-questions/","title":"Uncommon Questions","text":""},{"location":"uncommon-questions/#what-are-all-the-features-available","title":"What are all the features available?","text":"On the official releases page you will find all the features listed, with details on the Getting Started page with a brief summary on the Navigation Overview page.
"},{"location":"uncommon-questions/#what-is-the-purpose-of-using-an-sd-card-with-the-device","title":"What is the purpose of using an SD card with the device?","text":"SD card use is optional, but can be used to upgrade the firmware, save settings, cnc/file, QR codes, XPUBs, encrypted mnemonics, and also to save and load PSBTs, messages and wallet output descriptors.
"},{"location":"getting-started/","title":"Getting Started","text":"Krux is open-source Bitcoin signing firmware for devices with the K210 chipset; also known as a hardware signer.
Signing operations in Krux are done offline via QR code or via SD card using the PSBT functionality. You can create/load your BIP-39 mnemonic, or import a wallet descriptor, and sign transactions all without having to plug the device into your computer (except to initially install the firmware). It reads QR codes with its camera and outputs QR codes to its screen, or to paper via an optional thermal printer attachment.
Krux runs offline, and therefore never handles the broadcasting part of the PSBT transaction. Instead, you can use Krux with third-party wallet coordinators to broadcast transactions from your online computer or mobile device while keeping your keys offline. Krux was built to be vendor agnostic and works with many popular wallet coordinators, including:
- Sparrow Wallet (desktop)
- Specter Desktop (desktop)
- Nunchuk (mobile)
- BlueWallet (mobile)
"},{"location":"getting-started/navigation/","title":"Navigation Overview","text":"Below is the mind map representation of the currently menus available. Click the circle with a number (Ex.: ) to the right of each node to expand and explore. Also, enable full screen in the top right menu for better viewing .
"},{"location":"getting-started/navigation/#login-menu","title":"Login Menu","text":""},{"location":"getting-started/navigation/#home-menu-loaded-a-mnemonic","title":"Home Menu (Loaded a mnemonic)","text":""},{"location":"getting-started/settings/","title":"Settings","text":"In the Krux home menu, there is a Settings entry. Some submenu entries have too many options to fit on one screen, swipe up or down to navigate between the screens if your device has a touchscreen. Below is a breakdown of the options you can change:
"},{"location":"getting-started/settings/#default-wallet","title":"Default Wallet","text":"Set the default attributes for wallet loading.
"},{"location":"getting-started/settings/#multisig","title":"Multisig","text":"Set this to true if you are more likely to use Krux for multisig setups. This way, you won't need to \"Customize\" your wallet attributes every time you load a key.
"},{"location":"getting-started/settings/#network","title":"Network","text":"This option allows you to switch between mainnet (the default) and testnet. Testnet can be used to try out different wallet coordinators or for development.
"},{"location":"getting-started/settings/#encryption","title":"Encryption","text":"Modify the encryption method and parameters to fit your needs. This will be used when storing encrypted mnemonics or creating encrypted QR codes. For more info see Krux Encrypted Mnemonics.
"},{"location":"getting-started/settings/#pbkdf2-iter-iterations","title":"PBKDF2 Iter. (Iterations)","text":"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 stands for the amount of derivations that will be performed over your key prior to encrypt/decrypt your mnemonic.
If you increase this value it will make the encryption harder, at the cost of taking longer to encrypt/decrypt your mnemonics.
Values must be multiple of 10,000. This was done to save data space on QR codes.
"},{"location":"getting-started/settings/#encryption-mode","title":"Encryption Mode","text":"Choose between well known and widely used AES (Advanced Encryption Standard) modes:
"},{"location":"getting-started/settings/#aes-ecb","title":"AES-ECB","text":"ECB (Electronic Codebook) is a simpler method where data blocks are encrypted individually. Compared to CBC, it will be faster and simpler to encrypt, QR codes will have a lower density and will be easier to transcribe.
"},{"location":"getting-started/settings/#aes-cbc","title":"AES-CBC","text":"CBC (Cipher-block Chaining) is considered more secure than ECB. 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, ensuring chaining.
Encryption will take longer because a snapshot will be needed to generate the IV. This IV will be stored together with the encrypted data, making encrypted QR codes denser and harder to transcribe.
"},{"location":"getting-started/settings/#hardware","title":"Hardware","text":"Customize the parameters available for your device and change printer settings.
"},{"location":"getting-started/settings/#encoder-maix-dock-only","title":"Encoder (Maix Dock only)","text":"If your device has a rotary encoder, you can change the debounce threshold in milliseconds. With lower values, faster movements and navigation will be allowed.
The caveat is low values can cause issues, such as double step and unexpected movements, especially with lower quality encoders. If this is the case increase the value to make navigation more stable.
"},{"location":"getting-started/settings/#display-maix-amigo-only","title":"Display (Maix Amigo only)","text":"Some Maix Amigo screens are different, here you can customize the BGR Colors, Flipped X Coordinates, Inverted Colors and LCD Type. For more info see Troubleshooting
"},{"location":"getting-started/settings/#printer","title":"Printer","text":"You can set up a TTL serial thermal printer or tell Krux to store a GRBL CNC instructions file on a SD card to machine QR codes.
"},{"location":"getting-started/settings/#cnc","title":"CNC","text":"Define several machining parameters according to the desired size, material you'll use, and your CNC characteristics and capabilities.
"},{"location":"getting-started/settings/#thermal","title":"Thermal","text":"Printers can come with different baudrates from the manufacturer. By default, Krux assumes the connected printer will have a baudrate of 9600. If yours is different, you can change it here.
Also setup the TX Pin you'll use (e.g. 35 for M5StickV and 7 for Maix Amigo) and tweak other parameters according to your printer recommendations. For most printers you will only need to connect 2 cables, the device TX to the printer RX and ground. Current uses of printing are listed here. Consult the parts list for supported printers.
"},{"location":"getting-started/settings/#driver","title":"Driver","text":"Here you choose between Thermal, CNC or none (default). Leave this setting to \"none\" if you won't use a printer and don't want to be bothered by print prompts.
"},{"location":"getting-started/settings/#touchscreen-maix-amigo-and-yahboom-only","title":"Touchscreen (Maix Amigo and Yahboom only)","text":"If your device has touchscreen you can change the touch detection threshold. If it is being too sensitive or detecting false or ghost touches, you should increase the threshold value, making it less sensitive. The other way is also valid, reduce the threshold to make the screen more sensitive to touches.
"},{"location":"getting-started/settings/#language-locale","title":"Language - Locale","text":"Here you can change Krux to your desired language.
"},{"location":"getting-started/settings/#persist","title":"Persist","text":"Choose between flash (device's internal memory) or SD card for the place where your settings will be stored.
"},{"location":"getting-started/settings/#security","title":"Security","text":"Adjust settings that may impact your security protocols.
"},{"location":"getting-started/settings/#shutdown-time","title":"Shutdown Time","text":"Set the time it takes for Krux to automatically shut down. This feature not only conserves your device's battery, if it has one, but also serves as an important security measure. If you forget your device with private keys loaded, it will shut down automatically after the set time.
Please note that devices without batteries and power management will not shut down but will reboot instead, which is sufficient to unload private keys.
"},{"location":"getting-started/settings/#tc-flash-hash-at-boot","title":"TC Flash Hash at Boot","text":"Chose if you would like to run Tamper Check Flash Hash every time the device is powered on.
Activating TC Flash Hash at boot helps prevent unauthorized use by requiring the TC Code. But is important to note, unlike a PIN, the TC Code does not provide access control over USB. This means that the device's memory remains accessible for reading and writing via USB, allowing it to be flashed with firmware that does not require the TC Code, which could then allow unauthorized use through its human interface.
"},{"location":"getting-started/settings/#hide-mnemonics","title":"Hide Mnemonics","text":"When \"Hide Mnemonics\" mode is set to \"True\", your device will not display private key data or backup tools when a key is loaded. It will only show public key information and allow signing operations.
"},{"location":"getting-started/settings/#tamper-check-code","title":"Tamper Check Code","text":"Create or modify a Tamper Check Code. This code will be required every time Tamper Check Flash Hash is executed.
After creating the code, you will be prompted to fill the empty memory spaces with random entropy from the camera. This step is important to make TC Flash Hash more resilient to data manipulation by eliminating empty memory spaces that could be exploited in a sophisticated tamper attempt.
The filling process requires good entropy images. If, for any reason, such as starting the process in a dark room, you fail to capture good entropy images, you can restart the filling process by resetting your TC Code.
The TC Code will be deleted if the device is wiped or user data is erased, which will consequently disable TC Flash Hash.
"},{"location":"getting-started/settings/#appearance","title":"Appearance","text":"Configure screensaver time and change Krux to your desired theme.
"},{"location":"getting-started/settings/#screensaver-time","title":"Screensaver time","text":"Set how long to wait idle before the screensaver appears. Enter 0 to disable the screensaver.
"},{"location":"getting-started/settings/#theme","title":"Theme","text":"Choose your color theme according to your preference. Some themes may be more suitable for some devices, coordinator cameras and environments. As an example, it may be easier to scan QR codes from Krux devices using light theme in brighter environments.
"},{"location":"getting-started/settings/#factory-settings","title":"Factory Settings","text":"Restore device to factory settings and reboot.
"},{"location":"getting-started/features/QR-transcript-tools/","title":"Transcribing QR Codes","text":"When you export a mnemonic, encrypted mnemonic or a generic text QR code, alternative visualization modes will be available. Swipe left or right to change modes, or if your device doesn't have a touchscreen, press the PAGE buttons. Find transcribe templates here.
"},{"location":"getting-started/features/QR-transcript-tools/#standard-mode","title":"Standard Mode","text":"This mode is optimized for scanning, the raw QR code will be displayed
"},{"location":"getting-started/features/QR-transcript-tools/#lines-mode","title":"Lines Mode","text":"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.
"},{"location":"getting-started/features/QR-transcript-tools/#zoomed-regions-mode","title":"Zoomed Regions Mode","text":"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.
"},{"location":"getting-started/features/QR-transcript-tools/#highlighted-regions-mode","title":"Highlighted Regions Mode","text":"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.
"},{"location":"getting-started/features/QR-transcript-tools/#grided-mode","title":"Grided Mode","text":"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 (tracing). Be careful not to damage your screen with pen and markers, use an insulating plastic tape or film to protect the device when using this method.
"},{"location":"getting-started/features/encrypted-mnemonics/","title":"Encrypted Mnemonics","text":""},{"location":"getting-started/features/encrypted-mnemonics/#introduction","title":"Introduction","text":"There are many possible security layers one could add to protect a wallet\u2019s 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\u2019s 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:
"},{"location":"getting-started/features/encrypted-mnemonics/#aes-ecb","title":"AES-ECB","text":"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.
"},{"location":"getting-started/features/encrypted-mnemonics/#aes-cbc","title":"AES-CBC","text":"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.
"},{"location":"getting-started/features/encrypted-mnemonics/#cbc-encryption-iv","title":"CBC Encryption IV","text":"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.
"},{"location":"getting-started/features/encrypted-mnemonics/#pbkdf2-iterations","title":"PBKDF2 Iterations","text":"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.
"},{"location":"getting-started/features/encrypted-mnemonics/#encrypted-qr-codes-data-and-parsing","title":"Encrypted QR Codes Data and Parsing","text":"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:
ID length (1) ID (2) Version (3) Key Derivations (4) IV (5) Encrypted Mnemonic (6) Validation Block (7) 1 Byte Variable 1 Byte 3 Bytes 16 Bytes (optional) 16 Bytes (12 words) 32 Bytes (24 words) 16 Bytes - Visible data (1 to 4):
- (1) Mnemonic ID length (1 Byte).
- (2) Mnemonic ID (variable lenght): Custom ID or wallet fingerprint.
- (3) Version (1 Byte): Version of encryption method, currently two are available:
- 0: AES-ECB-PBKDF2: Electronic Codebook with PBKDF2 key derivation.
- 1: AES-CBC-PBKDF2: Cypher Block Chaining with PBKDF2 key derivation.
- (4) Key derivation iterations (3 Bytes): Number of PBKDF2 key derivations times 10,000.
- Cipher data (5 to 7):
- (5) IV (16 Bytes-optional): Initial vector for AES-CBC encryption, possibility to be nonce for future AES-CTR or other encryption methods.
- (6) Encrypted Mnemonic (16 Bytes - 12 words, 32 Bytes - 24 words): Mnemonic ciphertext.
- (7) Validation block (16 Bytes): Currently using first 16 bytes of sha256 of the mnemonic bytes as checksum, could be used in future to store AES-AEX validation tag.
"},{"location":"getting-started/features/encrypted-mnemonics/#considerations","title":"Considerations","text":"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, 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, the best way to undo this is to erase user's data.
"},{"location":"getting-started/features/entropy/","title":"Empirical Entropy Measurement","text":""},{"location":"getting-started/features/entropy/#why-does-krux-say-the-entropy-of-my-fifty-dice-rolls-does-not-contain-128-bits-of-entropy","title":"Why Does Krux Say the Entropy of My Fifty Dice Rolls Does Not Contain 128 Bits of Entropy?","text":"This question, frequently raised in Krux chat groups, highlights the need to clarify the concepts and tools used by Krux to help users detect possible issues in the mnemonic creation procedure. Tools in Krux were designed to help users understand the concepts involved in the process, present statistics and indicators, and encourage users to experiment and evaluate results. This way, users learn about best practices in key generation. Below, we will dive deeper into entropy concepts to better support users in the fundamental requirement for sovereign self-custody, which is to build up knowledge.
"},{"location":"getting-started/features/entropy/#entropy-in-dice-rolls","title":"Entropy in Dice Rolls","text":"Rolling dice and collecting the resulting values can be an effective method for generating cryptographic keys due to the inherent randomness and unpredictability of each roll. Each roll of a die produces a random number within a specific range, and when multiple rolls are combined, they create a sequence that is difficult to predict or reproduce. This sequence can be used to generate cryptographic keys that are robust against attacks. By ensuring that the dice rolls are conducted in a controlled and secure environment, and by using a sufficient number of rolls to achieve the desired level of randomness, one can create cryptographic keys that are highly secure and resistant to brute-force attacks or other forms of cryptanalysis.
"},{"location":"getting-started/features/entropy/#entropy-definitions","title":"Entropy Definitions","text":"Entropy, a fundamental concept in various scientific disciplines, measures the degree of disorder or uncertainty within a system. This notion is interpreted differently across fields, leading to distinct types of entropy: mechanical entropy, Shannon's entropy, and cryptographic entropy.
Mechanical entropy, rooted in thermodynamics and statistical mechanics, quantifies the disorder in a physical system. It describes how energy is distributed among the particles in a system, reflecting the system's tendency towards equilibrium and maximum disorder.
Shannon's entropy, from information theory, measures the uncertainty or information content in a message or data source. Introduced by Claude Shannon, it quantifies the average amount of information produced by a stochastic source of data, indicating how unpredictable the data is.
Cryptographic entropy, crucial in security, refers to the unpredictability and randomness required for secure cryptographic keys and processes. High cryptographic entropy ensures that keys are difficult to predict or reproduce, providing robustness against attacks.
While mechanical entropy deals with physical systems, Shannon's entropy focuses on information content, and cryptographic entropy emphasizes security through randomness.
"},{"location":"getting-started/features/entropy/#measuring-dice-rolls-entropy","title":"Measuring Dice Rolls Entropy","text":"Entropy is a theoretical measure and is not directly measurable from a single roll but rather from the probability distribution of outcomes over many rolls. We can use Shannon's formula for theoretical and empirical calculations. Entropy S can be quantified with:
S = -\\sum_{i=1}^{n} p_i \\log(p_i) - Empirical Measurement:
- Roll the dice a large number of times to observe the frequency of each outcome.
-
Estimate the probabilities p_i based on observed frequencies.
-
Theoretical Calculation:
- Use the uniform distribution assumption (equal probability for all outcomes).
where: - p_i is the probability of each possible outcome (or state) of the system. - n is the number of possible outcomes.
"},{"location":"getting-started/features/entropy/#empirical-real-vs-theoretical-entropy-in-dice-rolls","title":"Empirical (Real) vs. Theoretical Entropy in Dice Rolls","text":"When calculating the entropy of dice rolls, the difference between real and theoretical results arises from the assumption of perfect fairness and uniformity versus the inherent imperfections in real-world experiments.
"},{"location":"getting-started/features/entropy/#theoretical-entropy","title":"Theoretical Entropy","text":"The theoretical entropy calculation assumes that the dice are perfectly fair, meaning each face has an equal probability of landing face up.
Consider a fair six-sided die. The possible outcomes when rolling one die are {1, 2, 3, 4, 5, 6}, each with an equal probability of \\frac{1}{6}.
- Single Die Roll:
- Each outcome has a probability p_i = \\frac{1}{6}.
- The entropy S for one die roll is calculated as:
S = - \\sum_{i=1}^{6} \\left( \\frac{1}{6} \\log_2 \\left( \\frac{1}{6} \\right) \\right) Since \\log_2(1/6) = -\\log_2(6) :
S = -6 \\left( \\frac{1}{6} \\times -\\log_2(6) \\right) = \\log_2(6) \\approx 2.585 \\text{ bits} - Multiple Dice Rolls:
- For multiple dice, the entropy increases as the number of possible outcomes increases. For k fair dice, the number of possible outcomes is 6^k.
-
The entropy S for k dice is:
S = \\log_2(6^k) = k \\log_2(6) \\approx 2.585k \\text{ bits}
-
For example, entropy for the roll of 50 fair dice is calculated as:
S = \\log_2(6^{50}) = 50 \\log_2(6) \\approx 2.585 \\times 50 \\approx 129.25 \\text{ bits}
This calculation assumes that every outcome (each face of the die) has an equal likelihood, leading to a uniform distribution.
"},{"location":"getting-started/features/entropy/#empirical-entropy","title":"Empirical Entropy","text":"In a real sample of dice rolls, several factors can cause deviations from the perfect uniform distribution:
- Imperfect Dice: Real dice may not be perfectly balanced. Small manufacturing defects can make certain faces slightly heavier or lighter, causing biases.
- Rolling Conditions: The way the dice are rolled, the surface they land on, and even air currents can introduce slight biases.
- Finite Sample Size: When rolling dice a finite number of times, the observed frequencies of each face will naturally deviate from the expected uniform distribution due to random variations. This phenomenon is more pronounced with smaller sample sizes.
When you roll a die multiple times and observe the outcomes, you can calculate the empirical probabilities p_i of each face. Using these probabilities, the entropy is calculated as:
S = - \\sum_{i=1}^{6} p_i \\log_2(p_i)"},{"location":"getting-started/features/entropy/#example","title":"Example","text":"Suppose you roll a six-sided die 50 times and get the following results:
- 1: 4 times
- 2: 9 times
- 3: 7 times
- 4: 10 times
- 5: 12 times
- 6: 8 times
We can calculate Shannon's entropy as follows:
"},{"location":"getting-started/features/entropy/#step-1-calculate-probabilities","title":"Step 1: Calculate Probabilities","text":"Total number of rolls:
N = 4 + 9 + 7 + 10 + 12 + 8 = 50 Probabilities for each outcome:
p_1 = \\frac{4}{50} = 0.08 p_2 = \\frac{9}{50} = 0.18 p_3 = \\frac{7}{50} = 0.14 p_4 = \\frac{10}{50} = 0.2 p_5 = \\frac{12}{50} = 0.24 p_6 = \\frac{8}{50} = 0.16"},{"location":"getting-started/features/entropy/#step-2-compute-entropy","title":"Step 2: Compute Entropy","text":"Using Shannon's entropy formula:
S = -\\sum_{i=1}^{n} p_i \\log_2(p_i) Calculate each term:
S_1 = -p_1 \\log_2(p_1) = -0.08 \\log_2(0.08) = -0.08 \\times (-3.64386) = 0.291509 S_2 = -p_2 \\log_2(p_2) = -0.18 \\log_2(0.18) = -0.18 \\times (-2.47393) = 0.445307 S_3 = -p_3 \\log_2(p_3) = -0.14 \\log_2(0.14) = -0.14 \\times (-2.8365) = 0.39711 S_4 = -p_4 \\log_2(p_4) = -0.2 \\log_2(0.2) = -0.2 \\times (-2.32193) = 0.464386 S_5 = -p_5 \\log_2(p_5) = -0.24 \\log_2(0.24) = -0.24 \\times (-2.05889) = 0.494132 S_6 = -p_6 \\log_2(p_6) = -0.16 \\log_2(0.16) = -0.16 \\times (-2.64386) = 0.423018 Sum the contributions:
S = S_1 + S_2 + S_3 + S_4 + S_5 + S_6 S = 0.291509 + 0.445307 + 0.39711 + 0.464386 + 0.494132 + 0.423018 = 2.515462 Thus, the Shannon's entropy for the given distribution of dice rolls is approximately 2.52 bits per roll.
This will give you a different value than \\log_2(6) due to the deviations in the empirical probabilities.
The total entropy for the N = 50 rolls is:
S_{total} = S \\times N = 2.515 + 50 \\approx 125.8 \\text{ bits}"},{"location":"getting-started/features/entropy/#shannons-entropy-in-practice","title":"Shannon's Entropy in Practice","text":"Calculating Shannon's entropy on a real sample of dice rolls provides insights into the actual randomness and fairness of the dice and rolling conditions. Deviations from the theoretical entropy reflect the natural imperfections and variances inherent in real-world scenarios. This understanding helps in evaluating and improving the fairness and randomness of dice or similar systems.
Shannon's entropy evaluates the statistical probability distribution of samples of a dice roll. An even distribution results in higher entropy, closer to the theoretical maximum entropy, which assumes perfectly distributed rolls. An uneven distribution, created, for example, by a biased die, will result in lower Shannon's entropy. In an extreme case, with a terribly biased die that always lands on the same side, Shannon's entropy will be zero.
"},{"location":"getting-started/features/entropy/#cryptographic-entropy","title":"Cryptographic Entropy","text":"Shannon's entropy, while a powerful measure of information content and uncertainty in a statistical distribution for natural samples, is not considered cryptographic entropy due to its inability to detect patterns or other sources of predictability within data. Shannon's formula quantifies the average information produced by a stochastic process, essentially measuring the expected surprise in a sequence of symbols based on their probabilities. However, it does not account for potential structure, correlations, or regularities within the data that could be inserted by a user and exploited by an attacker.
Cryptographic entropy, on the other hand, requires a higher standard of unpredictability. It must ensure that every bit of the cryptographic key is as random and independent as possible, making it resilient against any form of analysis that could reveal patterns or reduce the effective randomness. While Shannon's entropy can evaluate the statistical distribution of symbols, it falls short in guaranteeing the absence of patterns or dependencies, which are crucial for maintaining the security of cryptographic systems. Thus, cryptographic entropy encompasses a broader concept of randomness, ensuring that the generated keys are not only statistically random but also free from any detectable structure or predictability.
"},{"location":"getting-started/features/entropy/#pattern-detection","title":"Pattern Detection","text":"It is possible to have dice rolls with an even distribution but poor cryptographic entropy. This issue arises when patterns are present in the sequences. Examples include sequences like 123456123456123..., 111122223333..., and 654321654321..., which exhibit poor cryptographic entropy despite having even distribution and high Shannon's entropy.
To mitigate this issue, Krux has implemented a pattern detection algorithm that evaluates the Shannon's entropy of the rolls' derivatives. In practice, this algorithm detects arithmetic progression components in the dice rolls and raises a warning if a certain threshold is crossed.
"},{"location":"getting-started/features/entropy/#what-krux-does","title":"What Krux Does?","text":" - Krux requires a minimum number of rolls based on theoretical entropy.
- Krux warns the user if low Shannon's entropy, calculated with the actual rolls, is detected.
- Krux warns the user if it suspects there are patterns within the actual rolls.
"},{"location":"getting-started/features/entropy/#conclusion","title":"Conclusion","text":"While Krux cannot ensure rolls have good or bad cryptographic entropy, it does provide indicators to help users detect issues and learn about the concepts involved in mnemonic generation.
"},{"location":"getting-started/features/printing/","title":"Printing","text":"Warning/Disclaimer: This feature is intended for individuals with experience in electronics tinkering and soldering.
Krux has the ability to print mnemonic backup (Words, Numbers, Tiny Seed template; but not Stackbit 1248) and any QR code (SeedQR, signed PSBT, Address, XPUB, Wallet output descriptor, ...) via a locally-connected TTL serial thermal printer. Consult the parts list page for supported printers.
Once a thermal printer and driver have been enabled in Krux settings, all screens that display a QR code will offer the option to Print to QR. Other formats of mnemonic backup will also ask if you want to Print to QR?.
There are many ways you can use this functionality, including:
- Printing backups of your mnemonics and multisig wallet output descriptor
- Printing your xpubs and receive addresses to share
- Printing signed messages and PSBTs
Since printed thermal paper fades quickly, you can also print your backups on sticker thermal paper to use as templates for punching into more resilient materials like steel.
We also have plans to add support for other kinds of QR \"printers\" in the future, including CNC machines. In this case, gcode will be generated that can be sent directly to a GRBL controller to cut your QRs out of wood or metal!
Just be careful what you do with the printed codes, since most smartphones can now quickly and easily read QR codes. Treat your QR mnemonic the same way you would treat a plaintext copy of it.
"},{"location":"getting-started/features/sd-card-update/","title":"SD Card Updates","text":""},{"location":"getting-started/features/sd-card-update/#upgrade-via-microsd-card","title":"Upgrade via microSD card","text":"Once you've installed the initial firmware on your device via USB, you can either continue updating the device by flashing via USB or you can perform upgrades via microSD card to keep the device airgapped.
To perform an upgrade, simply copy the official release firmware.bin and firmware.bin.sig files to the root of a FAT-32 / MBR formatted microSD card, insert the card into your device, and reboot the device. If it detects the new firmware file and is able to verify the signature, you will be prompted to install it.
Once installation is complete, eject the microSD card and delete the firmware files before reinserting and rebooting. Otherwise you will be prompted to install it again.
We cannot guarantee that a microSD card is compatible and will work in your device; you'll need to test it on the device to be sure, read the Troubleshooting for more info. Only official releases are signed and can be installed via microSD card.
"},{"location":"getting-started/features/tamper-detection/","title":"Tamper Detection Mechanism (Experimental)","text":"Krux's tamper detection tool combines cryptographic hashes, a Tamper Check Code, and camera-generated entropy to create a tamper indicator that is unique to each device, represented by a memorable image and four words.
Before we get into details, let's start with some limitations and necessary prerequisites to allow the feature to work.
"},{"location":"getting-started/features/tamper-detection/#krux-security-model-good-practices-and-limitations","title":"Krux Security Model - Good Practices and Limitations","text":"To secure your Krux device, always verify firmware authenticity before installation, particularly when flashing via USB.
"},{"location":"getting-started/features/tamper-detection/#firmware-verification-methods","title":"Firmware Verification Methods","text":" -
Using OpenSSL Command-Line Tool: Follow the Krux documentation to verify the firmware's signature manually. This method provides a high level of assurance but requires familiarity with command-line operations.
-
Using Krux-Installer: For a more user-friendly experience, verify the Krux-Installer's signature using GPG. Graphical interfaces like Sparrow Wallet can facilitate this process. Krux-Installer automatically downloads the firmware from Github, verifies the firmware signature, informs you of the results, and guides you through manual verification if desired.
"},{"location":"getting-started/features/tamper-detection/#recommendations","title":"Recommendations","text":" -
Learn Verification Tools: Familiarize yourself with verification methods and tools to maintain control over your device's security.
-
Build from Source: Consider building the firmware from source code and verifying its reproducibility for maximum assurance.
-
Use SD Card for Updates: After the initial flash through USB, perform subsequent updates via the SD card. This keeps your device air-gapped and allows the existing firmware to verify new updates before installation.
Note: The effectiveness of the TC Flash Hash tamper detection feature relies on running legitimate, uncompromised firmware and safely protecting your Tamper Check Code.
"},{"location":"getting-started/features/tamper-detection/#tamper-check-code-tc-code","title":"Tamper Check Code (TC Code)","text":"A Tamper Check Code, composed of numbers, letters and special characters, with a minimum length of six characters, can be stored and required to execute Tamper Check (TC) Flash Hash tamper verification before Krux boots at the main application, or optionally as a feature available in Tools -> Flash Tools.
Before being stored in the device\u2019s flash, the TC Code is hashed together with the K210 chip\u2019s unique ID and stretched using PBKDF2. This ensures the TC Code is not retrievable via a flash dump and can only be brute-forced outside the device if the attacker also has access to the device\u2019s unique ID. By allowing letters, special characters, and running 100k iterations of PBKDF2, brute-forcing the TC Code from dumped data becomes more time-consuming and resource-intensive.
"},{"location":"getting-started/features/tamper-detection/#enhancing-tamper-detection","title":"Enhancing Tamper Detection","text":"After setting the TC Code, you are prompted to fill empty flash memory blocks with random entropy from the camera. This process ensures that attackers cannot exploit unused memory space.
"},{"location":"getting-started/features/tamper-detection/#tamper-check-tc-flash-hash-a-tamper-detection-tool","title":"Tamper Check (TC) Flash Hash - A Tamper Detection Tool","text":""},{"location":"getting-started/features/tamper-detection/#introduction","title":"Introduction","text":"The \"TC Flash Hash\" tool enables you to verify if the flash memory content has been altered.
"},{"location":"getting-started/features/tamper-detection/#how-it-works","title":"How It Works","text":"The tool generates a unique image and four tamper detection words based on a hash of your TC Code, the device's UID, and the flash content. The flash memory is divided into two regions:
-
Firmware Region: Generates the image and the first two words.
-
User's Region: Generates the last two words.
Example: The blue symbol and words 'tail monkey' represent the firmware region, while 'wrestle over' reflects the user region.
Any change in the flash content results in a different image or words:
-
Firmware Changes: Alterations in the firmware region, including the bootloader, change the image and the first two words.
-
User's Data Changes: Modifications in the user's region, such as new settings or stored mnemonics, change the last two words.
-
TC Code Changes: Replacing the TC Code alters the image and all four words.
"},{"location":"getting-started/features/tamper-detection/#filling-empty-flash-blocks","title":"Filling Empty Flash Blocks","text":"Krux performs a memory sweep while simultaneously capturing a live feed from the camera. Whenever an empty block is found in the flash memory, Krux estimates the image's entropy by evaluating its color variance. Krux waits until minimum threshold is met, then uses the data from the image to fill these empty spaces with rich, random entropy.
"},{"location":"getting-started/features/tamper-detection/#ensuring-tamper-detection","title":"Ensuring Tamper Detection","text":"The TC Flash Hash function securely hashes the combination of the TC Code, UID, and flash content:
hash(TC Code,UID,Flash content) -> Image + Words
Hash properties ensure that without knowing the TC Code, UID, and flash content, an attacker cannot reproduce the TC Flash Hash results.
"},{"location":"getting-started/features/tamper-detection/#executing-tc-flash-hash","title":"Executing TC Flash Hash","text":"After setting a TC Code user can use the TC Flash Hash feature, available in Tools -> Flash Tools -> TC Flash Hash.
By navigating to Settings -> Security -> TC Flash Hash at Boot, you can set Krux to always require TC Flash Hash verification after device is turned on.
If a wrong TC Code is typed at boot, the device will turn off. As storing code typing attempts count on flash would change its contents, there will be no consequences if wrong TC Code is typed multiple times.
As TC Code verification data is stored in the user's region of memory, TC Flash Hash and TC Code requirement is disabled if the user wipes the device. Flashing an older firmware version will also disable the feature.
"},{"location":"getting-started/features/tamper-detection/#potential-attack-scenarios-and-their-mitigation","title":"Potential Attack Scenarios and Their Mitigation","text":""},{"location":"getting-started/features/tamper-detection/#challenge-for-an-attacker","title":"Challenge for an Attacker","text":"An attacker faces major challenges in replacing the firmware:
-
Lack of Original Flash Data: Without the exact original flash content, the attacker cannot reproduce the correct hash.
-
Sequential Hash Dependency: The hash function processes data sequentially (TC Code, UID, flash content), preventing the attacker from injecting or rearranging data to produce the same hash.
-
One-Way Hash Functions: Cryptographic hash functions like SHA-256 are one-way, making it infeasible to reverse-engineer or manipulate the hash without the original inputs.
"},{"location":"getting-started/features/tamper-detection/#why-tampered-firmware-cannot-bypass-verification","title":"Why Tampered Firmware Cannot Bypass Verification","text":" -
Cannot Reconstruct the Hash: Without the original flash data, the attacker cannot generate the correct hash, even if they know the UID and TC Code after the user enters it.
-
Hash Sensitivity: Any alteration in the flash content changes the hash output, which will be evident through a different image or tamper detection words.
-
Entropy Filling: Filling empty flash blocks with camera-generated entropy leaves no space for malicious code and any changes to these blocks will alter the hash.
"},{"location":"getting-started/features/tamper-detection/#possible-attack-strategies-and-failures","title":"Possible Attack Strategies and Failures","text":" -
Precomputing Hashes: The attacker cannot precompute the correct hash without the TC Code, UID, and exact flash content.
-
Storing Hashes: Storing hash(flash content) is ineffective because the overall hash depends on the sequential combination of TC Code, UID, and flash data.
-
Inserting Malicious Code: Attempting to insert code into empty spaces fails because the entropy filling process and hash verification will detect any changes.
-
Using an SD Card to Store a Copy of Original Flash Content: An attacker could extract an exact copy of the flash contents to an SD card and subsequently install malicious firmware. This firmware could capture the chip's UID and the user's TC Code, then hash the content of the SD card instead of the flash memory. Although this would make the verification process slower, it introduces a potential security risk. To mitigate this vulnerability, it is advisable to avoid performing verifications while an SD card is inserted.
"},{"location":"getting-started/features/tamper-detection/#conclusion","title":"Conclusion","text":"The TC Flash Hash tool significantly enhances security by making it infeasible for attackers to tamper with the firmware without detection. By combining TC Code hashing, filling empty memory with random entropy, and verifying flash integrity through unique images and words, Krux significantly enhances the detection of any tamper attempts.
Note: The strength of this defense strategy depends on maintaining a strong, confidential TC Code and following secure practices when unlocking the device.
"},{"location":"getting-started/features/tinyseed/","title":"Tiny Seed and other metal plates","text":""},{"location":"getting-started/features/tinyseed/#background","title":"Background","text":"The examples below have been created so that you can test the workflow for scanning both 12 and 24 word mnemonics. (Scanning the left plate for a 12 word mnemonic and both plates for 24) The resulting fingerprint from an successful scan is also incldued in the image.
"},{"location":"getting-started/features/tinyseed/#tinyseed","title":"TinySeed","text":""},{"location":"getting-started/features/tinyseed/#onekey-keytag","title":"OneKey KeyTag","text":""},{"location":"getting-started/features/tinyseed/#binary-grid","title":"Binary Grid","text":""},{"location":"getting-started/features/tinyseed/#size-offset-and-padding-reference","title":"Size, Offset and Padding Reference","text":"The general logic for how these are processed is:
- Krux first looks for a square (Which works best if with a well lit square, with clean edges, on a dark background)
- This square is checked and if the ratio of length to height is within a defined range for the given seed type, the square is further processed. (Uses the aspect_high and aspect_low variables)
- An X and Y offset are applied to work out the corner of the seed grid within the seed plate. Some devices like the Maix Amigo use a mirrored coordinate system and some seed types will have a slightly different layout on the front and back of the plate. (Uses the x_offset and y_offset variables, p0 for the front face and p1 for the reverse face)
- The location of each cell within the 12x12 grid is calculated. (This uses the xpad and ypad variables)
- Krux uses the grid created in 4 to evaluate which cells are marked and which are blank, once a seed with a valid checksum is detected, the user can then confirm the dots.
If you have a different type of grid that you want to use, you will need to edit the offsets and padding numbers in tiny_seed.py. (All of the sizes are scaled based on the size of the square detected in step 1...)
You can match the pre-sets for supported key-types to the physical dimensions of the tag as shown below. (The numbers for these offsets are in 1/10th of a millimeter)
"},{"location":"getting-started/features/tools/","title":"Tools","text":"Here are some useful tools that are available as soon as Krux starts! These are offered as a complement to managing your device and wallets.
"},{"location":"getting-started/features/tools/#check-sd-card","title":"Check SD Card","text":"You can check if a SD card can be detected and read by your device and explore its content. If there are too many files to fit on one screen, swipe up or down to navigate between the screens if your device has a touchscreen.
"},{"location":"getting-started/features/tools/#print-test-qr","title":"Print Test QR","text":"Quickly print a test QR code to check and optimize your printer setup.
"},{"location":"getting-started/features/tools/#create-qr-code","title":"Create QR Code","text":"Enter text to create, print or transcribe a QR code that can later be used as an encryption key or passphrase. Swipe left or right to change modes if your device has a touchscreen.
"},{"location":"getting-started/features/tools/#descriptor-addresses","title":"Descriptor Addresses","text":"Verify if an address or list of addresses belong to a wallet without needing to load private keys. Simply load a trusted wallet descriptor from a QR code or SD card.
"},{"location":"getting-started/features/tools/#flash-tools","title":"Flash Tools","text":"Tools to inspect the content of device's flash memory and clear user's area
"},{"location":"getting-started/features/tools/#flash-map","title":"Flash Map","text":"Flash map indicates which memory blocks (4086 Bytes each) are empty. Memory is separated in two regions: Firmware and User's Data. White or colored blocks contain data, while grey blocks are empty.
This is an interesting tool to visualize the effects of filling the memory with ramdom entropy, what is done during the setup of a new TC Code, used with TC Flash Hash tool, described below.
"},{"location":"getting-started/features/tools/#tc-flash-hash","title":"TC Flash Hash","text":"Tamper Check Flash Hash is a tamper detection mechanism that enables you to verify if the flash memory content has been altered. To use it first, need to create a TC Code on Settings -> Security -> Tamper Check Code. TC Flash Hash will hash this code, K210 chip's unique ID and the content of the whole flash memory together and produce an image. The tool generates a unique image and four tamper detection words based on a hash of your TC Code, the device's UID, and the flash content. The flash memory is divided into two regions:
-
Firmware Region: Generates the image and the first two words.
-
User's Region: Generates the last two words.
Learn more about Tamper Check Flash Hash on Tamper Detection
"},{"location":"getting-started/features/tools/#erase-users-data","title":"Erase User's Data","text":"This option permanently removes all stored encrypted mnemonics, settings and TC Code from the device's internal flash memory. It ensures that the data is irrecoverable, making it an adequate measure to take if any important mnemonics were stored with a weak encryption key.
"},{"location":"getting-started/features/tools/#remove-mnemonic","title":"Remove Mnemonic","text":"This option allows you to remove any stored encrypted mnemonic from the device's internal memory or an SD card. For more information, see Krux Encrypted Mnemonics.
When mnemonics are removed from the device's flash memory, Krux will no longer be able to access them. However, as with most operating systems, the data may still be recoverable using specialized tools. If you stored any important keys with a weak encryption key, it is recommended to use the \"Wipe Device\" feature below to ensure that the data is irrecoverable.
When mnemonics are removed from an SD card, Krux will overwrite the region where the encrypted mnemonic was stored with empty data. This makes it more secure to delete mnemonics from SD cards using Krux rather than a PC or another device. However, Krux does not have a \"Wipe\" feature for SD cards; you can find this feature in third-party applications.
"},{"location":"getting-started/installing/from-pre-built-release/","title":"From pre-built official release","text":"This page explains how to install Krux from an official, pre-built release.
"},{"location":"getting-started/installing/from-pre-built-release/#download-the-latest-release","title":"Download the latest release","text":"Head over to the releases page and download the latest signed release.
"},{"location":"getting-started/installing/from-pre-built-release/#verify-the-files","title":"Verify the files","text":"Before installing the release, it's a good idea to check that:
- The SHA256 hash of
krux-v24.11.1.zip matches the hash in krux-v24.11.1.zip.sha256.txt - The signature file
krux-v24.11.1.zip.sig can be verified with the selfcustody.pem public key found in the root of the krux repository.
You can either do this manually or with the krux shell script, which contains helper commands for this:
### Using krux script ###\n# Hash checksum\n./krux sha256 krux-v24.11.1.zip\n# Signature\n./krux verify krux-v24.11.1.zip selfcustody.pem\n\n### Manually ###\n# Hash checksum\nsha256sum krux-v24.11.1.zip.sha256.txt -c\n#Signature\nopenssl sha256 <krux-v24.11.1.zip -binary | openssl pkeyutl -verify -pubin -inkey selfcustody.pem -sigfile krux-v24.11.1.zip.sig\n
On Mac you may need to install coreutils to be able to use sha256sum
brew install coreutils\n
Fun fact: Each Krux release is signed with Krux!
"},{"location":"getting-started/installing/from-pre-built-release/#flash-the-firmware-onto-the-device","title":"Flash the firmware onto the device","text":"Extract the latest version of Krux you downloaded and enter the folder:
unzip krux-v24.11.1.zip && cd krux-v24.11.1\n
Connect the device to your computer via USB (for Maix Amigo, make sure you\u2019re using bottom port), power it on, and run the following, replacing DEVICE with either m5stickv, amigo, bit, cube, dock or yahboom (to yahboom you may need to manually specify the port, for example /dev/ttyUSB0 on Linux or COM6 on Windows):
./ktool -B goE -b 1500000 maixpy_DEVICE/kboot.kfpkg\n
For dock use the -B dan parameter:
./ktool -B dan -b 1500000 maixpy_dock/kboot.kfpkg\n
When the flashing process completes, you should see the Krux logo:
If it doesn't, try turning your device off and on by holding down the power button for six seconds.
Congrats, you're now running Krux!
"},{"location":"getting-started/installing/from-pre-built-release/#a-note-about-the-maix-amigo","title":"A note about the Maix Amigo","text":"Some Amigo screens have inverted X coordinates, others display colors differently. For more info see Troubleshooting.
"},{"location":"getting-started/installing/from-pre-built-release/#troubleshooting","title":"Troubleshooting","text":"If ktool fails to run, you may need to give it executable permissions with chmod +x ./ktool, or you might need to use \"sudo\" if your user don't have access to serial port. In Windows or Mac you may need to explicitly allow the tool to run by adding an exception for it.
If the flashing process fails midway through, check the connection, restart the device, and try the command again.
Two serial ports are created when Amigo and Bit are connected to a PC. Sometimes Ktool will pick the wrong port and flashing will fail. Manually specify the serial port to overcome this issue using -p argument:
"},{"location":"getting-started/installing/from-pre-built-release/#linux","title":"Linux","text":"See the correct port using ls /dev/ttyUSB*, in the example below we use /dev/ttyUSB0:
./ktool-linux -B goE -b 1500000 maixpy_amigo/kboot.kfpkg -p /dev/ttyUSB1\n
"},{"location":"getting-started/installing/from-pre-built-release/#windows","title":"Windows","text":"See the correct port at Device Manager > Ports (COM & LPT), in the example below we use COM6:
.\\ktool-win.exe -B goE -b 1500000 maixpy_amigo\\kboot.kfpkg -p COM6\n
"},{"location":"getting-started/installing/from-pre-built-release/#mac","title":"Mac","text":"Remove the Gatekeeper quarantine extended attribute from ktool-mac:
xattr -d com.apple.quarantine ktool-mac\n
See the correct port using the command line: ls /dev/cu.usbserial*, in the example below we use /dev/cu.usbserial-10 (If the output isn't what you expect try a different cable, preferably a smartphone usb-c charger cable):
./ktool-mac -B goE -b 1500000 maixpy_amigo/kboot.kfpkg -p /dev/cu.usbserial-10\n
Different OS versions may have different port names, and the absence of ports may indicate a connection, driver or hardware related issue. See Troubleshooting for more info.
"},{"location":"getting-started/installing/from-pre-built-release/#multilingual-support","title":"Multilingual support","text":"Prefer a different language? Krux has support for multiple languages. Once at the start screen, go to Settings, followed by Locale, and select the locale you wish to use.
"},{"location":"getting-started/installing/from-pre-built-release/#upgrade-via-microsd-card","title":"Upgrade via microSD card","text":"Once you've installed the initial firmware on your device via USB, you can either continue updating the device by flashing or you can perform upgrades via microSD card to keep the device airgapped.
"},{"location":"getting-started/installing/from-source/","title":"From source","text":"This page explains how to install Krux from source. You can check a simplified version of these instructions in our README too.
"},{"location":"getting-started/installing/from-source/#fetch-the-code","title":"Fetch the code","text":"This will download the source code of Krux as well as the code of all its dependencies inside a new folder called krux (needs git):
git clone --recurse-submodules https://github.com/selfcustody/krux\n
Note: When you wish to pull updates (to all submodules, their submodules, ...) to this repo, use:
git pull origin main && git submodule update --init --recursive\n
"},{"location":"getting-started/installing/from-source/#prerequisite-for-upgrading-via-microsd","title":"Prerequisite for upgrading via microSD","text":"If you wish to perform airgapped upgrades via microSD card later, you will need to have a private and public key pair to sign your builds and verify the signatures. If you do not want to perform further airgapped upgrades, jump to build section.
You can use an existing Krux installation and mnemonic to sign your builds with, or you can generate a keypair and sign from the openssl CLI. Commands have been added to the krux shell script to make this easier.
In either case, you will need to update the SIGNER_PUBKEY field in src/krux/metadata.py to store your public key so that Krux can verify future builds before installing.
To generate a keypair:
./krux generate-keypair\n./krux pem-to-pubkey pubkey.pem\n
The first command will create privkey.pem and pubkey.pem files you can use with openssl, and the second command will output your public key in the form expected by Krux.
Once you've updated the SIGNER_PUBKEY with this value, you can proceed with the regular build process.
"},{"location":"getting-started/installing/from-source/#build-the-firmware-linux-or-wsl","title":"Build the firmware (Linux or WSL)","text":"The krux bash script contains commands for common development tasks. It assumes a Linux host, you will need to have Docker Desktop or Docker Engine, openssl, and wget installed at a minimum for the commands to work as expected. It works on Windows using WSL. The channel Crypto Guide from Youtube made a step-by-step video - Krux DIY Bitcoin Signer: Build From Source & Verify (With Windows + WSL2 + Docker)
To build and flash the firmware:
# build firmware for Maix Amigo\n./krux build maixpy_amigo\n
The first time, the build can take around an hour or so to complete. Subsequent builds should take only a few minutes. If all goes well, you should see a new build folder containing firmware.bin and kboot.kfpkg files when the build completes.
Note: if you encounter any of these errors while building, it is a problem connecting to github, try again (if the error persists, try changing the DNS/VPN or correcting the hostname resolution of github.com to an IP that is working for you):
error: RPC failed; curl 92 HTTP/2 stream 0 was not closed cleanly: CANCEL (err8)\nfatal: the remote end hung up unexpectedly\nfatal: early EOF\nfatal: index-pack failed\nfatal: clone of ... failed\nFailed to clone ...\n
"},{"location":"getting-started/installing/from-source/#reproducibility","title":"Reproducibility","text":"If you build from the main branch of the source code, you should be able to reproduce the build process used to generate the latest release binaries and obtain exactly the same copies of the firmware.bin and kboot.kfpkg files, with matching hash checksums (to check for an older version, use the tag instead).
To check, use the compiled files for the target device. Each command should output the same hash for the two provided files:
sha256sum build/firmware.bin krux-v24.11.1/maixpy_DEVICE/firmware.bin\nsha256sum build/kboot.kfpkg krux-v24.11.1/maixpy_DEVICE/kboot.kfpkg\n
If you want to extract and verify the firmware.binfile contained in kboot.kfpkg, use the following:
unzip kboot.kfpkg -d ./kboot/\n
"},{"location":"getting-started/installing/from-source/#flash-the-firmware-onto-the-device","title":"Flash the firmware onto the device","text":"Connect the device to your computer via USB (for Maix Amigo, make sure you\u2019re using bottom port), power it on, and run the following, replacing DEVICE with either m5stickv, amigo, bit, cube, dock or yahboom:
# flash firmware to DEVICE\n./krux flash maixpy_DEVICE\n
If flashing fails try reading Troubleshooting When the flashing process completes, you should see the Krux logo:
If it doesn't, try turning your device off and on by holding down the power button for six seconds.
Congrats, you're now running Krux!
"},{"location":"getting-started/installing/from-source/#a-note-about-the-maix-amigo","title":"A note about the Maix Amigo","text":"Some Amigo screens have inverted X coordinates, others display colors differently. For more info see Troubleshooting.
"},{"location":"getting-started/installing/from-source/#signing-the-firmware","title":"Signing the firmware","text":"You can sign the firmware to perform airgapped upgrades using one of the two methods listed below:
"},{"location":"getting-started/installing/from-source/#method-1-signing-from-krux","title":"Method 1: Signing from Krux","text":"First, calculate the SHA256 hash of the new firmware by running:
./krux sha256 build/firmware.bin\n
Copy this hex string and turn it into a QR code using whichever QR code generator you'd like.
In Krux, enter the mnemonic of your private key that will be used for signing, and go to Sign > Message. Scan the QR code you generated, and you will be asked if you wish to sign the hash. Proceed, and you will be presented with a base64-encoded string containing the signature, as text and as a QR code.
Take this string and create a signature file by running:
./krux b64decode \"signature-in-base64\" > build/firmware.bin.sig\n
This will generate a firmware.bin.sig file containing a signature of the firmware's SHA256 hash.
"},{"location":"getting-started/installing/from-source/#method-2-signing-from-your-computer-with-openssl","title":"Method 2: Signing from your computer with OpenSSL","text":"With the keypair you generated before, you can now run:
./krux sign build/firmware.bin privkey.pem\n
This will generate a firmware.bin.sig file containing a signature of the firmware's SHA256 hash.
"},{"location":"getting-started/installing/from-test-release/","title":"From pre-built test release","text":"This page explains how to install Krux from a test (beta), pre-built release.
"},{"location":"getting-started/installing/from-test-release/#warning","title":"Warning","text":"Keep in mind that these are unsigned binaries.
"},{"location":"getting-started/installing/from-test-release/#download","title":"Download","text":"Download experimental compiled firmware or the Android app apk from our test (beta) repository.
"},{"location":"getting-started/installing/from-test-release/#android","title":"Android","text":"The Krux Android app is designed for learning about Krux and Bitcoin air-gapped transactions. Due to the numerous potential vulnerabilities inherent in smartphones, such as the lack of control over the operating system, libraries, and hardware peripherals, the Krux app should NOT be used to manage wallets containing savings or important keys and mnemonics. For secure management of your keys, a dedicated device is recommended.
"},{"location":"getting-started/installing/from-test-release/#compiled-firmware-for-kendryte-k210-devices","title":"Compiled firmware for Kendryte K210 devices","text":""},{"location":"getting-started/installing/from-test-release/#m5stickv","title":"M5StickV","text":"To Flash M5StickV run the following.
"},{"location":"getting-started/installing/from-test-release/#linux","title":"Linux","text":"./ktool-linux -B goE -b 1500000 maixpy_m5stickv/kboot.kfpkg\n
"},{"location":"getting-started/installing/from-test-release/#mac","title":"Mac","text":"./ktool-mac -B goE -b 1500000 maixpy_m5stickv/kboot.kfpkg\n
"},{"location":"getting-started/installing/from-test-release/#windows","title":"Windows","text":".\\ktool-win.exe -B goE -b 1500000 maixpy_m5stickv\\kboot.kfpkg\n
"},{"location":"getting-started/installing/from-test-release/#sipeed-maix-amigo","title":"Sipeed Maix Amigo","text":"To Flash Maix Amigo run the following.
"},{"location":"getting-started/installing/from-test-release/#linux_1","title":"Linux","text":"./ktool-linux -B goE -b 1500000 maixpy_amigo/kboot.kfpkg\n
"},{"location":"getting-started/installing/from-test-release/#mac_1","title":"Mac","text":"./ktool-mac -B goE -b 1500000 maixpy_amigo/kboot.kfpkg\n
"},{"location":"getting-started/installing/from-test-release/#windows_1","title":"Windows","text":".\\ktool-win.exe -B goE -b 1500000 maixpy_amigo\\kboot.kfpkg\n
"},{"location":"getting-started/installing/from-test-release/#a-note-about-the-maix-amigo","title":"A note about the Maix Amigo","text":"Some Amigo screens have inverted X coordinates, others display colors differently. For more info see Troubleshooting.
"},{"location":"getting-started/installing/from-test-release/#sipeed-maix-bit","title":"Sipeed Maix Bit","text":"To Flash Maix Bit run the following.
"},{"location":"getting-started/installing/from-test-release/#linux_2","title":"Linux","text":"./ktool-linux -B goE -b 1500000 maixpy_bit/kboot.kfpkg\n
"},{"location":"getting-started/installing/from-test-release/#mac_2","title":"Mac","text":"./ktool-mac -B goE -b 1500000 maixpy_bit/kboot.kfpkg\n
"},{"location":"getting-started/installing/from-test-release/#windows_2","title":"Windows","text":".\\ktool-win.exe -B goE -b 1500000 maixpy_bit\\kboot.kfpkg\n
"},{"location":"getting-started/installing/from-test-release/#sipeed-maix-cube","title":"Sipeed Maix Cube","text":"To Flash Maix Cube run the following.
"},{"location":"getting-started/installing/from-test-release/#linux_3","title":"Linux","text":"./ktool-linux -B goE -b 1500000 maixpy_cube/kboot.kfpkg\n
"},{"location":"getting-started/installing/from-test-release/#mac_3","title":"Mac","text":"./ktool-mac -B goE -b 1500000 maixpy_cube/kboot.kfpkg\n
"},{"location":"getting-started/installing/from-test-release/#windows_3","title":"Windows","text":".\\ktool-win.exe -B goE -b 1500000 maixpy_cube\\kboot.kfpkg\n
"},{"location":"getting-started/installing/from-test-release/#sipeed-maix-dock","title":"Sipeed Maix Dock","text":"To Flash Maix Dock you need to pass the -B dan parameter.
"},{"location":"getting-started/installing/from-test-release/#linux_4","title":"Linux","text":"./ktool-linux -B dan -b 1500000 maixpy_dock/kboot.kfpkg\n
"},{"location":"getting-started/installing/from-test-release/#mac_4","title":"Mac","text":"./ktool-mac -B dan -b 1500000 maixpy_dock/kboot.kfpkg\n
"},{"location":"getting-started/installing/from-test-release/#windows_4","title":"Windows","text":".\\ktool-win.exe -B dan -b 1500000 maixpy_dock\\kboot.kfpkg\n
"},{"location":"getting-started/installing/from-test-release/#aimotion-yahboom-k210-module","title":"Aimotion Yahboom k210 module","text":"To Flash Yahboom k210 module you'll have to manually specify the port.
"},{"location":"getting-started/installing/from-test-release/#linux_5","title":"Linux","text":"See the correct port using ls /dev/ttyUSB*, in the example below we use /dev/ttyUSB0:
./ktool-linux -B goE -b 1500000 -p /dev/ttyUSB0 maixpy_yahboom/kboot.kfpkg\n
"},{"location":"getting-started/installing/from-test-release/#mac_5","title":"Mac","text":"See the correct port using the command line: ls /dev/cu.usbserial*, in the example below we use /dev/cu.usbserial-10:
./ktool-mac -B goE -b 1500000 -p /dev/cu.usbserial-10 maixpy_yahboom/kboot.kfpkg\n
"},{"location":"getting-started/installing/from-test-release/#windows_5","title":"Windows","text":"See the correct port at Device Manager > Ports (COM & LPT), in the example below we use COM6:
.\\ktool-win.exe -B goE -b 1500000 -p COM6 maixpy_yahboom\\kboot.kfpkg\n
"},{"location":"getting-started/installing/","title":"Installing","text":"You can install Krux in four different ways:
- From GUI application
- From pre-built official release
- From pre-built test (beta) release
- From source
"},{"location":"getting-started/installing/#requirements","title":"Requirements","text":"Please, check the parts list for the compatible devices and requirements.
After the first firmware install, you can use a microSD card if you wish to perform further airgapped updates.
"},{"location":"getting-started/installing/from-gui/debian-like/","title":"Download assets","text":" krux-installer_0.0.20-beta_amd64.debkrux-installer_0.0.20-beta_amd64.deb.sha256.txtkrux-installer_0.0.20-beta_amd64.deb.sig
"},{"location":"getting-started/installing/from-gui/debian-like/#verify-the-integrity","title":"Verify the integrity","text":"Open your terminal and type the command below:
sha256sum --check ./krux-installer_0.0.20-beta_amd64.deb.sha256.txt\n
"},{"location":"getting-started/installing/from-gui/debian-like/#verify-the-authenticity","title":"Verify the authenticity","text":"The first step is import the developer's key:
gpg --keyserver hkps://keys.openpgp.org --recv-keys B4281DDDFBBD207BFA4113138974C90299326322\n
Then, to verify yourself, run this command on your terminal:
gpg --verify ./krux-installer_0.0.20-beta_amd64.deb.sig\n
\u26a0\ufe0f TIP: If the verification was successful, you may get a message similar to: Good signature from \"qlrddev <qlrddev@gmail.com>\"
"},{"location":"getting-started/installing/from-gui/debian-like/#install","title":"Install","text":"krux-installer isn't available on Debian or Ubuntu repositories. Therefore, only the apt-get install command will not work. To install, it'll be necessary two steps:
- Install the .deb package itself:
sudo dpkg -i krux-installer_0.0.20-beta_amd64.deb\n
- Update the installed package:
sudo apt-get install -f\n
It will warn you that your system user was added to dialout group and maybe you need to reboot to activate the sudoless flash procedure.
"},{"location":"getting-started/installing/from-gui/debian-like/#after-install","title":"After install","text":""},{"location":"getting-started/installing/from-gui/fedora-like/","title":"Download assets","text":" krux-installer-0.0.20_beta-1.x86_64.rpmkrux-installer-0.0.20_beta-1.x86_64.rpm.sha256.txtkrux-installer-0.0.20_beta-1.x86_64.rpm.sig
"},{"location":"getting-started/installing/from-gui/fedora-like/#verify-the-integrity","title":"Verify the integrity","text":"Open your terminal and type the command below:
sha256sum --check ./krux-installer-0.0.20_beta-1.x86_64.rpm.sha256.txt\n
"},{"location":"getting-started/installing/from-gui/fedora-like/#verify-the-authenticity","title":"Verify the authenticity","text":"The first step is import the developer's key:
gpg --keyserver hkps://keys.openpgp.org --recv-keys B4281DDDFBBD207BFA4113138974C90299326322\n
Then, to verify yourself, run this command on your terminal:
gpg --verify ./krux-installer-0.0.20_beta-1.x86_64.rpm.sig\n
\u26a0\ufe0f TIP: If the verification was successful, you may get a message similar to: Good signature from \"qlrddev <qlrddev@gmail.com>\"
"},{"location":"getting-started/installing/from-gui/fedora-like/#install","title":"Install","text":"krux-installer isn't available on Fedora or RedHat repositories. You'll need to add it manually:
"},{"location":"getting-started/installing/from-gui/fedora-like/#fedora","title":"Fedora","text":"sudo dnf install krux-installer-0.0.20_beta-1.x86_64.rpm\n
"},{"location":"getting-started/installing/from-gui/fedora-like/#other-redhat-based-distros","title":"Other RedHat based distros:","text":"sudo yum localinstall krux-installer-0.0.20_beta-1.x86_64.rpm\n
It will warn you that your system user was added to dialout group and maybe you need to reboot to activate the sudoless flash procedure.
"},{"location":"getting-started/installing/from-gui/fedora-like/#after-install","title":"After install","text":""},{"location":"getting-started/installing/from-gui/","title":"From GUI application","text":"You can install Krux (both official or beta releases) onto your K210-based device using our official desktop application, KruxInstaller, available for:
\u26a0\ufe0f WARNING: Krux-Installer latest version is in it's alpha version. Maybe you can experience bugs or don't like something. If it is the case, please submit a issue.
- Windows
- MacOS Intel
- MacOS M1/M2/M3
- Debian and like
- Fedora and like
- Other linux distros
"},{"location":"getting-started/installing/from-gui/macos-arm64/","title":"Download assets","text":" krux-installer_0.0.20-beta_arm64.dmgkrux-installer_0.0.20-beta_arm64.dmg.sha256.txtkrux-installer_0.0.20-beta_arm64.dmg.sig
"},{"location":"getting-started/installing/from-gui/macos-arm64/#verify-the-integrity","title":"Verify the integrity","text":"Open your terminal and type the command below:
sha256sum --check ./krux-installer_0.0.20-beta_arm64.dmg.sha256.txt\n
"},{"location":"getting-started/installing/from-gui/macos-arm64/#verify-the-authenticity","title":"Verify the authenticity","text":"The first step is import the developer's key:
gpg --keyserver hkps://keys.openpgp.org --recv-keys B4281DDDFBBD207BFA4113138974C90299326322\n
Then, to verify yourself, run this command on your terminal:
gpg --verify ./krux-installer_0.0.20-beta_arm64.dmg.sig\n
\u26a0\ufe0f TIP: If the verification was successful, you may get a message similar to: Good signature from \"qlrddev <qlrddev@gmail.com>\"
"},{"location":"getting-started/installing/from-gui/macos-arm64/#install","title":"Install","text":"Open the dmg file and a new volume will be presented; drag'n'drop the krux-installer to the Applications folder:
Before run, you'll need to remove the quarantine flag from application. This occurs because we don't added the Apple's code signing and notarization.
To fix this, open your terminal and execute the following command:
xattr -d com.apple.quarantine -r /Applications/krux-installer.app\n
\ud83d\udee1\ufe0f TIP: If you followed the steps presented in authenticity section, you already have the assurance that the software is from a verified and genuine software publisher. This will also help establish a chain of trust when you perform the firmware verification step before flashing.
"},{"location":"getting-started/installing/from-gui/macos-arm64/#after-install","title":"After install","text":""},{"location":"getting-started/installing/from-gui/macos-intel/","title":"Download assets","text":" krux-installer_0.0.20-beta_x86_64.dmgkrux-installer_0.0.20-beta_x86_64.dmg.sha256.txtkrux-installer_0.0.20-beta_x86_64.dmg.sig
"},{"location":"getting-started/installing/from-gui/macos-intel/#verify-the-integrity","title":"Verify the integrity","text":"Open your terminal and type the command below:
sha256sum --check ./krux-installer_0.0.20-beta_x86_64.dmg.sha256.txt\n
"},{"location":"getting-started/installing/from-gui/macos-intel/#verify-the-authenticity","title":"Verify the authenticity","text":"The first step is import the developer's key:
gpg --keyserver hkps://keys.openpgp.org --recv-keys B4281DDDFBBD207BFA4113138974C90299326322\n
Then, to verify yourself, run this command on your terminal:
gpg --verify ./krux-installer_0.0.20-beta_x86_64.dmg.sig\n
\u26a0\ufe0f TIP: If the verification was successful, you may get a message similar to: Good signature from \"qlrddev <qlrddev@gmail.com>\"
"},{"location":"getting-started/installing/from-gui/macos-intel/#install","title":"Install","text":"Open the dmg file and a new volume will be presented; drag'n'drop the krux-installer to the Applications folder:
Before run, you'll need to remove the quarantine flag from application. This occurs because we don't added the Apple's code signing and notarization.
To fix this, open your terminal and execute the following command:
xattr -d com.apple.quarantine -r /Applications/krux-installer.app\n
\ud83d\udee1\ufe0f TIP: If you followed the steps presented in authenticity section, you already have the assurance that the software is from a verified and genuine software publisher. This will also help establish a chain of trust when you perform the firmware verification step before flashing.
"},{"location":"getting-started/installing/from-gui/macos-intel/#after-install","title":"After install","text":""},{"location":"getting-started/installing/from-gui/other-linux-distro/","title":"Download assets","text":"For this installation, we'll use the .deb sources:
krux-installer_0.0.20-beta_amd64.debkrux-installer_0.0.20-beta_amd64.deb.sha256.txtkrux-installer_0.0.20-beta_amd64.deb.sig
"},{"location":"getting-started/installing/from-gui/other-linux-distro/#verify-the-integrity","title":"Verify the integrity","text":"Open your terminal and type the command below:
sha256sum --check ./krux-installer_0.0.20-beta_amd64.deb.sha256.txt\n
"},{"location":"getting-started/installing/from-gui/other-linux-distro/#verify-the-authenticity","title":"Verify the authenticity","text":"The first step is import the developer's key:
gpg --keyserver hkps://keys.openpgp.org --recv-keys B4281DDDFBBD207BFA4113138974C90299326322\n
Then, to verify yourself, run this command on your terminal:
gpg --verify ./krux-installer_0.0.20-beta_amd64.deb.sig\n
\u26a0\ufe0f TIP: If the verification was successful, you may get a message similar to: Good signature from \"qlrddev <qlrddev@gmail.com>\"
"},{"location":"getting-started/installing/from-gui/other-linux-distro/#install","title":"Install","text":"This step it's not really an installation. At least it will make the program's binary available somewhere on your computer; it can be useful if you want to develop a package for your distro.
To do this you'll need two tools:
ar;bsdtar.
"},{"location":"getting-started/installing/from-gui/other-linux-distro/#extract-contents","title":"Extract contents","text":" - Extract the
.deb contents:
ar xv krux-installer_0.0.20-beta_amd64.deb\n
- Extract the
data.tar.zst contents:
bsdtar -xvf data.tar.zst\n
The binary will be located at ./usr/local/bin/krux-installer.
"},{"location":"getting-started/installing/from-gui/usage/","title":"Usage","text":"This guide will walk through the basic use of the installer. At startup, it can differ in some operational systems. In the rest, the procedures will be similar.
"},{"location":"getting-started/installing/from-gui/usage/#main-menu","title":"Main Menu","text":"When executing the Krux Installer, you will be presented with a menu of 4 enabled buttons and two disabled buttons:
-
Enabled buttons:
-
Version: select a firmware version;
-
Device: select a supported device for the selected version;
-
Settings: change some application settings;
-
About: just show some information about the application.
-
Disabled buttons:
-
Flash firmware: This button will start the flash firmware procedure;
- It will be enabled when user select both version and device;
-
Wipe device: This button will start the wipe device procedure.
- It will be enabled when user select the device.
"},{"location":"getting-started/installing/from-gui/usage/#select-version","title":"Select version","text":"At startup, the application will setup it to the latest one, krux-v24.11.1. But you can select even a beta release or older versions:
-
Click in the button that show the text Version: krux-v24.11.1;
-
To select a beta release, click on button that show the text odudex/krux_binaries;
-
To select an older version, click on button that show the text Old versions;
"},{"location":"getting-started/installing/from-gui/usage/#beta-release","title":"Beta release","text":"After choose odudex/krux_binaries, you'll be warned with a message:
"},{"location":"getting-started/installing/from-gui/usage/#older-versions","title":"Older versions","text":" - We put this option in case you have any interest in the history of firmware development;
-
Each version supports one device or the other;
-
For example: the version v22.03.0 has support only for m5stickv.
"},{"location":"getting-started/installing/from-gui/usage/#settings","title":"Settings","text":"krux-Installer will give to you some freedom of choices for:
-
Krux-Installer settings;
-
General settings;
"},{"location":"getting-started/installing/from-gui/usage/#krux-installer-specific-settings","title":"krux-installer specific settings","text":"Here you can configure some of the specifics of krux firmare, like:
-
Where you'll save downloaded assets;
-
The flash baudrate
-
The natural language that will be used in the application (system locale).
"},{"location":"getting-started/installing/from-gui/usage/#flash-baudrate","title":"Flash baudrate","text":"The flash baudrate is how quickly the firmware will be written to the device.
But not any value can be used. The valid ones are: 9600, 19200, 28800, 38400, 57600, 76800, 115200, 230400, 460800, 576000, 921600, 1500000.
"},{"location":"getting-started/installing/from-gui/usage/#system-locale","title":"System locale","text":"At startup, krux-installer recognize the locale used in your system. If your language isn't supported, it will defaults to en_US.
"},{"location":"getting-started/installing/from-gui/usage/#select-device","title":"Select Device","text":"Everytime you select a new version, you'll see that the device button will be reseted to Device: select a new one state. Once a version is selected you can choose a device on which the firmware will be written.
First, select the device we want to flash. After that the menu will shown three items:
Note that some devices may be disabled if they are not supported by the chosen version
"},{"location":"getting-started/installing/from-gui/usage/#flash-device","title":"Flash device","text":"Once you choose the device and version, it enables the \"flash device\" button. It will start an automatic process of:
-
For official firmware's releases:
-
Warning;
-
Download;
-
Verification:
-
Unzip the correct firmware;
-
Flash:
-
The flash itself via USB;
-
Air-gapped update via SD card;
-
For beta releases:
-
Download asset;
-
The flash itself;
"},{"location":"getting-started/installing/from-gui/usage/#warning","title":"Warning","text":"If you already downloaded assets, you'll be warned about this and will be offered the possibility to download again or continue without downloading:
"},{"location":"getting-started/installing/from-gui/usage/#download","title":"Download","text":"Krux-installer download can download four assets for official releases or one for beta releases.
"},{"location":"getting-started/installing/from-gui/usage/#official-releases","title":"Official releases","text":" -
A zip file containing all firmwares for each device;
-
Download a zip.sha256.txt file containing a zip's digital fingerprint;
-
Download a zip.sig file containing a zip's digital signature;
-
Download the selfcustody.pem file containing a public key certificate, signed by odudex;
"},{"location":"getting-started/installing/from-gui/usage/#beta-releases","title":"Beta releases","text":" - A
kfpkg file containing the specific firmware for choosen device;
"},{"location":"getting-started/installing/from-gui/usage/#verification","title":"Verification","text":" -
Integrity verification compares the computed hash of zip against thei provided zip.sha256.txt;
-
Authenticity verification check if the zip file was really signed by odudex, using the zip.sig and selfcustody.pem.
"},{"location":"getting-started/installing/from-gui/usage/#unzip","title":"Unzip","text":"Now you will be able to select if you do a flash process or need to do an airgap process:
Click on Flash with to install via USB or Air-gapped update with to perform upgrades via a SD card.
"},{"location":"getting-started/installing/from-gui/usage/#flash-with","title":"Flash with","text":"When flash starts, it will warn you to not disconnect the device until the process is complete. You'll be able to see the flash progress:
\u26a0\ufe0f TIP: You must connect and turn on your device before click extract and flashing starts!.
As well a done icon:
\u26a0\ufe0f TIP: When the flashing process completes, you should see the Krux logo:
If it doesn't, try turning your device off and on by holding down the power button for six seconds.
Congrats, you're now running Krux!
"},{"location":"getting-started/installing/from-gui/usage/#air-gapped-update-with","title":"Air-gapped update with","text":"Once you've installed the initial firmware on your device via USB, you can perform upgrades via SD card to keep the device airgapped.
\u26a0\ufe0f Click on \"Air-gapped update with\"
Once the firmware.bin and firmware.bin.sig are extracted, you'll see a warning message.
Insert the SD card and click 'Proceed' to allow the installer to detect it.
\u26a0\ufe0f If a single SD card is inserted, the screen will display a large button. If multiple removable drives are detected, both SD cards and other drives will be listed.
Select the desired removable drive to copy both firmware.bin and firmware.bin.sig. The first is the Krux firmware, and the second is a signature file that verifies the firmware\u2019s integrity and authenticity.
Now you can compare the firmware's hash computed by installer with the firmware's hash computed by the device.
\u26a0\ufe0f Once files are copied, remove the SD card from computer, connect to device and compare the hashes
"},{"location":"getting-started/installing/from-gui/usage/#wipe-device","title":"Wipe device","text":"This is two step process:
-
Warning
-
Wipe
"},{"location":"getting-started/installing/from-gui/usage/#warning_1","title":"Warning","text":"Before the wipe starts, it will show to you a message:
\u26a0\ufe0f TIP: It's useful when your device is not working or for security reasons. To use Krux again, you'll need to re-flash the firmware.
"},{"location":"getting-started/installing/from-gui/usage/#wipe","title":"Wipe","text":"Once the process starts, the screen will appear frozen and a spinner will keep moving. When it's done, you can scroll down you will see a check icon.
\u26a0\ufe0f TIP: Do not unplug or poweroff your device or computer. Wait until the process finishes.
"},{"location":"getting-started/installing/from-gui/usage/#tips-after-install","title":"Tips after install","text":""},{"location":"getting-started/installing/from-gui/usage/#multilingual-support","title":"Multilingual support","text":"Prefer a different language? Krux has support for multiple languages. Once at the start screen, go to Settings, followed by Locale, and select the locale you wish to use.
"},{"location":"getting-started/installing/from-gui/usage/#upgrade-via-microsd-card","title":"Upgrade via microSD card","text":"Once you've installed the initial firmware on your device via USB, you can either continue updating the device by flashing or you can perform upgrades via microSD card to keep the device airgapped.
"},{"location":"getting-started/installing/from-gui/windows/","title":"Download assets","text":" krux-installer_v0.0.20-beta.Setup.exekrux-installer_v0.0.20-beta.Setup.exe.sha256.txtkrux-installer_v0.0.20-beta.Setup.exe.sig
"},{"location":"getting-started/installing/from-gui/windows/#verify-the-integrity","title":"Verify the integrity","text":"Open your terminal and type the command below:
(Get-FileHash '.\\krux-installer_v0.0.20-beta.Setup.exe').Hash.ToLower() -eq (Get-Content '.\\krux-installer_v0.0.20-beta.Setup.exe.sha256.txt').split(\" \")[0]\n
The result in prompt should be True.
Alternatively, you can check more closely in two steps:
- Compute the binary sha256sum hash:
# Option 1: Compute in default way\nGet-FileHash '.\\krux-installer_v0.0.20-beta.Setup.exe'\n\n# Option 2: Compute and filter the necessary information\n(Get-FileHash '.\\krux-installer_v0.0.20-beta.Setup.exe').Hash\n\n# Option 3: Compute, filter and process the Hash for lowercase letters\n(Get-FileHash '.\\krux-installer_v0.0.20-beta.Setup.exe').Hash.ToLower()\n
- Compare with provided hash:
# Option 1: Get content \nGet-Content '.\\krux-installer_v0.0.20-beta.Setup.exe.sha256.txt'\n\n# Option 2: Get content and filter the necessary information\n(Get-Content '.\\krux-installer_v0.0.20-beta.Setup.exe.sha256.txt').split(\" \")[0]\n
"},{"location":"getting-started/installing/from-gui/windows/#verify-the-authenticity","title":"Verify the authenticity","text":" - You'll need have GPG installed;
- We recommend installing GPG4Win.
The first step is import the developer's key:
gpg --keyserver hkps://keys.openpgp.org --recv-keys B4281DDDFBBD207BFA4113138974C90299326322\n
Then, to verify yourself, run this command on your terminal:
gpg --verify ./krux-installer_v0.0.20-beta.Setup.exe.sig\n
\u26a0\ufe0f TIP: If the verification was successful, you may get a message similar to: Good signature from \"qlrddev <qlrddev@gmail.com>\"
"},{"location":"getting-started/installing/from-gui/windows/#install","title":"Install","text":"Execute the krux-installer_v0.0.20-beta.Setup.exe. You'll be faced with a blue window saying \"Windows protected your PC\". This occurs because we don't have a code signing certificate:
\ud83d\udee1\ufe0f TIP: If you followed the steps presented in authenticity section, you already have the assurance that the software is from a verified and genuine software publisher. This will also help establish a chain of trust when you perform the firmware verification step before flashing.
Follow the installer's instructions to complete the installation. At the end, click on \"Create desktop icon\":
"},{"location":"getting-started/installing/from-gui/windows/#after-install","title":"After install","text":""},{"location":"getting-started/templates/templates/","title":"Templates","text":""},{"location":"getting-started/templates/templates/#templates","title":"Templates","text":"Here we offer a few templates to transcribe QR codes, TinySeed or Binary Grid backups.
"},{"location":"getting-started/templates/templates/#qr-code-templates","title":"QR Code Templates","text":"Print the templates in standard, wax or slide paper, make sure the scale is set to 1:1 in printer setup. You can manually copy compact SeedQR codes or place a proper sized template over the device screen. Protect the template backside with a transparent tape so you won't bleed ink through the paper to your device's screen. Then, using a marker, paint the QR code.
Transcribe Templates - pdf
Transcribe Templates - svg
"},{"location":"getting-started/templates/templates/#tinyseed-templates","title":"TinySeed Templates","text":"TinySeed background of blank templates to be manually filled.
"},{"location":"getting-started/templates/templates/#binary-grid-templates","title":"Binary Grid Templates","text":"Binary Grid labeled and and \"stealth\" clean templates
Binary Grid svg source
Binary Grid Clean svg source
"},{"location":"getting-started/templates/templates/#edit-templates","title":"Edit Templates","text":"To edit the source file (.svg) it is recommended to use Inkscape and set it to use mm unit. \"Unscaled models\" from QR code templates have the 21x21 or 25x25mm size for 12 or 24 respectively, this way making them easier to edit.
"},{"location":"getting-started/usage/generating-a-mnemonic/","title":"Generating a Mnemonic","text":"Krux supports creating 12 and 24-word BIP-39 mnemonic seed phrases. Since generating true entropy is challenging, especially with an embedded device, we recommend outsourcing entropy generation using dice rolls. However, it is also possible to randomly pick words (e.g., SeedPicker) or use the camera as a source of entropy to quickly create a mnemonic.
At the start screen, after selecting New Mnemonic, you will be taken to a second menu where you can choose to create a mnemonic via the camera, words, rolls of a D6 (standard six-sided die), or a D20 (20-sided die).
"},{"location":"getting-started/usage/generating-a-mnemonic/#camera","title":"Camera","text":"(Experimental!) Choose between 12, 24 words or double mnemonic, then take a random picture and Krux will generate a mnemonic from the hash of the image bytes.
"},{"location":"getting-started/usage/generating-a-mnemonic/#image-entropy-quality-estimation","title":"Image Entropy Quality Estimation","text":"During image capture, entropy quality estimation is displayed to assist you in obtaining a high-quality image source for your key. After a snapshot is taken, Shannon's entropy and pixel deviation indices are presented. Minimum thresholds are established to prevent the use of poor-quality images with low entropy for key generation. It's important to note that these values serve as indicators or estimations of entropy quality, but they are not absolute entropy values in a cryptographic context.
"},{"location":"getting-started/usage/generating-a-mnemonic/#double-mnemonic","title":"Double mnemonic","text":"It is the combination of two 12-word mnemonics that also forms a valid 24-word BIP-39 mnemonic. This is achieved by using the first 16 bytes (128 bits) of the image's entropy to generate the first 12-word, then using the next 16 bytes to generate the second 12-word and checking if these two 12-word together forms a valid 24-word, if not, we iterate over the second 12-word incrementing its entropy bytes until the two 12-word forms a valid 24-word.
Some might say that the name double mnemonic is incorrect because we end up with two 12-word plus a 24-word mnemonic (12 + 12 + 24), so it's a triple mnemonic! But we only use entropy for the two 12-word ones, hence the name double mnemonic. Also, this name has already been used in this double mnemonic generator since July 2023.
Some may wonder what is the use of this, it may be useful to some plausible deniability or even a way to improve your OPSEC.
"},{"location":"getting-started/usage/generating-a-mnemonic/#words","title":"Words","text":"Print the BIP39 word list in 3D or on paper, then cut out the words and place them in a bucket. Manually draw 11 or 23 words from the bucket. For the final word, Krux will assist you in picking a valid 12th or 24th word by adjusting its smart keypad to only allow typing words with a valid checksum. Alternatively, you can leave it empty, and Krux will select a final, valid checksum word for you.
"},{"location":"getting-started/usage/generating-a-mnemonic/#dice-rolls","title":"Dice Rolls","text":""},{"location":"getting-started/usage/generating-a-mnemonic/#via-d6","title":"Via D6","text":"Choose between 12 or 24 words. The entropy in a single roll of a D6 is 2.585 bits ( log2(6) ); therefore a minimum of a 50 rolls will be required for 128 bits of entropy, enough to generate a 12-word mnemonic. For 24-word, or an entropy of 256 bits, a minimum of 99 rolls will be required.
"},{"location":"getting-started/usage/generating-a-mnemonic/#via-d20","title":"Via D20","text":"Since a D20 has more possible outcomes, the entropy is increased per roll to 4.322 bits ( log2(20) ). This means that only 30 rolls are necessary to create a 12-word mnemonic and 60 rolls for a 24-word mnemonic.
"},{"location":"getting-started/usage/generating-a-mnemonic/#dice-rolls-entropy-quality-estimation","title":"Dice Rolls Entropy Quality Estimation","text":"When you input your dice rolls, you'll see two progress bars filling up. The top progress bar shows how many rolls you've entered compared to the minimum number needed. The bottom progress bar shows the real-time calculated Shannon's entropy compared to the required minimum (128 bits for 12 words and 256 bits for 24 words). When the Shannon's entropy estimation reaches the recommended level, the progress bar will be full, and its frame will change color. If you've met the minimum number of rolls but the entropy estimation is still below the recommended level, a warning will appear, suggesting you add more rolls to increase entropy. Note: Similar to image entropy quality estimation, dice rolls Shannon's entropy serves as an indicator and should not be considered an absolute measure of cryptographic entropy.
Learn more about Krux Entropy Quality Estimation.
"},{"location":"getting-started/usage/generating-a-mnemonic/#stats-for-nerds","title":"Stats for Nerds","text":"A low Shannon's entropy value could suggest that your dice are biased or that there's a problem with how you're gathering entropy. To investigate further, examine the \"Stats for Nerds\" section to check the distribution of your rolls and look for any abnormalities.
"},{"location":"getting-started/usage/generating-a-mnemonic/#editing-a-new-mnemonic-optional","title":"Editing a New Mnemonic - Optional","text":"After entering dice rolls, random words, or captured entropy through the camera, you can manually add custom entropy by editing some of the words. Edited words will be highlighted, and the final word will automatically update to ensure a valid checksum. However, proceed with caution, modifying words can negatively impact the natural entropy previously captured.
"},{"location":"getting-started/usage/generating-a-mnemonic/#how-entropy-capture-works","title":"How Entropy Capture Works","text":"For dice rolls, Krux keeps track of every roll you enter and displays the cumulative string of outcomes after each roll.
When you have entered your final roll, Krux will hash this string using SHA256 and output the resulting hash to the screen so that you can verify it for yourself.
In case a camera snapshot is used as a source, the image bytes, which contain pixels data in RGB565 format, will be hashed in the same way as the dice rolls.
Krux then takes this hash, runs unhexlify on it to encode it as bytes, and deterministically converts it into a mnemonic according to the BIP-39 Reference Implementation.
Note: For 12-word mnemonics, only the first half of the SHA256 hash is used (128 bits), while 24-word mnemonics use the full hash (256 bits).
"},{"location":"getting-started/usage/generating-a-mnemonic/#how-to-verify","title":"How to Verify","text":"Don't trust, verify. We encourage you not to trust any claim you cannot verify yourself. Therefore, there are wallets that use compatible algorithms to calculate the entropy derived from dice rolls. You can use the SeedSigner or Coldcard hardware wallets, or even the Bitcoiner Guide website, they share the same logic that Krux uses and will give the same mnemonic for the dice roll method.
"},{"location":"getting-started/usage/loading-a-mnemonic/","title":"Loading a Mnemonic","text":"Once you have either a 12 or 24-word BIP-39 mnemonic, choose Load Mnemonic on Krux's start menu (aka login menu), and you will be presented with several input methods:
"},{"location":"getting-started/usage/loading-a-mnemonic/#input-methods","title":"Input Methods","text":""},{"location":"getting-started/usage/loading-a-mnemonic/#via-camera","title":"Via Camera","text":"You can choose to use the camera to scan a QR code, Tiny Seed, OneKey KeyTag or a Binary Grid.
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. Some cameras (OV7740, OV2640 and GC2145) have an anti-glare mode to better capture images from high brightness screens or with incident light, they are present on M5StickV, Amigo, Cube and Yahboom. To enable/disable the anti-glare mode on a supported device just press the PAGE button while scanning.
"},{"location":"getting-started/usage/loading-a-mnemonic/#qr-code","title":"QR Code","text":"It's unpleasant having to manually enter 12 or 24 words every time you want to use Krux. To remedy this you can instead use the device's camera to read a QR code containing the words. Krux will decode QR codes of four types:
- Plain text QR: The mnemonic words encoded as text, with words separated by spaces.
- SeedQR: Basically, it is the mnemonic words of the respective BIP-39 numbers concatenated, encoded as text.
- Compact SeedQR: Basically, it is the mnemonic words bits concatenated as bytes.
- Encrypted Mnemonic: A specification created by Krux that encrypts the mnemonic words bits and adds some information about the encryption used.
After opening a wallet via one of the methods available you can use Krux to backup the mnemonic as QR code, transcribe them to paper or metal using the transcription helpers or attach a thermal printer to your Krux and print out the mnemonic as QR. Check out the printing section for more information. You can also use an offline QR code generator for this (ideally on an airgapped device).
"},{"location":"getting-started/usage/loading-a-mnemonic/#tiny-seed-onekey-keytag-or-binary-grid","title":"Tiny Seed, OneKey KeyTag or Binary Grid","text":"Tiny Seed, Onekey KeyTag and others directly encode a seed as binary, allowing for a very compact mnemonic storage. Krux devices have machine vision capabilities that allow users to scan these metal plates and instantly load mnemonics engraved on them (this feature is not available in Krux Android app).
To properly scan, place the backup plate over a black background and paint the punched bits black to increase contrast. You can also scan the thermally printed version, or a filled template. You can find some examples of mnemonics encoded here. Alternatively, you can find templates to scan or print here.
"},{"location":"getting-started/usage/loading-a-mnemonic/#via-manual-input","title":"Via Manual Input","text":"Manually type Words, Word Numbers, Tiny Seed (toggle the bits or punches) or Stackbit 1248.
"},{"location":"getting-started/usage/loading-a-mnemonic/#words","title":"Words","text":"Enter each word of your BIP-39 mnemonic one at a time. Krux will disable impossible-to-reach letters as you type and will attempt to autocomplete your words to speed up the process.
"},{"location":"getting-started/usage/loading-a-mnemonic/#word-numbers","title":"Word Numbers","text":""},{"location":"getting-started/usage/loading-a-mnemonic/#decimal","title":"Decimal","text":"Enter each word of your BIP-39 mnemonic as a number (1-2048) one at a time. You can use this list for reference.
"},{"location":"getting-started/usage/loading-a-mnemonic/#hexadecimal-and-octal","title":"Hexadecimal and Octal","text":"You can also enter your BIP-39 mnemonic word's numbers (1-2048) in hexadecimal format, with values ranging from 0x1 to 0x800, or in octal format, with values ranging from 01 to 04000. This is useful with some metal plate backups that uses those formats.
"},{"location":"getting-started/usage/loading-a-mnemonic/#tiny-seed-bits","title":"Tiny Seed (Bits)","text":"Enter the BIP-39 mnemonic word's numbers (1-2048) in binary format, toggling necessary bits to recreate each of the word's respective number. The last word will have checksum bits dynamically toggled while you fill the bits.
"},{"location":"getting-started/usage/loading-a-mnemonic/#stackbit-1248","title":"Stackbit 1248","text":"Enter the BIP-39 mnemonic word's numbers (1-2048) using the Stackbit 1248 metal plate backup method, where each of the four digits of the word's number is a sum of the numbers marked (punched) 1, 2, 4, or 8. For example, to enter the word \"oyster\", number 1268, you must punch (1)(2)(2,4)(8).
"},{"location":"getting-started/usage/loading-a-mnemonic/#from-storage","title":"From Storage","text":"You can retrieve mnemonics previously stored on device's internal flash or external (SD card). All stored mnemonics are encrypted, to load them you'll have to enter the same key you used to encrypt them.
"},{"location":"getting-started/usage/loading-a-mnemonic/#wallet-loading","title":"Wallet Loading","text":""},{"location":"getting-started/usage/loading-a-mnemonic/#confirm-mnemonic-words","title":"Confirm Mnemonic Words","text":"Once you have entered your mnemonic, you will be presented with the full list of words to confirm.
If you see an asterisk (*) in the header, it means this is a double mnemonic.
"},{"location":"getting-started/usage/loading-a-mnemonic/#edit-mnemonic-optional","title":"Edit Mnemonic - Optional","text":"If you make a mistake while loading a mnemonic, you can easily edit it. Simply touch or navigate to the word you want to change and replace it. Edited words will be highlighted in a different color. If the final word contains an invalid checksum, it will appear in red. If your checksum word is red, please review your mnemonic carefully, as there may be an error.
"},{"location":"getting-started/usage/loading-a-mnemonic/#confirm-wallet-attributes","title":"Confirm Wallet Attributes","text":"You will be presented with a screen containing wallet attributes, if they are as expected just press Load Wallet and you'll be ready to use your loaded key.
"},{"location":"getting-started/usage/loading-a-mnemonic/#fingerprint","title":"Fingerprint","text":" -
73c5da0a: The BIP-32 master wallet's fingerprint, if you have it noted down, will help you make sure you entered the correct mnemonic and passphrase (optional) and will load the expected wallet.
"},{"location":"getting-started/usage/loading-a-mnemonic/#network","title":"Network","text":" Mainnet: Check if you are loading a Testnet or Mainnet wallet.
"},{"location":"getting-started/usage/loading-a-mnemonic/#single-multisig","title":"Single / Multisig","text":" Single-sig: Check if you are loading a Single-sig or Multisig wallet.
"},{"location":"getting-started/usage/loading-a-mnemonic/#derivation-path","title":"Derivation Path","text":" m/84'/0'/0': The derivation path is a sequence of numbers, or \"nodes\", that define the script type, network, and account index of your wallet. - Script Type
84': The first number defines the script type. The default is 84', corresponding to a Native Segwit wallet. Other values include: 44' for Legacy49' for Nested Segwit86' for Taproot48' for Multisig
- Network
0': The second number defines the network: 0' for Mainnet1' for Testnet
- Account Index
0': The third number is the account index, with 0' being the default. - Additional: For multisig wallets, a fourth node with the value
2' is added to the derivation path.
"},{"location":"getting-started/usage/loading-a-mnemonic/#passphrase","title":"Passphrase","text":" No Passphrase: Informs if the wallet has a loaded passphrase.
"},{"location":"getting-started/usage/loading-a-mnemonic/#customize","title":"Customize","text":"You can change any of the attributes before and after loading a wallet. It is also possible to change default settings for Network and Single/Multisig on settings.
"},{"location":"getting-started/usage/loading-a-mnemonic/#passphrase_1","title":"Passphrase","text":"You can type or scan a BIP-39 passphrase. When typing, swipe left or right to change keypads if your device has a touchscreen. You can also hold the button PAGE or PAGE_PREV when navigating among letters while typing text to fast forward or backward. For scanning, you can also create a QR code from your offline passphrase using the create QR code tool.
"},{"location":"getting-started/usage/loading-a-mnemonic/#customize_1","title":"Customize","text":"Press Customize to open a menu where you can change the Network, Single/Multisig, Script Type and Account.
Now, onto the main menu...
"},{"location":"getting-started/usage/navigating-the-main-menu/","title":"Navigating the Main Menu","text":"After entering your mnemonic, and loading a wallet, you will find yourself on Krux's main menu. Below is a breakdown of the entries available:
"},{"location":"getting-started/usage/navigating-the-main-menu/#backup-mnemonic","title":"Backup Mnemonic","text":"This will open a new submenu with different types of backups. QR Code based, Encrypted and Other Formats
If you set a printer, it will also give the option to print them!
"},{"location":"getting-started/usage/navigating-the-main-menu/#qr-code","title":"QR Code","text":" - Plaintext QR
Generate a QR containing the mnemonic words as regular text, where words are separated by spaces. Any QR code can be printed if a thermal printer driver is set.
- Compact SeedQR
A QR code is created from a binary representation of mnemonic words. Format created by SeedSigner, more info here.
- SeedQR
Words are converted to their BIP-39 numeric indexes, those numbers are then concatenated as a string and finally converted to a QR code. Format created by SeedSigner, more info here.
- Encrypted QR Code
This option converts the encrypted mnemonic into a QR code. Enter an encryption key and, optionally, a custom ID. When you scan this QR code through \"Load Mnemonic\" -> \"Via Camera\" -> \"QR Code,\" you will be prompted to enter the decryption key to load the mnemonic stored in it. Like any QR code, it can be printed if a thermal printer driver is set up.
"},{"location":"getting-started/usage/navigating-the-main-menu/#encrypted","title":"Encrypted","text":"This feature allows you to back up your mnemonic by encrypting it and storing it on the device's flash memory, an SD card, or in QR code format. You can customize the encryption method and parameters in the settings.
For convenience, you may choose to store the encrypted mnemonic on flash memory or an SD card, but it is advisable not to rely solely on these methods for backup. Flash storage can degrade over time and may be subject to permanent damage, resulting in the loss of stored information.
When using any of the encryption methods, you will be prompted to enter an encryption key. This key can be provided in text or QR code format. Additionally, you have the option to set a custom ID for easier management of your mnemonics. If a custom key is not specified, the device's current loaded wallet fingerprint will be used as the ID.
See this page to find out more about: Krux Mnemonics Encryption.
- Store on Flash
This option stores the encrypted mnemonic in the device's flash memory. You can decrypt and load it later through the \"Load Mnemonic\" -> \"From Storage\" option.
- Store on SD Card
If an SD card is available, this option stores the encrypted mnemonic on it. You can decrypt and load it later through the \"Load Mnemonic\" -> \"From Storage\" option.
- Encrypted QR Code It's another path for the same functionality present on QR Code backups, described above.
"},{"location":"getting-started/usage/navigating-the-main-menu/#other-formats","title":"Other Formats","text":" - Words
Display the BIP-39 mnemonic words as text so you can write them down.
- Numbers
Display the BIP-39 mnemonic word numbers (1-2048) in decimal, hex, or octal format.
- Stackbit 1248
This metal backup format represents the BIP-39 mnemonic word's numbers (1-2048). Each of the four digits is converted to a sum of 1, 2, 4 or 8. This option does not print even if a printer driver is set.
- Tiny Seed
This metal backup format represents the BIP-39 mnemonic word's numbers (1-2048) in binary format on a metal plate, where the 1's are marked (punched) and the 0's are left intact. You can also print your mnemonic in this format if a thermal printer driver is set.
"},{"location":"getting-started/usage/navigating-the-main-menu/#extended-public-key","title":"Extended Public Key","text":"A menu will be presented with options to display your master extended public key (xpub) as text and as a QR code. Depending on the script type or whether a single-sig or multisig wallet was loaded, the options shown will be xpub, ypub, zpub, or Zpub. When displayed as text, the extended public key can be stored on an SD card if available. If you choose to export a QR code, you can not only scan it but also save it as an image on an SD card or print it if a thermal printer is attached.
All QR codes will contain key origin information in key expressions. If your coordinator cannot parse this information, it will not be capable of importing the wallet's fingerprint. As a result, Krux will not perform important verifications when signing transactions created by it unless you manually add the fingerprint so that it can be used to create Krux-compatible PSBTs.
Always prefer to import extended public keys directly from Krux when setting up a coordinator instead of copying it (or parts of it) from other sources.
"},{"location":"getting-started/usage/navigating-the-main-menu/#wallet","title":"Wallet","text":"Here you can load view and save wallet descriptors, add or change passphrases, customize wallet's attributes, derive BIP85 mnemonics and passwords.
"},{"location":"getting-started/usage/navigating-the-main-menu/#wallet-descriptor","title":"Wallet Descriptor","text":"A Bitcoin Wallet Output Script Descriptor defines a set of addresses in a wallet. It includes the following information: - Script Type: Specifies the type of script (e.g., P2PKH, P2SH, P2WPKH). - Origin Info: Defines the master fingerprint and derivation path used to derive keys. - Extended Public Keys: usually represented as an xpub, but could be ypub, zpub, etc.
Output descriptors standardize how wallets generate addresses, ensuring compatibility and security. They help wallets and other software understand how to derive and verify the addresses used in transactions.
For multisig wallets, it is essential to load a descriptor to check addresses and perform full PSBT verification. For single-sig wallets, loading a descriptor is optional and serves as a redundancy check of the coordinator's wallet attributes.
When you select the \"Wallet Descriptor\" option for the first time, you will be prompted to load a wallet descriptor via QR code or SD card. After loading, a preview of the wallet attributes will be displayed for confirmation.
If you access the \"Wallet Descriptor\" option again after loading your wallet, you will see the wallet's name, fingerprints, and the abbreviated XPUBs of all cosigners, along with a QR code containing the exact data that was initially loaded. If an SD card is inserted, you can save the descriptor to it for later use without the assistance of a coordinator. Additionally, if you have a thermal printer attached, you can print this QR code.
Krux also allows you to verify a descriptor's receive and change addresses without the need to load private keys. Simply turn on your Krux, access \"Tools\" -> \"Descriptor Addresses,\" and load a trusted descriptor from a QR code or SD card.
Please note that if you customize the wallet parameters or restart the device, the descriptor will be unloaded, and you may need to load it again to check addresses.
"},{"location":"getting-started/usage/navigating-the-main-menu/#passphrase","title":"Passphrase","text":"If you forgot to load a passphrase while loading your wallet, or if you use multiple passphrases with the same mnemonic, you can add, replace, or remove a passphrase here. Simply choose between typing or scanning it.
To remove a passphrase, select \"Type BIP39 Passphrase,\" leave the field blank, and press \"Go.\"
Don't forget to verify the resulting fingerprint in the status bar to ensure you've loaded the correct key.
"},{"location":"getting-started/usage/navigating-the-main-menu/#customize","title":"Customize","text":"Here you are presented to the exact same customization options you have while loading a key and wallet. You can change the Network, Single/Multisig, Script Type and Account. More about wallet attributes
"},{"location":"getting-started/usage/navigating-the-main-menu/#bip85","title":"BIP85","text":"Bitcoin BIP85, also known as Deterministic Entropy From BIP32 Keychains, allows for the generation of deterministic entropy using a BIP32 master key. This entropy can then be used to create various cryptographic keys and mnemonics (e.g., BIP39 seed phrases). BIP85 ensures that all derived keys and mnemonics are deterministic and reproducible, meaning they can be recreated from the same master key. This feature is useful for securely managing multiple child keys from a single master key without the need to store each one separately.
BIP39 Mnemonic
Choose between 12 or 24 words, then type the desired index to export a child mnemonic. After being presented with the new mnemonic, you can choose to load and use it right away.
Please note that any passphrase from the parent mnemonic will be removed when loading a BIP85 child mnemonic.
Base64 Password
To create a Base64 password, which can be used in a variety of logins, from email to social media accounts, choose an index and then a length of at least 20 characters.
The resulting password will be displayed on the screen and can also be exported to an SD Card or as a QR code.
"},{"location":"getting-started/usage/navigating-the-main-menu/#address","title":"Address","text":"Scan, verify, export or print your wallet addresses.
"},{"location":"getting-started/usage/navigating-the-main-menu/#scan-address","title":"Scan Address","text":"This option turns on the camera and allows you to scan in a QR code of a receive address. Upon scanning, it will render its own QR code of the address back to the display along with the (text) address below it. You could use this feature to scan the address of someone you want to send coins to and display the QR back to your wallet coordinator rather than copy-pasting an address. If you have a thermal printer attached, you can also print this QR code.
After proceeding through this screen, you will be asked if you want to check that the address belongs to your wallet. If you confirm, it will exhaustively search through as many addresses derived from your wallet as you want in order to find a match.
This option exists as an extra security check to verify that the address your wallet coordinator has generated is authentic and belongs to your wallet.
"},{"location":"getting-started/usage/navigating-the-main-menu/#receive-addresses","title":"Receive Addresses","text":"List your wallet receiving addresses, you can browse to select an arbitrary address to show your QR code and print if you want.
"},{"location":"getting-started/usage/navigating-the-main-menu/#change-addresses","title":"Change Addresses","text":"List your wallet change addresses, you can browse to select an arbitrary address to show your QR code and print if you want.
"},{"location":"getting-started/usage/navigating-the-main-menu/#sign","title":"Sign","text":"Under Sign, you can choose to sign a PSBT or a message. You can load both PSBTs and messages scanning QR codes or loading from files on a SD card.
"},{"location":"getting-started/usage/navigating-the-main-menu/#psbt","title":"PSBT","text":"To sign a Bitcoin PSBT, you have the following options:
- Scan an Animated QR Code: Turn on the camera and scan an animated QR code of a PSBT generated by your wallet coordinator software. If you have any issues, see Troubleshooting.
- Load from SD Card: Load an unsigned PSBT file from your SD card.
Upon loading the PSBT, you will be presented with a preview showing the amount of BTC being sent, the recipient's address, and the transaction fee. Amounts are displayed according to your locale and the International Bureau of Weights and Measures, while still adhering to the concept of the Satcomma standard format.
If you choose to proceed and sign the transaction, the signed PSBT can be exported in two ways:
- As an animated QR code, which can be scanned back into your coordinator wallet.
- As a signed PSBT file, which can be saved to your SD card and then loaded back into your coordinator wallet for broadcasting.
If a thermal printer is attached to your device, you can also print the PSBT QR codes for record-keeping or further processing.
"},{"location":"getting-started/usage/navigating-the-main-menu/#message","title":"Message","text":"Similar to PSBTs, Krux can load, sign, and export signatures for messages. This feature allows you to attest not only to the ownership of the messages themselves but also to the ownership of Bitcoin addresses and the authorship of documents and files.
"},{"location":"getting-started/usage/navigating-the-main-menu/#standard-messages-and-files","title":"Standard Messages and Files","text":"You can scan or load a file from an SD card, the content can be plaintext or the SHA-256 hash of a message. Upon loading, you will be shown a preview of the message's SHA-256 hash for confirmation before signing.
If you confirm, a signature will be generated, and you will see a base64-encoded version of it. You can then choose to export it as a QR code or save it to an SD card. If a thermal printer is attached, you can also print the QR code.
Following this, you will see and be allowed to export your raw (master) public key in hexadecimal form, which can be used by others to verify your signature. If a thermal printer is attached, you can also print this QR code.
This feature is used to sign Krux releases, airgapped, using a Krux device.
"},{"location":"getting-started/usage/navigating-the-main-menu/#messages-at-address","title":"Messages at Address","text":"Coordinators like Sparrow and Specter offer the possibility to sign messages at a Bitcoin receive address, allowing you to attest ownership of that address. Krux will detect if the message is of this type and present a similar workflow for signing. The main difference is that the address will be displayed along with the raw message, and since the message is signed with a derived address instead of the master public key, Krux won't offer the option to export the raw public key after the signature.
"},{"location":"getting-started/usage/setting-a-coordinator-and-signing/","title":"Setting a Coordinator and Signing","text":"After creating a mnemonic, making a safe backup, and testing to recover your mnemonic, it's time to set up a coordinator.
Krux can work with multiple coordinator wallets. Popular options include:
-
Sparrow Wallet (desktop)
-
Specter Desktop (desktop)
-
Nunchuk (mobile)
-
BlueWallet (mobile)
"},{"location":"getting-started/usage/setting-a-coordinator-and-signing/#step-1-install-the-coordinator-wallet","title":"Step 1: Install the Coordinator Wallet","text":"Download and install the appropriate version of your chosen coordinator wallet for your device and operating system.
"},{"location":"getting-started/usage/setting-a-coordinator-and-signing/#step-2-create-a-new-wallet-with-krux-as-a-signer","title":"Step 2: Create a New Wallet with Krux as a Signer","text":"Depending on the coordinator, the steps to add Krux as a signer may vary slightly:
Specter and Nunchuk Single-sig: Add Krux as signer device, then create a wallet that uses it.
Specter and Nunchuk Multisig: Add Krux as signer device, add other devices, then create a wallet that uses them.
Sparrow and BlueWallet: Create a wallet (or vault in Blue Wallet) first, then add signer device(s).
- Load a mnemonic and wallet in Krux.
-
On your coordinator, when presented with possible signer devices to add, choose Krux if available, otherwise choose \"other\" or even another QR code compatible signer. As Krux is compatible with many QR code formats, most of available alternatives should work.
-
When prompted by your coordinator to import signer's public key, access the \"Extended Public Key\" on Krux.
- Export an XPUB (or YPUB, ZPUB, etc., based on the script type) as a QR code.
-
Scan this QR code with your coordinator.
-
Ensure the coordinator\u2019s wallet attributes (policy type, script type, fingerprint, and derivation) match those in Krux.
"},{"location":"getting-started/usage/setting-a-coordinator-and-signing/#step-3-load-and-backup-wallet-descriptor-multisig-only","title":"Step 3: Load and Backup Wallet Descriptor (Multisig Only)","text":" - In your coordinator, export the wallet descriptor containing information about the wallet and all cosigners:
- Sparrow: \"Descriptor\"
- Specter: \"Export Wallet\"
- Nunchuk: \"Export Wallet Configuration\"
- BlueWallet: \"Export Coordination Setup\"
- Export the descriptor as a QR code or file.
- On Krux, go to \"Wallet\" -> \"Wallet Descriptor\" to scan the descriptor QR code or load it via SD card.
-
If you access \"Wallet\" -> \"Wallet Descriptor\" again, you will be able to:
- Check the wallet cosigners.
- Save the descriptor on an SD card (useful if you initially loaded it from QR codes).
It is crucial to have a backup of this descriptor to recover your wallet in case one of the cosigners is lost.
"},{"location":"getting-started/usage/setting-a-coordinator-and-signing/#step-4-verify-addresses","title":"Step 4: Verify Addresses","text":"For single-sig or multisig (after loading a descriptor):
-
Go to \"Address\" on Krux.
-
List \"Receive Addresses\" and \"Change Addresses\" or use \"Scan Address\" to verify if addresses from your coordinator are matched by Krux.
"},{"location":"getting-started/usage/setting-a-coordinator-and-signing/#step-5-funding-your-wallet","title":"Step 5: Funding your Wallet","text":"Once addresses are verified, send a small test amount to your wallet. Test signing and sending a transaction before adding more funds.
"},{"location":"getting-started/usage/setting-a-coordinator-and-signing/#step-6-sign-psbts-and-messages","title":"Step 6: Sign PSBTs and Messages","text":""},{"location":"getting-started/usage/setting-a-coordinator-and-signing/#psbts","title":"PSBTs","text":" -
Create a transaction in your coordinator.
-
Export the transaction as a QR code.
-
On Krux, go to \"Sign\" -> \"PSBT\" -> \"Load from camera\".
-
Scan the animated QR code.
-
Verify the transaction details.
-
If correct, press \"Sign to QR code\".
-
Scan the signed transaction QR code back into the coordinator to broadcast it.
Alternatively, you can use an SD card:
Save the transaction as a file on an SD card. On Krux, go to \"Sign\" -> \"PSBT\" -> \"Load from SD card\" and \"Sign to SD card\". Load the signed transaction on the coordinator and broadcast it.
"},{"location":"getting-started/usage/setting-a-coordinator-and-signing/#messages","title":"Messages","text":"Some coordinators, like Sparrow, allow you to sign messages linked to your wallet's addresses. Signing and verifying a message signature attests to the ownership of an address and serves as an additional test for your setup.
"},{"location":"getting-started/usage/video-tutorials/","title":"Video Tutorials","text":""},{"location":"getting-started/usage/video-tutorials/#krux-video-tutorials","title":"Krux Video Tutorials","text":"Most people prefer to learn by watching videos, and we are fortunate to have excellent content creators in the Bitcoin space, here are some examples of Krux related content and tutorials.
"},{"location":"getting-started/usage/video-tutorials/#english","title":"English","text":""},{"location":"getting-started/usage/video-tutorials/#krux-on-m5stickv-sparrow","title":"Krux on M5StickV + Sparrow","text":"Krux on M5StickV + Sparrow Wallet by Crypto Guide
"},{"location":"getting-started/usage/video-tutorials/#krux-on-maix-amigo-blue","title":"Krux on Maix Amigo + Blue","text":"Krux on Maix Amigo + Blue Wallet by Crypto Guide
"},{"location":"getting-started/usage/video-tutorials/#diy-only-multisig","title":"DIY-Only MultiSig","text":"DIY-Only Multivendor Hardware Wallet MultiSig: SeedSigner, Jade, Krux, Satochip + Sparrow & Electrum by Crypto Guide
"},{"location":"getting-started/usage/video-tutorials/#build-from-source-verify","title":"Build From Source & Verify","text":"Krux DIY Bitcoin Signer: Build From Source & Verify (With Windows + WSL2 + Docker) by Crypto Guide
"},{"location":"getting-started/usage/video-tutorials/#portuguese","title":"Portuguese","text":""},{"location":"getting-started/usage/video-tutorials/#krux-facil-de-instalar","title":"Krux f\u00e1cil de instalar","text":"Hardwallet Krux f\u00e1cil de instalar + QRs criptografados - por Bitdov
"},{"location":"getting-started/usage/video-tutorials/#multisig-com-krux","title":"Multisig com Krux","text":"Multisig com Krux e Nunchuk no celular - por Bitdov
"},{"location":"getting-started/usage/video-tutorials/#krux-com-impressora-termica","title":"Krux com impressora t\u00e9rmica","text":"Usando a Krux com impressora t\u00e9rmica - por Bitdov
"},{"location":"getting-started/usage/video-tutorials/#krux-no-celular","title":"Krux no celular","text":"Carteira Bitcoin com celular OFFLINE - Krux mobile APK - por Dig
"},{"location":"getting-started/usage/video-tutorials/#krux-no-celular-ii","title":"Krux no celular II","text":"Como utilizar a carteira Krux no celular - por Jo\u00e3o Trein
"},{"location":"getting-started/usage/video-tutorials/#faca-sua-krux","title":"Fa\u00e7a sua Krux","text":"Fa\u00e7a sua hardware wallet em casa com a KRUX! - por Caiovski
"},{"location":"getting-started/usage/video-tutorials/#korean","title":"Korean","text":"Krux \uc6d4\ub81b \uc124\uce58 \ubc0f \uac80\uc99d \ubc29\ubc95
\uc548\uc0ac\uba74 \uc190\ud574? \uc138\uc0c1\uc5d0\uc11c \uac00\uc7a5 \ud22c\uba85\ud55c \ube44\ud2b8\ucf54\uc778 \uc804\uc6a9 \uc9c0\uac11
"}]}
\ No newline at end of file
diff --git a/sitemap.xml b/sitemap.xml
index a590182f..5630f8e2 100644
--- a/sitemap.xml
+++ b/sitemap.xml
@@ -2,218 +2,212 @@
https://selfcustody.github.io/krux/faq/
- 2024-11-19
+ 2024-11-29
daily
https://selfcustody.github.io/krux/
- 2024-11-19
+ 2024-11-29
daily
https://selfcustody.github.io/krux/parts/
- 2024-11-19
+ 2024-11-29
daily
https://selfcustody.github.io/krux/support/
- 2024-11-19
+ 2024-11-29
daily
https://selfcustody.github.io/krux/troubleshooting/
- 2024-11-19
+ 2024-11-29
daily
https://selfcustody.github.io/krux/uncommon-questions/
- 2024-11-19
+ 2024-11-29
daily
https://selfcustody.github.io/krux/getting-started/
- 2024-11-19
+ 2024-11-29
daily
https://selfcustody.github.io/krux/getting-started/navigation/
- 2024-11-19
+ 2024-11-29
daily
https://selfcustody.github.io/krux/getting-started/settings/
- 2024-11-19
+ 2024-11-29
daily
https://selfcustody.github.io/krux/getting-started/features/QR-transcript-tools/
- 2024-11-19
+ 2024-11-29
daily
https://selfcustody.github.io/krux/getting-started/features/encrypted-mnemonics/
- 2024-11-19
+ 2024-11-29
daily
https://selfcustody.github.io/krux/getting-started/features/entropy/
- 2024-11-19
+ 2024-11-29
daily
https://selfcustody.github.io/krux/getting-started/features/printing/
- 2024-11-19
+ 2024-11-29
daily
https://selfcustody.github.io/krux/getting-started/features/sd-card-update/
- 2024-11-19
+ 2024-11-29
daily
https://selfcustody.github.io/krux/getting-started/features/tamper-detection/
- 2024-11-19
+ 2024-11-29
daily
https://selfcustody.github.io/krux/getting-started/features/tinyseed/
- 2024-11-19
+ 2024-11-29
daily
https://selfcustody.github.io/krux/getting-started/features/tools/
- 2024-11-19
+ 2024-11-29
daily
https://selfcustody.github.io/krux/getting-started/installing/from-pre-built-release/
- 2024-11-19
+ 2024-11-29
daily
https://selfcustody.github.io/krux/getting-started/installing/from-source/
- 2024-11-19
+ 2024-11-29
daily
https://selfcustody.github.io/krux/getting-started/installing/from-test-release/
- 2024-11-19
+ 2024-11-29
daily
https://selfcustody.github.io/krux/getting-started/installing/
- 2024-11-19
+ 2024-11-29
daily
https://selfcustody.github.io/krux/getting-started/installing/from-gui/debian-like/
- 2024-11-19
+ 2024-11-29
daily
https://selfcustody.github.io/krux/getting-started/installing/from-gui/fedora-like/
- 2024-11-19
+ 2024-11-29
daily
https://selfcustody.github.io/krux/getting-started/installing/from-gui/
- 2024-11-19
+ 2024-11-29
daily
https://selfcustody.github.io/krux/getting-started/installing/from-gui/macos-arm64/
- 2024-11-19
+ 2024-11-29
daily
https://selfcustody.github.io/krux/getting-started/installing/from-gui/macos-intel/
- 2024-11-19
+ 2024-11-29
daily
https://selfcustody.github.io/krux/getting-started/installing/from-gui/other-linux-distro/
- 2024-11-19
+ 2024-11-29
daily
https://selfcustody.github.io/krux/getting-started/installing/from-gui/usage/
- 2024-11-19
+ 2024-11-29
daily
https://selfcustody.github.io/krux/getting-started/installing/from-gui/windows/
- 2024-11-19
+ 2024-11-29
daily
https://selfcustody.github.io/krux/getting-started/templates/templates/
- 2024-11-19
+ 2024-11-29
daily
https://selfcustody.github.io/krux/getting-started/usage/generating-a-mnemonic/
- 2024-11-19
+ 2024-11-29
daily
https://selfcustody.github.io/krux/getting-started/usage/loading-a-mnemonic/
- 2024-11-19
+ 2024-11-29
daily
https://selfcustody.github.io/krux/getting-started/usage/navigating-the-main-menu/
- 2024-11-19
+ 2024-11-29
daily
https://selfcustody.github.io/krux/getting-started/usage/setting-a-coordinator-and-signing/
- 2024-11-19
+ 2024-11-29
daily
https://selfcustody.github.io/krux/getting-started/usage/video-tutorials/
- 2024-11-19
+ 2024-11-29
daily
-
- https://selfcustody.github.io/krux/snippets/after-install-installer/
- 2024-11-19
- daily
-
\ No newline at end of file
diff --git a/sitemap.xml.gz b/sitemap.xml.gz
index f58a7e50..47e65cd3 100644
Binary files a/sitemap.xml.gz and b/sitemap.xml.gz differ
diff --git a/snippets/after-install-installer/index.html b/snippets/after-install-installer/index.html
deleted file mode 100644
index bb2e768e..00000000
--- a/snippets/after-install-installer/index.html
+++ /dev/null
@@ -1,1506 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- After install installer - Krux - Open-source signing device firmware for Bitcoin
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- After install installer
-
-Once installed, you can proceed to firmware installation.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff --git a/snippets/sd-card-info-faq.txt b/snippets/sd-card-info-faq.txt
index 8545fd8c..9dbaef25 100644
--- a/snippets/sd-card-info-faq.txt
+++ b/snippets/sd-card-info-faq.txt
@@ -1 +1 @@
-We cannot guarantee that a microSD card is compatible and will work in your device; you'll need to test it on the device to be sure, read the [Troubleshooting](troubleshooting.md/#why-isnt-krux-detecting-my-microsd-card-or-presenting-an-error) for more info.
\ No newline at end of file
+We cannot guarantee that a microSD card is compatible and will work in your device; you'll need to test it on the device to be sure, read the [Troubleshooting](/krux/troubleshooting/#why-isnt-krux-detecting-my-microsd-card-or-presenting-an-error) for more info.
\ No newline at end of file
diff --git a/support/index.html b/support/index.html
index 55f09e17..88c5ed2e 100644
--- a/support/index.html
+++ b/support/index.html
@@ -1560,7 +1560,7 @@ Krux EthosMission¶
To implement ideas that make self-custody more powerful, accessible, and user-friendly.
Don't Trust, Verify¶
-Do not trust developers’ intentions or competence. Krux is a DIY, use-at-your-own-risk project. We are committed to continuously improving security, but will not make claims or create marketing narratives about it. It is up to the users verify their hardware, the firmware and Krux-Installer
+Do not trust developers’ intentions or competence. Krux is a DIY, use-at-your-own-risk project. We are committed to continuously improving security, but will not make claims or create marketing narratives about it. It is up to the users verify their hardware, the firmware and Krux-Installer
Donations¶
Krux will not solicit, receive, manage, or distribute donations. Therefore, Krux has no budget for publicity, audits, or similar activities. Contributors to Krux will fund their own work—whether by promoting their efforts, applying for grants, or seeking direct individual donations.
Krux is Public Domain¶