Security

Authenticated encryption

NokVault encrypts file contents with AES-256-GCM. AES-256-GCM provides confidentiality and integrity to holders of the correct secret; it does not establish author identity.

• Confidentiality: ciphertext cannot be read without the derived encryption key
• Integrity: tampering with ciphertext or the authentication tag causes decryption to fail
• Not identity: successful decryption proves possession of the secret, not who authored the file

Cryptographic randomness from the platform CSPRNG is used for the per-file salts and nonces that current encryption code generates. Identical plaintexts therefore produce different ciphertexts under normal operation.

Key derivation

Passwords are never used directly as encryption keys. NokVault derives keys with Argon2id. Argon2id parameters and salts follow the format-v2 behavior documented by the CLI:

• New encrypted files (format v2) store Argon2id memory, time, and parallelism in the file header
• Decryption uses the parameters that were active at encryption time
• Older v1 files rely on built-in defaults (64 MiB memory, time 3, parallelism 4)
• Config changes affect new encryptions only - they never alter how existing files are decrypted
• Each file uses a unique salt

Path containment and symlinks

NokVault does not follow symbolic links, Windows junctions, or other detected reparse points. Encrypt, decrypt, rotate-key, secure-delete, watch, schedule, and keyfiles share that default-deny policy. There is no follow opt-in. Nested-link rejection applies to commands that recurse.

• Validation walks existing path components with Lstat. Missing output leaves are allowed; an existing redirected parent is not.
• On Windows, Lstat-visible symlinks and ModeIrregular entries are rejected, as are paths whose reparse attributes can be read. If GetFileAttributes fails on an ordinary-looking path, that component cannot be conclusively classified and is not treated as a redirect.
• Directory outputs must remain under the selected root. Containment uses cleaned absolute paths and filepath.Rel, not a string-prefix check.
• Rejected paths return SYMLINK_DISALLOWED or PATH_ESCAPE with a hint.
• These checks run before dry-run previews and before any password prompt.

Path containment blocks links visible at validation time but is not descriptor-relative race protection. A privileged local attacker who replaces a path component between validation and open is out of scope. X1 atomic no-replace writes still cover output-file replacement races on supported filesystems.

Limitations

• Go memory zeroization is best-effort; swap, crash dumps, copies, and runtime behavior remain limitations. Passwords and keys are cleared when the CLI finishes with them, but that does not guarantee erasure from all system media.
• Do not treat password or key “verification” as a custom constant-time comparison path. Authentication failure on decrypt comes from AES-GCM tag checking in the standard library; there is no separate constant-time password compare step in the CLI decrypt flow.
• Secure delete is best-effort and cannot guarantee erasure on SSD, snapshots, or copy-on-write storage. Prefer never writing plaintext you cannot afford to leave behind.
• Release provenance, keyfile permissions, backups, and credential handling remain operator responsibilities - see Best Practices.

Operational guidance

• Use keyfiles instead of passwords when possible (chmod 0600; no symlinks)
• Store keyfiles securely and back them up
• Never pass passwords on the command line - --password is refused
• After decrypt, file modes are clamped to owner-only by default; use --preserve-mode only when you intentionally need the original (often world-readable) mode
• Rotate keys periodically
• Never commit passwords or keyfiles to version control
• Prefer keyfiles over NOKVAULT_PASSWORD for automation (env vars are still visible to local processes)
• Keep NokVault updated to the latest verified release
• Point commands at regular files and directories, not symlinks or junctions

See the Best Practices page for detailed guidance.