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, if set and there is an error and append
               is not set, we try to delete this file before exiting,
               default stdout
 -a            append to -o instead of truncate
 -b <max_mb>   maximum megabytes of ram to use per read/write buffer, so while
               decrypting/encrypting twice this will be used, but these are
               only allocated after scrypt is finished so max usage will be
               the highest of these only, not both combined, 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, 51 byte header, 16 byte footer:

| 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-38         | 32 randomly generated bytes                 | scrypt key derivation seed     |
| 39-50        | 12 randomly generated bytes                 | AES-256-GCM IV                 |
| 51-X         | any number of bytes                         | AES-256-GCM encrypted data     |
| (X+1)-(X+16) | 16 bytes, always last 16 bytes in file      | AES-256-GCM authentication 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