An encrypted overlay filesystem written in Go. Official website:
https://nuetzlich.net/gocryptfs (markdown
source).
Folders side-by-side
animation
gocryptfs is built on top the excellent go-fuse FUSE library. This
project was inspired by EncFS and strives to fix its security issues
while providing good performance (benchmarks).
For details on the security of gocryptfs see the Security design
document.
All tags from v0.4 onward are signed by the gocryptfs signing
key. Please check Signed Releases for
details.
Current Status
gocryptfs has reached version 1.0 on July 17, 2016. It has gone
through hours and hours of stress (fsstress, extractloop.bash) and
correctness testing (xfstests). It is now considered ready for general
consumption.
The old principle still applies: Important data should have a backup.
Also, keep a copy of your master key (printed at init) in a safe place.
This allows you to access the data even if the gocryptfs.conf config
file is damaged or you lose the password.
The security of gocryptfs has been audited in March 3, 2017. The
audit is available here
(defuse.ca).
Platforms
Linux is gocryptfs’ native platform.
Beta-quality macOS support is available, which means most things work
fine but you may hit an occasional problem. Check out ticket #15 for
the history of macOS support but please create a new ticket if you hit a
problem.
For Windows, an independent C++ reimplementation can be found here:
cppcryptfs
Standalone tools:
gocryptfs-inspect
is Python tool that can decrypt files & file names without using
FUSE.
Precompiled binaries that work on all x86_64 Linux systems are
available for download from the github releases page. The
fuse package from your distribution must be installed for
mounting to work.
gocryptfs is also available as a package in most distributions.
Examples:
gocryptfs comes with is own test suite that is constantly expanded as
features are added. Run it using ./test.bash. It takes
about 1 minute and requires FUSE as it mounts several test
filesystems.
The stress_tests directory contains stress tests that
run indefinitely.
In addition, I have ported xfstests to FUSE, the result
is the fuse-xfstests
project. gocryptfs passes the “generic” tests with one exception,
results: XFSTESTS.md
A lot of work has gone into this. The testing has found bugs in
gocryptfs as well as in the go-fuse library.
Compile
Install Go 1.13 or higher:
Debian/Ubuntu: apt install golang
Fedora: dnf install golang
Then, download the source code and compile:
$ git clone https://github.com/rfjakob/gocryptfs.git
$ cd gocryptfs
$ ./build-without-openssl.bash
This will compile a static binary that uses the Go stdlib crypto
backend.
If you want to use the OpenSSL crypto backend (faster on old CPUs
lacking AES-NI), you have to install a few dependencies:
Since version 0.7.2, gocryptfs is as fast as EncFS in the default
mode, and significantly faster than EncFS’ “paranoia” mode that provides
a security level comparable to gocryptfs.
On CPUs without AES-NI, gocryptfs uses OpenSSL through a thin wrapper
called stupidgcm. This provides a 4x speedup compared to
Go’s builtin AES-GCM implementation. See CPU-Benchmarks
for details, or run gocryptfs -speed to see the encryption
performance of your CPU. Example for a CPU with AES-NI:
$ ./gocryptfs -speed
gocryptfs v2.2.0-beta1-5-g52b0444-dirty; go-fuse v2.1.1-0.20210825171523-3ab5d95a30ae; 2021-09-14 go1.17.1 linux/amd64
cpu: Intel(R) Core(TM) i5-3470 CPU @ 3.20GHz; with AES acceleration
AES-GCM-256-OpenSSL 862.79 MB/s
AES-GCM-256-Go 997.71 MB/s (selected in auto mode)
AES-SIV-512-Go 159.58 MB/s
XChaCha20-Poly1305-OpenSSL 729.65 MB/s
XChaCha20-Poly1305-Go 843.97 MB/s (selected in auto mode)
You can run ./benchmark.bash to run gocryptfs’ canonical
set of benchmarks that include streaming write, extracting a linux
kernel tarball, recursively listing and finally deleting it. The output
will look like this:
Fix warnings
cipherSize X: incomplete last block (Y bytes), padding to Z bytes
(harmless but annoying, #951)
MacOS: Fix GUI apps reporting failure to save files #914
MacOS: Fix test-without-openssl.bash trying to build
tests with openssl enabled (2ebd0d754b8ee4)
v2.6.0, 2025-07-14
Upgrade to go-fuse v2.8.0
Switch to the new go-fuse directory API(
https://github.com/rfjakob/gocryptfs/commit/ae3c859c1179498a4882b4bd69c2243aa6912332
)
Fix -force_owner not allowing file/dir create (
https://github.com/rfjakob/gocryptfs/issues/783 )
Skip TestBtrfsQuirks if mkfs.btrfs is not installed (
https://github.com/rfjakob/gocryptfs/issues/930 )
v2.5.4, 2025-04-13
Drop GOAMD64=v2 from build.bash, there’s
user(s) still running GOAMD64=v1 CPUs (#908, commit)
v2.5.3, 2025-04-05
Fix go install failing with
g: malformed file path "tests/fsck/malleable_base64/27AG8t-XZH7G9ou2OSD_z\ng": invalid char '\n'
(c80558)
Fix panic when go-fuse is newer than specified in go.mod (#897)
v2.5.2, 2025-03-19
Use our own syscallcompat.Setreuid (and friends)
wrappers (6b1ba584)
Upgrade golang.org/x/sys again
Provide arm64 binaries in releases in addition to amd64
v2.5.1, 2025-01-23
Downgrade golang.org/x/sys to unbreak
unix.Setreuid and -allow_other (6d342f3,
#893, #892)
v2.5.0, 2025-01-18
Important fixes for -reverse mode affecting the
virtual gocryptfs.diriv and
gocryptfs.longname.*.name files. The bug can cause
file names to become undecryptable. To make sure that sync
tools like rsync copy new, good copies, gocryptfs v2.5.0 and later
advance ctime and mtime for these files by 10 seconds.
Fix -reverse mode sometimes (triggered by inode number
reuse) returning stale data for gocryptfs.diriv (#802)
Fix -reverse mode hardlinking
gocryptfs.longname.*.name files of hardlinked files
together (#802)
Fix -reverse mode ignoring -force-owner
(#809)
Add workaround for excessive file fragementation on btrfs
(#811)
MacOS: merge kernel options before passing them on (#854, #557)
Add -fido2-assert-option (#807)
-init now accepts -masterkey
-passwd now ignores -extpass and
-passfile for the new password (#287, #882)
v2.4.0, 2023-06-10
Try the mount(2) syscall before falling back to
fusermount(1). This means we don’t need
fusermount(1) at all if running as root or in a root-like
namespace (#697)
Identical to v2.3, just tagged once more in full semver x.y.z
format. This make Go’s fetching logic happy, which ignores v2.3 (without
the third digit) completely. Fixes #694, #688.
v2.3, 2022-08-28
Add -longnamemax flag to
-init (#499). Can be
used to work around file or path length restrictions on online storage.
See the man
page for details.
Fix -force_owner not not affecting socket files (#629
MacOS: fix inaccessible gocryptfs.conf in reverse mode
(commit)
Raise ctlsock operation timeout from 1 to 10 seconds (#683)
v2.2.1, 2021-10-20
Fix -force_owner only taking effect after 2 seconds (#609). This
was a regression introduced in v2.0.
MacOS: Fix build.bash failure with error
date: illegal option -- - when
SOURCE_DATE_EPOCH is set (#570)
-init: suggest xchacha on CPUs without AES acceleration
(commit)
-info: add contentEncryption to output
v2.2.0, 2021-09-25
-deterministic-names: new option for
-init, both for reverse and forward mode. Disables
file name randomisation & gocryptfs.diriv files (#151, #402, #592)
New feature flag! You need gocryptfs v2.2 or higher to mount a
filesystem that uses this flag.
-xchacha: new option for
-init (forward mode only). Selects
XChaCha20-Poly1305 for content encryption. Gives much better
performance on CPUs without AES acceleration (#452).
New feature flag! You need gocryptfs v2.2 or higher to mount a
filesystem that uses this flag.
Test with gocryptfs -speed what is fastest for your
CPU, or read here
Rewrite OpenSSL
backend for better performance on AES-GCM-256-OpenSSL and
XChaCha20-Poly1305-OpenSSL
-serialize_reads: get rid of delay logic by taking
advantage of the kernel flag FUSE_CAP_ASYNC_READ (go-fuse
commit, gocryptfs
commit)
Fix reverse mode sometimes remapping most inode numbers to
>281474976710656 (commit)
This version will be called v2.2.0 (instead of v2.2) to comply with
the Go module
versioning convention. Later releases will also follow the
convention.
v2.1, 2021-08-18
-fido2: do not request PIN on
gocryptfs -init fixing
FIDO_ERR_UNSUPPORTED_OPTION with YubiKey (#571)
go-fuse: track most recent parent. This improves robustness
when the filesystem is modified behind the back of gocryptfs. Helps both
with -sharedstorage and also without. (commit
1, commit
2, #549)
Add directory fd caching for 2x - 3x speed boost in small file ops
compared to v2.0-beta2 (performance
numbers)
Warning 2021-02-07: This feature is incomplete! Do
not use ACLs before gocryptfs v2.0 final! Reading and writing ACLs
works, but they are not enforced or inherited (#542)
Has been disabled since v1.7 due to issues a third-party
module.
Please use FIDO2 instead (gocryptfs v2.0)
v1.7.1, 2019-10-06
Support wild cards in reverse mode via
--exclude-wildcard (#367). Thanks
@ekalin!
Create gocryptfs.diriv files with 0440 permissions to
make it easier to share an encrypted folder via a network drive (#387). Note:
as a security precaution, the owner must still manually
chmod gocryptfs.conf 0440 to allow mounting.
Allow the nofail option in /etc/fstab
-passwd can now change the -scryptn
parameter for existing filesystems (#400)
Fix -idle unmounting the filesystem despite recent
activity (#421)
Fix a race condition related to inode number reuse (#363).
It could be triggered by concurrently creating and deleting files and
can lead to data loss in the affected file. This bug was found by the
automated tests on Travis and was very hard to trigger locally.
tests: use /var/tmp instead of /tmp by default (commit
8c4429)
v1.7, 2019-03-17
Fix possible symlink race attacks in forward mode
when using allow_other + plaintextnames
If you use both-allow_otherand-plaintextnames, you should upgrade. Malicious users could
trick gocryptfs into modifying files outside of CIPHERDIR,
or reading files inside CIPHERDIR that they should not have
access to.
If you do not use -plaintextnames (disabled per
default), these attacks do not work as symlinks are encrypted.
Forward mode has been reworked to use the “*at” family of system
calls everywhere (Openat/Unlinkat/Symlinkat/...).
As a result, gocryptfs may run slightly slower, as the caching logic
has been replaced and is very simple at the moment.
The possibility for such attacks was found during an internal code
review.
Reverse mode: fix excluded, unaccessible files showing up in
directory listings (#285, #286)
gocryptfs-xray: add -aessiv flag for correctly parsing
AES-SIV format files (#299)
Ensure that standard fds 0,1,2 are always initialized (#320).
Prevents trouble in the unlikely case that gocryptfs is called with
stdin,stdout and/or stderr closed.
-extpass now can be specified multiple times to support
arguments containing spaces (#289)
Drop Fstatat, Mkdirat, Syslinkat, Fchownat, Unlinkat, Renameat,
Openat emulation of MacOS and instead use native functions (thanks @slackner !)
Use Setreuid to robustly set the owner with allow_other
(@slackner, (commit))
Pack the rendered man page into the source code archive for user
convenience (issue
355)
Disable Trezor support again (commit
16fac26c57ba303bf60266d24c17f5243e5ea376)
Trezor support has been broken since Sept 2018 due to issues in a
third-party module (#261)
v1.6.1, 2018-12-12
Fix “Operation not supported” chmod errors on Go 1.11 (#271)
v1.6, 2018-08-18
Add -e / -exclude option
for reverse mode (#235, commit)
Add support for the Trezor One HSM PR#247, thanks
@xaionaro!
Use ./build.bash -tags enable_trezor to compile with
Trezor support
Then, use gocryptfs -init -trezor to create a
filesystem locked with a physical Trezor device.
Note 2021-01-31: Support was removed again in gocryptfs v1.7. Please
use -fido2 in gocryptfs v2.0.
From gocryptfs v1.4, I will only release statically-built binaries.
These support all Linux distributions but cannot use OpenSSL.
OpenSSL is still supported - just compile from source!
Add -force_owner option to allow files to be presented
as owned by a different user or group from the user running gocryptfs.
Please see caveats and guidance in the man page before using this
functionality.
Implement path decryption via ctlsock (#84).
Previously, decryption was only implemented for reverse mode. Now both
normal and reverse mode support both decryption and encryption of paths
via ctlsock.
Add more specific exit codes for the most common failure modes,
documented in CLI_ABI.md
Reverse mode: make sure hard-linked files always return the same
ciphertext (commit
9ecf2d1a)
Display a shorter, friendlier help text by default.
Parallelize file content encryption by splitting
data blocks into two threads (ticket#116)
Prefetch random nonces in the background (commit
80516ed)
Add -info option to pretty-print infos about a
filesystem.
v1.3, 2017-04-29
Use HKDF to derive separate keys for GCM and EME
New feature flag: HKDF (enabled by default)
This is a forwards-compatible change. gocryptfs v1.3 can mount
filesystems created by earlier versions but not the other way
round.
Enable Raw64 filename encoding by default (gets rid of
trailing == characters)
This is a forwards-compatible change. gocryptfs v1.3 can mount
filesystems created by earlier versions but not the other way
round.
Drop Go 1.4 compatibility. You now need Go 1.5 (released 2015-08-19)
or higher to build gocryptfs.
Add -serialize_reads command-line option
This can greatly improve performance on storage that is very slow
for concurrent out-of-order reads. Example: Amazon Cloud Drive (#92)
Handle additional corner cases in -ctlsock path
sanitization
Use dedicated exit code 12 on “password incorrect”
v1.2, 2016-12-04
Add a control socket interface. Allows to encrypt and decrypt
filenames. For details see backintime#644.
New command-line option: -ctlsock
Under certain circumstances, concurrent truncate and read could
return an I/O error. This is fixed by introducing a global open file
table that stores the file IDs (commit).
Coalesce 4kB ciphertext block writes up to the size requested
through the write FUSE call (commit
with benchmarks)
Add -noprealloc command-line option
Greatly speeds up writes on Btrfs (#63) at the
cost of reduced out-of-space robustness.
This is a workaround for Btrfs’ slow fallocate(2)
Preserve owner for symlinks an device files (fixes bug #64)
Include rendered man page gocryptfs.1 in the release
tarball
v1.1.1, 2016-10-30
Fix a panic on setting file timestamps (go-fuse#131)
Work around an issue in tmpfs that caused a panic in xfstests
generic/075 (gocryptfs#56)
AES-SIV (RFC5297) encryption to implement deterministic encryption
securely. Uses the excellent jacobsa/crypto
library. The corresponding feature flag is called
AESSIV.
New command-line options: -reverse,
-aessiv
Filesystems using reverse mode can only be mounted with gocryptfs
v1.1 and later.
The default, forward mode, stays fully compatible with older
versions. Forward mode will keep using GCM because it is much
faster.
Accept -o foo,bar,baz-style options that are passed at
the end of the command-line, like mount(1) does. All other options must
still precede the passed paths.
This allows mounting from /etc/fstab. See #45 for
details.
To prevent confusion, the old -o option had to be
renamed. It is now called -ko. Arguments to
-ko are passed directly to the kernel.
New -passfile command-line option. Provides an easier
way to read the password from a file. Internally, this is equivalent to
-extpass "/bin/cat FILE".
Enable changing the password when you only know the master key (#28)
v1.0, 2016-07-17
Deprecate very old filesystems, stage 3/3
Filesystems created by v0.6 can no longer be mounted
Drop command-line options -gcmiv128,
-emenames, -diriv. These are now always
enabled.
Add fallocate(2) support
New command-line option -o
Allows to pass mount options directly to the kernel
Add support for device files and suid binaries
Only works when running as root
Must be explicitly enabled by passing “-o dev” or “-o suid” or “-o
suid,dev”
Experimental Mac OS X support. See ticket #15 for
details.
v0.12, 2016-06-19
Deprecate very old filesystems, stage 2/3
Filesystems created by v0.6 and older can only be mounted
read-only
A message
explaining the situation is printed as well
gocryptfs now has its own thin wrapper to OpenSSL’s GCM
implementation called stupidgcm.
This should fix the compile issues
people are seeing with spacemonkeygo/openssl. It also gets
us a 20% performance boost for streaming writes.
Automatically choose between OpenSSL and Go cryptoissue #23
Go 1.6 added an optimized GCM implementation in amd64 assembly that
uses AES-NI. This is faster than OpenSSL and is used if available. In
all other cases OpenSSL is much faster and is used instead.
-openssl=auto is the new default
Passing -openssl=true/false overrides the
autodetection.
Warn but continue anyway if fallocate(2) is not supported by the
underlying filesystem, see issue #22
Enables to use gocryptfs on ZFS and ext3, albeit with reduced
out-of-space safety.
gocryptfs now supports file names up to 255 characters.
This is a forwards-compatible change. gocryptfs v0.9 can mount
filesystems created by earlier versions but not the other way
round.
Refactor gocryptfs into multiple “internal” packages
New command-line options:
-longnames: Enable long file name support (default
true)
-nosyslog: Print messages to stdout and stderr instead
of syslog (default false)
-wpanic: Make warning messages fatal (used for
testing)
-d: Alias for -debug
-q: Alias for -quiet
v0.8, 2016-01-23
Redirect output to syslog when running in the background
New command-line option:
-memprofile: Write a memory allocation debugging
profile the specified file
v0.7.2, 2016-01-19
Fix performance issue in small file creation
This brings performance on-par with EncFS paranoia mode, with
streaming writes significantly faster
The actual fix
is in the go-fuse library. There are no code changes in gocryptfs.
v0.7.1, 2016-01-09
Make the build.bash script compatible with Go 1.3
Disable fallocate on OSX (system call not available)
Introduce pre-built binaries for Fedora 23 and Debian 8
v0.7, 2015-12-20
Extend GCM IV size to 128 bit from Go’s default of 96
bit
This pushes back the birthday bound to make IV collisions virtually
impossible
This is a forwards-compatible change. gocryptfs v0.7 can mount
filesystems created by earlier versions but not the other way
round.
New command-line option:
-gcmiv128: Use 128-bit GCM IVs (default true)
v0.6, 2015-12-08
Wide-block filename encryption using EME + DirIV
EME (ECB-Mix-ECB) provides even better security than CBC as it fixes
the prefix leak. The used Go EME implementation is
https://github.com/rfjakob/eme which is, as far as I know, the first
implementation of EME in Go.
This is a forwards-compatible change. gocryptfs v0.6 can mount
filesystems created by earlier versions but not the other way
round.
Fix a rename regression caused by DirIV and add test case
Use fallocate to guard against out-of-space errors
v0.5, 2015-12-04
Stronger filename encryption: DirIV
Each directory gets a random 128 bit file name IV on creation,
stored in gocryptfs.diriv
This makes it impossible to identify identically-named files across
directories
A single-entry IV cache brings the performance cost of DirIV close
to zero for common operations (see performance.txt)
This is a forwards-compatible change. gocryptfs v0.5 can mount
filesystems created by earlier versions but not the other way
round.
New command-line option:
-diriv: Use the new per-directory IV file name
encryption (default true)
-scryptn: allows to set the scrypt cost parameter N.
This option can be used for faster mounting at the cost of lower
brute-force resistance. It was mainly added to speed up the automated
tests.
v0.4, 2015-11-15
New command-line options:
-plaintextnames: disables filename encryption, added on
user request
-extpass: calls an external program for prompting for
the password
-config: allows to specify a custom gocryptfs.conf
path
Add FeatureFlags gocryptfs.conf parameter
This is a config format change, hence the on-disk format is
incremented
Used for ext4-style filesystem feature flags. This should help avoid
future format changes. The first user is
-plaintextnames.
On-disk format 2
v0.3, 2015-11-01
Add a random 128 bit file header to authenticate
file->block ownership
This is an on-disk-format change
On-disk format 1
v0.2, 2015-10-11
Replace bash daemonization wrapper with native Go
implementation
