pegh/README.md

pegh
----

pegh is a file encryption tool using passwords and authenticated encryption. It is simple, secure, and returns proper exit codes so you can tell whether encryption or decryption failed or not.

[pegh](http://klingonska.org/dict/?q=tlh%3Apegh) is Klingon for secret

Usage
-----

```sh
# encrypt file.txt to file.txt.pegh with password SUPER_SECRET_1942
pegh -e SUPER_SECRET_1942 <file.txt >file.txt.pegh

# decrypt file.txt.pegh to file.txt with password SUPER_SECRET_1942
pegh -d SUPER_SECRET_1942 <file.txt.pegh >file.txt

# make enrypted backup
tar czv -C /path/to/dir/ . | pegh SUPER_SECRET_1942 -o foo.tar.gz.pegh

# extract encrypted backup
pegh SUPER_SECRET_1942 -d -i foo.tar.gz.pegh | tar xzv
```

The easiest way to scale cost/time it takes for bruteforcing is simply to continue doubling -s, on both encryption and decryption commands.

full help:
```
$ pegh -h
usage: pegh [options...] password
 -e            encrypt input to output, default mode
 -d            decrypt input to output
 -i <filename> file to use for input, default stdin
 -o <filename> file to use for output, default stdout
 -a            append to -o instead of truncate
 -c <max_mb>   maximum megabytes of ram to use per encrypted chunk, so while
               decrypting/encrypting twice this will be used, the same
               amount will be needed for decryption as encryption and is
               saved in the file format, so decryption will fail if this
               isn't set high enough, these are
               only allocated after scrypt is finished so max usage will be
               the highest of these only, not both combined,
               max: 2047, default: 16
 -m <max_mb>   maximum megabytes of ram to use when deriving key from password
               with scrypt, applies for encryption AND decryption, must
               almost linearly scale with -N, if too low operation will fail,
               default: 64
 -N <num>      scrypt parameter N, only applies for encryption, default 32768
               this is rounded up to the next highest power of 2
 -r <num>      scrypt parameter r, only applies for encryption, default 8
 -p <num>      scrypt parameter p, only applies for encryption, default 1
 -s <num>      multiplication factor to apply to both -N and -m for easy
               work scaling, rounded up to the next highest power of 2,
               BEWARE: -s 32 requires 2G ram, -s 64 requires 4G and so on,
               default: 1
 -h            print this usage text
 -q            do not print error output to stderr
 -V            show version number and format version support then quit

For additional info on scrypt params refer to:
    https://blog.filippo.io/the-scrypt-parameters/
    https://tools.ietf.org/html/rfc7914#section-2
```

pegh file format
----------------

pegh implements a simple versioned file format so encryption parameters can change in the future. Numbers here are inclusive 0-based byte array indices, 0th byte is always version number, everything else depends on version number, currently only version 0 exists.

Version 0, scrypt key derivation, aes-256-gcm encryption, 43 byte header, 16 byte auth tag per chunk. The 12-byte IV for the first chunk is 0, and is incremented by 1 for each successive chunk, if it ever rolls back over to 0 encryption should be aborted (chunk size should be increased).

| indices      | format                                      | value interpretation                    |
|--------------|---------------------------------------------|-----------------------------------------|
| 0            | 8  bit unsigned byte                        | pegh file format version                |
| 1-4          | 32 bit unsigned integer in big endian order | scrypt N parameter                      |
| 5            | 8  bit unsigned byte                        | scrypt r parameter                      |
| 6            | 8  bit unsigned byte                        | scrypt p parameter                      |
| 7-10         | 32 bit unsigned integer in big endian order | aes encrypted chunk size                |
| 11-42        | 32 randomly generated bytes                 | scrypt key derivation seed              |
| 43+end       | any number of chunks, chunk_size + 16 long  | chunks followed by AES-256-GCM auth tag |

License
-------

pegh.c: AGPLv3 for now, message me if you have a problem with this

documentation/file format: consider this your choice of MIT, Apache 2, or public domain