moparisthebest/pegh
1
0
Fork 0
Code Issues Pull Requests Releases 1 Wiki Activity

Clean up documentation

Browse Source
This commit is contained in:
Travis Burtrum 2020-01-01 22:34:20 -05:00
parent fe7c7f982b
commit 355c05219e
2 changed files with 44 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
README.md
View File

@ -1,7 +1,7 @@
pegh 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 is a file encryption tool using passwords with modern, standardized, 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 [pegh](http://klingonska.org/dict/?q=tlh%3Apegh) is Klingon for secret
@ -33,14 +33,17 @@ usage: pegh [options...] password
-i <filename> file to use for input, default stdin -i <filename> file to use for input, default stdin
-o <filename> file to use for output, default stdout -o <filename> file to use for output, default stdout
-a append to -o instead of truncate -a append to -o instead of truncate
-c <max_mb> maximum megabytes of ram to use per encrypted chunk, so while -v pegh file format version to output,
decrypting/encrypting twice this will be used, the same either 0 (AES-256-GCM) or 1 (Chacha20-Poly1305),
amount will be needed for decryption as encryption and is default: 0 if AES is hardware accelerated, 1 otherwise
saved in the file format, so decryption will fail if this -c <mb> chunk size for encryption, while decrypting/encrypting twice
isn't set high enough, these are this ram will be used, the same amount will be needed for
only allocated after scrypt is finished so max usage will be decryption as encryption. This value is saved in the file
the highest of these only, not both combined, format, so decryption will fail if this isn't set high enough,
max: 2047, default: 16 these are only allocated after scrypt is finished so max usage
will be the highest of these only, not both combined,
max: 65535 (AES-256-GCM) or 262143 (Chacha20-Poly1305),
default: 32
-m <max_mb> maximum megabytes of ram to use when deriving key from password -m <max_mb> maximum megabytes of ram to use when deriving key from password
with scrypt, applies for encryption AND decryption, must with scrypt, applies for encryption AND decryption, must
almost linearly scale with -N, if too low operation will fail, almost linearly scale with -N, if too low operation will fail,
@ -62,12 +65,19 @@ For additional info on scrypt params refer to:
https://tools.ietf.org/html/rfc7914#section-2 https://tools.ietf.org/html/rfc7914#section-2
``` ```
Security
--------
Each chunk is fully decrypted and authenticated in memory before being written out as plaintext, so an attacker may be able to truncate a file, but NEVER flip any bytes or corrupt it. Order is enforced by the incrementing the IV, so re-ordered chunks would be decrypted with the wrong IV and would fail authentication.
Of course standard password bruteforcing is possible, but can be mitigated with increased scrypt parameters and longer password lengths.
pegh file format 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. 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 versions 0 and 1 exist.
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). 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 | | indices | format | value interpretation |
|--------------|---------------------------------------------|-----------------------------------------| |--------------|---------------------------------------------|-----------------------------------------|
@ -79,6 +89,8 @@ Version 0, scrypt key derivation, aes-256-gcm encryption, 43 byte header, 16 byt
| 11-42 | 32 randomly generated bytes | scrypt key derivation seed | | 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 | | 43+end | any number of chunks, chunk_size + 16 long | chunks followed by AES-256-GCM auth tag |
Version 1 has the exact same structure as version 0, except Chacha20-Poly1305 encryption instead of AES-256-GCM, key, IV, tag lengths are all the same.
License License
------- -------

35
pegh.c
View File

@ -65,9 +65,9 @@ const uint32_t BUFFER_SIZE_MB = 32;
* 0th byte is always version number, everything else depends on version number * 0th byte is always version number, everything else depends on version number
* *
* |------------------------------------------------------------------------------------------------------| * |------------------------------------------------------------------------------------------------------|
* | Version 0, scrypt key derivation, aes-256-gcm encryption, 43 byte header, 16 byte auth tag per chunk | * | 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 | * | 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). * | ever rolls back over to 0 encryption should be aborted (chunk size should be increased). |
* |--------------|---------------------------------------------|-----------------------------------------| * |--------------|---------------------------------------------|-----------------------------------------|
* | indices | format | value interpretation | * | indices | format | value interpretation |
* |--------------|---------------------------------------------|-----------------------------------------| * |--------------|---------------------------------------------|-----------------------------------------|
@ -79,6 +79,9 @@ const uint32_t BUFFER_SIZE_MB = 32;
* | 11-42 | 32 randomly generated bytes | scrypt key derivation seed | * | 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 | * | 43+end | any number of chunks, chunk_size + 16 long | chunks followed by AES-256-GCM auth tag |
* |------------------------------------------------------------------------------------------------------| * |------------------------------------------------------------------------------------------------------|
*
* Version 1 has the exact same structure as version 0, except Chacha20-Poly1305 encryption instead of AES-256-GCM,
* key, IV, tag lengths are all the same.
*/ */
/* don't touch below here unless you know what you are doing */ /* don't touch below here unless you know what you are doing */
@ -845,18 +848,21 @@ usage: pegh [options...] password\n\
-e encrypt input to output, default mode\n\ -e encrypt input to output, default mode\n\
-d decrypt input to output\n\ -d decrypt input to output\n\
-i <filename> file to use for input, default stdin\n\ -i <filename> file to use for input, default stdin\n\
-o <filename> file to use for output, default stdout\n"); -o <filename> file to use for output, default stdout\n\
fprintf(stderr, "\
-a append to -o instead of truncate\n\ -a append to -o instead of truncate\n\
-c <max_mb> maximum megabytes of ram to use per encrypted chunk, so while\n\ -v pegh file format version to output,\n");
decrypting/encrypting twice this will be used, the same\n\
amount will be needed for decryption as encryption and is\n\
saved in the file format, so decryption will fail if this\n\
isn't set high enough, these are\n");
fprintf(stderr, "\ fprintf(stderr, "\
only allocated after scrypt is finished so max usage will be\n\ either 0 (AES-256-GCM) or 1 (Chacha20-Poly1305),\n\
the highest of these only, not both combined,\n\ default: 0 if AES is hardware accelerated, 1 otherwise\n\
max: %lu (AES-256-GCM) or %lu (Chacha20-Poly1305), default: %d\n\ -c <mb> chunk size for encryption, while decrypting/encrypting twice\n\
this ram will be used, the same amount will be needed for\n\
decryption as encryption. This value is saved in the file\n\
format, so decryption will fail if this isn't set high enough,\n");
fprintf(stderr, "\
these are only allocated after scrypt is finished so max usage\n\
will be the highest of these only, not both combined,\n\
max: %lu (AES-256-GCM) or %lu (Chacha20-Poly1305),\n\
default: %d\n\
-m <max_mb> maximum megabytes of ram to use when deriving key from password\n\ -m <max_mb> maximum megabytes of ram to use when deriving key from password\n\
with scrypt, applies for encryption AND decryption, must\n\ with scrypt, applies for encryption AND decryption, must\n\
almost linearly scale with -N, if too low operation will fail,\n\ almost linearly scale with -N, if too low operation will fail,\n\
@ -1095,7 +1101,7 @@ int main(int argc, char **argv)
/* small SIZE_MAX, Chacha20 */ /* small SIZE_MAX, Chacha20 */
version = 1; version = 1;
#else #else
/* greated than 32gb SIZE_MAX, AES */ /* greater than 32gb SIZE_MAX, AES */
version = 0; version = 0;
#endif #endif
#endif /* PEGH_OPENSSL */ #endif /* PEGH_OPENSSL */
@ -1103,8 +1109,9 @@ int main(int argc, char **argv)
exit_code = pegh_encrypt(password, scrypt_max_mem, buffer_size, in, out, err, (uint8_t) version, N, r, p); exit_code = pegh_encrypt(password, scrypt_max_mem, buffer_size, in, out, err, (uint8_t) version, N, r, p);
} }
if(NULL != in_filename) if(NULL != in_filename) {
fclose(in); fclose(in);
}
if(NULL != out_filename) { if(NULL != out_filename) {
fclose(out); fclose(out);
} }