README.md

   1 # ezcrypt [![CI status](https://ci.codeberg.org/api/badges/13354/status.svg)](https://ci.codeberg.org/repos/13354)
   2
   3 A tool for strong file encryption.
   4
   5 ## Features
   6
   7 ### Easy to use
   8
   9 - Plain and simple encryption/decryption of any file with a passphrase.
  10 - No cryptographic keys required (although pepper files are supported).
  11 - Familiar CLI interface, similar to [gzip](https://www.gzip.org/).
  12
  13 ### Resistant against cryptanalytic attacks
  14
  15 - Strong encryption, making [brute-force](https://en.wikipedia.org/wiki/Brute-force_attack) key attacks impractical.
  16   - Four levels of encryption, each with a 256-bit key.
  17   - The total effective key space is <span title="179,769,313,486,231,590,772,930,519,078,902,473,361,797,697,894,230,657,273,430,081,157,732,675,805,500,963,132,708,477,322,407,536,021,120,113,879,871,393,357,658,789,768,814,416,622,492,847,430,639,474,124,377,767,893,424,865,485,276,302,219,601,246,094,119,453,082,952,085,005,768,838,150,682,342,462,881,473,913,110,540,827,237,163,350,510,684,586,298,239,947,245,938,479,716,304,835,356,329,624,224,137,216">2<sup>1024</sup></span> (for reference, the age of the universe is less than 2<sup>79</sup> microseconds).
  18 - High cost [key derivation function](https://en.wikipedia.org/wiki/Key_derivation_function), making brute-force passphrase attacks impractical.
  19   - Configurable cost, up to several minutes per passphrase-to-key derivation on a 5 GHz CPU core.
  20   - Cache hard algorithm, making GPU implementations inefficient.
  21   - Strong [salt](https://en.wikipedia.org/wiki/Salt_(cryptography)), making precomputed [rainbow table](https://en.wikipedia.org/wiki/Rainbow_table) attacks impractical.
  22   - Optional strong [secret pepper](https://en.wikipedia.org/wiki/Pepper_(cryptography)) for additional security.
  23 - The decryption algorithm does not know nor report whether the passphrase was correct or not.
  24   - Decryption always produces a result (with an incorrect passphrase the result will be garbage).
  25   - An attacker has to inspect the decrypted message and heuristically determine if it is correct.
  26
  27 ### Portable
  28
  29 - Written in portable [C11](https://en.wikipedia.org/wiki/C11_(C_standard_revision)).
  30 - Works on most operating systems (including Linux, macOS, Windows, FreeBSD).
  31 - Works on most CPU architectures (including 64- and 32-bit x86, ARM, RISC-V, etc).
  32 - Fully self contained without any dependencies on 3rd party cryptography libraries.
  33
  34 ### Free, open source and public domain
  35
  36 All code is free and unencumbered software released into the public domain, including the cryptographic algorithms.
  37
  38 For more information, see [unlicense.org](https://unlicense.org/).
  39
  40 ## Principles
  41
  42 ### File format
  43
  44 ![ezcrypt file format](doc/fileformat.png)
  45
  46 Encryption is done in four layers. At each level a different [cipher](https://en.wikipedia.org/wiki/Cipher) is used, and each level has its own [encyrption key](https://en.wikipedia.org/wiki/Key_(cryptography)) and its own [initialization vector](https://en.wikipedia.org/wiki/Initialization_vector) (IV). The different ciphers are:
  47
  48 1. [AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard), CBC, 256-bit key (outermost level)
  49 2. [ChaCha](https://en.wikipedia.org/wiki/Salsa20#ChaCha_variant), 20 rounds, 256-bit key
  50 3. [Twofish](https://en.wikipedia.org/wiki/Twofish), CBC, 256-bit key
  51 4. [Serpent](https://en.wikipedia.org/wiki/Serpent_(cipher)), CBC, 256-bit key (innermost level)
  52
  53 The [salt](https://en.wikipedia.org/wiki/Salt_(cryptography)) and the IV for each encryption level is generated from system level [entropy](https://en.wikipedia.org/wiki/Entropy_(computing)) (i.e. highly random data), and is different for each run of ezcrypt. Thus encrypting the same file twice will result in two different [ciphertexts](https://en.wikipedia.org/wiki/Ciphertext) (even if the same passphrase is used).
  54
  55 Note that the encrypted file does not contain any header or other identification metadata. This is by design.
  56
  57 ### Key derivation
  58
  59 ![ezcrypt key derivation](doc/key-derivation.png)
  60
  61 The key at each level is generated from a combination of the user supplied [passphrase](https://en.wikipedia.org/wiki/Passphrase), an optional user supplied [pepper](https://en.wikipedia.org/wiki/Pepper_(cryptography)) file (hashed to 256 bits) and a per-level 256-bit [salt](https://en.wikipedia.org/wiki/Salt_(cryptography)). This is done using a compute intensive key derivation function called [ZKDF](doc/zkdf.md).
  62
  63 ## Installation
  64
  65 Prerequisites: A C compiler and [CMake](https://cmake.org/).
  66
  67 To build:
  68
  69 ```bash
  70 mkdir out && cd out
  71 cmake -DCMAKE_BUILD_TYPE=Release ../src
  72 cmake --build .
  73 ```
  74
  75 The resulting executable file is `out/ezcrypt`.
  76
  77 To install (from the `out` folder):
  78
  79 ```bash
  80 sudo cmake --install .
  81 ```
  82
  83 ## Testing
  84
  85 To run a full build-and-test suite in a Docker environment (from the repo root):
  86
  87 ```bash
  88 docker-compose build
  89 docker-compose run --rm ezcrypt-test
  90 ```
  91
  92 ## Example usage
  93
  94 The canonical help for ezcrypt can be obtained with:
  95
  96 ```bash
  97 $ ezcrypt --help
  98 ```
  99
 100 ### Encrypt a file
 101
 102 Encrypt the file `myfile`, with the passphrase provided via a terminal prompt. The output file is called `myfile.z` (the original file is kept):
 103
 104 ```bash
 105 $ ezcrypt myfile
 106 Enter passphrase:
 107 Please repeat the passphrase:
 108 ```
 109
 110 ### Decrypt a file
 111
 112 Decrypt the file `myfile.z`, with the passphrase provided via a terminal prompt. The output file is called `myfile` (the original file is kept):
 113
 114 ```bash
 115 $ ezcrypt -d myfile.z
 116 Enter passphrase:
 117 ```
 118
 119 ### Decrypt and print a file
 120
 121 Decrypt the file `myfile.z` to stdout, with the passphrase provided via the environment variable `$SECRET`:
 122
 123 ```bash
 124 $ ezcrypt --show -E SECRET myfile.z
 125 ```
 126
 127 ### Encrypt & decrypt via pipes
 128
 129 ```bash
 130 $ echo "Hello world!" | ezcrypt -E SECRET | ezcrypt -d -E SECRET
 131 Hello world!
 132 ```
 133
 134 ### Edit an encrypted text file
 135
 136 Edit the plaintext contents of the encrypted file `myfile.z`, using the default text editor (e.g. `$EDITOR` or `notepad.exe`):
 137
 138 ```bash
 139 $ ezcrypt --edit myfile.z
 140 ```
 141
 142 Note: If the plaintext is not modified by the editor, `myfile.z` remains unmodified. This is useful if you accidentally use the wrong passphrase (you will notice right away since the plaintext will appear as garbage), in which case you can just exit the editor.