gocryptfs: A FUSE Encrypted Overlay Filesystem in Go

The problem gocryptfs solves for Linux users

Full-disk encryption protects a machine that is off. It does nothing for a directory you sync to a cloud provider, copy onto a USB stick, or hand to a backup service. gocryptfs targets that gap: it presents a normal directory of readable files while the bytes on disk are ciphertext. The README describes it as "an encrypted overlay filesystem written in Go", built on the go-fuse FUSE library, and states that the project was inspired by EncFS and "strives to fix its security issues while providing good performance".

The audience is narrow and specific. Linux is described as the native platform. macOS support is called beta quality, with the README warning that "most things work fine but you may hit an occasional problem" and pointing at ticket #15 for the history. For Windows there is no build here at all: the README directs readers to cppcryptfs, an independent C++ reimplementation. If your workflow is a Linux laptop or server with a directory that leaves the machine, this is the shape of tool you are looking for. If it is a Windows desktop, it is not.

How the overlay, file names and reverse mode work

The mechanism is a FUSE mount over two directories. You create a cipher directory and a plain directory, initialise the first, then mount the second on top of it. Everything you do in the plain directory is translated into encrypted operations in the cipher directory. File contents and file names are both encrypted, so the cipher directory does not leak the names of what you stored.

The storage overhead is documented precisely. Empty files take 0 bytes on disk. Non-empty files carry an 18 byte header, described as 2 bytes of version plus 16 bytes of random file id. Each 4 kB block adds 32 bytes: a 16 byte nonce and a 16 byte auth tag. That is a per-block cost, so a large file pays it repeatedly. The README points to Documentation/file-format.md for the full layout, which is the document to read if you care about the exact byte accounting rather than the summary.

Reverse mode inverts the direction. The README gives the example of initialising the plain directory and mounting the cipher directory over it, so a normal directory is presented as encrypted output. The practical use is encrypting a tree before it is uploaded somewhere, without first building a second encrypted copy by hand. It is a different data flow from the normal mode, not a flag on the same one, and the mount arguments reflect that.

Installing gocryptfs and mounting a first encrypted directory

The README states that precompiled binaries for x86_64 Linux are available from the GitHub releases page, and that the fuse package from your distribution must be installed for mounting to work. Distribution packages are listed too, for example apt install gocryptfs on Debian and Ubuntu, pacman -S gocryptfs on Arch, and port install gocryptfs on MacPorts.

If you prefer to build from source, the README requires Go 1.13 or higher and gives these steps. The first script builds a static binary using the Go standard library crypto backend. The second builds against OpenSSL, which the README says is faster on old CPUs that lack AES-NI, and needs libssl-dev, gcc and pkg-config on Debian or Ubuntu.

git clone https://github.com/rfjakob/gocryptfs.git
cd gocryptfs
./build-without-openssl.bash

Once you have the binary, the README's use section is three commands. The first creates the two directories, the second initialises the cipher directory and prints a master key, and the third mounts the plain view.

mkdir cipher plain
./gocryptfs -init cipher
./gocryptfs cipher plain

The README is explicit that you should keep a copy of the master key printed at init in a safe place, because it lets you access the data even if gocryptfs.conf is damaged or you lose the password. Read that line twice before you type anything into the plain directory. The manpage in Documentation/MANPAGE.md covers the remaining command-line options.

To check what your own CPU can do before committing, the README documents a self-test that prints the available cipher backends and their throughput, and selects one in auto mode.

./gocryptfs -speed

Where gocryptfs is the wrong tool

The most obvious limitation is the platform boundary. There is no Windows build in this repository. The README routes Windows users to cppcryptfs, which is a separate C++ project with its own GUI, so any Windows deployment is a different codebase with a different audit history. Treating gocryptfs as cross-platform because it is written in Go would be a mistake.

Second, the macOS story is self-described as incomplete. Beta quality means occasional problems, and the README asks users who hit one to open a new ticket rather than implying a fix is pending. If your team standardises on macOS laptops, you are adopting a tool whose own documentation declines to promise a clean run.

The third constraint is the trust model. The README's own framing is that "Important data should have a backup", and the master key is a single artifact whose loss or exposure matters. There is also no rollback story in the README: nothing describes reverting a mount or recovering from a partially written cipher directory beyond keeping the master key. And the project has never been a full-disk encryption replacement. It protects a directory, not a boot volume, so it does not answer the threat model that LUKS or BitLocker address.

How gocryptfs differs from VeraCrypt, EncFS and LUKS

The closest comparison the README makes is with EncFS, which it names as the inspiration and whose security issues it says it set out to fix. The difference is not cosmetic: gocryptfs is built on go-fuse and has been audited, with the audit linked from the README as having taken place on March 3, 2017. EncFS carries a different history. If you are choosing between the two, the audit and the file-format documentation are the concrete artifacts to compare, not the feature lists.

Against VeraCrypt the split is architectural. VeraCrypt creates encrypted containers and volumes at the block layer, which is the right shape for a whole disk or a portable container that must open on Windows. gocryptfs mounts a directory through FUSE and encrypts per file, which is the right shape for a directory that gets synced, rsynced or backed up file by file, because the ciphertext is ordinary files in an ordinary directory. You cannot rsync a VeraCrypt volume incrementally the way you can a gocryptfs cipher directory.

Against LUKS the difference is scope rather than design quality. LUKS is full-disk encryption: it protects a block device and everything on it when the machine is off. gocryptfs sits above the filesystem and protects one directory while the system is running. They solve different problems and can be used together, since a LUKS volume can hold a gocryptfs cipher directory without conflict.

Licence, testing and what an upgrade costs

The licence is MIT, and the repository ships the LICENSE file at the top level. The Makefile's install target places the binary, the gocryptfs-xray binary, the two manpages and a copy of the licence under /usr/share/licenses/gocryptfs, and the uninstall target removes exactly those paths. That pairing means a packaged install is cleanly reversible. MIT is permissive, so redistribution inside a product is a licensing question rather than a copyleft one, but this is not legal advice and the LICENSE file is the authority.

The project carries an unusual amount of test infrastructure for a filesystem of this size. The README states that ./test.bash runs the suite in about one minute and requires FUSE because it mounts several test filesystems. The stress_tests directory holds tests that run indefinitely, and the author ported xfstests to FUSE as the separate fuse-xfstests project. The README notes that gocryptfs passes the "generic" xfstests with one exception, recorded in Documentation/XFSTESTS.md. That exception is the first thing to read before assuming parity with a kernel filesystem.

Upgrade cost is tied to the ciphertext format rather than the binary. The file format is versioned and documented in Documentation/file-format.md, and the README states that all tags from v0.4 onward are signed by the gocryptfs signing key, with details on the signed releases page. Verify the signature before replacing a binary that reads your only copy of a directory. The CLI ABI in Documentation/CLI_ABI.md is described as stable and regression-tested, which matters if you drive gocryptfs from a script rather than by hand.

Editorial conclusion

Adopt gocryptfs if you want a per-directory encrypted view on Linux and you accept the FUSE dependency and the need to keep the master key printed at init somewhere safe. Do not adopt it if you need a supported Windows build (the README points to the independent C++ cppcryptfs instead) or a stable macOS experience, since the README describes that support as beta quality. Before trusting it with anything, run ./test.bash on your own kernel and check that the FUSE package is installed, because mounting will not work without it.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. rfjakob/gocryptfs on GitHub