Security Best Practices

Passwords

• Never pass passwords on the command line - --password is refused
• Prefer interactive prompts or a keyfile over NOKVAULT_PASSWORD
• If you must automate with NOKVAULT_PASSWORD, restrict who can read the process environment and unset the variable after use
• Choose long, unique passwords; passwords are stretched with Argon2id but weak secrets remain weak
• There is no password recovery - losing the password loses access to the ciphertext

# Prefer interactive prompt or a keyfile
nokvault encrypt file.txt

# Automation fallback (visible to local processes)
export NOKVAULT_PASSWORD="secure-password"
nokvault encrypt file.txt --no-prompt
unset NOKVAULT_PASSWORD

Keyfiles

Keyfiles avoid typing secrets and are usually easier to rotate and revoke than shared passwords.

• Generate key material with a CSPRNG (for example openssl rand)
• Store keyfiles as regular files with mode 0600 on Unix - not symlinks
• Keep keyfiles out of the same directory as the encrypted data
• Never commit keyfiles to version control; ignore *.key, *.pem, and secret paths
• Rotate compromised or shared keys with rotate-key

# Generate a secure keyfile
openssl rand -out ~/.keys/master.key 32
chmod 600 ~/.keys/master.key

nokvault encrypt file.txt --keyfile ~/.keys/master.key

# Re-key after compromise or access change
nokvault rotate-key file.nokv \
  --old-keyfile ~/.keys/old.key \
  --new-keyfile ~/.keys/new.key

Path policy for keyfiles and targets

NokVault refuses symbolic links, Windows junctions, and other detected reparse points. There is no --follow-symlinks flag. If you see SYMLINK_DISALLOWED, replace the link with the real file or directory. If you see PATH_ESCAPE, keep the output relative path inside the selected directory. Policy errors are reported before dry-run previews and before password prompts. Do not treat this as protection against a privileged process swapping path components after validation.

Backups

• Back up encrypted files regularly
• Store keyfiles and credential backups separately from ciphertext (there is no password recovery)
• Use more than one backup location
• Test restoration before deleting originals
• After decrypt, file modes are clamped to owner-only by default; use --preserve-mode only when you intentionally need the original mode
• Keep NokVault updated; verify release binaries with checksums and attestations where available

Access control

• Limit who can read keyfiles and automation environments
• Use separate keyfiles for different projects or trust boundaries
• Log operations without logging secrets

Secure deletion

When removing sensitive unencrypted files, use secure-delete. Secure delete is best-effort and cannot guarantee erasure on SSD, snapshots, or copy-on-write storage.

# Preview, then securely delete
nokvault secure-delete sensitive-file.txt --dry-run
nokvault secure-delete sensitive-file.txt --yes --passes 7

Regular deletion only removes directory entries. Overwriting helps on traditional disks; SSD wear leveling, snapshots, and copy-on-write filesystems may retain prior data. Prefer encrypting before plaintext ever lands on durable storage you cannot scrub.