bacd9b6410333a02275c840af7e912add9d1b626
[gohpenc.git] / README
1 Go high-performance encryption utility.
2
3 gohpenc highly resembles hpenc tool (https://github.com/vstakhov/hpenc).
4 hpenc solves the problem that there is no simple tool to quickly
5 transfer data with encryption and authentication:
6
7 * openssl enc -- uses single CPU, no authentication
8 * GnuPG -- complex key generation/management, relatively slow
9 * OpenSSH -- uses single CPU, not very fast
10
11 Why gohpenc was written? hpenc has some problems: it does not work on
12 aarch64 and sparc64 architectures under FreeBSD (as seen in the port's
13 Makefile) and produces incompatible output (unauthenticated after 8192
14 blocks) between FreeBSD and HardenedBSD systems somehow. Instead of
15 painful debugging I decided to write something similar on the Go
16 language, widening supported platforms.
17
18 gohpenc is incompatible with hpenc and much simpler:
19
20 * it uses only XChaCha20-Poly1305 algorithm
21 * no random data generation mode
22 * no metadata in output stream and no structure validation. Only blocks
23   authentication
24 * no key derivation -- new key for each block
25
26 But it still satisfies most of hpenc aims:
27
28 * Very simple key management -- single pre-shared key
29 * Parallelizeable -- each block is encrypted in different thread, so all
30   your CPUs could be utilized
31 * Very fast -- ChaCha20-Poly1305 is fast even on relatively low-end
32   devices like mobile devices. Despite gohpenc is written on Go, its
33   dependent libraries contain assembly-optimized code
34 * Built-in authentication and integrity check with small data overhead
35
36 Usage is very simple:
37
38     $ gohpenc -psk
39     DTGZI5R2HS4YEDSIO56AFKPONE6KJE3Q2QETODDOH3O6UYFPROHQ
40     $ echo "message to be transmitted" | gohpenc -k DTGZI5R2HS4YEDSIO56AFKPONE6KJE3Q2QETODDOH3O6UYFPROHQ > encrypted
41     $ gohpenc -k DTGZI5R2HS4YEDSIO56AFKPONE6KJE3Q2QETODDOH3O6UYFPROHQ -d < encrypted
42
43 How encryption/authentication is performed:
44
45 * First 16 bytes of the stream contain random data -- nonce salt
46 * XChaCha20-Poly1305 algorithm is initialized with the key and 24-byte
47   nonce, where 16 bytes is the salt, and 8 bytes is 64-bit unsigned
48   big-endian block number
49 * 32-bit big-endian value with the length of the block is outputted,
50   then an encrypted and authenticated block goes further, with
51   authenticated data containing that 32-bit length value
52
53        /----------BLOCK-------------\ /----------BLOCK------------\
54 +------+-----+------------+----------+-----+------------+----------+----
55 | SALT | LEN | CIPHERTEXT | AUTH TAG | LEN | CIPHERTEXT | AUTH TAG | ...
56 +------+-----+------------+----------+-----+------------+----------+----
57
58 gohpenc preallocates memory for one block for each thread and one block
59 for buffered reading from stdin. If you want to process data with 1 MiB
60 blocks in 4 threads, then you have to have at least 5 MiBs of free
61 memory. Moreover you have at least 1 MiB of free memory on the
62 decrypting side.
63
64 gohpenc is free software: see the file COPYING for copying conditions.