cipherlock

README

cipherlock

AES-256-GCM file encryption with Argon2id key derivation.

cipherlock is a Go library and CLI tool for encrypting files and directories using authenticated encryption. It uses Argon2id (memory-hard key derivation) to resist GPU and ASIC brute-force attacks, and AES-256-GCM for verified confidentiality and integrity.

Features

• Strong encryption: AES-256-GCM authenticated encryption with 12-byte random nonces.
• Memory-hard KDF: Argon2id key derivation with configurable time, memory, and parallelism parameters. Defaults follow OWASP recommendations (time=3, memory=64MB, threads=4).
• Streaming API: Encrypt and decrypt arbitrary data streams via io.Reader and io.Writer interfaces.
• Directory encryption: Archive entire directories (tar + gzip) before encryption for atomic encrypted bundles.
• Pipe mode: Encrypt from stdin and write to stdout for seamless shell integration.
• Password generation: Generate cryptographically random passwords with --gen-password.
• ASCII-armor output: Base64 armored format for sharing encrypted files via text or email.
• Key file support: Read password from a file instead of interactive prompt.
• Secure file shredding: Overwrite original with random data before deletion on --in-place.
• Shell completion: Generate completion scripts for bash, zsh, fish, and powershell.
• V1 backward compatibility: Decrypt files created with the original PBKDF2+SHA1 format.
• Progress indication: Visual progress bar for large file operations.
• Library + CLI dual use: Importable Go package with a full-featured command-line interface built with Cobra.

Usage

Encrypt a file

cipherlock encrypt document.pdf

Creates document.pdf.encrypted in the same directory.

Decrypt a file

cipherlock decrypt document.pdf.encrypted

Restores document.pdf if the password is correct.

Encrypt in-place (overwrite source)

cipherlock encrypt --in-place document.pdf

Encrypts the file and replaces the original. A temporary file is used so the original is only overwritten on successful encryption.

Specify output path

cipherlock encrypt document.pdf -o secret.enc
cipherlock decrypt secret.enc -o document.pdf

Encrypt a directory

cipherlock encrypt ./projects/secrets/

Archives the directory (tar+gzip), encrypts it, and writes secrets.cipherlock.

Decrypt a directory

cipherlock decrypt secrets.cipherlock -o ./restored/

Use pipe mode

cat document.pdf | cipherlock encrypt > document.pdf.enc
cat document.pdf.enc | cipherlock decrypt > document.pdf

Generate a password

cipherlock encrypt --gen-password document.pdf

Generates a 64-character hex-encoded random password and prints it to stderr. The password is shown only once during encryption.

Armor mode (ASCII-armor output)

cipherlock encrypt --armor document.pdf -o document.asc

Wraps the encrypted output in base64 with PEM-style headers. Suitable for sharing via email, chat, or other text-only channels.

-----BEGIN CIPHERLOCK-----
<base64-encoded data, wrapped at 64 characters>
-----END CIPHERLOCK-----

Decrypt auto-detects the armor format -- no special flag required.

Use a key file

cipherlock encrypt --key-file ~/.keys/myapp.key document.pdf
cipherlock decrypt --key-file ~/.keys/myapp.key document.pdf.encrypted

Reads the password from a file instead of prompting interactively. Useful for scripts and automation.

Shell completion

cipherlock completion bash > /etc/bash_completion.d/cipherlock
cipherlock completion zsh > "${fpath[1]}/_cipherlock"
cipherlock completion fish > ~/.config/fish/completions/cipherlock.fish

Supports bash, zsh, fish, and powershell. Requires no additional dependencies -- generated by cobra's built-in completion engine.

Legacy format support

Files encrypted with the original file-encryption tool (PBKDF2+SHA1, 4096 iterations) can be decrypted using the same decrypt command. cipherlock detects the format automatically.

Library usage

Import cipherlock in your Go project:

import "github.com/valonmulolli/cipherlock/cipherlock"

Encrypt data

var buf bytes.Buffer
err := cipherlock.Encrypt(&buf, someReader, password, nil)

Decrypt data

var buf bytes.Buffer
err := cipherlock.Decrypt(&buf, someReader, password)

Encrypt a file

err := cipherlock.EncryptFile("source.txt", "source.txt.encrypted", password, nil)

Decrypt a file

err := cipherlock.DecryptFile("source.txt.encrypted", "source.txt", password)

Encrypt a directory

err := cipherlock.EncryptDir("./mydir", "mydir.cipherlock", password, nil)

Decrypt a directory

err := cipherlock.DecryptDir("mydir.cipherlock", "./mydir", password)

Custom configuration

config := &cipherlock.Config{
    SaltLen: 16,
    Time:    4,
    Memory:  128 * 1024, // 128 MB
    Threads: 8,
    KeyLen:  32,
}
err := cipherlock.Encrypt(dst, src, password, config)

Setting nil uses cipherlock.DefaultConfig (time=3, memory=64MB, threads=4).

Check if a file is encrypted

ok, err := cipherlock.IsEncrypted("file.enc")

Encrypt with ASCII armor

var encrypted bytes.Buffer
cipherlock.Encrypt(&encrypted, someReader, password, nil)
var armored bytes.Buffer
cipherlock.Armor(&armored, encrypted.Bytes())

Decrypt armored data

data, _ := cipherlock.UnarmorBytes(armoredData)
var plaintext bytes.Buffer
cipherlock.Decrypt(&plaintext, bytes.NewReader(data), password)

Check if data is armored

if cipherlock.IsArmored(data) {
    // handle armored format
}

Securely delete a file

err := cipherlock.Shred("sensitive-file.txt")

Overwrites the file with random data, then zeros, then removes it.

Decrypt legacy V1 format

err := cipherlock.DecryptFileV1("old_file.encrypted", "old_file", password)

File format

cipherlock uses a self-describing binary format:

4 bytes    Magic: "CV2\0"
1 byte     Version: 0x02
2 bytes    Salt length (little-endian)
N bytes    Argon2id salt
4 bytes    Argon2 time parameter (little-endian)
4 bytes    Argon2 memory parameter (little-endian)
1 byte     Argon2 threads parameter
4 bytes    Key length (little-endian)
12 bytes   AES-GCM nonce
Variable   Ciphertext + GCM authentication tag (last 16 bytes)

This header enables full parameter recovery during decryption without external configuration.

ASCII-armor format

When using --armor, the binary format above is wrapped in base64 encoding with PEM-style delimiters:

-----BEGIN CIPHERLOCK-----
<base64-encoded ciphertext, wrapped at 64 columns>
-----END CIPHERLOCK-----

The armored format is self-identifying -- decrypt detects it automatically by reading the header line.

Security

Key derivation

cipherlock uses Argon2id, the current state of the art in password-based key derivation. It is memory-hard, meaning an attacker needs a proportionally large amount of memory to attempt each password guess, making GPU and ASIC acceleration impractical.

Default parameters (time=3, memory=64MB, threads=4) follow the OWASP Password Storage Cheat Sheet recommendations for 2024+. For higher security environments, increase the Memory parameter to 128MB or 256MB.

Authenticated encryption

AES-256-GCM provides both confidentiality and integrity. Any tampering with the ciphertext is detected during decryption, and the operation fails with an authentication error before any data is written.

Nonce generation

A fresh 12-byte random nonce is generated for every encryption operation using crypto/rand. Nonces never repeat with overwhelming probability.

Safe file operations

When using --in-place, cipherlock writes to a temporary file first. Only after a successful encryption does it atomically replace the original. A failed operation never destroys the source data.

After successful replacement, the original file is securely shredded (overwritten with random data, then zeros, then removed) to prevent recovery of the plaintext from disk blocks.

V1 format caveat

The original file-encryption tool used PBKDF2 with only 4096 iterations and SHA-1. Files created with that tool remain decryptable via cipherlock, but re-encrypt them with the V2 format to get Argon2id protection.

Installation

Via Go install

go install github.com/valonmulolli/cipherlock@latest

From source

git clone https://github.com/valonmulolli/cipherlock.git
cd cipherlock
go build -o cipherlock .

Prebuilt binaries

Download the latest release for your platform from the releases page. Binaries are available for Linux, macOS, and Windows (amd64 and arm64).

Development

git clone https://github.com/valonmulolli/cipherlock.git
cd cipherlock
go test ./...

License

MIT