More detailed README

1 files changed, 24 insertions, 2 deletions

diff --git a/README.md b/README.md
index 13492dc..7dd075f 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,8 @@
 # Powxy – anti-scraper reverse proxy
 
-Powxy uses a SHA-256 proof-of-work challenge to protect upstream resources from
-scraper bots.
+Powxy is a reverse proxy that sits in front of your upstream service and
+enforces a SHA-256 proof-of-work challenge. The goal is to discourage scraping,
+as it becomes expensive for a client to perform en masse.
 
 ## Demo
 
@@ -49,6 +50,27 @@ 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
+and its 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. 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