Skip to content

Commit 43d6f3a

Browse files
authored
Merge pull request #517 from tadeubas/docs-hint
Docs lots of txt changes + image additions
2 parents 124d4e5 + 45dd2ac commit 43d6f3a

File tree

99 files changed

+571
-375
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

99 files changed

+571
-375
lines changed

docs/faq.en.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,9 @@ The term "hardware wallet" typically refers to devices dedicated to storing priv
33

44
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.
55

6-
Krux does not include hardware secure elements. The security of stored data relies on encryption.
6+
Krux does not include hardware secure elements. The security of stored data relies on encryption. Read more about [Krux Encrypted Mnemonics](./getting-started/features/encrypted-mnemonics.md).
77

8-
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.
8+
**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.
99

1010
## What is Beta version?
1111
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](https://github.com/odudex/krux_binaries/). 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.
@@ -21,4 +21,4 @@ The Krux Android app is available as an APK in the [test (beta) repository](http
2121
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.
2222

2323
### Is it safe to use?
24-
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.
24+
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.

docs/getting-started/features/QR-transcript-tools.en.md

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,23 +12,23 @@ This mode is optimized for scanning, the raw QR code will be displayed
1212
<img src="../../../img/maixpy_m5stickv/lines-qr-code-250.png" align="right" class="m5stickv">
1313
<img src="../../../img/maixpy_amigo/lines-qr-code-300.png" align="right" class="amigo">
1414

15-
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.
15+
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.
1616

1717
<div style="clear: both"></div>
1818

1919
### Zoomed Regions Mode
2020
<img src="../../../img/maixpy_m5stickv/zoomed-qr-code-250.png" align="right" class="m5stickv">
2121
<img src="../../../img/maixpy_amigo/zoomed-qr-code-300.png" align="right" class="amigo">
2222

23-
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.
23+
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.
2424

2525
<div style="clear: both"></div>
2626

2727
### Highlighted Regions Mode
2828
<img src="../../../img/maixpy_m5stickv/regions-qr-code-250.png" align="right" class="m5stickv">
2929
<img src="../../../img/maixpy_amigo/regions-qr-code-300.png" align="right" class="amigo">
3030

31-
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.
31+
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.
3232

3333
<div style="clear: both"></div>
3434

@@ -39,3 +39,11 @@ QR codes will be split into regions, of 5x5 or 7x7 "blocks". One QR code region
3939
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.
4040

4141
<div style="clear: both"></div>
42+
43+
### QR Viewer
44+
<img src="../../../img/maixpy_m5stickv/qr-viewer-250.png" align="right" class="m5stickv">
45+
<img src="../../../img/maixpy_amigo/qr-viewer-300.png" align="right" class="amigo">
46+
47+
Almost every QR code in Krux will also bring up this menu with these extra options: `Toggle Brightness`, `Save QR Image to SD Card` and `Print as QR`. If `Save QR Image to SD Card` shows as disabled it means that the SD card was not detected. To enable `Print as QR` you need to configure your printer driver in [settings](../settings.md#thermal).
48+
49+
<div style="clear: both"></div>

docs/getting-started/features/encrypted-mnemonics.en.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,16 @@
11
## Introduction
22

3-
There are many possible security layers one could add to protect a wallet’s private key. Adding a BIP-39 passphrase to the mnemonic is the most common method. Encrypting a BIP-39 mnemonic has a similar use case as the BIP-39 passphrase, but the user experience may differ depending on the implementation. The main difference between BIP-39 passphrases and Krux’s encrypted mnemonic implementation is that when users type the wrong key, encrypted mnemonics will return an error instead of loading a different wallet, as BIP-39 passphrases do. This difference may be desired or not. The implementation also has the convenience of storing a mnemonic ID together with the stored or QR code encrypted mnemonics. Mnemonic encryption, with its own key, can be used together with BIP-39 passphrase as an extra security layer.
3+
There are many possible security layers one could add to protect a wallet’s private key. Adding a BIP39 passphrase to the mnemonic is the most common method. Encrypting a BIP39 mnemonic has a similar use case as the BIP39 passphrase, but the user experience may differ depending on the implementation. The main difference between BIP39 passphrases and Krux’s encrypted mnemonic implementation is that when users type the wrong key, encrypted mnemonics will return an error instead of loading a different wallet, as BIP39 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 BIP39 passphrase as an extra security layer.
44

55
We use standard AES encryption modes ECB and CBC:
66

77
### AES-ECB
88

9-
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.
9+
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](./QR-transcript-tools.md). 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.
1010

1111
### AES-CBC
1212

13-
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.
13+
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](./QR-transcript-tools.md).
1414

1515
#### CBC Encryption IV
1616

@@ -40,6 +40,6 @@ In search of efficiency and smaller QR codes, all data is converted to bytes and
4040
* **(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.
4141

4242
## Considerations
43-
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.
43+
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. Flash storage can degrade over time and may be subject to permanent damage, resulting in the loss of stored information.
4444

45-
Remember that the stored encrypted mnemonic is protected by the key you defined to encrypt it. If the defined [key is weak](https://www.hivesystems.com/blog/are-your-passwords-in-the-green), your encrypted mnemonic will not be protected. If you have stored a mnemonic with funds in the device's internal flash memory using a [weak key](https://www.hivesystems.com/blog/are-your-passwords-in-the-green), the best way to undo this is to [erase user's data](tools.md/#erase-users-data).
45+
Remember that the stored encrypted mnemonic is protected by the key you defined to encrypt it. If the defined [key is weak](https://www.hivesystems.com/blog/are-your-passwords-in-the-green), your encrypted mnemonic will **not be protected**. If you have stored a mnemonic with funds in the device's internal flash memory using a [weak key](https://www.hivesystems.com/blog/are-your-passwords-in-the-green), the best way to undo this is to [erase user's data](tools.md/#erase-users-data).

docs/getting-started/features/entropy.en.md

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,22 @@
11

22
## Why Does Krux Say the Entropy of My Fifty Dice Rolls Does Not Contain 128 Bits of Entropy?
3-
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.
3+
We want Krux 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 delve deeper into the concepts of entropy to better support users' knowledge of sovereign self-custody.
44

55
## Entropy in Dice Rolls
66

77
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.
88

99
### Entropy Definitions
1010

11-
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.
11+
Entropy, a fundamental concept in various scientific disciplines, is most commonly associated with a state of disorder, randomness, or uncertainty within a system. We use the concepts from [thermodynamics entropy](https://en.wikipedia.org/wiki/Entropy_(classical_thermodynamics)), [Shannon's entropy](https://en.wikipedia.org/wiki/Entropy_(information_theory)), and [cryptographic entropy](https://en.wikipedia.org/wiki/Entropy_(computing)).
1212

13-
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.
13+
- **Thermodynamics entropy** deals with heat and work. It describes how energy is distributed among the particles in a system, reflecting the system's tendency towards equilibrium and maximum disorder.
1414

15-
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.
15+
- **Shannon's entropy**, from information theory, measures the uncertainty or information content in a message or data source. It quantifies the average amount of information produced by a stochastic source of data, indicating how unpredictable the data is.
1616

17-
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.
17+
- **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.
1818

19-
While mechanical entropy deals with physical systems, Shannon's entropy focuses on information content, and cryptographic entropy emphasizes security through randomness.
19+
While thermodynamics entropy deals with physical systems, Shannon's entropy focuses on information content, and cryptographic entropy emphasizes security through randomness.
2020

2121
### Measuring Dice Rolls Entropy
2222
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:

docs/getting-started/features/printing.en.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
12
----8<----
23
warning-printer.en.txt
34
----8<----
@@ -23,7 +24,7 @@ Krux has the ability to print mnemonic backup (Words, Numbers, Tiny Seed templat
2324
<img src="../../../img/maixpy_m5stickv/print-qr-prompt-250.png" align="right" class="m5stickv">
2425
<img src="../../../img/maixpy_amigo/print-qr-prompt-300.png" align="right" class="amigo">
2526

26-
Once a thermal printer and driver have been enabled in [Krux settings](../settings.md/#thermal), 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?`.
27+
Once a thermal printer and driver have been enabled in [settings](../settings.md/#thermal), all screens that display a QR code will offer the option to `Print as QR`. Other formats of mnemonic backup will also ask if you want to `Print as QR?`.
2728

2829
There are many ways you can use this functionality, including:
2930

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,15 @@
11
### Upgrade via microSD card
2-
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.
2+
Once you've installed Krux firmware on your device via USB, you can either continue updating the device via USB or you can perform upgrades via microSD card to keep the device airgapped.
33

4-
To perform an upgrade, simply copy the [official release](https://github.com/selfcustody/krux/releases) `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.
4+
<img src="../../../img/maixpy_m5stickv/firmware-update-250.png" align="right" class="m5stickv">
5+
<img src="../../../img/maixpy_amigo/firmware-update-300.png" align="right" class="amigo">
56

6-
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.
7+
To perform an upgrade, simply copy the [official release](https://github.com/selfcustody/krux/releases) `firmware.bin` and `firmware.bin.sig` files to the root of a FAT32 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. Only official releases are signed.
8+
9+
Once installation is complete, you will be prompted to remove firmware files from the SD Card, if you do not remove it, upon reboot you will be prompted to install it again.
710

811
----8<----
912
sd-card-info-faq.en.txt
1013
----8<----
11-
Only official releases are signed and can be installed via microSD card.
14+
15+
<div style="clear: both"></div>

0 commit comments

Comments
 (0)