README.md

   1 ![SlunkCrypt](etc/img/SlunkCrypt-Logo.png)
   2
   3 Introduction
   4 ============
   5
   6 SlunkCrypt is an experimental cryptography library and command-line tool.
   7
   8
   9 Legal Warning
  10 =============
  11
  12 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, but we can't vouch for its correctness.
  13
  14
  15 Command-line Usage
  16 ==================
  17
  18 This section describes the SlunkCypt command-line front-end.
  19
  20 Synopsis
  21 --------
  22
  23 The SlunkCypt command-line program is invoked as follows:
  24
  25     slunkcrypt --encrypt [[@][:]<passphrase>] <input.txt> <output.enc>
  26     slunkcrypt --decrypt [[@][:]<passphrase>] <input.enc> <output.txt>
  27
  28 Commands
  29 --------
  30
  31 One of the following commands must be chosen:
  32
  33 - **`--encrypt` (`-e`):**
  34   Encrypt the plaintext in the given input file. The ciphertext is written to the specified output file.
  35 - **`--decrypt` (`-d`):**
  36   Decrypt the ciphertext in the given input file. The plaintext is written to the specified output file.
  37 - **`--self-test` (`-t`):**
  38   Run self-test and exit application.
  39
  40 Options
  41 -------
  42
  43 The following options are available:
  44
  45 - If `<passphrase>` is prefixed with a **`@`** character, then it specifies the file to read the passphrase from.
  46   *Note:* Only the first non-empty line in the specified file is used!
  47 - If `<passphrase>` is prefixed with a **`:`** character, then the leading character is ignored.
  48 - If `<passphrase>` is omitted, then the passphrase is read from the `SLUNK_PASSPHRASE` environment variable.
  49 - If `<passphrase>` is set to **`@-`**, then the passphrase is read from the standard input stream.
  50
  51
  52 Programming Interface (API)
  53 ===========================
  54
  55 C99 API
  56 -------
  57
  58 This section describes the "low-level" C99 API of the SlunkCypt library.
  59
  60 ### slunkcrypt_alloc()
  61
  62 Allocate and initialize a new SlunkCrypt encryption/decryption context.
  63
  64     slunkcrypt_t slunkcrypt_alloc(
  65         const uint64_t nonce,
  66         const uint8_t *const passwd,
  67         const size_t passwd_len
  68     );
  69
  70 ***Parameters:***
  71   * `nonce`
  72     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.
  73
  74     *Note:* It is recommended to generate a random nonce via the `slunkcrypt_generate_nonce()` function for each message!
  75
  76   * `passwd`
  77     The password to "protect" the message. The password is given as an array of bytes (`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!
  78
  79     *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.
  80
  81   * `passwd_len`
  82     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.
  83
  84 ***Return value:***
  85   * If successful, a handle to the new SlunkCrypt context is return; otherwise `SLUNKCRYPT_NULL` is returned.
  86
  87     *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.
  88
  89 ### slunkcrypt_reset()
  90
  91 Re-initialize an existing SlunkCrypt encryption/decryption context.
  92
  93     int slunkcrypt_reset(
  94         const slunkcrypt_t context,
  95         const uint64_t nonce,
  96         const uint8_t *const passwd,
  97         const size_t passwd_len
  98     );
  99
 100 ***Parameters:***
 101   * `context`
 102     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 and that has **not** been `free`'d since then.
 103
 104   * `nonce`
 105     Please refer to the  `slunkcrypt_alloc()` function for details!
 106
 107   * `passwd`
 108     Please refer to the  `slunkcrypt_alloc()` function for details!
 109
 110   * `passwd_len`
 111     Please refer to the  `slunkcrypt_alloc()` function for details!
 112
 113 ***Return value:***
 114   * If successful, `SLUNKCRYPT_SUCCESS` is returned; otherwise `SLUNKCRYPT_FAILURE` or `SLUNKCRYPT_ABORTED` is returned.
 115
 116 ### slunkcrypt_free()
 117
 118 De-allocate an existing SlunkCrypt encryption/decryption context. This will "clear" and release any memory occupied by the context.
 119
 120     void slunkcrypt_free(
 121         const slunkcrypt_t context
 122     );
 123
 124 ***Parameters:***
 125  * `context`
 126     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 and that has **not** been `free`'d since then.
 127
 128     *Note:* Once a handle has been passed to this function, that handle is *invalidated* and **must not** be used again!
 129
 130 ### slunkcrypt_generate_nonce()
 131
 132 Generate a new random *nonce* (number used once), using the system's "cryptographically secure" entropy source.
 133
 134     int slunkcrypt_generate_nonce(
 135       int64_t* const nonce
 136     );
 137
 138 ***Parameters:***
 139  * `nonce`
 140    A pointer to a variable of type `int64_t` that receives the new random nonce.
 141
 142 ***Return value:***
 143   * If successful, `SLUNKCRYPT_SUCCESS` is returned; otherwise `SLUNKCRYPT_FAILURE` or `SLUNKCRYPT_ABORTED` is returned.
 144
 145 ### slunkcrypt_encrypt()
 146
 147 Encrypt the next message chunk, using separate input/output buffers.
 148
 149     int slunkcrypt_encrypt(
 150         const slunkcrypt_t context,
 151         const uint8_t *const input,
 152         uint8_t* const output,
 153         size_t length
 154     );
 155
 156 ***Parameters:***
 157  * `context`
 158     The existing SlunkCrypt context to be used for encrypting the message chunk. This context will be updated.
 159
 160  * `input`
 161     A pointer to the *input* buffer containing the next chunk of the plaintext to be encrypted. The plaintext is given as an array of bytes (`uint8_t`). This can be arbitrary binary data, e.g. UTF-8 encoded text. NULL bytes are **not** treated specially.
 162
 163     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!
 164
 165  * `output`
 166     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 an array of bytes (`uint8_t`); it has the same length as the plaintext data.
 167
 168     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!
 169
 170  * `length`
 171    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.
 172
 173 ***Return value:***
 174   * If successful, `SLUNKCRYPT_SUCCESS` is returned; otherwise `SLUNKCRYPT_FAILURE` or `SLUNKCRYPT_ABORTED` is returned.
 175
 176 ### slunkcrypt_encrypt_inplace()
 177
 178 Encrypt the next message chunk, using a single buffer.
 179
 180     int slunkcrypt_encrypt(
 181         const slunkcrypt_t context,
 182         uint8_t* const buffer,
 183         size_t length
 184     );
 185
 186 ***Parameters:***
 187  * `context`
 188     The existing SlunkCrypt context to be used for encrypting the message chunk. This context will be updated.
 189
 190  * `buffer`
 191     A pointer to the buffer initially containing the next chunk of the plaintext to be encrypted. The plaintext is given as an array of bytes (`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.
 192
 193     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.
 194
 195  * `length`
 196    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.
 197
 198 ***Return value:***
 199   * If successful, `SLUNKCRYPT_SUCCESS` is returned; otherwise `SLUNKCRYPT_FAILURE` or `SLUNKCRYPT_ABORTED` is returned.
 200
 201
 202 License
 203 -------
 204
 205 This work has been released under the **CC0 1.0 Universal** license.
 206
 207 For details, please refer to:
 208 <https://creativecommons.org/publicdomain/zero/1.0/legalcode>