Skip to content

fix(rpc): compare the admin API key in constant time - #1826

Open
ygd58 wants to merge 1 commit into
genlayerlabs:v0.123-devfrom
ygd58:fix/admin-key-constant-time-compare
Open

ygd58 wants to merge 1 commit into
genlayerlabs:v0.123-devfrom
ygd58:fix/admin-key-constant-time-compare

Conversation

@ygd58

@ygd58 ygd58 commented Nov 12, 2026

Copy link
Copy Markdown

What

  • Compare ADMIN_API_KEY with hmac.compare_digest instead of == in the three places that check it: the require_admin_access decorator (also exported as check_forbidden_method_in_hosted_studio), cancel_transaction and admin_upgrade_contract_code.
  • One small helper, _admin_key_matches(presented, configured), in endpoints.py next to the decorator. Behaviour is unchanged: same results, same errors.
  • 39 new unit tests in tests/unit/test_admin_key_comparison.py.

Why

== on strings returns at the first differing character, so the time a wrong key takes to be rejected tells a remote caller how much of it was right. The key guards what a hosted Studio keeps away from anonymous callers (validators, providers, snapshots, DB tables, tiers and API keys).

This is a hardening, not a demonstrated exploit. A timing attack against a network-served comparison is hard, and I did not try one or measure anything against a live instance. Constant-time comparison is the standard answer and costs nothing here, in the same direction as #1801 and #1731.

Testing done

  • Reproduced the starting point by reading and by a scan of backend/ for secrets compared with ==: exactly these three places, and no use of compare_digest anywhere. API keys are not affected: they are stored as SHA-256 hashes and looked up by the unique key_hash.
  • Same answers as before: the helper was compared with the old == on 60,008 inputs (ASCII, unicode, lone surrogates, near-equal prefixes, longer/shorter keys, and non-string values like None, ints, bytes, lists): no difference and no exception.
  • New tests: the helper itself (equal, different, prefix, case, non-ASCII, lone surrogates, non-strings), the decorator (correct key runs, eight kinds of wrong or odd key give Invalid or missing admin key, hosted without a key is still blocked), and the two inline checks (an odd admin_key gives JSONRPCError, not TypeError or UnicodeEncodeError).
  • The tests that check that compare_digest is really used (one per call site, 3 in total) fail when the old == behaviour is restored (verified with a plugin that swaps the helper for plain equality); the other 36 pass on both, they pin the behaviour that must not change.
  • pytest tests/unit: 1890 passed, 7 skipped. ruff check (0.15.22) and black --check are clean.
  • Not run: integration and e2e suites (they need Docker and an LLM). tests/integration/test_upgrade_contract.py exercises the upgrade endpoint and I could not run it.

Decisions made

  • Bytes with surrogatepass. compare_digest accepts only ASCII str, and JSON can carry a lone surrogate like "\ud800", which .encode() rejects. Without surrogatepass such a key would turn "wrong key" into an internal error; with it the answer is the same as with ==.
  • A key that is not a string never matches, as with ==.
  • The helper lives in endpoints.py, next to the decorator, because all three call sites are in that file. I did not add a module for it.
  • No new setting, no change to which operations are gated.
  • The unrelated sim_* methods that are not gated (sim_fundAccount, sim_cancelTransaction, sim_upgradeContractCode, ...) were checked while I was here: the last two authorize inside the function (admin key or the deployer's/sender's signature), so I left them alone.

Checks

  • I have tested this code
  • I have reviewed my own PR
  • I have created an issue for this PR: none, I did not want to open a public issue for a hardening that is visible in the source anyway
  • I have set a descriptive PR title compliant with conventional commits

Reviewing tips

The behaviour is in the 17 lines of _admin_key_matches; the three call-site changes are one line each. The tests are easiest to read from TestAdminKeyMatches down.

User facing release notes

None. The admin key is checked the same way as before, only in constant time.

The admin key that protects the operations a hosted Studio keeps away from
anonymous callers was checked with `==` in three places: the
`require_admin_access` decorator (aliased as
`check_forbidden_method_in_hosted_studio`), `cancel_transaction` and
`admin_upgrade_contract_code`. Comparing strings with `==` returns at the
first differing character, so the time a wrong key takes to be rejected tells
a remote caller how much of it was right.

This is a hardening, not a demonstrated exploit: a timing attack on a
network-served comparison is hard, and I did not try one. Constant-time
comparison is the standard answer and costs nothing here.

Use `hmac.compare_digest` through one small helper. The values are compared as
UTF-8 bytes because `compare_digest` only accepts ASCII `str`, and lone
surrogates, which JSON can carry, are passed through with `surrogatepass` so
that an odd key is rejected like any other wrong key instead of raising. A key
that is not a string never matches, as before.

The helper agrees with the old `==` on 60,000 random strings (ASCII, unicode,
lone surrogates, near-equal prefixes) and on non-string values. A scan of the
backend found no other secret compared with `==`: API keys are stored as
SHA-256 hashes and looked up by a unique `key_hash`.
@coderabbitai

coderabbitai Bot commented Nov 12, 2026

Copy link
Copy Markdown
Contributor

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 00780185-c67a-480f-ba33-22988b3eab68

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • Trigger review
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant