rans

rans is a command-line tool for encrypting and decrypting files and directories using AES-256-GCM — an authenticated encryption algorithm that provides both confidentiality and integrity guarantees.

---

Features

• AES-256-GCM — authenticated encryption; detects tampering automatically.
• Unique nonce per file — a fresh 12-byte nonce is generated with crypto/rand for every file, preventing nonce reuse.
• Single binary — no runtime, no dependencies to install.
• Cross-platform — Linux, macOS, Windows (amd64 and arm64).
• Dry-run mode — preview which files would be affected without modifying anything.
• Structured logging — machine-readable output with configurable log level.

---

Installation

Pre-built binaries (recommended)

Download the latest release for your platform from the Releases page, extract, and place the binary in your $PATH.

# Linux / macOS example
curl -L https://github.com/gerijacki/rans/releases/latest/download/rans_linux_amd64.tar.gz | tar xz
sudo mv rans /usr/local/bin/

Install with Go

go install github.com/gerijacki/rans/cmd/rans@latest

Build from source

git clone https://github.com/gerijacki/rans.git
cd rans
make build
./rans --version

---

Usage

1. Generate a key

rans keygen --output key.bin

This creates a 32-byte (256-bit) cryptographically random key. Keep this file safe. Without it, you cannot decrypt your files.

2. Encrypt a directory

rans encrypt --key key.bin ./documents

Each file in ./documents is encrypted in-place: file.txt becomes file.txt.enc and the original is removed. Files already ending in .enc are skipped.

3. Decrypt a directory

rans decrypt --key key.bin ./documents

Each .enc file is decrypted back to its original name and the .enc file is removed.

Dry-run (preview without changes)

rans encrypt --key key.bin --dry-run ./documents
rans decrypt --key key.bin --dry-run ./documents

All flags

Flags (global):
  --log-level string   Log level: debug, info, warn, error (default "info")
  -v, --version        Print version

rans keygen:
  -o, --output string  Path for the key file (default "key.bin")

rans encrypt / rans decrypt:
  -k, --key string     Path to the key file (default "key.bin")
      --dry-run        Preview without modifying files

---

Security

Encryption scheme

Wire format (per file):
[ 12 bytes: nonce ][ ciphertext + 16 bytes: GCM authentication tag ]

• Algorithm: AES-256-GCM (NIST SP 800-38D)
• Key size: 256 bits (32 bytes)
• Nonce: 96 bits (12 bytes), generated with crypto/rand per file
• Authentication tag: 128 bits (16 bytes), appended to ciphertext

The GCM authentication tag means any modification to the ciphertext — bit flip, truncation, or substitution — will be detected and the decryption will fail with an explicit error, rather than silently returning garbage.

Key storage

The key file is written with 0600 permissions (owner read/write only) on Unix systems. Never commit your key file to version control — it is excluded by the default .gitignore.

Responsible disclosure

To report a security vulnerability, see SECURITY.md.

---

Development

Requirements

• Go 1.21+
• golangci-lint (for linting)
• goreleaser (for releases)

Common commands

make build      # Build binary
make test       # Run tests with race detector
make lint       # Run golangci-lint
make cover      # Generate HTML coverage report
make snapshot   # Build release binaries locally (no tag required)

Project structure

cmd/rans/           CLI entry point (cobra commands)
internal/crypto/    AES-256-GCM encryption/decryption logic
internal/keymgmt/   Key generation and persistence
internal/walker/    Recursive file system traversal
.github/workflows/  CI (tests + lint) and Release pipelines

---

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening a pull request.

---

License

MIT — Copyright (c) 2026 Gerijacki