feat(nvs): cryptographic hash with key derivation

Use the hardware and a configurable salt to encrypt sensitive datas

Author: Times-Z

include/config/SecureStorage.h

@@ -31,6 +31,9 @@ class SecureStorage {
     bool remove(const char* key);
     String get(const char* key, const char* defaultValue = nullptr);
 
+    // Set the public salt (should be called before begin())
+    static void setSalt(const String& salt);
+
    private:
     size_t _eepromSize;
     bool loadToMemory();

readme.md

@@ -209,6 +209,25 @@ cp data/config-{hellocubic|smalltv}.example data/config.json
 
 You can edit this JSON file to configure your firmware, for example by modifying `wifi_ssid` and `wifi_password` so that your device connects to your network
 
+Note: The Wi-Fi credentials in config.json are migrated to EEPROM “secure storage” on first boot. After that, the Wi-Fi credentials are erased from config.json
+
+Security of stored secrets:
+
+- All sensitive values (API keys, wifi credentials, tokens, etc.) are stored in EEPROM using a device-unique obfuscation scheme
+- The obfuscation key is derived from the ESP8266's MAC address, chip ID, and a salt (configurable [here](./src/main.cpp#L37) in code) using SHA-256
+- The JSON payload is XORed with this derived key before being written to EEPROM, and de-obfuscated on read
+- This makes it much harder to recover secrets from a raw flash dump on another device, or with only partial knowledge of the hardware
+
+Limitations:
+
+- This is not true encryption and does not provide hardware-backed security or protection against a determined attacker with full device access
+- The public salt is not secret; if an attacker knows the salt, MAC, and chip ID, they can reconstruct the key
+- There is no secure element or tamper resistance
+
+**Do not assume confidentiality against a determined attacker**
+
+Warning: If the salt, the chip ID or the mac address change, the eeprom secure storage is clear and reset to ensure no data leak is possible
+
 ### 3. Build the firmware and filesystem
 
 To build the firmware you can use decontainer, docker or build it by yourself using [PlateformIO](https://docs.platformio.org/en/latest/core/installation/methods/installer-script.html)
@@ -275,15 +294,6 @@ From there, select and flash the filesystem using the `littlefs.bin` file
 
 Once the device reboots, the setup is complete!
 
-Note: The Wi-Fi credentials in config.json are migrated to EEPROM “secure storage” on first boot. After that, the Wi-Fi credentials are erased from config.json
-
-Data stored in EEPROM (or flash-based EEPROM emulation) is not secure by default
-All values (API keys, Wi-Fi credentials, tokens, etc.) are currently stored in clear text and can be recovered by anyone with physical access to the device or the ability to read the flash memory
-
-This project does not provide hardware-backed security
-
-Do not assume confidentiality against a determined attacker
-
 ## License
 
 This project is licensed under the **GPLv3 License** - see the [LICENSE](LICENSE) file for details

src/config/SecureStorage.cpp

@@ -20,6 +20,9 @@
 #include <array>
 #include <EEPROM.h>
 #include <Logger.h>
+#include <ESP8266WiFi.h>
+#include <user_interface.h>
+#include <BearSSLHelpers.h>
 
 #include "config/SecureStorage.h"
 
@@ -28,6 +31,35 @@ static constexpr uint8_t LEN_SHIFT = 8;
 static constexpr uint8_t LEN_HIGH_IDX = 4;
 static constexpr uint8_t LEN_LOW_IDX = 5;
 static constexpr uint8_t LEN_MASK = 0xFF;
+static constexpr size_t KEY_LEN = 32;
+
+static String kvSalt;
+
+/**
+ * @brief Set the public salt used in key derivation
+ *
+ * @param salt The public salt string
+ */
+void SecureStorage::setSalt(const String& salt) { kvSalt = salt; }
+
+/**
+ * @brief Derive the obfuscation key from device-unique parameters and public salt
+ *
+ * @param out32 Output buffer for the 32-byte derived key
+ *
+ * @returns void
+ */
+static void deriveKey(uint8_t* out32) {
+    String mac = WiFi.macAddress();
+    uint32_t chip = system_get_chip_id();
+
+    String input = mac + String(chip) + kvSalt;
+
+    br_sha256_context ctx;
+    br_sha256_init(&ctx);
+    br_sha256_update(&ctx, (const unsigned char*)input.c_str(), input.length());
+    br_sha256_out(&ctx, out32);
+}
 
 SecureStorage::SecureStorage(size_t eepromSize) : _eepromSize(eepromSize), _doc() {}
 
@@ -105,6 +137,13 @@ auto const SecureStorage::loadToMemory() -> bool {
 
     buf[len] = '\0';
 
+    // De-obfuscate using derived key
+    std::array<uint8_t, KEY_LEN> key;
+    deriveKey(key.data());
+    for (uint16_t i = 0; i < len; ++i) {
+        buf[i] ^= key[static_cast<size_t>(i) % KEY_LEN];
+    }
+
     DeserializationError err = deserializeJson(_doc, buf);
 
     if (err) {
@@ -150,8 +189,12 @@ auto const SecureStorage::flushToEEPROM() -> bool {
     EEPROM.write(LEN_HIGH_IDX, static_cast<uint8_t>((len >> LEN_SHIFT) & LEN_MASK));
     EEPROM.write(LEN_LOW_IDX, static_cast<uint8_t>(len & LEN_MASK));
 
+    // Obfuscate using derived key
+    std::array<uint8_t, KEY_LEN> key;
+    deriveKey(key.data());
     for (uint16_t i = 0; i < len; ++i) {
-        EEPROM.write(static_cast<int>(headerSize + i), static_cast<uint8_t>(out.charAt(i)));
+        uint8_t obfuscatedString = out.charAt(i) ^ key[static_cast<size_t>(i) % KEY_LEN];
+        EEPROM.write(static_cast<int>(headerSize + i), obfuscatedString);
     }
 
     if (!EEPROM.commit()) {

src/main.cpp

@@ -34,6 +34,7 @@ ConfigManager configManager;
 const char* AP_SSID = "GeekMagic";
 const char* AP_PASSWORD = "$str0ngPa$$w0rd";
 WiFiManager* wifiManager = nullptr;
+static String KV_SALT = "GeekMagicOpenFirmwareIsAwesome";
 
 static constexpr uint32_t SERIAL_BAUD_RATE = 115200;
 static constexpr uint32_t BOOT_DELAY_MS = 200;
@@ -67,6 +68,8 @@ void setup() {
 
     step++;
 
+    SecureStorage::setSalt(KV_SALT);
+
     if (configManager.secure.begin()) {
         Logger::info("SecureStorage initialized successfully", "ConfigManager");
     }