Jump to content

# gocryptfs

From ArchWiki

Related articles

- Data-at-rest encryption
- Encfs

From gocryptfs:

  gocryptfs uses file-based encryption that is implemented as a mountable FUSE filesystem. Each file in gocryptfs is stored one corresponding encrypted file on the hard disk.
  The highlights are: Scrypt password hashing, GCM encryption for all file contents, EME wide-block encryption for file names with a per-directory IV.

See the gocryptfs project home for further introduction of its features, benchmarks, etc. See Data-at-rest encryption#Comparison table for an overview of alternative methods and EncFS for the direct alternative.

Note

- To achieve its design goal of authenticated encryption, gocryptfs implements a AES-EME encryption mode (for filenames, the content is encrypted using standard libraries). While the EME mode is not widely used/audited yet, gocryptfs encryption modes bring integrity protection for the data.
- See the project's tracking bug report regarding findings of the first security audit for more information.

## Installation

Install gocryptfs or gocryptfs-gitAUR.

As a FUSE filesystem, gocryptfs is fully configurable by the user and stores its configuration files in the user's directory paths.

## Usage

See gocryptfs(1) and its examples first. As a first-time user, check the gocryptfs best practices next.

Upon initialization of the cryptography for a directory, the master key is output before it is cryptographically wrapped in the `gocryptfs.conf` file. It can be used to recreate the configuration with a restore procedure. If it happens that the master key itself is lost but the configuration file available, see gocryptfs-xray(1) for how to output it again with the encryption password.

Tip

- Execute `gocryptfs -speed` to test throughput for available encryption modes. The automatic selection will choose the fastest mode available for the system.
- A `-fido2` option allows the convenience of U2F hardware tokens to initialize and mount the encrypted data.

### Example using normal mode

Create `cipher` directory to store encrypted data, and `plain` directory to access them decrypted. Then, run gocryptfs initialization to setup encryption.

    $ mkdir cipher plain
    $ gocryptfs -init cipher
    Choose a password for protecting your files.
    Password:
    Repeat:

    Your master key is:
    [...]

To open the encrypted directory `cipher` and access it from `plain`:

    $ gocryptfs cipher plain
    Password:
    Decrypting master key
    Filesystem mounted and ready

You now have a working gocryptfs that is stored in `cipher` and mounted to `plain`. You can verify this by creating a blank file in the `plain` directory. This file will show up encrypted in the `cipher` directory.

    $ touch plain/test.txt
    $ ls cipher
      gocryptfs.conf  gocryptfs.diriv  ZSuIZVzYDy5-TbhWKY-ciA==

When done unmount the plain directory, optionally delete the empty folder:

    $ fusermount3 -u plain
    $ rmdir plain

To show filesystem information use the `-info` option, consistency can be checked with `-fsck`.

### Example using reverse mode

A major application for file-based encryption methods are encrypted backups. FUSE-based filesystems are flexible for this, since they allow a wide array of backup destinations using standard tools. For example, a gocryptfs-encrypted FUSE mount point can be easily created directly on a Samba/NFS share or Dropbox location, synchronized to a remote host with rsync, or just be manually copied to a remote backup storage.

Warning By default the `gocryptfs.conf` file is stored within the backup directory for convenience. If you upload the `gocryptfs.conf` file to an online source, your backup can be decrypted if your password is known or cracked. Using a strong password will lower the chances of a successful attack. [1] You can choose to use a `gocryptfs.conf` file from another location by providing the `-config` option along with the path to your configuration file.

The reverse mode of gocryptfs is particularly useful for creating encrypted backups, since it requires virtually no extra storage capacity on the machine to back up.

The following shows an example of user archie creating a backup of `/home/archie`:

First, archie initializes the configuration for the home directory:

    $ gocryptfs -init -reverse /home/archie

    Choose a password for protecting your files.
    Password:
    ...

Second, an empty directory for the encrypted view of the home directory is created and mounted:

    $ mkdir /tmp/crypt
    $ gocryptfs -reverse /home/archie /tmp/crypt
    Password:
    Decrypting master key

    Your master key is:
    ...
    Filesystem mounted and ready.
    $

Tip

- To account for above warning, a `-config /home/archie/gocryptfs.conf` during initialization could be used, thereby reverse-encrypting the configuration file as well.
- A number of options to exclude files or directories from the reverse mount are available; see gocryptfs(1) § EXCLUDING_FILES. Note that with software like rsync errors or warnings may occur if exclusions are done later only.[2]

Third, archie creates a backup of the encrypted directory, a simple local copy for this example:

    $ cp -a /tmp/crypt /tmp/backup

and done.

The encrypted directory can stay mounted for the user session, or be unmounted manually:

    $ fusermount -u /tmp/crypt
    $ rmdir /tmp/crypt

To restore from the encrypted backup, a plain-text view is mounted using gocryptfs's normal mode:

    $ mkdir /tmp/restore
    $ gocryptfs /tmp/backup/ /tmp/restore
    Password:
    Decrypting master key
    ...
    Filesystem mounted and ready.
    $

Now the required files can be restored.

### Example using the FIDO2 option

Options to use U2F hardware tokens, instead of a password, to initialize and mount an encrypted directory are available. It is possible to enforce or toggle FIDO2 token options for PIN/user-presence (touch)/user-verification (fingerprint) verification for the decryption (see fido2-assert(1)).

The following initializes, mounts and unmounts an encrypted directory with a token and PIN-verification:

    $ gocryptfs -init -fido2 /dev/hidraw0 -fido2-assert-option pin=true crypt
    FIDO2 Register: interact with your device ...
    Enter PIN for /dev/hidraw0:
    FIDO2 Secret: interact with your device ...
    Enter PIN for /dev/hidraw0:
    Your master key is:
        ea6d7d00-...
    $ gocryptfs -fido2 /dev/hidraw0 crypt plain
    FIDO2 Secret: interact with your device ...
    Enter PIN for /dev/hidraw0:
    Decrypting master key
    Filesystem mounted and ready.
    $ fusermount -u plain

The user-presence interaction (`interact with your device ...`) was used, because the token defaults to it. Using a `-fido2-assert-option up=false` option would toggle it during initialization.

Note Since the feature does not create a FIDO2 residential key on the token, the generated master key can be used to decrypt and mount the directory without it.

    $ gocryptfs -masterkey=ea6d7d00-e2187a69-fab9c952-223e7821-16fb0ac2-ae4ffa1e-5469f9f1-2a7b051c crypt plain
    Using explicit master key.
    THE MASTER KEY IS VISIBLE VIA "ps ax" AND MAY BE STORED IN YOUR SHELL HISTORY!
    ONLY USE THIS MODE FOR EMERGENCIES
    Filesystem mounted and ready.

## Mounting automatically with pam_mount

If your encrypted directory uses the same password as your user account, you can automount it on login with pam_mount.

While gocryptfs command works with fuse3 when directly invoked, pam_mount it tries to use `mount.fuse` from fuse2.

You need to add pam_mount to `/etc/pam.d/system-login` as specified in pam_mount#Login manager configuration, then you must configure the specific directories to mount in a `/etc/security/pam_mount.conf.xml` configuration. An example is given below:

    /etc/security/pam_mount.conf.xml

    <!-- Example using gocryptfs -->
      <volume
          fstype="fuse"
          mountpoint="/home/YOURUSER/plain"
          path="/usr/bin/gocryptfs#/home/YOURUSER/cipher"
          options="nodev,nosuid"
          user="YOURUSER"
      />

## GUI wrappers

There are a couple of applications available that provide a graphical user interface for gocryptfs.

### SiriKali

A Qt/C++ GUI application that manages gocryptfs, eCryptfs, cryfs, EncFS, fscrypt, and securefs encrypted folders. It can also connect to SSH servers using SSHFS. Install it from sirikaliAUR.

### gocryptfs-ui

A bash script gocryptfs-ui provides a simple zenity GUI around the gocryptfs command line utility to mount and unmount an encrypted directory. It includes a desktop launcher. Install it from gocryptfs-uiAUR.

### cryptor

cryptor is a vala/gtk3 based application providing a GUI to create and mount encrypted directories. It can store configuration files with a list of encrypted directories, has tray-icon support and includes a desktop launcher. Install it from cryptorAUR.

## See also

- A first security audit of gocryptfs
- RFC 5297 Synthetic Initialization Vector (SIV) Authenticated Encryption Using the Advanced Encryption Standard (AES)

Categories:

- Data-at-rest encryption
- FUSE

gocryptfs
Add topic