X-Git-Url: http://www.git.cypherpunks.ru/?a=blobdiff_plain;f=README;h=bacd9b6410333a02275c840af7e912add9d1b626;hb=43162227c8405de5a2d835ee306459993ff0ba6d;hp=802056ab261b239612e146fbc06157c6dc9209d8;hpb=ae7a2efeea1aadfaf3a098e0449997f5b5840b44;p=gohpenc.git

diff --git a/README b/README
index 802056a..bacd9b6 100644
--- a/README
+++ b/README
@@ -1,21 +1,27 @@
 Go high-performance encryption utility.
 
 gohpenc highly resembles hpenc tool (https://github.com/vstakhov/hpenc).
+hpenc solves the problem that there is no simple tool to quickly
+transfer data with encryption and authentication:
 
-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.
+* openssl enc -- uses single CPU, no authentication
+* GnuPG -- complex key generation/management, relatively slow
+* OpenSSH -- uses single CPU, 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.
 
 gohpenc is incompatible with hpenc and much simpler:
 
-* it uses only ChaCha20-Poly1305 algorithm
+* it uses only XChaCha20-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
+* no key derivation -- new key for each block
 
 But it still satisfies most of hpenc aims:
 
@@ -27,15 +33,19 @@ But it still satisfies most of hpenc aims:
   dependent libraries contain assembly-optimized code
 * Built-in authentication and integrity check with small data overhead
 
+Usage is very simple:
+
+    $ gohpenc -psk
+    DTGZI5R2HS4YEDSIO56AFKPONE6KJE3Q2QETODDOH3O6UYFPROHQ
+    $ echo "message to be transmitted" | gohpenc -k DTGZI5R2HS4YEDSIO56AFKPONE6KJE3Q2QETODDOH3O6UYFPROHQ > encrypted
+    $ gohpenc -k DTGZI5R2HS4YEDSIO56AFKPONE6KJE3Q2QETODDOH3O6UYFPROHQ -d < encrypted
+
 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
+* First 16 bytes of the stream contain random data -- nonce salt
+* XChaCha20-Poly1305 algorithm is initialized with the key and 24-byte
+  nonce, where 16 bytes is the salt, and 8 bytes is 64-bit unsigned
+  big-endian block number
 * 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