Go to file
Drew DeVault 6f9ea7d249 Overwrite spinner when showing proof 2020-12-26 19:24:50 -05:00
argon2i Add 'argon2i/' from commit '440ceb9612d5a20997e3e12728542df2de713ca4' 2020-11-25 10:48:57 -05:00
doc Return 1 for invalid proof, 2 for usage errors 2020-12-06 12:17:10 -05:00
include Fix build on macos 2020-12-24 14:22:11 -05:00
src Overwrite spinner when showing proof 2020-12-26 19:24:50 -05:00
.gitignore .gitignore: add object files and manpages 2020-11-26 08:06:19 -05:00
COPYING Initial commit 2020-11-25 10:48:52 -05:00
Makefile Add install and uninstall targets 2020-11-25 12:26:09 -05:00
README Use leading zero bits instead of digits 2020-12-24 09:04:22 -05:00
config.sh Add install and uninstall targets 2020-11-25 12:26:09 -05:00
configure Implement everything 2020-11-25 12:05:19 -05:00



mkproof is a small C program for generating proofs of work.


If mkproof is available as a package on your system, prefer to install that
rather than build it yourself.

mkproof depends only on a POSIX-like environment and a C99 compiler.

	$ ./configure
	$ make

This will produce three executables: mkchallenge, mkproof, and checkproof.


The situation: Bob wants Alice to do something, but Alice isn't sure if Bob is a

1. Alice runs `mkchallenge` and sends the challenge to Bob.
2. Bob runs `mkproof <challenge>` and wastes some CPU time. After several
   minutes of work, a proof is printed to stdout.
3. Bob sends the proof to Alice.
4. Alice runs `checkproof <challenge> <proof>` to verify the work.

Now Alice can be reasonably confident that Bob is not a robot, and proceed with
Bob's request.


To make a challenge, generate 16 random bytes. Choose the argon2 iterations and
memory parameters, and the number of zeroed digits, to tune the difficulty. The
challenge string is the terms "argon2id"; the iterations, memory use, and number
of digits which shall be zero, as decimal integers; and the random bytes as
hexadecimal; joining the terms with ":".

To make a proof, split the challenge by ":" and verify that the first token is
"argon2id". Decode the iterations, memory, and digits parameters, and the
challenge bytes.

Repeat the following algorithm to generate proofs until an argon2id key
is found whose first N bits are zero, where N is equal to the digits

1. Generate 16 random bytes (password).
2. Run argon2id with the generated password, and the memory and iteration
   parameters provided by the challenge, and the challenge bytes as the salt.
   The hash length and parallelism parameters shall be respectively set to 32
   and 1.
3. Encode the argon2id hash as hexadecimal.

When a suitable hash is found, encode the password in hexadecimal. This is the
proof which should be transmitted to the challenger.

To verify the proof, simply run the proof algorithm with the original challenge
parameters and the challengee's provided password and verify that the resulting
hexadecimal string is prefixed with the appropriate number of zeroes.


The defaults are tuned to take about five minutes on one core of a modern
consumer CPU.