jolokia

Simple, strong encryption.

Examples

$ jolokia keygen
hNbaua5cGlUNsEp4HSUTSJG7gl5IURQiTvnABzhFW4w

$ jolokia encrypt "hello, world!" --key hNbaua5cGlUNsEp4HSUTSJG7gl5IURQiTvnABzhFW4w
Q0gyMAGnAk2xt/+cAAAAHYUv/WBO+VxMGHodIL0Qzjbtnv/LPpQd3CCcYW0kAAAAAA

# Same as passing `--key`.
$ export JOLOKIA_CIPHER_KEY=hNbaua5cGlUNsEp4HSUTSJG7gl5IURQiTvnABzhFW4w

$ jolokia decrypt Q0gyMAGnAk2xt/+cAAAAHYUv/WBO+VxMGHodIL0Qzjbtnv/LPpQd3CCcYW0kAAAAAA
hello, world!

# The key can be stored inside a file as well.
$ jolokia decrypt --key /secrets/jolokia.key Q0gyMAGnAk2xt/+cAAAAHYUv/WBO+VxMGHodIL0Qzjbtnv/LPpQd3CCcYW0kAAAAAA
hello, world!

Get --help

Simple, strong encryption.

Usage: jolokia [<options>] <command> [<args>]

Commands:
  keygen                  Generate cipher key
  encrypt                 Encrypt plaintext
  decrypt                 Decrypt ciphertext

Args:
  <MESSAGE>
  -a, --algorithm <ALGO>  Cipher algorithm (default: ChaCha20-Poly1305)
  -k, --key <KEY>         Cipher key (base64)
  -r, --raw               Handle message as raw binary
  -f, --file <FILE>       Read message from file
    -i, --in-place        Write output to input file
  -o, --output <FILE>     Write output to file

Options:
  -h, --help              Show help message and exit
  -V, --version           Show the version and exit

What does jolokia do?

jolokia provides strong, modern, hard-to-misuse encryption for the general public.

[!WARNING]

jolokia has not been audited for security. It is based on audited dependencies for the underlying algorithm implementations, but the final package (what you're using) was not.

[!CAUTION]

Do not encrypt data you can't afford to lose. Be especially cautious of in-place encryption; always make a backup first. If you lose your key, or if there's a bug, YOUR DATA WILL NOT BE RECOVERABLE.

Algorithms

ChaCha20-Poly1305 is the default algorithm. Names are case-insensitive, and hyphens are optional.

Accepted values:

• ChaCha20-Poly1305: chacha20poly1305, chacha20, chacha, cha20, cha
• HPKE: hpke
• ROT-n: rotn, rot

For example:

$ jolokia encrypt "hello"
$ jolokia encrypt "hello" -a chacha
$ jolokia keygen --algorithm hpke
$ jolokia decrypt "uryyb" -a rot --key 13
$ jolokia encrypt "hello" -a bf

Key

In jolokia, a key is always a base64-encoded string of bytes. The size of the key varies depending on the selected algorithm.

To generate a new key run:

$ jolokia keygen
hNbaua5cGlUNsEp4HSUTSJG7gl5IURQiTvnABzhFW4w

To use the key, pass it as --key or -k:

$ jolokia encrypt "foo" --key hNbaua5cGlUNsEp4HSUTSJG7gl5IURQiTvnABzhFW4w
Q0gyMAGSwlWJdALzAAAAE448viN3l+rwa7W4RdkRI0V/VckAAAAA

Or as an environment variable (but --key has precedence):

$ export JOLOKIA_CIPHER_KEY=hNbaua5cGlUNsEp4HSUTSJG7gl5IURQiTvnABzhFW4w
$ jolokia encrypt "foo"
Q0gyMAGSwlWJdALzAAAAE448viN3l+rwa7W4RdkRI0V/VckAAAAA

The key can also be the name of a file that contains a key:

$ echo hNbaua5cGlUNsEp4HSUTSJG7gl5IURQiTvnABzhFW4w > /secrets/jolokia.key
$ jolokia decrypt --key /secrets/jolokia.key Q0gyMAGSwlWJdALzAAAAE448viN3l+rwa7W4RdkRI0V/VckAAAAA
foo

To set a key permanently, the recommended solution is to point the environment variable to a file:

$ echo hNbaua5cGlUNsEp4HSUTSJG7gl5IURQiTvnABzhFW4w > ~/.jolokia.key
$ echo 'export JOLOKIA_CIPHER_KEY="$HOME/.jolokia.key"' >> ~/.bashrc

Message

The message can be passed on the command line:

$ jolokia encrypt "bar"
Q0gyMAHPNRsLieAOAAAAE/ssTCh2zCm73t+aQf9aKNepgPkAAAAA

Or from a file:

$ jolokia encrypt --file bar.txt
Q0gyMAHPNRsLieAOAAAAE/ssTCh2zCm73t+aQf9aKNepgPkAAAAA

Or via stdin (but the command line has precedence):

$ cat bar.txt | jolokia encrypt
Q0gyMAHPNRsLieAOAAAAE/ssTCh2zCm73t+aQf9aKNepgPkAAAAA

By definition, you can round-trip it:

$ jolokia encrypt "hello, world" -o encrypted.txt
$ jolokia decrypt -f encrypted.txt
hello, world

You can also encrypt or decrypt a file in-place:

$ jolokia encrypt -f cat.gif --in-place
$ jolokia decrypt -f cat.gif -i

Raw I/O

If you do not want base64 encoding, you can pass the --raw or -r flag. This makes sense for larger files for which you don't want the ~33% size overhead of base64.

$ jolokia encrypt --raw "hello, world" > hello.enc
$ cat hello.enc | jolokia decrypt --raw
hello, world

Base64 is the simplest and safest option for most users. It makes it easy to copy-paste and share ciphertext. Use --raw only if you know what you're doing.

Compression

BYOC. jolokia does not provide built-in compression, but you can bring your own:

$ gzip -c cat.gif | jolokia encrypt -r > out.enc
$ jolokia decrypt -r -f out.enc | gunzip > cat.gif

If you need to compress and encrypt multiple files or directories, consider taring them:

$ tar -czf - cat.gif more-gifs/ | jolokia encrypt -r > out.enc
$ jolokia decrypt -r -f out.enc | tar -xzf -

It makes sense to combine compression with --raw to get the smallest file size possible.

Roadmap

• If multiple algorithms, should we keep JOLOKIA_CIPHER_KEY as default also support specialized: JOLOKIA_CIPHER_KEY_CHACHA20POLY1305?). If so, rename JOLOKIA_CIPHER_KEY to just JOLOKIA_KEY.
• Add tests. Test coverage is decent. What's missing to get to 100% are tests for the error cases, edge cases, and false negatives.

Installation

Install from crates.io with Cargo:

cargo install jolokia

Pre-built binaries for Linux and macOS are available on the latest GitHub release.

Documentation is available on docs.rs.