2 title: "![SlunkCrypt](etc/img/SlunkCrypt-Logo.png)"
9 SlunkCrypt is an experimental cross-platform cryptography library and command-line tool. A fully-featured GUI is provided for the Windows platform.
11 Please refer to the section [*encryption algorithm*](#encryption-algorithm) for more details!
17 Use of SlunkCrypt may be illegal in countries where encryption is outlawed. We believe it is legal to use SlunkCrypt in many countries all around the world, but we are not lawyers, and so if in doubt you should seek legal advice before downloading it. You may find useful information at [cryptolaw.org](http://www.cryptolaw.org/), which collects information on cryptography laws in many countries.
23 The SlunkCrypt library and the command-line application currently run on the following platforms:
25 * **Microsoft Windows** (Windows XP SP-3, or later) — i686, x86-64 and ARM64
26 * **Linux** (kernel version 3.17, or later) — i686, x86-64, ARM64 and MIPS
27 * **Various BSD flavors** (tested on NetBSD 9.2, FreeBSD 13.0 and OpenBSD 7.0) — i686 and x86-64
28 * **Solaris** (tested on Solaris 11.4 and OmniOS/illumos) — i686 and x86-64
29 * **GNU/Hurd** (tested on Debian GNU/Hurd 0.9) — i686
30 * **Haiku** (tested on Haiku R1/b3) — i686 and x86-64
31 * **Mac OS X** (tested on “Big Sur”) — x86-64 and ARM64
33 The SlunkCrypt GUI application currently runs on the following platforms:
35 * **Microsoft Windows** with .NET Framework 4.5 — can be installed on Windows Vista, or later
41 This is how the graphical user interface (GUI) for SlunkCrypt looks on [Windows 11](https://i.pinimg.com/736x/0f/57/4c/0f574c445b497cc4748a9e1ab7491582--taps-funny-stuff.jpg):
43 ![](etc/img/SlunkCrypt-GUI.jpg)
48 Please be sure to install the **.NET Framework 4.5**, or any later *.NET Framework 4.x* version, before running the SlunkCrypt GUI application:
49 <https://dotnet.microsoft.com/download/dotnet-framework>
51 ***Note:*** If you are running Windows 8 or later, then almost certainly a suitable version of the .NET Framework is already installed 😎
56 The following settings can be adjusted in the `slunkcrypt-gui.exe.config` configuration file:
58 - **`DisableBusyIndicator`:**
59 If set to `true`, the “busy indicator” animation will be *disabled* on application startup — default value: `false`.
62 Specifies the number of worker threads to use — default value: `0` (i.e. detect the number of available processors and create one thread for each processor).
64 - **`KeepIncompleteFiles`:**
65 If set to `true`, incomplete or corrupted output files will *not* be deleted — default value: `false`.
70 This section describes the SlunkCypt command-line application.
75 The SlunkCypt command-line program is invoked as follows:
77 slunkcrypt --encrypt [pass:<pass>|file:<file>] <input.txt> <output.enc>
78 slunkcrypt --decrypt [pass:<pass>|file:<file>] <input.enc> <output.txt>
79 slunkcrypt --make-pw [<length>]
84 One of the following commands **must** be chosen:
86 - **`--encrypt` (`-e`):**
87 Run application in ***encrypt*** mode. Reads the given *plaintext* and generates *ciphertext*.
88 - **`--decrypt` (`-d`):**
89 Run application in ***decrypt*** mode. Reads the given *ciphertext* and restores *plaintext*.
90 - **`--make-pw` (`-p`):**
91 Generate a "strong" random passphrase, suitable for use with SlunkCrypt.
92 - **`--self-test` (`-t`):**
93 Run the application in ***self-test*** mode. Program will exit after all test are completed.
98 The following command-line options are available:
101 * Specifies the "secret" passphrase directly on the command-line. This is considered *insecure*.
103 * Specifies a file to read the passphrase from. Only the *first* line of the file will be read!
104 * *Note:* It is also possible to specify **`-`** in order to read the passphrase from the *stdin*.
106 * In ***encrypt*** mode – specifies the *plaintext* file (unencrypted information) that is to be encrypted.
107 * In ***decrypt*** mode – specifies the *ciphertext* file (result of encryption) that is to be decrypted.
109 * In ***encrypt*** mode – specifies the file where the *ciphertext* (result of encryption) will be stored.
110 * In ***decrypt*** mode – specifies the file where the *plaintext* (unencrypted information) will be stored.
112 * Specifies the length of the passphrase to be generated. If *not* specified, defaults to 24.
114 ### Remarks {.unlisted}
116 - The same passphrase must be used for both, ***encrypt*** and ***decrypt*** mode. The decryption of the ciphertext will only be possible, if the "correct" passphrase is known. It is recommended to choose a "random" password that is at least 12 characters in length and consists of a mix of upper-case characters, lower-case characters, digits as well as special characters.
118 - Passing the passphrase directly on the command-line is insecure, because the full command-line may be visible to other users!
123 The following environment variables may be used:
125 - **`SLUNK_PASSPHRASE`**:
126 Specifies the "secret" passphrase. This environment variables is only evaluated, if the passphrase was **not** specified on the command-line.
127 Passing the passphrase via environment variable is considered more secure, because environment variables are not normally visible to other (unprivileged) users.
129 - **`SLUNK_KEEP_INCOMPLETE`**:
130 If set to a *non-zero* value, incomplete or corrupted output files will **not** be deleted automatically. By default, the files will be deleted.
132 - **`SLUNK_THREADS`**:
133 Specifies the number of worker threads to use. By default, SlunkCrypt detects the number of available processors and creates one thread for each processor.
138 Here are some examples on how to use the SlunkCrypt command-line application:
140 ### Example #1 {.unlisted}
142 1. Let's generate a new random (secure) password first:
148 cdG2=fh<C=3[SSCzf[)iDjIV
150 2. Now, encrypt the plaintext message, using the generated password:
152 slunkcrypt --encrypt pass:"cdG2=fh<C=3[SSCzf[)iDjIV" plaintext.txt ciphertext.enc
154 Optionally, let's have a look at the ciphertext:
156 hexdump -C ciphertext.enc
158 3. Finally, decrypt the ciphertext, using the same password as before:
160 slunkcrypt --decrypt pass:"cdG2=fh<C=3[SSCzf[)iDjIV" ciphertext.enc plaintext.out
162 Optionally, verify that the decrypted file is identical to the original:
164 sha256sum -b plaintext.txt plaintext.out
166 ### Example #2 {.unlisted}
168 1. Generate a new password and store it to a text file:
170 slunkcrypt --make-pw > passwd.txt
172 Optionally, output the generated password to the terminal:
176 2. Encrypt file by reading the password from the text file:
178 slunkcrypt --encrypt file:passwd.txt plaintext.txt ciphertext.enc
180 ### Example #3 {.unlisted}
182 1. Generate a new password directly to an environment variable:
184 MY_PASSWD="$(slunkcrypt --make-pw)"
186 Optionally, output the generated password to the terminal:
190 2. Encrypt file by reading the password from the *stdin*:
192 slunkcrypt --encrypt - plaintext.txt ciphertext.enc <<< "${MY_PASSWD}"
198 The SlunkCrypt algorithm is based on core concepts of the well-known [**Enigma**](https://en.wikipedia.org/wiki/Enigma_machine) machine but with numerous improvements, largely inspired by R. Anderson's [***“A Modern Rotor Machine”***](https://rdcu.be/cBo8y):
200 - The original Enigma machine had only *three* (or, in some models, *four*) rotors, plus a static "reflector" wheel. In SlunkCrypt, we uses **256** simulated rotors for an improved security. Furthermore, the original Enigma machine supported only 26 distinct symbols, i.e. the letters `A` to `Z`. In SlunkCrypt, we use **256** distinct symbols, i.e. the byte values `0x00` to `0xFF`, which allows the encryption (and decryption) of arbitrary streams of bytes, rather than just plain text. Of course, SlunkCrypt can encrypt (and decrypt) text files as well.
202 - In the original Enigma machine, the signal passes through the rotors *twice*, once in forward direction and then again in backwards direction – thus the "reflector" wheel. This way, the Enigma's encryption was made *involutory*, i.e. encryption and decryption were the same operation. While this was highly convenient, it also severely weakened the cryptographic strength of the Enigma machine, because the number of possible permutations was reduced drastically! This is one of the main reasons why the Enigma machine eventually was defeated. In SlunkCrypt, the signal passes through the simulated rotors just *once*, in order to maximize the number of possible permutations. This eliminates the most important known weakness of the Enigma machine. Obviously, in SlunkCrypt, separate "modes" for encryption and decryption need to be provided, since encryption and decryption *no* longer are the same operation.
204 - In the original Enigma machine, the rightmost rotor was moved, by one step, after every symbol. Meanwhile, all other rotors were moved, by one step, *only* when their right-hand neighbor had completed a full turn – much like the odometer in a car. The fact that most of the rotors remained in the same "static" position most of the time was an important weakness of the Enigma machine. Also, the sequence of the Enigma's rotor positions started to repeat after only 16,900 characters. SlunkCrypt employs an improved stepping algorithm, based on a ***linear-feedback shift register* (LSFR)**, ensuring that *all* rotors move frequently and in a "randomized" unpredictable pattern. The rotor positions of SlunkCrypt practically *never* repeat.
206 - The internal wiring of each of the original Enigma machine's rotors was *fixed*. Each rotor "type" came with a different internal wiring (i.e. permutation). Some models had up to eight rotor "types" to choose from, but only three or four rotors were used at a time. Nonetheless, the internal wiring (i.e. permutation) of each of the supplied rotors was **not** modifiable. This severely restricted the key space of the Enigma machine, as far as the rotors are concerned, because *only* the order of the rotors and the initial position of each rotor could be varied. In SlunkCrypt, a fully *randomized* wiring (i.e. permutation) is generated from the password for each of the 256 simulated rotors. The initial rotor positions are *randomized* as well.
208 - SlunkCrypt does **not** currently implement the *plugboard* (“Steckerbrett”) of the original Enigma machine. That is because, even though the plugboard has a large key space, it is just a *fixed* substitution cipher that does *not* contribute much to the cryptographic strength of the Enigma machine. In fact, the plugboard could be "erased" by Welchman's [diagonal board](https://en.wikipedia.org/wiki/Bombe#Stecker_values).
211 Programming Interface (API)
212 ===========================
214 This section describes the SlunkCypt library interface for software developers.
219 In order to use the SlunkCypt library in your C++ code, include **`<slunkcrypt.hpp>`** header and instantiate the appropriate SlunkCypt classes:
221 ### Example #1 {.unlisted}
223 Here is a simple example on how to use the SlunkCrypt [**`Encryptor`**](#encryptor) class:
225 #include <slunkcrypt.hpp>
231 /* Open input and output files here */
232 uint8_t buffer[BUFF_SIZE];
233 slunkcrypt::Encryptor slunk_encrypt(passphrase);
236 input.read(reinterpret_cast<char*>(buffer), BUFF_SIZE);
237 if ((!input.bad()) && (input.gcount() > 0))
239 if (!slunk_encrypt.inplace(buffer, (size_t)input.gcount()))
241 /* Implement error handling here */
243 output.write(reinterpret_cast<char*>(buffer), count);
246 std::cout << std::hex << slunk_encrypt.get_nonce() << std::endl;
249 ### Example #2 {.unlisted}
251 Here is a simple example on how to use the SlunkCrypt [**`Decryptor`**](#decryptor) class:
253 #include <slunkcrypt.hpp>
259 /* Open input and output files here */
260 uint8_t buffer[BUFF_SIZE];
261 slunkcrypt::Decryptor slunk_decrypt(passphrase, nonce);
264 input.read(reinterpret_cast<char*>(buffer), BUFF_SIZE);
265 if ((!input.bad()) && (input.gcount() > 0))
267 if (!slunk_decrypt.inplace(buffer, (size_t)input.gcount()))
269 /* Implement error handling here */
271 output.write(reinterpret_cast<char*>(buffer), count);
279 This section describes the "high-level" C++11 API of the SlunkCrypt library. All SlunkCrypt classes live in the **`slunkcrypt`** namespace.
283 Class for *encrypting* data using the SlunkCrypt library.
287 Create and initialize a new **``Encryptor``** instance. Also generated a new, random nonce.
289 Encryptor::Encryptor(
290 const std::string &passwd,
291 const size_t thread_count = 0U
297 The password to "protect" the message. The password is given as an `std::string`, e.g. UTF-8 encoded characters. The same password **may** be used to encrypt *multiple* messages. Also, the same password **must** be used for both, encryption *and* decryption; it will *only* be possible decrypt the ciphertext, if the "correct" password is known. The password must be kept confidential under all circumstances!
299 *Note:* In order to thwart *brute force* attacks, it is recommended to choose a "random" password that is at least 12 characters in length and that consists of upper-case characters, lower-case characters, digits as well as other "special" characters.
302 Specifies the number of worker threads to use (optional). By default, SlunkCrypt detects the number of available processors and creates one thread for each processor.
306 * Throws `std::runtime_error`, if the nonce could not be generated, or if the SlunkCrypt context could not be allocated.
308 #### Encryptor::process() [1]
310 Encrypt the next message chunk, using separate input/output buffers.
313 const uint8_t *const input,
314 uint8_t *const output,
321 A pointer to the *input* buffer containing the next chunk of the plaintext to be encrypted. The plaintext is given as a byte array (`uint8_t`). This can be arbitrary binary data, e.g. UTF-8 encoded text. NULL bytes are **not** treated specially.
323 The *input* buffer must contain *at least* `length` bytes of data. If the buffer is longer than `length` bytes, then only the first `length` bytes will be processed and the remainder is ignored!
326 A pointer to the *output* buffer where the ciphertext chunk that corresponds to the given plaintext chunk will be stored. The ciphertext is stored as a byte array (`uint8_t`); it has the same length as the plaintext data.
328 The *output* buffer must provide sufficient space for storing *at least* `length` bytes of encrypted data. If the buffer is longer than `length` bytes, then only the first `length` bytes of the buffer will be filled with encrypted data!
331 The length of the plaintext chunk contained in the *input* buffer given by the `input` parameter, in bytes. At the same time, this determines the minimum required size of the *output* buffer given by the `output` parameters, in bytes.
333 *Note:* It is recommended to process chunks of at least ∼64 KB each, in order to take full advantage of multi-threading.
337 * If successful, `true` is returned; otherwise `false` is returned.
339 #### Encryptor::process() [2]
341 Encrypt the next message chunk, using separate input/output containers (`std::vector`).
344 const std::vector<uint8_t> &input,
345 std::vector<uint8_t> &output
351 A reference to the `std::vector<uint8_t>` instance containing the next chunk of the plaintext to be encrypted. This can be arbitrary binary data, e.g. UTF-8 encoded text. NULL bytes are **not** treated specially.
354 A reference to the `std::vector<uint8_t>` instance where the ciphertext that corresponds to the given plaintext will be stored.
356 The `output.size()` must be *greater than or equal* to `input.size()`. If the `output.size()` is larger than the `input.size()`, then only the first `input.size()` elements of `output` will be filled with encrypted data!
360 * If successful, `true` is returned; otherwise `false` is returned. The function fails, if the *output* `std::vector` is too small.
362 #### Encryptor::inplace() [1]
364 Encrypt the next message chunk, using a single buffer.
367 uint8_t *const buffer,
374 A pointer to the buffer initially containing the next chunk of the plaintext to be encrypted. The plaintext is given as a byte array (`uint8_t`). This can be arbitrary binary data, e.g. UTF-8 encoded text. NULL bytes are **not** treated specially. The ciphertext chunk that corresponds to the given plaintext chunk will be stored to the *same* buffer, thus replacing the plaintext data.
376 The buffer must initially contain *at least* `length` bytes of input data; the first `length` bytes of the buffer will be overwritten with the encrypted data. If the buffer is longer than `length` bytes, then only the first `length` bytes will be processed and overwritten.
379 The length of the plaintext chunk initially contained in the input/output buffer given by the `buffer` parameter, in bytes. At the same time, this determines the portion of the input/output buffer that will be overwritten with encrypted data, in bytes.
381 *Note:* It is recommended to process chunks of at least ∼64 KB each, in order to take full advantage of multi-threading.
385 * If successful, `true` is returned; otherwise `false` is returned.
387 #### Encryptor::inplace() [2]
389 Encrypt the next message chunk, using a single container (`std::vector`).
392 std::vector<uint8_t> &buffer
398 A reference to the `std::vector<uint8_t>` initially containing the next chunk of the plaintext to be encrypted. This can be arbitrary binary data, e.g. UTF-8 encoded text. NULL bytes are **not** treated specially. The ciphertext chunk that corresponds to the given plaintext chunk will be stored to the *same* `std::vector<uint8_t>`, thus replacing all the plaintext data.
402 * If successful, `true` is returned; otherwise `false` is returned.
404 #### Encryptor::get_nonce()
406 Retrieve the random nonce that is used to encrypt the message.
408 uint64_t get_nonce();
412 * Returns the nonce that is used to encrypt the message. The purpose of the nonce is to ensure that each message will be encrypted differently, even when the same password is used to encrypt multiple (possibly identical) messages. Therefore, a new random nonce must be chosen for each message! It is not necessary to keep the nonce confidential, but the same nonce must be used for both, encryption and decryption. Typically, the nonce is stored/transmitted alongside the ciphertext.
414 *Note:* The `Encryptor` class automatically generates a new, random nonce for each message to be encrypted. Use *this* function to retrieve that nonce, so that it can be passed to `Decryptor` for decryption later.
418 Class for *decrypting* data using the SlunkCrypt library.
422 Create and initialize a new **``Decryptor``** instance.
424 Decryptor::Decryptor(
425 const std::string &passwd,
426 const uint64_t nonce,
427 const size_t thread_count = 0U
433 The password to "protect" the message. The password is given as an `std::string`, e.g. UTF-8 encoded characters. The same password **may** be used to encrypt *multiple* messages. Also, the same password **must** be used for both, encryption *and* decryption; it will *only* be possible decrypt the ciphertext, if the "correct" password is known. The password must be kept confidential under all circumstances!
435 *Note:* In order to thwart *brute force* attacks, it is recommended to choose a "random" password that is at least 12 characters in length and that consists of upper-case characters, lower-case characters, digits as well as other "special" characters.
438 The *nonce* (number used once) to be used for the decryption process. The purpose of the nonce is to ensure that each message will be encrypted differently, even when the same password is used to encrypt *multiple* (possibly identical) messages. Therefore, a new *random* nonce **must** be chosen for each message! It is *not* necessary to keep the nonce confidential, but the same nonce **must** be used for both, encryption *and* decryption. Typically, the nonce is stored/transmitted alongside the ciphertext.
440 *Note:* The `Encryptor` class automatically generates a new, random nonce for each message to be encrypted. Use `Encryptor::get_nonce()` to retrieve that nonce, so that it can be passed to `Decryptor` for decryption later.
443 Specifies the number of worker threads to use (optional). By default, SlunkCrypt detects the number of available processors and creates one thread for each processor.
447 * Throws `std::runtime_error`, if the SlunkCrypt context could not be allocated.
449 #### Decryptor::process() [1]
451 Decrypt the next message chunk, using separate input/output buffers.
454 const uint8_t *const input,
455 uint8_t *const output,
462 A pointer to the *input* buffer containing the next chunk of the ciphertext to be decrypted. The ciphertext is given as a byte array (`uint8_t`).
464 The *input* buffer must contain *at least* `length` bytes of data. If the buffer is longer than `length` bytes, then only the first `length` bytes will be processed and the remainder is ignored!
467 A pointer to the *output* buffer where the plaintext chunk that corresponds to the given ciphertext chunk will be stored. The plaintext is stored as a byte array (`uint8_t`); it has the same length as the ciphertext data.
469 The *output* buffer must provide sufficient space for storing *at least* `length` bytes of decrypted data. If the buffer is longer than `length` bytes, then only the first `length` bytes of the buffer will be filled with decrypted data!
472 The length of the ciphertext chunk contained in the *input* buffer given by the `input` parameter, in bytes. At the same time, this determines the minimum required size of the *output* buffer given by the `output` parameters, in bytes.
474 *Note:* It is recommended to process chunks of at least ∼64 KB each, in order to take full advantage of multi-threading.
478 * If successful, `true` is returned; otherwise `false` is returned.
480 #### Decryptor::process() [2]
482 Decrypt the next message chunk, using separate input/output containers (`std::vector`).
485 const std::vector<uint8_t> &input,
486 std::vector<uint8_t> &output
492 A reference to the `std::vector<uint8_t>` instance containing the next chunk of the ciphertext to be decrypted.
495 A reference to the `std::vector<uint8_t>` instance where the plaintext that corresponds to the given ciphertext will be stored.
497 The `output.size()` must be *greater than or equal* to `input.size()`. If the `output.size()` is greater than the `input.size()`, then only the first `input.size()` elements of `output` will be filled with decrypted data!
501 * If successful, `true` is returned; otherwise `false` is returned. The function fails, if the *output* `std::vector` is too small.
503 #### Decryptor::inplace() [1]
505 Decrypt the next message chunk, using a single buffer.
508 uint8_t *const buffer,
515 A pointer to the buffer initially containing the next chunk of the ciphertext to be decrypted. The ciphertext is given as a byte array (`uint8_t`). The plaintext that corresponds to the given ciphertext will be stored to the *same* buffer, replacing the plaintext data.
517 The buffer must initially contain *at least* `length` bytes of input data; the first `length` bytes of the buffer will be overwritten with the encrypted data. If the buffer is longer than `length` bytes, then only the first `length` bytes will be processed and overwritten.
520 The length of the ciphertext chunk initially contained in the input/output buffer given by the `buffer` parameter, in bytes. At the same time, this determines the portion of the input/output buffer that will be overwritten with decrypted data, in bytes.
522 *Note:* It is recommended to process chunks of at least ∼64 KB each, in order to take full advantage of multi-threading.
526 * If successful, `true` is returned; otherwise `false` is returned.
528 #### Decryptor::inplace() [2]
530 Decrypt the next message chunk, using a single container (`std::vector`).
533 std::vector<uint8_t> &buffer
539 A reference to the `std::vector<uint8_t>` initially containing the next chunk of the ciphertext to be decrypted. The plaintext that corresponds to the given ciphertext will be stored to the *same* `std::vector<uint8_t>`, replacing all the ciphertext data.
543 * If successful, `true` is returned; otherwise `false` is returned.
548 This section describes the "low-level" C99 API of the SlunkCypt library.
552 The SlunkCypt library defines the following functions:
554 #### slunkcrypt_alloc()
556 Allocate and initialize a new SlunkCrypt encryption/decryption context.
558 slunkcrypt_t slunkcrypt_alloc(
559 const uint64_t nonce,
560 const uint8_t *const passwd,
561 const size_t passwd_len,
568 The *nonce* (number used once) to be used for the encryption/decryption process. The purpose of the nonce is to ensure that each message will be encrypted differently, even when the same password is used to encrypt *multiple* (possibly identical) messages. Therefore, a new *random* nonce **must** be chosen for each message to be encrypted! It is *not* necessary to keep the nonce confidential, but the same nonce **must** be used for both, encryption *and* decryption. Typically, the nonce is stored/transmitted alongside the ciphertext.
570 *Note:* It is recommended to generate a random nonce via the [`slunkcrypt_generate_nonce()`](#slunkcrypt_generate_nonce) function for each message!
573 The password to "protect" the message. The password is given as a byte array (`uint8_t`), e.g. UTF-8 encoded characters; a terminating NULL character is *not* required, as the length of the password is specified explicitly. The same password **may** be used to encrypt *multiple* messages. Also, the same password **must** be used for both, encryption *and* decryption; it will *only* be possible decrypt the ciphertext, if the "correct" password is known. The password must be kept confidential under all circumstances!
575 *Note:* In order to thwart *brute force* attacks, it is recommended to choose a "random" password that is at least 12 characters in length and that consists of upper-case characters, lower-case characters, digits as well as other "special" characters.
578 The length of password given by the `passwd` parameter, in bytes, **not** counting a terminating NULL character. The minimum/maximum length of the password are given by the `SLUNKCRYPT_PWDLEN_MIN` and `SLUNKCRYPT_PWDLEN_MAX` constants, respectively.
581 The mode of operation. Use `SLUNKCRYPT_ENCRYPT` in order to set up this context for *encryption*, or use `SLUNKCRYPT_DECRYPT` in order to set up this context for *decryption*.
585 * If successful, a handle to the new SlunkCrypt context is return; otherwise `SLUNKCRYPT_NULL` is returned.
587 *Note:* Applications **should** treat `slunkcrypt_t` as an *opaque* handle type. Also, as soon as the SlunkCrypt context is *not* needed anymore, the application **shall** call [`slunkcrypt_free()`](#slunkcrypt_free) in order to "erase" and de-allocate that context. If a SlunkCrypt context is *not* de-allocated properly, it will result in a memory leak!
589 #### slunkcrypt_alloc_ext()
591 Allocate and initialize a new SlunkCrypt encryption/decryption context with additional parameters.
593 slunkcrypt_t slunkcrypt_alloc_ext(
594 const uint64_t nonce,
595 const uint8_t *const passwd,
596 const size_t passwd_len,
598 const slunkparam_t *const param
604 The *nonce* (number used once) to be used for the encryption/decryption process. The purpose of the nonce is to ensure that each message will be encrypted differently, even when the same password is used to encrypt *multiple* (possibly identical) messages. Therefore, a new *random* nonce **must** be chosen for each message to be encrypted! It is *not* necessary to keep the nonce confidential, but the same nonce **must** be used for both, encryption *and* decryption. Typically, the nonce is stored/transmitted alongside the ciphertext.
606 *Note:* It is recommended to generate a random nonce via the [`slunkcrypt_generate_nonce()`](#slunkcrypt_generate_nonce) function for each message!
609 The password to "protect" the message. The password is given as a byte array (`uint8_t`), e.g. UTF-8 encoded characters; a terminating NULL character is *not* required, as the length of the password is specified explicitly. The same password **may** be used to encrypt *multiple* messages. Also, the same password **must** be used for both, encryption *and* decryption; it will *only* be possible decrypt the ciphertext, if the "correct" password is known. The password must be kept confidential under all circumstances!
611 *Note:* In order to thwart *brute force* attacks, it is recommended to choose a "random" password that is at least 12 characters in length and that consists of upper-case characters, lower-case characters, digits as well as other "special" characters.
614 The length of password given by the `passwd` parameter, in bytes, **not** counting a terminating NULL character. The minimum/maximum length of the password are given by the `SLUNKCRYPT_PWDLEN_MIN` and `SLUNKCRYPT_PWDLEN_MAX` constants, respectively.
617 The mode of operation. Use `SLUNKCRYPT_ENCRYPT` in order to set up this context for *encryption*, or use `SLUNKCRYPT_DECRYPT` in order to set up this context for *decryption*.
620 Additional parameters used to initialize the SlunkCrypt context, given as a pointer to a [`slunkparam_t`](#slunkcrypt-parameters) struct. The memory for the struct must be allocated by the caller and SlunkCrypt does **not** take owner ship of this memory; it will *copy* the relevant fields. The caller is responsible to free the struct; it can be allocated with automatic storage duration.
624 * If successful, a handle to the new SlunkCrypt context is return; otherwise `SLUNKCRYPT_NULL` is returned.
626 *Note:* Applications **should** treat `slunkcrypt_t` as an *opaque* handle type. Also, as soon as the SlunkCrypt context is *not* needed anymore, the application **shall** call [`slunkcrypt_free()`](#slunkcrypt_free) in order to "erase" and de-allocate that context. If a SlunkCrypt context is *not* de-allocated properly, it will result in a memory leak!
628 #### slunkcrypt_reset()
630 Re-initialize an existing SlunkCrypt encryption/decryption context.
632 int slunkcrypt_reset(
633 const slunkcrypt_t context,
634 const uint64_t nonce,
635 const uint8_t *const passwd,
636 const size_t passwd_len,
643 The existing SlunkCrypt context to be re-initialized. This must be a valid handle that was returned by a previous invocation of the [`slunkcrypt_alloc()`](#slunkcrypt_alloc) function.
645 * *other parameters*:
646 Please refer to the [`slunkcrypt_alloc()`](#slunkcrypt_alloc) function for details!
650 * If successful, `SLUNKCRYPT_SUCCESS` is returned; otherwise `SLUNKCRYPT_FAILURE` or `SLUNKCRYPT_ABORTED` is returned.
652 #### slunkcrypt_free()
654 De-allocate an existing SlunkCrypt encryption/decryption context. This will "clear" and release any memory occupied by the context.
656 void slunkcrypt_free(
657 const slunkcrypt_t context
663 The existing SlunkCrypt context to be de-allocated. This must be a valid handle that was returned by a previous invocation of the [`slunkcrypt_alloc()`](#slunkcrypt_alloc) function.
665 *Note:* Once a handle has been passed to this function, that handle is *invalidated* and **must not** be used again!
667 #### slunkcrypt_generate_nonce()
669 Generate a new random *nonce* (number used once), using the system's "cryptographically secure" entropy source.
671 int slunkcrypt_generate_nonce(
678 A pointer to a variable of type `int64_t` that receives the new random nonce.
682 * If successful, `SLUNKCRYPT_SUCCESS` is returned; otherwise `SLUNKCRYPT_FAILURE` or `SLUNKCRYPT_ABORTED` is returned.
684 #### slunkcrypt_process()
686 Encrypt or decrypt the next message chunk, using separate input/output buffers.
688 int slunkcrypt_process(
689 const slunkcrypt_t context,
690 const uint8_t *const input,
691 uint8_t *const output,
698 The existing SlunkCrypt context to be used for processing the message chunk. This context will be updated.
700 *Note:* This function operates either in "encryption" mode or in "decryption" mode, depending on how the given SlunkCrypt context has been [initialized](#slunkcrypt_alloc) or [re-initialized](#slunkcrypt_reset).
703 A pointer to the *input* buffer containing the next chunk of the plaintext to be encrypted (*encryption* mode), or the next chunk of the ciphertext to be decrypted (*decryption* mode). The input data is given as a byte array (`uint8_t`). This can be arbitrary binary data, e.g. UTF-8 encoded text. NULL bytes are **not** treated specially by this function.
705 The *input* buffer must contain *at least* `length` bytes of data. If the buffer is longer than `length` bytes, then only the first `length` bytes will be processed; the remainder is ignored!
708 A pointer to the *output* buffer where the ciphertext that corresponds to the given plaintext chunk (*encryption* mode), or the plaintext that corresponds to the given ciphertext chunk (*decryption* mode) will be stored. The output data is stored as a byte array (`uint8_t`) and it always has the same length as the input data.
710 The *output* buffer **must** provide sufficient space for storing *at least* `length` bytes. If the buffer is longer than `length` bytes, then only the first `length` bytes will be filled!
713 The length of the given plaintext chunk (*encryption* mode), or the length of the given ciphertext chunk (*decryption* mode) in the `input` buffer, in bytes. At the same time, this parameter determines the minimum required size of the `output` buffer, in bytes. If this parameter is set to *zero*, the function does nothing; this is *not* considered an error.
715 *Note:* It is recommended to process chunks of at least ∼64 KB each, in order to take full advantage of multi-threading.
719 * If successful, `SLUNKCRYPT_SUCCESS` is returned; otherwise `SLUNKCRYPT_FAILURE` or `SLUNKCRYPT_ABORTED` is returned.
721 #### slunkcrypt_inplace()
723 Encrypt or decrypt the next message chunk, using a *single* input/output buffer.
725 int slunkcrypt_inplace(
726 const slunkcrypt_t context,
727 uint8_t *const buffer,
734 The existing SlunkCrypt context to be used for processing the message chunk. This context will be updated.
736 *Note:* This function operates either in "encryption" mode or in "decryption" mode, depending on how the given SlunkCrypt context has been [initialized](#slunkcrypt_alloc) or [re-initialized](#slunkcrypt_reset).
739 A pointer to the buffer containing the next chunk of the plaintext to be encrypted (*encryption* mode), or the next chunk of the ciphertext to be decrypted (*decryption* mode). The input data is given as a byte array (`uint8_t`). This can be arbitrary binary data, e.g. UTF-8 encoded text. NULL bytes are **not** treated specially by this function. The ciphertext that corresponds to the given plaintext chunk (*encryption* mode), or the plaintext that corresponds to the given ciphertext chunk (*decryption* mode) will be stored to the ***same*** buffer.
741 The given buffer **must** initially contain *at least* `length` bytes of input data. The first `length` bytes in the buffer will be processed and will be *overwritten* with the corresponding output data. If the buffer is longer than `length` bytes, then only the first `length` bytes in the buffer will be processed; the remainder is ignored!
744 The length of the plaintext chunk (*encryption* mode), or the length of the ciphertext chunk (*decryption* mode) initially contained in the input/output buffer, in bytes.
746 *Note:* It is recommended to process chunks of at least ∼64 KB each, in order to take full advantage of multi-threading.
750 * If successful, `SLUNKCRYPT_SUCCESS` is returned; otherwise `SLUNKCRYPT_FAILURE` or `SLUNKCRYPT_ABORTED` is returned.
752 #### slunkcrypt_random_bytes()
754 Generate a sequence of random bytes, using the system's "cryptographically secure" entropy source.
756 size_t slunkcrypt_random_bytes(
757 uint8_t *const buffer,
764 A pointer to the *output* buffer where the random bytes will be stored.
766 The *output* buffer **must** provide sufficient space for storing *at least* `length` bytes of random data. *At most* the first `length` bytes of the buffer will be filled with random data!
769 The number of random bytes to be generated. At the same time, this parameter determines the minimum required size of the `output` buffer, in bytes.
773 * The number of random bytes that have been generated and that have been stored to the `output` buffer buffer is returned.
775 The number of generated random bytes can be *at most* `length`. Less than `length` random bytes will be generated, if and only if the the system's "cryptographically secure" entropy source could *not* provide the requested number of bytes at this time – in that case, you can try again later. The number of generated bytes can be as low as **0**.
778 #### slunkcrypt_bzero()
780 Erase the contents of a byte array, by overwriting it with *zero* bytes. Compiler optimizations will **not** remove the erase operation.
782 void slunkcrypt_bzero(
790 A pointer to the buffer whose content is to be erased.
792 The buffer **must** be *at least* `length` bytes in size. If the buffer is longer than `length` bytes, then *only* the first `length` bytes of the buffer will be erased!
795 The size of the buffer to be erased, in bytes.
799 #### SlunkCrypt parameters
801 The `slunkparam_t` struct is used to pass additional parameters that will be used for initializing the SlunkCrypt context. It contains the following fields:
803 * `version` – The version of the parameter struct; **must** be set to *`SLUNKCRYPT_PARAM_VERSION`*.
804 * `thread_count` – The number of worker threads to use. If this parameter is set to **0**, which is the *default* value, then SlunkCrypt automatically detects the number of available (logical) processors and creates one thread for each processor. Also, the number of threads is capped to a maximum of `MAX_THREADS` (currently defined as **16**).
808 The SlunkCypt library defines the following global variables:
810 #### Version information
812 These variables can be used to determine the version of the SlunkCrypt library at runtime, using the [semantic versioning](https://semver.org/spec/v2.0.0.html) scheme:
814 * `const uint16_t SLUNKCRYPT_VERSION_MAJOR` – The current *major* version.
815 * `const uint16_t SLUNKCRYPT_VERSION_MINOR` – The current *minor* version.
816 * `const uint16_t SLUNKCRYPT_VERSION_PATCH` – The current *patch* version.
817 * `const char *SLUNKCRYPT_BUILD` – The build date and time, as a C string, in the *`"mmm dd yyyy, hh:mm:ss"`* format.
821 If this flag is set to a non-zero value by the application, any ongoing SlunkCypt library invocation will be aborted as quickly as possible:
823 * `volatile int g_slunkcrypt_abort_flag` – The global abort flag.
825 *Note:* Applications may set this flag in their signal handler, e.g. when a `SIGINT` is received, in order to "gracefully" shut down the SlunkCypt library. All long-running library functions will return `SLUNKCRYPT_ABORTED`, if the invocation was interrupted. The application still is responsible for [free](#slunkcrypt_free)'ing any SlunkCypt contexts that it allocated successfully!
829 The SlunkCypt library defines the following constants:
831 #### Mode of operation
833 The SlunkCypt library supports the following modes of operation:
835 * `SLUNKCRYPT_ENCRYPT` – Run library in *encryption* mode, i.e. consume plaintext and produce ciphertext.
836 * `SLUNKCRYPT_DECRYPT` – Run library in *decryption* mode, i.e. consume ciphertext and produce plaintext.
840 The following limits are defined for the SlunkCypt library:
842 * `SLUNKCRYPT_PWDLEN_MIN` – The *minimum* required length of a password, currently **8** bytes.
843 * `SLUNKCRYPT_PWDLEN_MAX` – The *maximum* allowed length of a password, currently **256** bytes.
847 SlunkCypt library functions that return an error code may return one of the following constants:
849 * `SLUNKCRYPT_SUCCESS` – The operation completed successfully.
850 * `SLUNKCRYPT_FAILURE` – The operation has failed.
851 * `SLUNKCRYPT_ABORTED` – The operation was aborted before completion, as requested by the application.
856 The following functions are fully "thread-safe" and thus may safely be called by *any* thread at *any* time ***without*** the need for synchronization:
858 * `slunkcrypt_alloc()`
859 * `slunkcrypt_generate_nonce()`
860 * `slunkcrypt_random_bytes()`
861 * `slunkcrypt_bzero()`
862 * `Encryptor::Encryptor()`
863 * `Decryptor::Decryptor()`
865 The following functions are "reentrant" and thus may safely be called by *any* thread at *any* time ***without*** the need for synchronization – provided that each instance of `slunkcrypt_t`, `Encryptor` or `Decryptor` is "owned" by a *single* thread **and** that each instance will *exclusively* be access by its respective "owner" thread:
867 * `slunkcrypt_reset()`
868 * `slunkcrypt_free()`
869 * `slunkcrypt_process()`
870 * `slunkcrypt_inplace()`
871 * `Encryptor::process()`
872 * `Encryptor::inplace()`
873 * `Encryptor::get_nonce()`
874 * `Decryptor::process()`
875 * `Decryptor::inplace()`
877 ***Note:*** If the same `slunkcrypt_t`, `Encryptor` or `Decryptor` instance needs to be shared across *multiple* threads (i.e. the same instance is accessed by *concurrent* threads), then the application **must** *serialize* any invocation of the above functions on that shared instance, by using a suitable synchronization mechanism! This can be achieved by using a [*mutex*](https://linux.die.net/man/3/pthread_mutex_lock).
883 The latest SlunkCrypt source code is available from the official Git mirrors at:
885 * <https://osdn.net/projects/slunkcrypt/scm/git/SlunkCrypt/>
886 * <https://gitlab.com/lord_mulder/slunkcrypt/>
887 * <https://bitbucket.org/muldersoft/slunkcrypt/>
888 * <https://repo.or.cz/slunkcrypt.git>
889 * <https://punkindrublic.mooo.com:3000/Muldersoft/SlunkCrypt>
895 SlunkCrypt can be built from the sources on Microsoft Windows or any POSIX-compatible platform, using a C-compiler that supports the C99 standard.
897 * **Microsoft Windows:**
898 Project/solution files for [Visual Studio](https://visualstudio.microsoft.com/) are provided. These should work “out of the box” with Visual Studio 2017 or any later version.
899 Just open the solution, select the “Release” configuration, choose the “x86” or “x64” platform, and finally press `F5`.
900 Visual Studio also is the only way to build the SlunkCrypt GUI, which is based on Microsoft.NET and Windows Presentation Foundation (WPF).
902 Alternatively, SlunkCrypt can built using [Mingw-w64](https://www.mingw-w64.org/) (available via [MSYS2](https://www.msys2.org/)) or even [Cygwin](https://www.cygwin.com/) – see Linux instructions for details!
905 Please make sure that the *C compiler* (GCC or Clang) as well as *Make* are installed. Then simply run **`make -B`** from the project's base directory!
907 If not already installed, the required build tools can usually be installed via your distribution's package manager.
908 For example, on Debian-based distributions, the command **`sudo apt install build-essential`** installs all the required build tools at once.
910 In order to create a *fully-static* binary of SlunkCrypt that runs on ***any*** Linux distribution from the last decade, you can use [musl libc](https://musl.libc.org/):
911 `make -B CC=musl-gcc STATIC=1`
913 * **BSD and Solaris:**
914 SlunkCrypt can be built on various BSD flavors and Solaris, but the command **`gmake -B`** needs to be used here, since the native `make` doesn't work!
915 GNU Make can be installed from the package manager. For example, use **`pkg install gmake`** on FreeBSD or **`pkg_add gmake`** on OpenBSD.
918 Once you have managed to find a terminal (or even better, connect via SSH), Mac OS X almost works like a proper operating system.
919 The Xcode command-line tools can be installed with the command **`xcode-select --install`**, if not present yet. Then just type **`make -B`** to build!
921 *Hint:* If you want to build with GCC, which produces faster code than Apple's Xcode compiler, you may install it on Mac OS X via [Homebrew](https://formulae.brew.sh/formula/gcc).
927 This work has been released under the **CC0 1.0 Universal** license.
929 For details, please refer to:
930 <https://creativecommons.org/publicdomain/zero/1.0/legalcode>
935 SlunkCrypt incorporates code from the following *third-party* software projects:
937 * The "checksum" algorithm used by the SlunkCrypt command-line application was adapted from the **BLAKE2** reference C implementation.
939 BLAKE2 reference source code package - reference C implementations
940 Copyright 2012, Samuel Neves <sneves@dei.uc.pt>. You may use this under the
941 terms of the CC0, the OpenSSL Licence, or the Apache Public License 2.0, at
942 your option. The terms of these licenses can be found at:
943 - CC0 1.0 Universal : http://creativecommons.org/publicdomain/zero/1.0
944 - OpenSSL license : https://www.openssl.org/source/license.html
945 - Apache 2.0 : http://www.apache.org/licenses/LICENSE-2.0
947 More information about the BLAKE2 hash function can be found at
951 * ***Windows only:*** Builds of SlunkCypt that have multi-threading enabled use the **POSIX Threads for Windows (pthreads4w)** library.
953 Pthreads4w - POSIX Threads for Windows
954 Copyright 1998 John E. Bossom
955 Copyright 1999-2018, Pthreads4w contributors
957 Homepage: https://sourceforge.net/projects/pthreads4w/
959 Licensed under the Apache License, Version 2.0 (the "License");
960 you may not use this file except in compliance with the License.
961 You may obtain a copy of the License at
963 http://www.apache.org/licenses/LICENSE-2.0
965 Unless required by applicable law or agreed to in writing, software
966 distributed under the License is distributed on an "AS IS" BASIS,
967 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
968 See the License for the specific language governing permissions and
969 limitations under the License.