2 title: "![SlunkCrypt](etc/img/SlunkCrypt-Logo.png)"
9 SlunkCrypt is an experimental cryptography library and command-line tool. See [*encryption algorithm*](#encryption-algorithm) for details.
15 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.
21 This section describes the SlunkCypt command-line application.
26 The SlunkCypt command-line program is invoked as follows:
28 slunkcrypt --encrypt [[@][:]<passphrase>] <input> <output>
29 slunkcrypt --decrypt [[@][:]<passphrase>] <input> <output>
30 slunkcrypt --make-pw [<length>]
35 One of the following commands must be chosen:
37 - **`--encrypt` (`-e`):**
38 Run application in ***encrypt*** mode. Reads the given *plaintext* and generates *ciphertext*.
39 - **`--decrypt` (`-d`):**
40 Run application in ***decrypt*** mode. Reads the given *ciphertext* and restores *plaintext*.
41 - **`--make-pw` (`-p`):**
42 Generate and output a "strong" random passphrase suitable for use with SlunkCrypt.
43 - **`--self-test` (`-t`):**
44 Run application in ***self-test*** mode. Program will exit when test is completed.
49 The following options are available:
52 * The passphrase used to "protect" the message. The same passphrase must be used for both, ***encrypt*** and ***decrypt*** mode.
53 * It will only be possible decrypt the ciphertext, if the "correct" passphrase is known.
54 * Use **`--make-pw`** to generate a random passphrase. The passphrase must be kept confidential under all circumstances!
56 - If the passphrase is prefixed with an **`@`** character, then it specifies the file to read the passphrase from.
57 - If the passphrase is set to **`@-`**, then the passphrase is read from the standard input stream.
58 - If the passphrase is prefixed with an **`:`** character, then the leading character is ignored; use if passphrase contains **`@`** character.
59 - If the parameter is *omitted*, then the passphrase is read from the `SLUNK_PASSPHRASE` environment variable.
60 * *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.
62 * In ***encrypt*** mode, specifies the *plaintext* (unencrypted information) file that is to be encrypted.
63 * In ***decrypt*** mode, specifies the *ciphertext* (result of encryption) file that is to be decrypted.
65 * In ***encrypt*** mode, specifies the file where the *ciphertext* (result of encryption) will be stored.
66 * In ***decrypt*** mode, specifies the file where the *plaintext* (unencrypted information) will be stored.
68 * Speicifes the length of the passphrase to be generated, in characters. If *not* specified, defaults to 24.
73 Examples on how to use the SlunkCrypt command-line application:
75 1. Let's generate a new secure password first:
81 cdG2=fh<C=3[SSCzf[)iDjIV
83 2. Now, encrypt the plaintext message, using the generated password:
85 slunkcrypt --encrypt "cdG2=fh<C=3[SSCzf[)iDjIV" plaintext.txt ciphertext.enc
87 Optionally, let's have a look at the ciphertext:
89 hexdump -C ciphertext.enc
91 3. Finally, decrypt the ciphertext, using the same password as before:
93 slunkcrypt --decrypt "cdG2=fh<C=3[SSCzf[)iDjIV" ciphertext.enc plaintext.out
95 Optionally, verify that files are actually the same:
97 cmp --silent plaintext.txt plaintext.out && echo "files are the same"
103 The SlunkCrypt algorithm is based on concepts of the well-known [**Enigma**](https://en.wikipedia.org/wiki/Enigma_machine) machine, but with various improvements:
105 - The original Enigma machine had only *three* rotors (spinning wheels), plus a static "reflector" wheel. In SlunkCrypt, we uses **256** simulated rotors – because we can.
107 - 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.
109 - 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, because encryption and decryption *no* longer are the same.
111 - In the original Enigma machine, *only* the rightmost rotor was stepped after every symbol. The other rotors were stepped infrequently. Specifically, if one rotor has completed a full turn, it will cause the next rotor to move by one step – much like the odometer in a car. The fact that most of the rotors remained in the same position for a long time was another important weakness of the Enigma machine that ultimately lead to its demise. Furthermore, the positions of the Enigma's rotors would start to repeat after 16,900 characters. In SlunkCrypt an improved stepping algorithm is used, which ensures that *all* rotors are stepped often. At the same time, the rotor positions in SlunkCrypt *never* repeat (practically).
113 - The internal wiring of each of the original Enigma machine's rotors was *fixed*. Each rotor came with a different internal wiring (i.e. permutation). Some models even had more than three rotors to choose from, but only three rotors were used at a time. Nonetheless, TTBOMK, the internal wiring of each of the supplied rotors was *never* changed, for a specific model. 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.
115 - SlunkCrypt does **not** currently implement the *plugboard* of the original Enigma machine. That is because, even though the plugboard has a large key space, it effectively is just a *fixed* substitution cipher that does **not** contribute much to the cryptographic strength of the Enigma machine. In fact, the [bombe](https://en.wikipedia.org/wiki/Bombe#Stecker_values) was able to circumvent the plugboard.
118 Programming Interface (API)
119 ===========================
124 This section describes the "low-level" C99 API of the SlunkCypt library.
126 ### slunkcrypt_alloc()
128 Allocate and initialize a new SlunkCrypt encryption/decryption context.
130 slunkcrypt_t slunkcrypt_alloc(
131 const uint64_t nonce,
132 const uint8_t *const passwd,
133 const size_t passwd_len
139 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.
141 *Note:* It is recommended to generate a random nonce via the `slunkcrypt_generate_nonce()` function for each message!
144 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!
146 *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.
149 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.
153 * If successful, a handle to the new SlunkCrypt context is return; otherwise `SLUNKCRYPT_NULL` is returned.
155 *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()` in order to "clear" and de-allocate that context.
157 ### slunkcrypt_reset()
159 Re-initialize an existing SlunkCrypt encryption/decryption context.
161 int slunkcrypt_reset(
162 const slunkcrypt_t context,
163 const uint64_t nonce,
164 const uint8_t *const passwd,
165 const size_t passwd_len
171 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()` function.
174 Please refer to the `slunkcrypt_alloc()` function for details!
177 Please refer to the `slunkcrypt_alloc()` function for details!
180 Please refer to the `slunkcrypt_alloc()` function for details!
184 * If successful, `SLUNKCRYPT_SUCCESS` is returned; otherwise `SLUNKCRYPT_FAILURE` or `SLUNKCRYPT_ABORTED` is returned.
186 ### slunkcrypt_free()
188 De-allocate an existing SlunkCrypt encryption/decryption context. This will "clear" and release any memory occupied by the context.
190 void slunkcrypt_free(
191 const slunkcrypt_t context
197 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()` function.
199 *Note:* Once a handle has been passed to this function, that handle is *invalidated* and **must not** be used again!
201 ### slunkcrypt_generate_nonce()
203 Generate a new random *nonce* (number used once), using the system's "cryptographically secure" entropy source.
205 int slunkcrypt_generate_nonce(
212 A pointer to a variable of type `int64_t` that receives the new random nonce.
216 * If successful, `SLUNKCRYPT_SUCCESS` is returned; otherwise `SLUNKCRYPT_FAILURE` or `SLUNKCRYPT_ABORTED` is returned.
218 ### slunkcrypt_encrypt()
220 Encrypt the next message chunk, using separate input/output buffers.
222 int slunkcrypt_encrypt(
223 const slunkcrypt_t context,
224 const uint8_t *const input,
225 uint8_t* const output,
232 The existing SlunkCrypt context to be used for encrypting the message chunk. This context will be updated.
235 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.
237 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!
240 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.
242 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!
245 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.
249 * If successful, `SLUNKCRYPT_SUCCESS` is returned; otherwise `SLUNKCRYPT_FAILURE` or `SLUNKCRYPT_ABORTED` is returned.
251 ### slunkcrypt_encrypt_inplace()
253 Encrypt the next message chunk, using a single buffer.
255 int slunkcrypt_encrypt_inplace(
256 const slunkcrypt_t context,
257 uint8_t* const buffer,
264 The existing SlunkCrypt context to be used for encrypting the message chunk. This context will be updated.
267 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.
269 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.
272 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.
276 * If successful, `SLUNKCRYPT_SUCCESS` is returned; otherwise `SLUNKCRYPT_FAILURE` or `SLUNKCRYPT_ABORTED` is returned.
278 ### slunkcrypt_decrypt()
280 Decrypt the next ciphertext chunk, using separate input/output buffers.
282 int slunkcrypt_decrypt(
283 const slunkcrypt_t context,
284 const uint8_t *const input,
285 uint8_t* const output,
292 The existing SlunkCrypt context to be used for decrypting the ciphertext chunk. This context will be updated.
295 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`).
297 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!
300 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 plaintext data.
302 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!
305 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.
309 * If successful, `SLUNKCRYPT_SUCCESS` is returned; otherwise `SLUNKCRYPT_FAILURE` or `SLUNKCRYPT_ABORTED` is returned.
311 ### slunkcrypt_decrypt_inplace()
313 Decrypt the next ciphertext chunk, using a single buffer.
315 int slunkcrypt_decrypt_inplace(
316 const slunkcrypt_t context,
317 uint8_t* const buffer,
324 The existing SlunkCrypt context to be used for decrypting the ciphertext chunk. This context will be updated.
327 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, thus replacing the plaintext data.
329 The buffer must initially contain *at least* `length` bytes of input data; the first `length` bytes of the buffer will be overwritten with the decrypted data. If the buffer is longer than `length` bytes, then only the first `length` bytes will be processed and overwritten.
332 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.
336 * If successful, `SLUNKCRYPT_SUCCESS` is returned; otherwise `SLUNKCRYPT_FAILURE` or `SLUNKCRYPT_ABORTED` is returned.
338 ### slunkcrypt_random_bytes()
340 Generate a sequence of random bytes, using the system's "cryptographically secure" entropy source.
342 size_t slunkcrypt_random_bytes(
343 uint8_t* const buffer,
350 A pointer to the *output* buffer where the random bytes will be stored.
352 The *output* buffer must provide sufficient space for storing *at least* `length` bytes of random data. If the buffer is longer than `length` bytes, then *at most* the first `length` bytes of the buffer will be filled with random data!
355 The number of random bytes to be generated. At the same time, this determines the minimum required size of the *output* buffer given by the `output` parameters, in bytes.
359 * If successful, the number of random bytes that have been generated and stored to the *output* buffer is returned; otherwise `0` is returned.
361 The number of generated bytes can be *at most* `length`. Less than `length` bytes *may* be generated, if the entropy source could **not** provide the requested number of bytes at this time. In that case, you can try again.
364 ### slunkcrypt_bzero()
366 Erase the contents of a byte array, by overwriting it with *zero* bytes. Compiler optimizations will **not** remove the erase operation.
368 void slunkcrypt_bzero(
376 A pointer to the buffer whose content is to be erased.
378 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; the remainder of the buffer will *not* be modified!
381 The size of the buffer to be erased, in bytes.
387 This section describes the "high-level" C++ API of the SlunkCypt library.
391 Class for *encrypting* data using the SlunkCrypt library.
395 Create and initialize a new **``SlunkCryptEncr``** instance. Also generated a new, random nonce.
397 SlunkCryptEncr::SlunkCryptEncr(
398 const std::string &passwd
404 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!
406 *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.
410 * Throws `std::runtime_error`, if the nonce could not be generated, or if the SlunkCrypt context could not be allocated.
412 #### SlunkCryptEncr::encrypt() [1]
414 Encrypt the next message chunk, using separate input/output buffers.
417 const uint8_t* const input,
418 uint8_t* const output,
425 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.
427 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!
430 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.
432 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!
435 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.
439 * If successful, `true` is returned; otherwise `false` is returned.
441 #### SlunkCryptEncr::encrypt() [2]
443 Encrypt the next message chunk, using separate input/output containers (`std::vector`).
446 const std::vector<uint8_t> &input,
447 std::vector<uint8_t> &output
453 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.
456 A reference to the `std::vector<uint8_t>` instance where the ciphertext that corresponds to the given plaintext will be stored.
458 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!
462 * If successful, `true` is returned; otherwise `false` is returned. The function fails, if the *output* `std::vector` is too small.
464 #### SlunkCryptEncr::encrypt_inplace() [1]
466 Encrypt the next message chunk, using a single buffer.
468 bool encrypt_inplace(
469 uint8_t* const buffer,
476 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.
478 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.
481 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.
485 * If successful, `true` is returned; otherwise `false` is returned.
487 #### SlunkCryptEncr::encrypt_inplace() [2]
489 Encrypt the next message chunk, using a single container (`std::vector`).
491 bool encrypt_inplace(
492 std::vector<uint8_t> &buffer
498 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.
502 * If successful, `true` is returned; otherwise `false` is returned.
504 #### SlunkCryptEncr::get_nonce()
506 Retrieve the random nonce that is used to encrypt the message.
508 uint64_t get_nonce();
512 * 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.
514 *Note:* The `SlunkCryptEncr` 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 `SlunkCryptDecr` for decryption later.
518 Class for *decrypting* data using the SlunkCrypt library.
522 Create and initialize a new **``SlunkCryptDecr``** instance.
524 SlunkCryptDecr::SlunkCryptDecr(
525 const uint64_t nonce,
526 const std::string& passwd
532 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.
534 *Note:* The `SlunkCryptEncr` class automatically generates a new, random nonce for each message to be encrypted. Use `SlunkCryptEncr::get_nonce()` to retrieve that nonce, so that it can be passed to `SlunkCryptDecr` for decryption later.
537 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!
539 *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.
543 * Throws `std::runtime_error`, if the SlunkCrypt context could not be allocated.
545 #### SlunkCryptDecr::decrypt() [1]
547 Decrypt the next message chunk, using separate input/output buffers.
550 const uint8_t* const input,
551 uint8_t* const output,
558 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`).
560 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!
563 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.
565 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!
568 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.
572 * If successful, `true` is returned; otherwise `false` is returned.
574 #### SlunkCryptDecr::decrypt() [2]
576 Decrypt the next message chunk, using separate input/output containers (`std::vector`).
579 const std::vector<uint8_t> &input,
580 std::vector<uint8_t> &output
586 A reference to the `std::vector<uint8_t>` instance containing the next chunk of the ciphertext to be decrypted.
589 A reference to the `std::vector<uint8_t>` instance where the plaintext that corresponds to the given ciphertext will be stored.
591 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!
595 * If successful, `true` is returned; otherwise `false` is returned. The function fails, if the *output* `std::vector` is too small.
597 #### SlunkCryptDecr::decrypt_inplace() [1]
599 Decrypt the next message chunk, using a single buffer.
601 bool decrypt_inplace(
602 uint8_t* const buffer,
609 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.
611 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.
614 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.
618 * If successful, `true` is returned; otherwise `false` is returned.
620 #### SlunkCryptDecr::decrypt_inplace() [2]
622 Decrypt the next message chunk, using a single container (`std::vector`).
624 bool decrypt_inplace(
625 std::vector<uint8_t> &buffer
631 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.
635 * If successful, `true` is returned; otherwise `false` is returned.
640 The following functions are fully "thread-safe" and thus may safely be called by *any* thread at *any* time ***without*** the need for synchronization:
642 * `slunkcrypt_alloc()`
643 * `slunkcrypt_random_bytes()`
644 * `slunkcrypt_bzero()`
645 * `SlunkCryptEncr::SlunkCryptEncr()`
646 * `SlunkCryptDecr::SlunkCryptDecr()`
648 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 `slunkcrypt_t`, `SlunkCryptEncr` or `SlunkCryptDecr` instance is "owned" (i.e. accessed *exclusively*) and by a *single* thread:
650 * `slunkcrypt_reset()`
651 * `slunkcrypt_free()`
652 * `slunkcrypt_encrypt()`
653 * `slunkcrypt_encrypt_inplace()`
654 * `slunkcrypt_decrypt()`
655 * `slunkcrypt_decrypt_inplace()`
656 * `SlunkCryptEncr::encrypt()`
657 * `SlunkCryptEncr::encrypt_inplace()`
658 * `SlunkCryptEncr::get_nonce()`
659 * `SlunkCryptDecr::decrypt()`
660 * `SlunkCryptDecr::decrypt_inplace()`
662 ***Note:*** Iff the same `slunkcrypt_t`, `SlunkCryptEncr` or `SlunkCryptDecr` instance needs to be shared across *multiple* threads, then the application **must** *serialize* any invocations of the above functions (on the shared instance), by an *explicit* "mutex" synchronization!
668 This work has been released under the **CC0 1.0 Universal** license.
670 For details, please refer to:
671 <https://creativecommons.org/publicdomain/zero/1.0/legalcode>