One firmware: the Debug Console in every build, off until switched on, with the device's own token

There is no Debug Build any more (ADR 0010, issue #68, Q188 to Q195). The console and the test commands are compiled into every firmware. It listens only while Settings > Debug Console is on, which isn't the default; off, neither its task nor its 4 KB ring exists. The token is made by the device and shown on that page; a client proves it knows it by answering a challenge with an HMAC, so it never crosses the network, and five wrong answers close the console for a minute. DBG in the Status Bar while it listens. Over USB serial only: debug on, debug token <value>, debug token new. scripts/flash.sh --debug uses them to set a device up with the developer's token. scripts/rdbg.py takes the token from -t, $RORO_DEBUG_TOKEN or the file, answers the challenge, and fetches a release's ELF to decode a crash. Gone: the cardputer-adv-debug environment, RORO_DEBUG, the +debug version, scripts/debug_flags.py, update install ... force, and the rule that a Debug Build doesn't install releases. Old clients and old firmwares don't talk to each other. Against the builds it replaces: 30 KB more flash and 88 bytes more static RAM than the release, 4 KB less RAM than the Debug Build. 468 host tests. Checked on the device: off by default, login, the pause after wrong tokens, Safe Mode with the console, the setting surviving an update, debug off. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EhqxQ49eCju4CzKYNjZzwT
2026-10-06 22:59:35 +02:00
parent 1353e6a5f9
commit c68741cc46
65 changed files with 1245 additions and 374 deletions
@@ -0,0 +1,117 @@
+#include "debug_auth.h"
+
+#include <cstring>
+
+#include "sha256.h"
+
+namespace roro::debug {
+
+namespace {
+const char kAlphabet[] = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+}
+
+std::string makeToken(const uint8_t random[kTokenRandom]) {
+    std::string token;
+    uint32_t bits = 0;
+    int have = 0;
+    size_t next = 0;
+    while (token.size() < kTokenChars) {
+        if (have < 5) {
+            bits = (bits << 8) | random[next++];
+            have += 8;
+        }
+        token += kAlphabet[(bits >> (have - 5)) & 31];
+        have -= 5;
+    }
+    return token;
+}
+
+std::string tidyToken(const std::string& typed) {
+    std::string out;
+    for (char c : typed) {
+        if (c == '-' || c == ' ' || c == '\t' || c == '\r' || c == '\n') continue;
+        if (c >= 'a' && c <= 'z') c = static_cast<char>(c - 'a' + 'A');
+        // Crockford's rule for the letters his alphabet leaves out: read as the digit they look like.
+        if (c == 'O') c = '0';
+        if (c == 'I' || c == 'L') c = '1';
+        out += c;
+    }
+    return out;
+}
+
+bool validToken(const std::string& tidied) {
+    if (tidied.size() < kMinTokenChars || tidied.size() > kMaxTokenChars) return false;
+    for (char c : tidied)
+        if (c <= ' ' || c > '~' || c == '-' || (c >= 'a' && c <= 'z') || c == 'O' || c == 'I' || c == 'L') return false;
+    return true;
+}
+
+std::string groupToken(const std::string& token) {
+    std::string out;
+    for (size_t i = 0; i < token.size(); i++) {
+        if (i && i % 4 == 0) out += '-';
+        out += token[i];
+    }
+    return out;
+}
+
+void hmacSha256(const uint8_t* key, size_t keyLen, const uint8_t* message, size_t messageLen, uint8_t out[32]) {
+    uint8_t block[64] = {};
+    if (keyLen > sizeof block) Sha256::hash(key, keyLen, block);  // a long key is hashed first
+    else memcpy(block, key, keyLen);
+
+    uint8_t pad[64];
+    for (size_t i = 0; i < sizeof pad; i++) pad[i] = block[i] ^ 0x36;
+    uint8_t inner[32];
+    Sha256 in;
+    in.update(pad, sizeof pad);
+    in.update(message, messageLen);
+    in.finish(inner);
+
+    for (size_t i = 0; i < sizeof pad; i++) pad[i] = block[i] ^ 0x5c;
+    Sha256 outer;
+    outer.update(pad, sizeof pad);
+    outer.update(inner, sizeof inner);
+    outer.finish(out);
+}
+
+std::string toHex(const uint8_t* data, size_t len) {
+    static const char digits[] = "0123456789abcdef";
+    std::string out;
+    out.reserve(len * 2);
+    for (size_t i = 0; i < len; i++) {
+        out += digits[data[i] >> 4];
+        out += digits[data[i] & 15];
+    }
+    return out;
+}
+
+std::string answerFor(const std::string& token, const uint8_t nonce[kNonceBytes]) {
+    uint8_t mac[32];
+    hmacSha256(reinterpret_cast<const uint8_t*>(token.data()), token.size(), nonce, kNonceBytes, mac);
+    return toHex(mac, sizeof mac);
+}
+
+bool sameText(const std::string& a, const std::string& b) {
+    uint8_t diff = a.size() != b.size();
+    for (size_t i = 0; i < b.size(); i++) diff |= static_cast<uint8_t>((i < a.size() ? a[i] : 0) ^ b[i]);
+    return diff == 0;
+}
+
+bool AuthGate::locked(uint32_t nowMs) {
+    if (locked_ && nowMs - lockedAtMs_ >= kLockMs) {  // unsigned: right across the 49-day wrap too
+        locked_ = false;
+        failures_ = 0;
+    }
+    return locked_;
+}
+
+bool AuthGate::failed(uint32_t nowMs) {
+    if (locked(nowMs)) return false;
+    if (++failures_ < kMaxFailures) return false;
+    locked_ = true;
+    lockedAtMs_ = nowMs;
+    return true;
+}
+
+}  // namespace roro::debug
@@ -0,0 +1,59 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <string>
+
+// Who may use the Debug Console (ADR 0010): a token that only the device and its owner know, proved
+// with a challenge and an answer so that it never crosses the network, and a pause after wrong answers.
+namespace roro::debug {
+
+constexpr size_t kTokenChars = 20;     // a token the device makes: 100 bits
+constexpr size_t kTokenRandom = 13;    // the random bytes it takes
+constexpr size_t kMinTokenChars = 16;  // a token typed by hand, once tidied
+constexpr size_t kMaxTokenChars = 64;
+constexpr size_t kNonceBytes = 16;
+
+// A token from random bytes: 20 characters of Crockford's base32 (no I, L, O or U to misread).
+std::string makeToken(const uint8_t random[kTokenRandom]);
+
+// What a person typed, as it's stored and compared: no dashes or spaces, in capitals, and with O
+// read as 0, I and L as 1. So a token can be read off the screen in groups, typed in any case,
+// and the usual misreadings don't matter.
+std::string tidyToken(const std::string& typed);
+
+// A tidied token that may be stored: 16 to 64 printable ASCII characters, as tidyToken leaves them.
+bool validToken(const std::string& tidied);
+
+// For the screen: K7QF-3M2X-9WBD-HT4P-6RNC.
+std::string groupToken(const std::string& token);
+
+void hmacSha256(const uint8_t* key, size_t keyLen, const uint8_t* message, size_t messageLen, uint8_t out[32]);
+
+std::string toHex(const uint8_t* data, size_t len);
+
+// What a client must send back for a challenge: HMAC-SHA256 of the nonce, keyed by the token, in hex.
+std::string answerFor(const std::string& token, const uint8_t nonce[kNonceBytes]);
+
+// Compares without stopping at the first difference, so timing says nothing about the answer.
+bool sameText(const std::string& a, const std::string& b);
+
+// Five wrong answers in a row, from anyone, and nobody is listened to for a minute.
+class AuthGate {
+   public:
+    static constexpr int kMaxFailures = 5;
+    static constexpr uint32_t kLockMs = 60000;
+
+    bool locked(uint32_t nowMs);
+    // A wrong answer. True if it's the one that starts the pause.
+    bool failed(uint32_t nowMs);
+    void succeeded() { failures_ = 0; }
+    int failures() const { return failures_; }
+
+   private:
+    int failures_ = 0;
+    bool locked_ = false;
+    uint32_t lockedAtMs_ = 0;
+};
+
+}  // namespace roro::debug