CLI tool written in Go to encrypt/decrypt strings using AES-GCM.
It supports two modes:
-
Machine-bound mode (default): the encryption key is deterministically derived from:
- a secret prefix (configurable via env var)
- Machine ID
- OS
This means ciphertext is typically decryptable only on the same machine.
-
Passphrase mode (portable, optional): the encryption key is derived from a passphrase using Argon2id with a random salt. Ciphertext is self-contained and can be decrypted on any machine as long as you have the passphrase.
Security note: this is not a password hashing tool. If you need to store user passwords, use a dedicated password hashing algorithm (Argon2id / bcrypt / scrypt).
- Cross-platform (Windows / macOS / Linux)
- Authenticated encryption: AES-GCM
- Two modes:
- Machine-bound key derivation (SHA-256, 32 bytes → AES-256)
- Passphrase-based derivation (Argon2id + random salt, AES-256)
- Optional file logging (best-effort; failures do not stop the CLI)
- Input size limits (default 1 MiB) to mitigate trivial local DoS
- Go 1.17+ (as per
go.mod)
Dependencies are managed via Go modules (go.mod).
main.go: CLI entrypoint and command dispatchlib/lib.go: crypto and key-derivation library (AES-GCM, machine-bound key, passphrase key)
The CLI expects 2 arguments after the program name:
usage: encdec ENC <plain-text> | encdec DEC <hex-ciphertext> | encdec ENCPASS <plain-text> | encdec DECPASS <p1:ciphertext>Accepted operations:
ENCencrypt (machine-bound mode)DECdecrypt (machine-bound mode)ENCPASSencrypt (passphrase mode, requiresENCDEC_PASS)DECPASSdecrypt (passphrase mode, requiresENCDEC_PASS)
If an error occurs, the program prints the error on stderr and exits with code 1.
From the module folder (encdec/):
go mod tidyExamples below use go run . ... but the same arguments work with the built binary.
go run . ENC 'PasswordToEncrypt'Output:
encrypted : <hex-ciphertext>Notes:
- The output ciphertext is hex-encoded.
- Internally the ciphertext contains the nonce prepended to the AES-GCM output (this is handled transparently by the tool).
go run . DEC <hex-ciphertext>Output:
PasswordToEncryptNotes:
-
Decryption succeeds only if performed on the same machine (same Machine ID + OS) and with the same
ENCDEC_SECRET_PREFIXused at encryption time. -
If the Machine ID is empty or
uninitializedthe tool refuses to run:machine id: empty or uninitialized, refusing to derive a machine-bound key
On Linux, set a real ID (for example
systemd-machine-id-setup). Ciphertext created by an older version on such a host was not machine-bound: decrypt it with that version first, then encrypt it again once a real ID is set.
In this mode the passphrase is read from environment variable ENCDEC_PASS
(to avoid passing secrets through CLI args / history / process list).
export ENCDEC_PASS='your-strong-passphrase'go run . ENCPASS 'PasswordToEncrypt'Output:
encrypted : p1:<salt_b64>:<hex-ciphertext>go run . DECPASS 'p1:<salt_b64>:<hex-ciphertext>'Output:
PasswordToEncryptPassphrase ciphertext format details (as implemented in lib/lib.go):
- Prefix:
p1:(format/version marker) - Full format:
p1:<salt_b64>:<cipher_hex> <salt_b64>is encoded withbase64.RawStdEncoding- Salt length is 16 bytes (randomly generated on encryption)
- The derived key uses Argon2id with parameters:
- iterations:
1 - memory:
64*1024KiB (≈ 64 MiB) - parallelism:
4 - output key length:
32bytes (AES-256)
- iterations:
If the ciphertext does not start with p1: the tool returns:
invalid passphrase ciphertext format (missing p1: prefix)For an extra layer of security in machine-bound mode, change the secret prefix.
- Preferred (no rebuild): set the env var at runtime
export ENCDEC_SECRET_PREFIX='my-secret-prefix'
- Or compile a custom default into the binary by editing
defaultSecretKeyPrefixinlib/lib.go:const defaultSecretKeyPrefix = "jY-1"
If you want file logging at a different location, edit pathLog in main.go:
const pathLog = "/opt/frm/writable/logs/"Note: the project is now a multi-file Go package (
main.go+lib/), so build the package (.), not a single file.go build main.gofrom older versions no longer works.
go build -o encdec .General form:
env GOOS=<target-OS> GOARCH=<target-architecture> go build -o encdec .
envis a Linux/Unix command. On Windows use Git Bash, or set the variables with PowerShell /set(see Windows example below).
Linux example (amd64):
env GOOS=linux GOARCH=amd64 go build -o encdec .macOS examples:
# Intel Macs
env GOOS=darwin GOARCH=amd64 go build -o encdec .
# Apple Silicon (M1/M2/M3...)
env GOOS=darwin GOARCH=arm64 go build -o encdec .Windows examples (produces encdec.exe):
From Git Bash / Linux / macOS:
env GOOS=windows GOARCH=amd64 go build -o encdec.exe .From Windows PowerShell:
$env:GOOS="windows"; $env:GOARCH="amd64"; go build -o encdec.exe .From Windows cmd.exe:
set GOOS=windows
set GOARCH=amd64
go build -o encdec.exe .Reminder: on Windows the fixed Unix log path
/opt/...is not used, so file logging is skipped automatically (see Logging).
Common combinations supported by the Go toolchain:
| GOOS (Target OS) | GOARCH (Target architecture) |
|---|---|
| android | arm |
| darwin | amd64 |
| darwin | arm64 |
| dragonfly | amd64 |
| freebsd | 386 |
| freebsd | amd64 |
| freebsd | arm |
| linux | 386 |
| linux | amd64 |
| linux | arm |
| linux | arm64 |
| linux | ppc64 |
| linux | ppc64le |
| linux | mips |
| linux | mipsle |
| linux | mips64 |
| linux | mips64le |
| netbsd | 386 |
| netbsd | amd64 |
| netbsd | arm |
| openbsd | 386 |
| openbsd | amd64 |
| openbsd | arm |
| plan9 | 386 |
| plan9 | amd64 |
| solaris | amd64 |
| windows | 386 |
| windows | amd64 |
Run
go tool dist listto see the full, up-to-date list for your Go version.
Overrides the default secret prefix used in machine-bound key derivation.
- If not set, the code uses the built-in default prefix (see
defaultSecretKeyPrefixinlib/lib.go). - If you keep the default value and the code is public, the prefix should be considered not secret.
Example:
export ENCDEC_SECRET_PREFIX='my-secret-prefix'Important:
- To decrypt successfully in machine-bound mode,
ENCDEC_SECRET_PREFIXmust match the value used during encryption.
Required for ENCPASS / DECPASS.
Example:
export ENCDEC_PASS='your-strong-passphrase'The CLI tries to write logs to:
const pathLog = "/opt/frm/writable/logs/"Behavior (best-effort):
- The tool attempts to create the directory and append to:
/opt/frm/writable/logs/enc_dec.log - If any step fails (directory not writable/missing permissions/path not valid), the program continues without file logging.
Platform notes (as implemented in main.go):
- On Windows, file logging is skipped because the fixed Unix path
/opt/...is not suitable. - On non-Windows systems, the tool attempts to enforce file permissions
0664on the log file when possible.
To reduce accidental/malicious resource usage, inputs are limited:
Library limits (lib/lib.go):
- plaintext max: 1 MiB
- ciphertext max: 1 MiB of hex chars
CLI-level additional check (main.go):
- for
DEC, ciphertext max: 1 MiB of hex chars (secondary defense)
If exceeded, the tool returns an error similar to:
plaintext too large (max 1048576 bytes)or:
ciphertext too large (max 1048576 hex chars)- Machine-bound mode prevents “copy & decrypt on another machine” but does not protect against an attacker already running on the same host.
- Machine-bound mode requires a real machine ID:
ENCandDECexit with an error when the ID is empty, whitespace-only, or the systemd placeholderuninitialized. Without this check the key would depend only on the prefix and the OS, so with the default prefix anyone could compute it. Cloned images that share a real machine ID cannot be detected and still derive the same key. - Passphrase mode provides portability and shifts security to the strength/handling of the passphrase.
GNU General Public License v3.0
Danilo Ritarossi