SlunkCrypt/README.md

Introduction

SlunkCrypt is an experimental cryptography library and command-line tool.

Legal Warning

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, which collects information on cryptography laws in many countries, but we can't vouch for its correctness.

Command-line Usage

This section describes the SlunkCypt command-line application.

Synopsis

The SlunkCypt command-line program is invoked as follows:

slunkcrypt --encrypt [[@][:]<passphrase>] <input> <output>
slunkcrypt --decrypt [[@][:]<passphrase>] <input> <output>
slunkcrypt --make-pw [<length>]

Commands

One of the following commands must be chosen:

• --encrypt (-e):
  Run application in encrypt mode. Reads the given plaintext and generates ciphertext.
• --decrypt (-d):
  Run application in decrypt mode. Reads the given ciphertext and restores plaintext.
• --make-pw (-p):
  Generate and output a "strong" random passphrase suitable for use with SlunkCrypt.
• --self-test (-t):
  Run application in self-test mode. Program will exit when test is completed.

Options

The following options are available:

• <passphrase>:
  • The passphrase used to "protect" the message. The same passphrase must be used for both, encrypt and decrypt mode.
  • It will only be possible decrypt the ciphertext, if the "correct" passphrase is known.
  • Use --make-pw to generate a random passphrase. The passphrase must be kept confidential under all circumstances!
  • Syntax:
    • If the passphrase is prefixed with an @ character, then it specifies the file to read the passphrase from.
    • If the passphrase is set to @-, then the passphrase is read from the standard input stream.
    • If the passphrase is prefixed with an : character, then the leading character is ignored; use if passphrase contains @ character.
    • If the parameter is omitted, then the passphrase is read from the SLUNK_PASSPHRASE environment variable.
  • 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.
• <input>:
  • In encrypt mode, specifies the plaintext (unencrypted information) file that is to be encrypted.
  • In decrypt mode, specifies the ciphertext (result of encryption) file that is to be decrypted.
• <output>:
  • In encrypt mode, specifies the file where the ciphertext (result of encryption) will be stored.
  • In decrypt mode, specifies the file where the plaintext (unencrypted information) will be stored.
• <length>:
  • Speicifes the length of the passphrase to be generated, in characters. If not specified, defaults to 24.

Programming Interface (API)

C99 API

This section describes the "low-level" C99 API of the SlunkCypt library.

slunkcrypt_alloc()

Allocate and initialize a new SlunkCrypt encryption/decryption context.

slunkcrypt_t slunkcrypt_alloc(
    const uint64_t nonce,
    const uint8_t *const passwd,
    const size_t passwd_len
);

Parameters:

• nonce
  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.

  Note: It is recommended to generate a random nonce via the slunkcrypt_generate_nonce() function for each message!

• passwd
  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!

  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.

• passwd_len
  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.

Return value:

• If successful, a handle to the new SlunkCrypt context is return; otherwise SLUNKCRYPT_NULL is returned.

  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.

slunkcrypt_reset()

Re-initialize an existing SlunkCrypt encryption/decryption context.

int slunkcrypt_reset(
    const slunkcrypt_t context,
    const uint64_t nonce,
    const uint8_t *const passwd,
    const size_t passwd_len
);

Parameters:

• context
  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.

• nonce
  Please refer to the slunkcrypt_alloc() function for details!

• passwd
  Please refer to the slunkcrypt_alloc() function for details!

• passwd_len
  Please refer to the slunkcrypt_alloc() function for details!

Return value:

• If successful, SLUNKCRYPT_SUCCESS is returned; otherwise SLUNKCRYPT_FAILURE or SLUNKCRYPT_ABORTED is returned.

slunkcrypt_free()

De-allocate an existing SlunkCrypt encryption/decryption context. This will "clear" and release any memory occupied by the context.

void slunkcrypt_free(
    const slunkcrypt_t context
);

Parameters:

• context
  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.

  Note: Once a handle has been passed to this function, that handle is invalidated and must not be used again!

slunkcrypt_generate_nonce()

Generate a new random nonce (number used once), using the system's "cryptographically secure" entropy source.

int slunkcrypt_generate_nonce(
  int64_t* const nonce
);

Parameters:

• nonce
  A pointer to a variable of type int64_t that receives the new random nonce.

Return value:

• If successful, SLUNKCRYPT_SUCCESS is returned; otherwise SLUNKCRYPT_FAILURE or SLUNKCRYPT_ABORTED is returned.

slunkcrypt_encrypt()

Encrypt the next message chunk, using separate input/output buffers.

int slunkcrypt_encrypt(
    const slunkcrypt_t context,
    const uint8_t *const input,
    uint8_t* const output,
    size_t length
);

Parameters:

• context
  The existing SlunkCrypt context to be used for encrypting the message chunk. This context will be updated.

• input
  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.

  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!

• output
  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.

  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!

• length
  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.

Return value:

• If successful, SLUNKCRYPT_SUCCESS is returned; otherwise SLUNKCRYPT_FAILURE or SLUNKCRYPT_ABORTED is returned.

slunkcrypt_encrypt_inplace()

Encrypt the next message chunk, using a single buffer.

int slunkcrypt_encrypt_inplace(
    const slunkcrypt_t context,
    uint8_t* const buffer,
    size_t length
);

Parameters:

• context
  The existing SlunkCrypt context to be used for encrypting the message chunk. This context will be updated.

• buffer
  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.

  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.

• length
  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.

Return value:

• If successful, SLUNKCRYPT_SUCCESS is returned; otherwise SLUNKCRYPT_FAILURE or SLUNKCRYPT_ABORTED is returned.

slunkcrypt_decrypt()

Decrypt the next ciphertext chunk, using separate input/output buffers.

int slunkcrypt_decrypt(
    const slunkcrypt_t context,
    const uint8_t *const input,
    uint8_t* const output,
    size_t length
);

Parameters:

• context
  The existing SlunkCrypt context to be used for decrypting the ciphertext chunk. This context will be updated.

• input
  A pointer to the input buffer containing the next chunk of the ciphertext to be decrypted. The ciphertext is given as an array of bytes (uint8_t).

  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!

• output
  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 an array of bytes (uint8_t); it has the same length as the plaintext data.

  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!

• length
  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.

Return value:

• If successful, SLUNKCRYPT_SUCCESS is returned; otherwise SLUNKCRYPT_FAILURE or SLUNKCRYPT_ABORTED is returned.

slunkcrypt_decrypt_inplace()

Decrypt the next ciphertext chunk, using a single buffer.

int slunkcrypt_decrypt_inplace(
    const slunkcrypt_t context,
    uint8_t* const buffer,
    size_t length
);

Parameters:

• context
  The existing SlunkCrypt context to be used for decrypting the ciphertext chunk. This context will be updated.

• buffer
  A pointer to the buffer initially containing the next chunk of the ciphertext to be decrypted. The ciphertext is given as an array of bytes (uint8_t). The plaintext chunk that corresponds to the given ciphertext chunk will be stored to the same buffer, thus replacing the plaintext data.

  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.

• length
  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.

Return value:

• If successful, SLUNKCRYPT_SUCCESS is returned; otherwise SLUNKCRYPT_FAILURE or SLUNKCRYPT_ABORTED is returned.

slunkcrypt_random_bytes()

Generate a sequence of random bytes, using the system's "cryptographically secure" entropy source.

size_t slunkcrypt_random_bytes(
  uint8_t* const buffer,
  const size_t length
);

Parameters:

• buffer
  A pointer to the output buffer where the random bytes will be stored.

  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!

• length
  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.

Return value:

• If successful, the number of random bytes that have been generated and stored to the output buffer is returned; otherwise 0 is returned.

  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.

slunkcrypt_bzero()

Erase the contents of a byte array, by overwriting it with zero bytes, guaranteeing that compiler optimizations will not remove the erase operation.

void slunkcrypt_bzero(
  void* const buffer,
  const size_t length
);

Parameters:

• buffer
  A pointer to the buffer whose content is to be erased.

  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!

• length
  The size of the buffer to be erased, in bytes.

License

This work has been released under the CC0 1.0 Universal license.

For details, please refer to:
https://creativecommons.org/publicdomain/zero/1.0/legalcode