Table of contents
- Security Model: Why secret Alone Isn't Enough
- The design in one sentence
- Why bother - isn't the encryption itself enough?
- How much protection this actually provides - the honest math
- Why the binary being "technically readable" doesn't defeat this
- Why filesystem permissions matter as much as the crypto here
- What this design is, and isn't, protecting against
- Practical takeaway
- See also
Security Model: Why secret Alone Isn't Enough
This page explains the reasoning behind ProxyAuth's two-part token security design - why token forgery requires more than just config.json's secret, what that extra layer actually buys you, and where its real limits are. This is the threat-model rationale behind the mechanics described in How a Token Is Built and Verified and SSO Across Multiple Instances.
The design in one sentence
Forging a valid token requires knowing two independent things: config.json's secret, and a set of build-time constants baked into the compiled binary (build_rand, the field shuffle order, build_seed2). Leaking one without the other is not enough to forge tokens.
Why bother - isn't the encryption itself enough?
XChaCha20-Poly1305 (the AEAD cipher protecting the token on the wire - see How a Token Is Built and Verified) already guarantees authenticity: nobody without the derived key can produce a ciphertext that decrypts successfully at all. So in a pure "does this token decrypt" sense, the extra hashing layer adds nothing against someone who doesn't have secret.
What it does add is protection for a more specific, realistic scenario: secret leaks on its own, without the server itself being compromised. This happens more often than a full server breach - a config.json accidentally committed to a repo, exposed in a misconfigured backup, leaked via a logging mistake, or exfiltrated through an unrelated vulnerability that only reaches the filesystem's config directory. In that scenario, secret alone lets an attacker decrypt captured tokens (read session contents) but, by design, doesn't hand them the ability to forge new ones - because forging also requires the build constants, which live somewhere else entirely: inside the compiled binary, not in config.json.
How much protection this actually provides - the honest math
The relevant unknowns, and their real entropy as generated in build.rs:
| Unknown | Real space | Why |
|---|---|---|
| Field shuffle order | 720 (6!) | Only 6 fields are being ordered - regardless of how the seed is generated, there are at most 720 distinguishable outcomes. |
build_rand |
~10^9 (~30 bits) | rng.gen_range(1..999_999_999) |
build_seed2 |
~89 (~7 bits) | rng.gen_range(10..99), only used in non-fast mode |
build_time |
Low, in practice | Not random at all - the literal build timestamp. Often narrowable from public release dates, Docker image build times, or CI logs. |
Combined, assuming the attacker has zero contextual knowledge of build_time: roughly 720 x 10^9 x 89 x (a wide time range) ~ 2^73. That's a real, non-trivial search space - well beyond casual guessing, though short of the >=2^128 margin conventionally expected of a standalone cryptographic secret. If an attacker can narrow build_time using public context (a very realistic assumption for an open-source project with public releases), the effective space drops closer to 2^46 - crackable offline within hours on modest hardware, faster with parallelization.
Bottom line: this is meaningful defense-in-depth, not decorative - but it shouldn't be relied on as a standalone cryptographic guarantee. Its real strength depends heavily on how much the attacker already knows about your deployment.
Why the binary being "technically readable" doesn't defeat this
It's tempting to assume that since build_rand etc. end up as plain string literals in the compiled binary (via env!("BUILD_RAND") at compile time), anyone with shell access can trivially extract them - e.g. with strings /usr/local/bin/proxyauth | grep ....
In practice, that doesn't work. A Rust binary of any real size contains hundreds of incidental numeric string literals from its dependencies (hash tables, test fixtures, error codes, alignment padding) - a build constant doesn't stand out from the noise with a simple grep. Reliably identifying the specific string used by generate_token()/build_info::get() requires actual reverse engineering - disassembling the binary and tracing which literal is loaded at the relevant call site (tools like Ghidra/IDA, real effort, not a one-liner).
So: the binary is not a secure vault, but it's also not a soft target either. It raises the bar from "instant" to "requires deliberate reverse-engineering skill and effort" - genuinely useful, if not maximal, protection.
Why filesystem permissions matter as much as the crypto here
The two halves of this design are protected by two different access boundaries, which is what makes the separation meaningful in practice rather than just on paper:
| Secret half | Where it lives | Who can read it |
|---|---|---|
secret |
/etc/proxyauth/config.json |
Only the proxyauth system user and root - the directory is chmod 750, set up automatically by proxyauth prepare (see Installation & Deployment Guide) |
| Build constants | The compiled binary (e.g. /usr/local/bin/proxyauth) |
Typically any local user who can execute/read the binary - usual install permissions (755) |
This asymmetry is what actually makes the design work as intended:
- An attacker who only exfiltrates
config.json(e.g. via a backup leak, a misconfigured file share, an unrelated app-level vulnerability that reads files) getssecret- but doesn't automatically get a foothold to read the binary too, since that's a separate, unrelated access path. - An attacker with plain shell access to the box (but not
root/proxyauth) can potentially reverse-engineer the binary, but is blocked fromconfig.jsonentirely by filesystem permissions - nosecret, no way to use whatever they extract. - Only an attacker who compromises both -
root/proxyauth-level access to the config directory, and is willing to reverse-engineer the binary - gets everything needed to forge tokens outright. At that point, though, they typically already have far more direct options (reading tokens straight out of memory, modifying the running process, etc.), so this scenario is less about this specific mechanism failing and more a reflection of what full compromise generally means.
What this design is, and isn't, protecting against
Does protect against:
secretleaking in isolation (config backup exposure, accidental commit, log leak, a vulnerability elsewhere that only reaches the config file) without accompanying server/binary access.
Doesn't protect against:
- Full server compromise (root or equivalent access) - at that point, an attacker can generally read
secret, the binary, and live process memory alike; this mechanism doesn't meaningfully raise the bar further in that scenario. - An attacker who already has both
config.jsonand binary access through two independent, unrelated weaknesses.
Costs of the design:
- Tokens aren't portable between independently-built instances by default - this is why the SSO key export/import mechanism exists at all. A simpler protocol (encryption alone, no build-constant layer) wouldn't need it.
- More moving parts in the token-validation code path - historically, this is also where several of the constant-time-comparison issues turned up during the project's security audit (see
AUDIT_AI.md). More surface area for a home-grown mechanism means more chances to implement a piece of it incorrectly.
Practical takeaway
Treat this as one deliberate layer among several, not a substitute for protecting secret itself:
- Keep
/etc/proxyauthat its default750permissions - don't loosen it. - Don't distribute the compiled binary anywhere it doesn't need to be (public download mirrors are fine for the open-source release itself, but a production binary customized/configured differently shouldn't be casually copied around).
- Treat a
secretleak as a real incident regardless of this mechanism - rotate it, and be aware that any tokens issued under the old value remain decryptable by whoever has the old value, even if they can't forge new ones outright.
See also
- How a Token Is Built and Verified - the mechanics this page explains the reasoning for.
- Anti-Replay Protection - a complementary defense: per-request HMAC signing, independent of session tokens entirely.
- Group- and Role-Based Access Control - a separate layer worth knowing about here: once a token is valid, which routes it can reach depends on
username/groups/rolesmatching, not just the token being genuine - including the "all empty" gotcha where a route with none of the three configured is open to any authenticated account. - SSO Across Multiple Instances (GPG Key Export/Import) - why build constants need explicit, encrypted synchronization across instances.
- Installation & Deployment Guide - the
750permissions on/etc/proxyauth, set up byproxyauth prepare.
📖 Wiki Home · 💻 Source Code · 🐛 Report an Issue · 📜 License
Found an error or something outdated on this page? Open an issue or submit a PR against the wiki repository.