README.md

   1 # ezcrypt [![CI status](https://ci.codeberg.org/api/badges/13354/status.svg)](https://ci.codeberg.org/repos/13354)
   2
   3 ezcrypt is an easy to use tool for strong file encryption.
   4
   5 * [About](#about)
   6 * [Installation](#installation)
   7 * [Example usage](#example-usage)
   8 * [Principles](#principles)
   9 * [Resources](#resources)
  10
  11 ## About
  12
  13 ### Goals
  14
  15 ezcrypt is a (serious) hobby project with a few design goals:
  16
  17 * **Security**: Strong encryption and robust architecture.
  18 * **Simplicity**: Easy to use.
  19 * **Portability**: Works on most systems (even low end systems).
  20 * **Public domain**: Open source and completely free for everyone.
  21
  22 ### Features
  23
  24 #### Easy to use
  25
  26 - Plain and simple encryption/decryption of any file with a passphrase.
  27 - No cryptographic keys required (although pepper files are supported).
  28 - Familiar CLI interface, similar to [gzip](https://www.gzip.org/).
  29
  30 #### Resistant against cryptanalytic attacks
  31
  32 - Strong encryption, making [brute-force](https://en.wikipedia.org/wiki/Brute-force_attack) key attacks impractical.
  33   - Four levels of encryption ([cascade encryption](https://en.wikipedia.org/wiki/Multiple_encryption)), each with a 256-bit key.
  34   - 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).
  35 - High cost [key derivation function](https://en.wikipedia.org/wiki/Key_derivation_function), making brute-force passphrase attacks impractical.
  36   - Configurable cost, up to several minutes per passphrase-to-key derivation on a 5 GHz CPU core.
  37   - Cache hard algorithm, making GPU implementations inefficient.
  38   - Strong [salt](https://en.wikipedia.org/wiki/Salt_(cryptography)), making precomputed [rainbow table](https://en.wikipedia.org/wiki/Rainbow_table) attacks impractical.
  39   - Optional strong [secret pepper](https://en.wikipedia.org/wiki/Pepper_(cryptography)) for additional security.
  40 - [Authenticated encryption](https://en.wikipedia.org/wiki/Authenticated_encryption) using [Poly1305](https://en.wikipedia.org/wiki/Poly1305).
  41   - Both privacy and authenticity of the data is assured.
  42   - Tampering with the encrypted data is infeasible.
  43
  44 #### Portable
  45
  46 - Written in portable [C11](https://en.wikipedia.org/wiki/C11_(C_standard_revision)).
  47 - Works on most operating systems (including Linux, macOS, Windows, FreeBSD).
  48 - Works on most CPU architectures (including 64- and 32-bit x86, ARM, RISC-V, etc).
  49 - Fully self contained without any dependencies on 3rd party cryptography libraries.
  50
  51 #### Free, open source and public domain
  52
  53 All code is free and unencumbered software released into the public domain, including the cryptographic algorithms.
  54
  55 For more information, see [unlicense.org](https://unlicense.org/).
  56
  57 ### FAQ
  58
  59 See [Frequently asked questions](doc/faq.md).
  60
  61 ## Installation
  62
  63 Prerequisites: A C compiler and [CMake](https://cmake.org/). For Linux targets, GTK 3 is also recommended to enable GUI dialogs (e.g. `apt install libgtk-3-dev` on Ubuntu).
  64
  65 To build:
  66
  67 ```bash
  68 mkdir out && cd out
  69 cmake -DCMAKE_BUILD_TYPE=Release ../src
  70 cmake --build .
  71 ```
  72
  73 The resulting executable file is `out/ezcrypt`.
  74
  75 To install (from the `out` folder):
  76
  77 ```bash
  78 sudo cmake --install .
  79 ```
  80
  81 ### Testing
  82
  83 To run a full build-and-test suite in a Docker environment (from the repo root):
  84
  85 ```bash
  86 docker-compose build
  87 docker-compose run --rm ezcrypt-test
  88 ```
  89
  90 ## Example usage
  91
  92 The canonical help for ezcrypt can be obtained with:
  93
  94 ```bash
  95 $ ezcrypt --help
  96 ```
  97
  98 ### Encrypt a file
  99
 100 Encrypt the file `myfile`, with the passphrase provided via a terminal prompt (or a GUI prompt where available). The output file is called `myfile.z` (the original file is kept):
 101
 102 ```bash
 103 $ ezcrypt myfile
 104 Enter passphrase:
 105 Please repeat the passphrase:
 106 ```
 107
 108 ### Decrypt a file
 109
 110 Decrypt the file `myfile.z`, with the passphrase provided via a terminal prompt. The output file is called `myfile` (the original file is kept):
 111
 112 ```bash
 113 $ ezcrypt -d myfile.z
 114 Enter passphrase:
 115 ```
 116
 117 ### Decrypt and print a file
 118
 119 Decrypt the file `myfile.z` to stdout, with the passphrase provided via the environment variable `$SECRET`:
 120
 121 ```bash
 122 $ ezcrypt --show -E SECRET myfile.z
 123 ```
 124
 125 ### Encrypt & decrypt via pipes
 126
 127 ```bash
 128 $ echo "Hello world!" | ezcrypt -E SECRET | ezcrypt -d -E SECRET
 129 Hello world!
 130 ```
 131
 132 ### Edit an encrypted text file
 133
 134 Edit the plaintext contents of the encrypted file `myfile.z`, using the default text editor (e.g. `$EDITOR` or `notepad.exe`):
 135
 136 ```bash
 137 $ ezcrypt --edit myfile.z
 138 ```
 139
 140 Note: If the plaintext is not modified by the editor, `myfile.z` remains unmodified.
 141
 142 ## Principles
 143
 144 ### File format
 145
 146 ![ezcrypt file format](doc/fileformat.png)
 147
 148 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:
 149
 150 1. [AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard), CBC, 256-bit key (outermost level)
 151 2. [Twofish](https://en.wikipedia.org/wiki/Twofish), CBC, 256-bit key
 152 3. [Serpent](https://en.wikipedia.org/wiki/Serpent_(cipher)), CBC, 256-bit key
 153 4. [ChaCha](https://en.wikipedia.org/wiki/Salsa20#ChaCha_variant), 20 rounds, 256-bit key, XChaCha20 construction (innermost level)
 154
 155 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).
 156
 157 Note that the encrypted file does not contain any header or other identification metadata. This is by design.
 158
 159 ### Key derivation
 160
 161 ![ezcrypt key derivation](doc/key-derivation.png)
 162
 163 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).
 164
 165 ## Resources
 166
 167 * [Codeberg](https://codeberg.org/ezcrypt/ezcrypt) (main host)
 168 * [repo.or.cz](https://repo.or.cz/ezcrypt.git) (mirror)
 169 * <a rel="me" href="https://techhub.social/@ezcrypt">Mastodon</a>