Add bond conversion API between v1 and v2 bond data preserving old bonds

h2zero · h2zero · commit a7e6a092d75b · 2026-03-18T14:11:44.000-06:00
diff --git a/examples/NimBLE_Bond_Migration/NimBLE_Bond_Migration.ino b/examples/NimBLE_Bond_Migration/NimBLE_Bond_Migration.ino
@@ -0,0 +1,66 @@
+/**
+ * NimBLE_Bond_Migration Demo:
+ *
+ * This example demonstrates running one-time bond-store migration before
+ * NimBLE initialization. Set NIMBLE_BOND_MIGRATION_MODE to select direction:
+ * 0 = off, 1 = migrate to current, 2 = migrate to v1.
+ */
+
+#include <Arduino.h>
+#include <NimBLEDevice.h>
+#include <NimBLEBondMigration.h>
+
+namespace NimBLE_Bond_Migration = NimBLEBondMigration;
+
+#ifndef NIMBLE_BOND_MIGRATION_MODE
+#define NIMBLE_BOND_MIGRATION_MODE 0
+#endif
+
+#if (NIMBLE_BOND_MIGRATION_MODE < 0) || (NIMBLE_BOND_MIGRATION_MODE > 2)
+#error "NIMBLE_BOND_MIGRATION_MODE must be 0 (off), 1 (to current), or 2 (to v1)"
+#endif
+
+void setup() {
+    Serial.begin(115200);
+    Serial.println("Starting NimBLE_Bond_Migration Demo");
+
+#if NIMBLE_BOND_MIGRATION_MODE == 1
+    {
+        esp_err_t rc = NimBLE_Bond_Migration::migrateBondStoreToCurrent();
+        Serial.printf("NimBLE_Bond_Migration to current rc=%d\n", static_cast<int>(rc));
+    }
+#elif NIMBLE_BOND_MIGRATION_MODE == 2
+    {
+        esp_err_t rc = NimBLE_Bond_Migration::migrateBondStoreToV1();
+        Serial.printf("NimBLE_Bond_Migration to v1 rc=%d\n", static_cast<int>(rc));
+        if (rc == ESP_OK) {
+            Serial.println("NimBLE_Bond_Migration completed to v1, upload v1 firmware to continue");
+            while (true) {
+                delay(1000);
+            }
+        }
+    }
+#endif
+
+    NimBLEDevice::init("NimBLE");
+    NimBLEDevice::setPower(3); /** +3db */
+
+    NimBLEDevice::setSecurityAuth(true, true, false); /** bonding, MITM, don't need BLE secure connections as we are using passkey pairing */
+    NimBLEDevice::setSecurityPasskey(123456);
+    NimBLEDevice::setSecurityIOCap(BLE_HS_IO_DISPLAY_ONLY); /** Display only passkey */
+    NimBLEServer*         pServer                  = NimBLEDevice::createServer();
+    NimBLEService*        pService                 = pServer->createService("ABCD");
+    NimBLECharacteristic* pNonSecureCharacteristic = pService->createCharacteristic("1234", NIMBLE_PROPERTY::READ);
+    NimBLECharacteristic* pSecureCharacteristic =
+        pService->createCharacteristic("1235",
+                                       NIMBLE_PROPERTY::READ | NIMBLE_PROPERTY::READ_ENC | NIMBLE_PROPERTY::READ_AUTHEN);
+
+    pNonSecureCharacteristic->setValue("Hello Non Secure BLE");
+    pSecureCharacteristic->setValue("Hello Secure BLE");
+
+    NimBLEAdvertising* pAdvertising = NimBLEDevice::getAdvertising();
+    pAdvertising->addServiceUUID("ABCD");
+    pAdvertising->start();
+}
+
+void loop() {}
diff --git a/src/NimBLEBondMigration.h b/src/NimBLEBondMigration.h
@@ -0,0 +1,273 @@
+#pragma once
+
+#if !defined(ESP_PLATFORM)
+# error "NimBLEBondMigration.h currently requires ESP_PLATFORM (NVS backend)."
+#endif
+
+#include <stdint.h>
+#include <stdio.h>
+#include <string.h>
+
+#include "esp_err.h"
+#include "esp_log.h"
+#include "nvs.h"
+#include "syscfg/syscfg.h"
+
+namespace NimBLEBondMigration {
+
+namespace detail {
+
+static constexpr const char* kLogTag        = "NimBLEBondMigration";
+static constexpr const char* kBondNamespace = "nimble_bond";
+static constexpr const char* kOurSecPrefix  = "our_sec";
+static constexpr const char* kPeerSecPrefix = "peer_sec";
+static constexpr size_t      kNvsKeyMaxLen  = 16;
+
+typedef struct {
+    uint8_t type;
+    uint8_t val[6];
+} ble_addr_t;
+
+struct BleStoreValueSecV1 {
+    ble_addr_t peer_addr;
+
+    uint8_t key_size;
+    uint16_t ediv;
+    uint64_t rand_num;
+    uint8_t ltk[16];
+    uint8_t ltk_present : 1;
+
+    uint8_t irk[16];
+    uint8_t irk_present : 1;
+
+    uint8_t csrk[16];
+    uint8_t csrk_present : 1;
+
+    unsigned authenticated : 1;
+    uint8_t sc : 1;
+};
+
+struct BleStoreValueSecCurrent {
+    ble_addr_t peer_addr;
+    uint16_t   bond_count;
+
+    uint8_t key_size;
+    uint16_t ediv;
+    uint64_t rand_num;
+    uint8_t ltk[16];
+    uint8_t ltk_present : 1;
+
+    uint8_t irk[16];
+    uint8_t irk_present : 1;
+
+    uint8_t csrk[16];
+    uint8_t csrk_present : 1;
+    uint32_t sign_counter;
+
+    unsigned authenticated : 1;
+    uint8_t sc : 1;
+};
+
+struct MigrationStats {
+    uint16_t scanned;
+    uint16_t converted;
+    uint16_t alreadyTarget;
+    uint16_t skippedUnknownSize;
+};
+
+inline bool makeBondKey(char* out, size_t outLen, const char* prefix, uint16_t index) {
+    const int written = snprintf(out, outLen, "%s_%u", prefix, index);
+    return written > 0 && static_cast<size_t>(written) < outLen;
+}
+
+inline esp_err_t migrateEntryToCurrent(nvs_handle_t nvsHandle,
+                                       const char* key,
+                                       uint16_t index,
+                                       MigrationStats* stats) {
+    size_t blobSize = 0;
+    esp_err_t err = nvs_get_blob(nvsHandle, key, nullptr, &blobSize);
+    if (err == ESP_ERR_NVS_NOT_FOUND) {
+        return ESP_OK;
+    }
+    if (err != ESP_OK) {
+        return err;
+    }
+
+    stats->scanned++;
+
+    if (blobSize == sizeof(BleStoreValueSecCurrent)) {
+        stats->alreadyTarget++;
+        return ESP_OK;
+    }
+
+    if (blobSize != sizeof(BleStoreValueSecV1)) {
+        stats->skippedUnknownSize++;
+        ESP_LOGW(kLogTag,
+                 "Skipping key=%s due to unexpected size=%u",
+                 key,
+                 static_cast<unsigned>(blobSize));
+        return ESP_OK;
+    }
+
+    BleStoreValueSecV1 oldValue{};
+    size_t readSize = sizeof(oldValue);
+    err = nvs_get_blob(nvsHandle, key, &oldValue, &readSize);
+    if (err != ESP_OK) {
+        return err;
+    }
+
+    BleStoreValueSecCurrent newValue{};
+    newValue.peer_addr = oldValue.peer_addr;
+    newValue.bond_count = index;
+    newValue.key_size = oldValue.key_size;
+    newValue.ediv = oldValue.ediv;
+    newValue.rand_num = oldValue.rand_num;
+    memcpy(newValue.ltk, oldValue.ltk, sizeof(newValue.ltk));
+    newValue.ltk_present = oldValue.ltk_present;
+    memcpy(newValue.irk, oldValue.irk, sizeof(newValue.irk));
+    newValue.irk_present = oldValue.irk_present;
+    memcpy(newValue.csrk, oldValue.csrk, sizeof(newValue.csrk));
+    newValue.csrk_present = oldValue.csrk_present;
+    newValue.sign_counter = 0;
+    newValue.authenticated = oldValue.authenticated;
+    newValue.sc = oldValue.sc;
+
+    err = nvs_set_blob(nvsHandle, key, &newValue, sizeof(newValue));
+    if (err != ESP_OK) {
+        return err;
+    }
+
+    stats->converted++;
+    return ESP_OK;
+}
+
+inline esp_err_t migrateEntryToV1(nvs_handle_t nvsHandle,
+                                  const char* key,
+                                  MigrationStats* stats) {
+    size_t blobSize = 0;
+    esp_err_t err = nvs_get_blob(nvsHandle, key, nullptr, &blobSize);
+    if (err == ESP_ERR_NVS_NOT_FOUND) {
+        return ESP_OK;
+    }
+    if (err != ESP_OK) {
+        return err;
+    }
+
+    stats->scanned++;
+
+    if (blobSize == sizeof(BleStoreValueSecV1)) {
+        stats->alreadyTarget++;
+        return ESP_OK;
+    }
+
+    if (blobSize != sizeof(BleStoreValueSecCurrent)) {
+        stats->skippedUnknownSize++;
+        ESP_LOGW(kLogTag,
+                 "Skipping key=%s due to unexpected size=%u",
+                 key,
+                 static_cast<unsigned>(blobSize));
+        return ESP_OK;
+    }
+
+    BleStoreValueSecCurrent curValue{};
+    size_t readSize = sizeof(curValue);
+    err = nvs_get_blob(nvsHandle, key, &curValue, &readSize);
+    if (err != ESP_OK) {
+        return err;
+    }
+
+    BleStoreValueSecV1 oldValue{};
+    oldValue.peer_addr = curValue.peer_addr;
+    oldValue.key_size = curValue.key_size;
+    oldValue.ediv = curValue.ediv;
+    oldValue.rand_num = curValue.rand_num;
+    memcpy(oldValue.ltk, curValue.ltk, sizeof(oldValue.ltk));
+    oldValue.ltk_present = curValue.ltk_present;
+    memcpy(oldValue.irk, curValue.irk, sizeof(oldValue.irk));
+    oldValue.irk_present = curValue.irk_present;
+    memcpy(oldValue.csrk, curValue.csrk, sizeof(oldValue.csrk));
+    oldValue.csrk_present = curValue.csrk_present;
+    oldValue.authenticated = curValue.authenticated;
+    oldValue.sc = curValue.sc;
+
+    err = nvs_set_blob(nvsHandle, key, &oldValue, sizeof(oldValue));
+    if (err != ESP_OK) {
+        return err;
+    }
+
+    stats->converted++;
+    return ESP_OK;
+}
+
+inline esp_err_t migrateBondStore(bool toCurrent, uint16_t maxEntries) {
+    nvs_handle_t nvsHandle;
+    esp_err_t err = nvs_open(kBondNamespace, NVS_READWRITE, &nvsHandle);
+    if (err != ESP_OK) {
+        ESP_LOGE(kLogTag,
+                 "Failed to open NVS namespace '%s', err=%d",
+                 kBondNamespace,
+                 static_cast<int>(err));
+        return err;
+    }
+
+    MigrationStats stats{};
+    char key[kNvsKeyMaxLen]{};
+
+    for (uint16_t i = 1; i <= maxEntries; ++i) {
+        if (!makeBondKey(key, sizeof(key), kOurSecPrefix, i)) {
+            nvs_close(nvsHandle);
+            return ESP_FAIL;
+        }
+
+        err = toCurrent ? migrateEntryToCurrent(nvsHandle, key, i, &stats)
+                        : migrateEntryToV1(nvsHandle, key, &stats);
+        if (err != ESP_OK) {
+            nvs_close(nvsHandle);
+            return err;
+        }
+
+        if (!makeBondKey(key, sizeof(key), kPeerSecPrefix, i)) {
+            nvs_close(nvsHandle);
+            return ESP_FAIL;
+        }
+
+        err = toCurrent ? migrateEntryToCurrent(nvsHandle, key, i, &stats)
+                        : migrateEntryToV1(nvsHandle, key, &stats);
+        if (err != ESP_OK) {
+            nvs_close(nvsHandle);
+            return err;
+        }
+    }
+
+    if (stats.converted > 0) {
+        err = nvs_commit(nvsHandle);
+        if (err != ESP_OK) {
+            nvs_close(nvsHandle);
+            return err;
+        }
+    }
+
+    nvs_close(nvsHandle);
+
+    ESP_LOGI(kLogTag,
+             "Bond migration %s: scanned=%u converted=%u already=%u skipped=%u",
+             toCurrent ? "to-current" : "to-v1",
+             stats.scanned,
+             stats.converted,
+             stats.alreadyTarget,
+             stats.skippedUnknownSize);
+
+    return ESP_OK;
+}
+
+} // namespace detail
+
+inline esp_err_t migrateBondStoreToCurrent(uint16_t maxEntries = MYNEWT_VAL(BLE_STORE_MAX_BONDS)) {
+    return detail::migrateBondStore(true, maxEntries);
+}
+
+inline esp_err_t migrateBondStoreToV1(uint16_t maxEntries = MYNEWT_VAL(BLE_STORE_MAX_BONDS)) {
+    return detail::migrateBondStore(false, maxEntries);
+}
+
+} // namespace NimBLEBondMigration
