X-Git-Url: http://www.git.cypherpunks.ru/?a=blobdiff_plain;f=README;h=46c7543d216e8fc006ec20445bb85735a189c933;hb=93152d43b030d563997f79307be51a7c3707b45b;hp=a307e8d7fea5aceb2c180379d8338851c12a5a8f;hpb=915a46b16cf4f61778e4b30364e299026656a60e;p=gohpenc.git

diff --git a/README b/README
index a307e8d..46c7543 100644
--- a/README
+++ b/README
@@ -1,53 +1,37 @@
 Go high-performance encryption utility.
 
 gohpenc highly resembles hpenc tool (https://github.com/vstakhov/hpenc).
-
-Why it was written? hpenc has some problems: it does not work on aarch64
-and sparc64 architectures under FreeBSD (as seen in the port's Makefile)
-and produces incompatible output (unauthenticated after 8192 blocks)
-between FreeBSD and HardenedBSD systems somehow. Instead of painful
-debugging I decided to write something similar on the Go language,
-widening supported platforms.
-
-gohpenc is incompatible with hpenc and much simpler:
-
-* it uses only ChaCha20-Poly1305 algorithm
-* no random data generation mode
-* no metadata in output stream and no structure validation. Only blocks
-  authentication
-* simpler key derivation -- new key for each block
-
-But it still satisfies most of hpenc aims:
-
-* Very simple key management -- single pre-shared key
-* Parallelizeable -- each block is encrypted in different thread, so all
-  your CPUs could be utilized
-* Very fast -- ChaCha20-Poly1305 is fast even on relatively low-end
-  devices like mobile devices. Despite gohpenc is written on Go, its
-  dependent libraries contain assembly-optimized code
-* Built-in authentication and integrity check with small data overhead
-
-How encryption/authentication is performed:
-
-* First 32 bytes of the stream contains random data, called salt
-* BLAKE2X is initialized: unknown length, PSK key as a MAC key. It
-  creates XOF that will be used as a KDF
-* Salt is fed into that XOF
-* All data is processed block by block
-* New key is derived for each block by reading it from the XOF
-* ChaCha20-Poly1305 algorithm is initialized with that key
-* 32-bit big-endian value with the length of the block is outputted,
-  then an encrypted and authenticated block goes further, with
-  authenticated data containing that 32-bit length value
-
-       /----------BLOCK-------------\ /----------BLOCK------------\
-+------+-----+------------+----------+-----+------------+----------+----
-| SALT | LEN | CIPHERTEXT | AUTH TAG | LEN | CIPHERTEXT | AUTH TAG | ...
-+------+-----+------------+----------+-----+------------+----------+----
-
-gohpenc preallocates memory for one block for each thread. If you want
-to process data with 1 MiB blocks in 4 threads, then you have to have at
-least 4 MiBs of free memory. Moreover you have at least 1 MiB of free
-memory on the decrypting side.
+hpenc solves the problem that there is no simple tool to quickly
+transfer data with encryption and authentication:
+
+* openssl enc -- non-parallelized, no authentication
+* GnuPG -- non-parallelized, complex key generation/management
+* age -- non-parallelized
+* OpenSSH -- non-parallelized, not very fast
+
+Why gohpenc was written? hpenc has some problems: it does not work on
+aarch64 and sparc64 architectures under FreeBSD (as seen in the port's
+Makefile) and produces incompatible output (unauthenticated after 8192
+blocks) between FreeBSD and HardenedBSD systems somehow. Instead of
+painful debugging I decided to write something similar on the Go
+language, widening supported platforms. But with loose of compatibility
+with hpenc.
+
+Also hpenc won't fail if transmission was truncated (in valid block
+bounds).
+
+It uses ChaCha20-Poly1305, parallelized AEAD encryption of blocks.
+
+    $ key=`gohpenc -psk`
+    $ echo "message to be transmitted" | gohpenc -k $key > encrypted
+    $ gohpenc -d -k $key < encrypted
+
+Blocksize can be specified with -b option (in KiBs). By default it uses
+1MiB blocks. By default all CPUs are used, that can be overriden with -c
+option. If you have got 8 CPUs, then you require (8+1)*1MiB=9MiB of
+memory for buffers allocation.
+
+There is random number generation mode (-r option), that just generates
+random key and encrypt dummy data in the buffers.
 
 gohpenc is free software: see the file COPYING for copying conditions.