1GOCRYPTFS(1) GOCRYPTFS(1)
2
6 gocryptfs - create or mount an encrypted filesystem
7
9 Initialize encrypted filesystem
10 gocryptfs -init [OPTIONS] CIPHERDIR
11 Mount
13 gocryptfs [OPTIONS] CIPHERDIR MOUNTPOINT [-o COMMA-SEPARATED-OPTIONS]
14 Change password
16 gocryptfs -passwd [OPTIONS] CIPHERDIR
17 Check consistency
19 gocryptfs -fsck [OPTIONS] CIPHERDIR
20
22 gocryptfs is an encrypted overlay filesystem written in Go. Encrypted
23 files are stored in CIPHERDIR, and a plain-text view can be presented
24 by mounting the filesystem at MOUNTPOINT.
25 gocryptfs was inspired by encfs(1) and strives to fix its security is‐
27 sues while providing good performance.
28
30 Available options are listed below.
31 -aessiv
33 Use the AES-SIV encryption mode. This is slower than GCM but is secure
34 with deterministic nonces as used in “-reverse” mode.
35 -allow_other
37 By default, the Linux kernel prevents any other user (even root) to ac‐
38 cess a mounted FUSE filesystem. Settings this option allows access for
39 other users, subject to file permission checking. Only works if us‐
40 er_allow_other is set in /etc/fuse.conf. This option is equivalent to
41 “allow_other” plus “default_permissions” described in fuse(8).
42 -config string
44 Use specified config file instead of CIPHERDIR/gocryptfs.conf.
45 -cpuprofile string
47 Write cpu profile to specified file.
48 -ctlsock string
50 Create a control socket at the specified location. The socket can be
51 used to decrypt and encrypt paths inside the filesystem. When using
52 this option, make sure that the directory you place the socket in is
53 not world-accessible. For example, /run/user/UID/my.socket would be
54 suitable.
55 -d, -debug
57 Enable debug output.
58 -dev, -nodev
60 Enable (-dev) or disable (-nodev) device files in a gocryptfs mount
61 (default: -nodev). If both are specified, -nodev takes precedence.
62 You need root permissions to use -dev.
63 -devrandom
65 Use /dev/random for generating the master key instead of the default Go
66 implementation. This is especially useful on embedded systems with Go
67 versions prior to 1.9, which fall back to weak random data when the ge‐
68 trandom syscall is blocking. Using this option can block indefinitely
69 when the kernel cannot harvest enough entropy.
70 -e PATH, -exclude PATH
72 Only for reverse mode: exclude relative plaintext path from the en‐
73 crypted view. Can be passed multiple times. Example:
74 gocryptfs -reverse -exclude Music -exclude Movies /home/user /mnt/user.encrypted
76 -exec, -noexec
78 Enable (-exec) or disable (-noexec) executables in a gocryptfs mount
79 (default: -exec). If both are specified, -noexec takes precedence.
80 -extpass string
82 Use an external program (like ssh-askpass) for the password prompt.
83 The program should return the password on stdout, a trailing newline is
84 stripped by gocryptfs. If you just want to read from a password file,
85 see -passfile.
86 When -extpass is specified once, the string argument will be split on
88 spaces. For example, -extpass "md5sum my password.txt" will be execut‐
89 ed as "md5sum" "my" "password.txt", which is NOT what you want.
90 Specify -extpass twice or more to use the string arguments as-is. For
92 example, you DO want to call md5sum like this:
93 -extpass "md5sum" -extpass "my password.txt".
94 If you want to prevent splitting on spaces but don't want to pass argu‐
96 ments to your program, use "--", which is accepted by most programs:
97 -extpass "my program" -extpass "--"
98 -fg, -f
100 Stay in the foreground instead of forking away. Implies “-nosyslog”.
101 For compatibility, “-f” is also accepted, but “-fg” is preferred.
102 -force_owner string
104 If given a string of the form “uid:gid” (where both “uid” and “gid” are
105 substituted with positive integers), presents all files as owned by the
106 given uid and gid, regardless of their actual ownership. Implies “al‐
107 low_other”.
108 This is rarely desired behavior: One should usually run gocryptfs as
110 the account which owns the backing-store files, which should usually be
111 one and the same with the account intended to access the decrypted con‐
112 tent. An example of a case where this may be useful is a situation
113 where content is stored on a filesystem that doesn't properly support
114 UNIX ownership and permissions.
115 -forcedecode
117 Force decode of encrypted files even if the integrity check fails, in‐
118 stead of failing with an IO error. Warning messages are still printed
119 to syslog if corrupted files are encountered. It can be useful to re‐
120 cover files from disks with bad sectors or other corrupted media. It
121 shall not be used if the origin of corruption is unknown, specially if
122 you want to run executable files.
123 For corrupted media, note that you probably want to use dd_rescue(1)
125 instead, which will recover all but the corrupted 4kB block.
126 This option makes no sense in reverse mode. It requires gocryptfs to
128 be compiled with openssl support and implies -openssl true. Because of
129 this, it is not compatible with -aessiv, that uses built-in Go crypto.
130 Setting this option forces the filesystem to read-only and noexec.
132 -fsck
134 Check CIPHERDIR for consistency. If corruption is found, the exit code
135 is 26.
136 -fsname string
138 Override the filesystem name (first column in df -T). Can also be
139 passed as “-o fsname=” and is equivalent to libfuse's option of the
140 same name. By default, CIPHERDIR is used.
141 -fusedebug
143 Enable fuse library debug output.
144 -h, -help
146 Print a short help text that shows the more-often used options.
147 -hh
149 Long help text, shows all available options.
150 -hkdf
152 Use HKDF to derive separate keys for content and name encryption from
153 the master key.
154 -i duration, -idle duration
156 Only for forward mode: automatically unmount the filesystem if it has
157 been idle for the specified duration. Durations can be specified like
158 “500s” or “2h45m”. 0 (the default) means stay mounted indefinitely.
159 -info
161 Pretty-print the contents of the config file for human consumption,
162 stripping out sensitive data.
163 -init
165 Initialize encrypted directory.
166 -ko
168 Pass additional mount options to the kernel (comma-separated list).
169 FUSE filesystems are mounted with “nodev,nosuid” by default. If
170 gocryptfs runs as root, you can enable device files by passing the op‐
171 posite mount option, “dev”, and if you want to enable suid-binaries,
172 pass “suid”. “ro” (equivalent to passing the “-ro” option) and “noex‐
173 ec” may also be interesting. For a complete list see the section
174 FILESYSTEM-INDEPENDENT MOUNT OPTIONS in mount(8). On MacOS, “local”,
175 “noapplexattr”, “noappledouble” may be interesting.
176 Note that unlike “-o”, “-ko” is a regular option and must be passed BE‐
178 FORE the directories. Example:
179 gocryptfs -ko noexec /tmp/foo /tmp/bar
181 -longnames
183 Store names longer than 176 bytes in extra files (default true) This
184 flag is useful when recovering old gocryptfs filesystems using “-mas‐
185 terkey”. It is ignored (stays at the default) otherwise.
186 -masterkey string
188 Use a explicit master key specified on the command line or, if the spe‐
189 cial value “stdin” is used, read the masterkey from stdin. This option
190 can be used to mount a gocryptfs filesystem without a config file.
191 Note that the command line, and with it the master key, is visible to
192 anybody on the machine who can execute “ps -auxwww”. Use “-mas‐
193 terkey=stdin” to avoid that risk.
194 The masterkey option is meant as a recovery option for emergencies,
196 such as if you have forgotten the password or lost the config file.
197 Even if a config file exists, it will not be used. All non-standard
199 settings have to be passed on the command line: -aessiv when you mount
200 a filesystem that was created using reverse mode, or -plaintextnames
201 for a filesystem that was created with that option.
202 Examples:
204 -mas‐
205 terkey=6f717d8b-6b5f8e8a-fd0aa206-778ec093-62c5669b-abd229cd-241e00cd-b4d6713d
206 -masterkey=stdin
207 -memprofile string
209 Write memory profile to the specified file. This is useful when debug‐
210 ging memory usage of gocryptfs.
211 -nodev
213 See -dev, -nodev.
214 -noexec
216 See -exec, -noexec.
217 -nonempty
219 Allow mounting over non-empty directories. FUSE by default disallows
220 this to prevent accidental shadowing of files.
221 -noprealloc
223 Disable preallocation before writing. By default, gocryptfs preallo‐
224 cates the space the next write will take using fallocate(2) in mode
225 FALLOC_FL_KEEP_SIZE. The preallocation makes sure it cannot run out of
226 space in the middle of the write, which would cause the last 4kB block
227 to be corrupt and unreadable.
228 On ext4, preallocation is fast and does not cause a noticeable perfor‐
230 mance hit. Unfortunately, on Btrfs, preallocation is very slow, espe‐
231 cially on rotational HDDs. The “-noprealloc” option gives users the
232 choice to trade robustness against out-of-space errors for a massive
233 speedup.
234 For benchmarks and more details of the issue see https://github.com/rf‐
236 jakob/gocryptfs/issues/63 .
237 -nosyslog
239 Diagnostic messages are normally redirected to syslog once gocryptfs
240 daemonizes. This option disables the redirection and messages will
241 continue be printed to stdout and stderr.
242 -nosuid
244 See -suid, -nosuid.
245 -notifypid int
247 Send USR1 to the specified process after successful mount. This is
248 used internally for daemonization.
249 -o COMMA-SEPARATED-OPTIONS
251 For compatibility with mount(1), options are also accepted as “-o COM‐
252 MA-SEPARATED-OPTIONS” at the end of the command line. For example, “-o
253 q,zerokey” is equivalent to passing “-q -zerokey”.
254 Note that you can only use options that are understood by gocryptfs
256 with “-o”. If you want to pass special flags to the kernel, you should
257 use “-ko” (kernel option). This is different in libfuse-based filesys‐
258 tems, that automatically pass any “-o” options they do not understand
259 along to the kernel.
260 Example:
262 gocryptfs /tmp/foo /tmp/bar -o q,zerokey
264 -openssl bool/“auto”
266 Use OpenSSL instead of built-in Go crypto (default “auto”). Using
267 built-in crypto is 4x slower unless your CPU has AES instructions and
268 you are using Go 1.6+. In mode “auto”, gocrypts chooses the faster op‐
269 tion.
270 -passfile string
272 Read password from the specified file. A warning will be printed if
273 there is more than one line, and only the first line will be used. A
274 single trailing newline is allowed and does not cause a warning.
275 Before gocryptfs v1.7, using -passfile was equivant to writing
277 -extpass="/bin/cat -- FILE". gocryptfs v1.7 and later directly read
278 the file without invoking cat.
279 -passwd
281 Change the password. Will ask for the old password, check if it is
282 correct, and ask for a new one.
283 This can be used together with -masterkey if you forgot the password
285 but know the master key. Note that without the old password, gocryptfs
286 cannot tell if the master key is correct and will overwrite the old one
287 without mercy. It will, however, create a backup copy of the old con‐
288 fig file as gocryptfs.conf.bak. Delete it after you have verified that
289 you can access your files with the new password.
290 -plaintextnames
292 Do not encrypt file names and symlink targets.
293 -q, -quiet
295 Quiet - silence informational messages.
296 -raw64
298 Use unpadded base64 encoding for file names. This gets rid of the
299 trailing “\=\=”. A filesystem created with this option can only be
300 mounted using gocryptfs v1.2 and higher.
301 -reverse
303 Reverse mode shows a read-only encrypted view of a plaintext directory.
304 Implies “-aessiv”.
305 -rw, -ro
307 Mount the filesystem read-write (-rw, default) or read-only (-ro). If
308 both are specified, -ro takes precence.
309 -scryptn int
311 scrypt cost parameter expressed as scryptn=log2(N). Possible values
312 are 10 to 28, representing N=2^10 to N=2^28.
313 Setting this to a lower value speeds up mounting and reduces its memory
315 needs, but makes the password susceptible to brute-force attacks. The
316 default is 16.
317 -serialize_reads
319 The kernel usually submits multiple concurrent reads to service
320 userspace requests and kernel readahead. gocryptfs serves them concur‐
321 rently and in arbitrary order. On backing storage that performs poorly
322 for concurrent or out-of-order reads (like Amazon Cloud Drive), this
323 behavior can cause very slow read speeds.
324 The -serialize_reads option does two things: (1) reads will be submit‐
326 ted one-by-one (no concurrency) and (2) gocryptfs tries to order the
327 reads by file offset order.
328 The ordering requires gocryptfs to wait a certain time before submit‐
330 ting a read. The serialization introduces extra locking. These fac‐
331 tors will limit throughput to below 70MB/s.
332 For more details visit https://github.com/rfjakob/gocryptfs/issues/92 .
334 -sharedstorage
336 Enable work-arounds so gocryptfs works better when the backing storage
337 directory is concurrently accessed by multiple gocryptfs instances.
338 At the moment, it does two things:
340 1. Disable stat() caching so changes to the backing storage show up im‐
342 mediately.
343 2. Disable hard link tracking, as the inode numbers on the backing
345 storage are not stable when files are deleted and re-created behind
346 our back. This would otherwise produce strange “file does not ex‐
347 ist” and other errors.
348 When “-sharedstorage” is active, performance is reduced and hard links
350 cannot be created.
351 Even with this flag set, you may hit occasional problems. Running
353 gocryptfs on shared storage does not receive as much testing as the
354 usual (exclusive) use-case. Please test your workload in advance and
355 report any problems you may hit.
356 More info: https://github.com/rfjakob/gocryptfs/issues/156
358 -speed
360 Run crypto speed test. Benchmark Go's built-in GCM against OpenSSL (if
361 available). The library that will be selected on “-openssl=auto” (the
362 default) is marked as such.
363 -suid, -nosuid
365 Enable (-suid) or disable (-nosuid) suid and sgid executables in a
366 gocryptfs mount (default: -nosuid). If both are specified, -nosuid
367 takes precedence. You need root permissions to use -suid.
368 -trace string
370 Write execution trace to file. View the trace using “go tool trace
371 FILE”.
372 -trezor
374 With -init: Protect the masterkey using a SatoshiLabs Trezor instead of
375 a password.
376 This feature is disabled by default and must be enabled at compile time
378 using:
379 ./build.bash -tags enable_trezor
381 You can determine if your gocryptfs binary has Trezor support enabled
383 checking if the gocryptfs -version output contains the string en‐
384 able_trezor.
385 -version
387 Print version and exit. The output contains three fields separated by
388 “;”. Example: “gocryptfs v1.1.1-5-g75b776c; go-fuse 6b801d3;
389 2016-11-01 go1.7.3”. Field 1 is the gocryptfs version, field 2 is the
390 version of the go-fuse library, field 3 is the compile date and the Go
391 version that was used.
392 -wpanic
394 When encountering a warning, panic and exit immediately. This is use‐
395 ful in regression testing.
396 -zerokey
398 Use all-zero dummy master key. This options is only intended for auto‐
399 mated testing as it does not provide any security.
400 --
402 Stop option parsing. Helpful when CIPHERDIR may start with a dash “-”.
403
405 Create an encrypted filesystem in directory “g1” and mount it on “g2”:
406 mkdir g1 g2
408 gocryptfs -init g1
409 gocryptfs g1 g2
410 Mount an ecrypted view of joe's home directory using reverse mode:
412 mkdir /home/joe.crypt
414 gocryptfs -init -reverse /home/joe
415 gocryptfs -reverse /home/joe /home/joe.crypt
416
418 0: success
419 6: CIPHERDIR is not an empty directory (on “-init”)
420 10: MOUNTPOINT is not an empty directory
421 12: password incorrect
422 22: password is empty (on “-init”)
423 23: could not read gocryptfs.conf
424 24: could not write gocryptfs.conf (on “-init” or “-password”)
425 26: fsck found errors
426 other: please check the error message
427
429 mount(2) fuse(8) fallocate(2) encfs(1)
430
432 github.com/rfjakob.
433 Aug 2017 GOCRYPTFS(1)