Tamper Detection

docs/getting-started/features/tamper-detection.en.md

@@ -0,0 +1,116 @@
+# Tamper Detection Mechanism (Experimental)
+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.
+
+## Krux Security Model - Good Practices and Limitations
+
+To secure your Krux device, always verify firmware authenticity before installation, particularly when flashing via USB.
+
+### Firmware Verification Methods
+
+- **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.
+
+### Recommendations
+
+- **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*.
+
+## Tamper Check Code (TC Code)
+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’s flash, the *TC Code* is hashed together with the K210 chip’s 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’s 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.
+
+### Enhancing Tamper Detection
+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.
+
+## Tamper Check (TC) Flash Hash - A Tamper Detection Tool
+### Introduction
+
+The "TC Flash Hash" tool enables you to verify if the flash memory content has been altered.
+
+### How It Works
+
+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.
+
+<div style="text-align: center;">
+    <img src="../../img/flash_hash.bmp" alt="TC Flash Hash" width="200"/>
+</div>
+
+*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.
+
+### Filling Empty Flash Blocks
+
+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.
+
+### Ensuring Tamper Detection
+
+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.
+
+## Executing *TC Flash Hash*
+
+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.
+
+## Potential Attack Scenarios and Their Mitigation
+### Challenge for an Attacker
+
+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.
+
+### Why Tampered Firmware Cannot Bypass Verification
+
+- **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.
+
+### Possible Attack Strategies and Failures
+
+- **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. 
+
+## Conclusion
+
+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.

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

@@ -31,22 +31,52 @@ Enter text to create, print or transcribe a QR code that can later be used as an
 
 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.
 
-### Remove Mnemonic
-<img src="../../../img/maixpy_m5stickv/load-mnemonic-storage-options-125.png" align="right">
-<img src="../../../img/maixpy_amigo/load-mnemonic-storage-options-150.png" align="right">
+<div style="clear: both"></div>
 
-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](./encrypted-mnemonics.md).
+### Flash Tools
+Tools to inspect the content of device's flash memory and clear user's area
 
-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.
+<img src="../../../img/maixpy_m5stickv/flash-tools-125.png" align="right">
+<img src="../../../img/maixpy_amigo/flash-tools-150.png" align="right">
 
-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.
+<div style="clear: both"></div>
+
+#### Flash Map
+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.
+
+<img src="../../../img/maixpy_m5stickv/flash-map-125.png" align="right">
+<img src="../../../img/maixpy_amigo/flash-map-150.png" align="right">
 
 <div style="clear: both"></div>
 
-### Wipe Device
-<img src="../../../img/maixpy_m5stickv/wipe-device-125.png" align="right">
-<img src="../../../img/maixpy_amigo/wipe-device-150.png" align="right">
+#### TC Flash Hash
+*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.
 
-This option permanently removes all stored encrypted mnemonics and settings 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.
+Learn more about *Tamper Check Flash Hash* on [Tamper Detection](tamper-detection.md)
+
+#### Erase User's Data
+<img src="../../../img/maixpy_m5stickv/erase-data-125.png" align="right">
+<img src="../../../img/maixpy_amigo/erase-data-150.png" align="right">
+
+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.
 
 <div style="clear: both"></div>
+
+
+### Remove Mnemonic
+<img src="../../../img/maixpy_m5stickv/load-mnemonic-storage-options-125.png" align="right">
+<img src="../../../img/maixpy_amigo/load-mnemonic-storage-options-150.png" align="right">
+
+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](./encrypted-mnemonics.md).
+
+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.

docs/getting-started/settings.en.md

@@ -127,9 +127,21 @@ Set the time it takes for Krux to automatically shut down. This feature not only
 
 Please note that devices without batteries and power management will not shut down but will reboot instead, which is sufficient to unload private keys.
 
+#### TC Flash Hash at Boot
+Chose if you would like to run [Tamper Check Flash Hash](features/tamper-detection.en.md) 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.
+
 #### Hide Mnemonics
 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.
 
+#### Tamper Check Code
+Create or modify a Tamper Check Code. This code will be required every time [Tamper Check Flash Hash](features/tamper-detection.en.md) 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 *TC Code* will be deleted if the device is wiped or user data is erased, which will consequently disable *TC Flash Hash*.
+
 ### Appearance
 <img src="../../img/maixpy_m5stickv/settings-options-appearance-125.png" align="right">
 <img src="../../img/maixpy_amigo/settings-options-appearance-150.png" align="right">