aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorRunxi Yu <me@runxiyu.org>2025-03-24 22:26:38 +0800
committerRunxi Yu <me@runxiyu.org>2025-03-24 22:26:38 +0800
commit88500519a4d05459f426e7092f350ad4188a3222 (patch)
tree891410afb2c3f520149f577d95e6cd6cbd730de6
parentAdd website URLs in copyright text in wasm/solver.c (diff)
downloadpowxy-88500519a4d05459f426e7092f350ad4188a3222.tar.gz
powxy-88500519a4d05459f426e7092f350ad4188a3222.tar.zst
powxy-88500519a4d05459f426e7092f350ad4188a3222.zip
readme: Move the mechanism up a bit
-rw-r--r--README.md42
1 files changed, 21 insertions, 21 deletions
diff --git a/README.md b/README.md
index 9f6ad69..4761cb1 100644
--- a/README.md
+++ b/README.md
@@ -13,6 +13,27 @@ every hour.
A demo instance is available at [git.runxiyu.org](https://git.runxiyu.org/).
It may experience occasional outages.
+## Mechanism
+
+The client sends a request to the proxy. The proxy hashes information about the
+client's IP address and user agent to generate an identifier. It checks whether
+the client has a cookie containing an HMAC of the identifier. The connection is
+forwarded to the upstream server if and only if the identifier matches and the
+HMAC is valid.
+
+Otherwise, the client is presented with a challenge, which asks them to find
+a nonce that, when appended to the identifier, results in a SHA-256 hash that
+begins with a certain number of zero bits. The client must solve the challenge
+and submit it through an HTML form, which is then validated by the proxy. If
+validation passes, the client is issued a cookie containing their identifier's
+HMAC, and is redirected to request the page again, this time with the necessary
+cookie to pass the validation.
+
+JavaScript is provided to automatically solve the challenge without user
+interaction; the current solver requires WebAssembly. Clients that do not run
+JavaScript need to solve the challenge externally, e.g. via the C program
+provided near the HTML form, and submit their nonce manually.
+
## Bugs
- **The cryptography hasn't been audited.** I wrote this after a tiring school
@@ -58,27 +79,6 @@ Usage of ./powxy:
destination url base to proxy to (default "http://127.0.0.1:8080")
```
-## Mechanism
-
-The client sends a request to the proxy. The proxy hashes information about the
-client's IP address and user agent to generate an identifier. It checks whether
-the client has a cookie containing an HMAC of the identifier. The connection is
-forwarded to the upstream server if and only if the identifier matches and the
-HMAC is valid.
-
-Otherwise, the client is presented with a challenge, which asks them to find
-a nonce that, when appended to the identifier, results in a SHA-256 hash that
-begins with a certain number of zero bits. The client must solve the challenge
-and submit it through an HTML form, which is then validated by the proxy. If
-validation passes, the client is issued a cookie containing their identifier's
-HMAC, and is redirected to request the page again, this time with the necessary
-cookie to pass the validation.
-
-JavaScript is provided to automatically solve the challenge without user
-interaction; the current solver requires WebAssembly. Clients that do not run
-JavaScript need to solve the challenge externally, e.g. via the C program
-provided near the HTML form, and submit their nonce manually.
-
## Contribute
Create a branch that begins with `contrib/` and push to