SlunkCrypt

Introduction

SlunkCrypt is an experimental cross-platform cryptography library and command-line tool. A fully-featured GUI is provided for the Windows platform.

Please refer to the section encryption algorithm for more details!

For news and updates, please check out the official SlunkCrypt project web-site at: https://lord_mulder.gitlab.io/slunkcrypt/

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.

System Requirements

The SlunkCrypt library and the command-line application currently run on the following platforms:

The SlunkCrypt GUI application currently runs on the following platforms:

GUI Usage

This is how the graphical user interface (GUI) for SlunkCrypt looks on Windows 11:

Prerequisites

Please be sure to install the .NET Framework 4.7.2, or any later .NET Framework 4.x version, before running the SlunkCrypt Windows GUI application:
https://dotnet.microsoft.com/download/dotnet-framework

Note: If you are running Windows 8.1 or later, then almost certainly a suitable version of the .NET Framework is already installed 😎

Settings

The following settings can be adjusted in the slunkcrypt-gui.exe.config configuration file:

Command-line Usage

This section describes the SlunkCypt command-line application.

Synopsis

The SlunkCypt command-line program is invoked as follows:

slunkcrypt --encrypt [pass:<pass>|file:<file>] <input.txt> <output.enc>
slunkcrypt --decrypt [pass:<pass>|file:<file>] <input.enc> <output.txt>
slunkcrypt --make-pw [<length>]

Commands

One of the following commands must be chosen:

Options

The following command-line options are available:

Remarks

Environment

The following environment variables may be used:

Examples

Here are some examples on how to use the SlunkCrypt command-line application:

Example #1

  1. Let’s generate a new random (secure) password first:

    slunkcrypt --make-pw

    Example output:

    cdG2=fh<C=3[SSCzf[)iDjIV

  2. Now, encrypt the plaintext message, using the generated password:

    slunkcrypt --encrypt pass:"cdG2=fh<C=3[SSCzf[)iDjIV" plaintext.txt ciphertext.enc

    Optionally, let’s have a look at the ciphertext:

    hexdump -C ciphertext.enc

  3. Finally, decrypt the ciphertext, using the same password as before:

    slunkcrypt --decrypt pass:"cdG2=fh<C=3[SSCzf[)iDjIV" ciphertext.enc plaintext.out

    Optionally, verify that the decrypted file is identical to the original:

    sha256sum -b plaintext.txt plaintext.out

Example #2

  1. Generate a new password and store it to a text file:

    slunkcrypt --make-pw > passwd.txt

    Optionally, output the generated password to the terminal:

    cat passwd.txt

  2. Encrypt file by reading the password from the text file:

    slunkcrypt --encrypt file:passwd.txt plaintext.txt ciphertext.enc

Example #3

  1. Generate a new password directly to an environment variable:

    MY_PASSWD="$(slunkcrypt --make-pw)"

    Optionally, output the generated password to the terminal:

    echo "${MY_PASSWD}"

  2. Encrypt file by reading the password from the stdin:

    slunkcrypt --encrypt - plaintext.txt ciphertext.enc <<< "${MY_PASSWD}"

Encryption algorithm

SlunkCrypt is based on concepts of the well-known Enigma machine, but with significant improvements, largely inspired by Ross Anderson – “A Modern Rotor Machine”.

A great explanation and visualization of how the original Enigma machine works can be found in this video.

Overview

This section summarizes the improvements that have been implemented in SlunkCrypt:

Details

This section explains some crucial implementation details of the SlunkCrypt library:

Programming Interface (API)

This section describes the SlunkCypt library interface for software developers.

Getting started

In order to use the SlunkCypt library in your C++ code, include <slunkcrypt.hpp> header and instantiate the appropriate SlunkCypt classes:

Example #1

Here is a simple example on how to use the SlunkCrypt Encryptor class:

#include <slunkcrypt.hpp>
#include <fstream>
#include <iostream>

int main()
{
    /* Open input and output files here */
    uint8_t buffer[BUFF_SIZE];
    slunkcrypt::Encryptor slunk_encrypt(passphrase);
    while (input.good())
    {
        input.read(reinterpret_cast<char*>(buffer), BUFF_SIZE);
        if ((!input.bad()) && (input.gcount() > 0))
        {
            if (!slunk_encrypt.inplace(buffer, (size_t)input.gcount()))
            {
                /* Implement error handling here */
            }
            output.write(reinterpret_cast<char*>(buffer), count);
        }
    }
    std::cout << std::hex << slunk_encrypt.get_nonce() << std::endl;
}

Example #2

Here is a simple example on how to use the SlunkCrypt Decryptor class:

#include <slunkcrypt.hpp>
#include <fstream>
#include <iostream>

int main()
{
    /* Open input and output files here */
    uint8_t buffer[BUFF_SIZE];
    slunkcrypt::Decryptor slunk_decrypt(passphrase, nonce);
    while (input.good())
    {
        input.read(reinterpret_cast<char*>(buffer), BUFF_SIZE);
        if ((!input.bad()) && (input.gcount() > 0))
        {
            if (!slunk_decrypt.inplace(buffer, (size_t)input.gcount()))
            {
                /* Implement error handling here */
            }
            output.write(reinterpret_cast<char*>(buffer), count);
        }
    }
}

C++11 API

This section describes the “high-level” C++11 API of the SlunkCrypt library. All SlunkCrypt classes live in the slunkcrypt namespace.

Encryptor

Class for encrypting data using the SlunkCrypt library.

Constructor

Create and initialize a new Encryptor instance. Also generated a new, random nonce.

Encryptor::Encryptor(
  const std::string &passwd,
  const size_t thread_count = 0U,
  const bool legacy_compat = false,
  const bool debug_logging = false
);

Parameters:

Exceptions:

Encryptor::process() [1]

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

bool process(
  const uint8_t *const input,
  uint8_t *const output,
  size_t length
);

Parameters:

Return value:

Encryptor::process() [2]

Encrypt the next message chunk, using separate input/output containers (std::vector).

bool process(
  const std::vector<uint8_t> &input,
  std::vector<uint8_t> &output
);

Parameters:

Return value:

Encryptor::inplace() [1]

Encrypt the next message chunk, using a single buffer.

bool inplace(
  uint8_t *const buffer,
  size_t length
);

Parameters:

Return value:

Encryptor::inplace() [2]

Encrypt the next message chunk, using a single container (std::vector).

bool inplace(
  std::vector<uint8_t> &buffer
);

Parameters:

Return value:

Encryptor::get_nonce()

Retrieve the random nonce that is used to encrypt the message.

uint64_t get_nonce();

Return value:

Decryptor

Class for decrypting data using the SlunkCrypt library.

Constructor

Create and initialize a new Decryptor instance.

Decryptor::Decryptor(
  const std::string &passwd,
  const uint64_t nonce,
  const size_t thread_count = 0U,
  const bool legacy_compat = false,
  const bool debug_logging = false
);

Parameters:

Exceptions:

Decryptor::process() [1]

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

bool process(
  const uint8_t *const input,
  uint8_t *const output,
  size_t length
);

Parameters:

Return value:

Decryptor::process() [2]

Decrypt the next message chunk, using separate input/output containers (std::vector).

bool process(
  const std::vector<uint8_t> &input,
  std::vector<uint8_t> &output
);

Parameters:

Return value:

Decryptor::inplace() [1]

Decrypt the next message chunk, using a single buffer.

bool inplace(
  uint8_t *const buffer,
  size_t length
);

Parameters:

Return value:

Decryptor::inplace() [2]

Decrypt the next message chunk, using a single container (std::vector).

bool inplace(
  std::vector<uint8_t> &buffer
);

Parameters:

Return value:

C99 API

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

Functions

The SlunkCypt library defines the following functions:

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,
    const int mode
);

Parameters:

Return value:

slunkcrypt_alloc_ext()

Allocate and initialize a new SlunkCrypt encryption/decryption context with additional parameters.

slunkcrypt_t slunkcrypt_alloc_ext(
    const uint64_t nonce,
    const uint8_t *const passwd,
    const size_t passwd_len,
    const int mode,
    const slunkparam_t *const param
);

Parameters:

Return value:

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,
    const int mode
);

Parameters:

Return value:

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:

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:

Return value:

slunkcrypt_process()

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

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

Parameters:

Return value:

slunkcrypt_inplace()

Encrypt or decrypt the next message chunk, using a single input/output buffer.

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

Parameters:

Return value:

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:

Return value:

slunkcrypt_bzero()

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

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

Parameters:

Types

SlunkCrypt parameters

The slunkparam_t struct is used to pass additional parameters that will be used for initializing the SlunkCrypt context. It contains the following fields:

Global variables

The SlunkCypt library defines the following global variables:

Version information

These variables can be used to determine the version of the SlunkCrypt library at runtime, using the semantic versioning scheme:

Abort request

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:

Constants

The SlunkCypt library defines the following constants:

Mode of operation

The SlunkCypt library supports the following modes of operation:

Limits

The following limits are defined for the SlunkCypt library:

Error codes

SlunkCypt library functions that return an error code may return one of the following constants:

Thread safety

The following functions are fully “thread-safe” and thus may safely be called by any thread at any time without the need for synchronization:

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:

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.

Source Code

The latest SlunkCrypt source code is available from the official Git mirrors at:

Deprecated mirror sites:

Build Instructions

SlunkCrypt can be built from the sources on Microsoft Windows or any POSIX-compatible platform, using a C-compiler that supports the C99 standard.

Frequently Asked Questions

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

Acknowledgement

SlunkCrypt incorporates code from the following third-party software projects:

▮