1# securefs 2 3`securefs` is a filesystem in userspace (FUSE) with transparent encryption (when writing) and decryption (when reading). 4 5`securefs` mounts a regular directory onto a mount point. The mount point appears as a regular filesystem, where one can read/write/create files, directories and symbolic links. The underlying directory will be automatically updated to contain the encrypted and authenticated contents. 6 7## Motivation 8 9From sensitive financial records to personal diaries and collection of guilty pleasures, we all have something to keep private from prying eyes. Especially when we store our files in the cloud, the company and the NSA may well get their hands upon it. The best protection we can afford ourselves is **cryptography**, the discipline developed by mathematicians and military originally to keep the national secrets. 10 11Security, however, is often at odds with convenience, and people easily grow tired of the hassle and revert to no protection at all. Consider the case of protecting our files either locally or in the cloud: we have to encrypt the files before committing to the cloud and decrypt it every time we need to read and write. Worse still, such actions leave unencrypted traces on our hard drive. If we store data in the cloud, another issue arise: manual encryption and decryption prevent files from being synced efficiently. 12 13`securefs` is intended to make the experience as smooth as possible so that the security and convenience do not conflict. After mounting the virtual filesystem, everything just works™. 14 15## Comparison 16 17There are already many encrypting filesystem in widespread use. Some notable ones are TrueCrypt, FileVault, BitLocker, eCryptFS, encfs and gocryptfs. `securefs` differs from them in that it is the only one with all of the following features: 18 19* [Authenticated encryption](https://en.wikipedia.org/wiki/Authenticated_encryption) (hence secure against chosen ciphertext attacks) 20* [Probabilistic encryption](https://en.wikipedia.org/wiki/Probabilistic_encryption) (hence provides semantical security) 21* Supported on all major platforms (Mac, Linux, BSDs and Windows) 22* Efficient cloud synchronization (not a single preallocated file as container) 23 24## Install 25 26[![Actions Status](https://github.com/netheril96/securefs/workflows/C%2FC%2B%2B%20CI/badge.svg)](https://github.com/netheril96/securefs/actions) 27 28 29### macOS 30 31Install with [Homebrew](https://brew.sh). [macFUSE](https://osxfuse.github.io) has to be installed beforehand. 32``` 33brew install securefs 34``` 35 36### Windows 37 38Windows users can download prebuilt package from the releases section. It depends on [WinFsp](https://github.com/billziss-gh/winfsp/releases) and [VC++ 2017 redistribution package](https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads). 39 40### Linux 41 42Linux users have to build it from source. 43 44First `fuse` must be installed. 45 46* On Debian based Linux distro, `sudo apt-get install fuse libfuse-dev build-essential cmake`. 47* On RPM based Linux, `sudo yum install fuse fuse-devel`. 48 49Then clone the sources by `git clone --recursive`, and execute `linux-build.sh`. 50 51### FreeBSD (unofficial) 52 53Install using packages (recommended): 54```bash 55pkg install fusefs-securefs 56``` 57 58or ports: 59```bash 60make -C /usr/ports/sysutils/fusefs-securefs install 61``` 62 63Make sure you load the fuse kernel module before using securefs: 64```bash 65kldload fuse 66sysrc -f /boot/loader.conf fuse_load="YES" # Load fuse automatically at boot 67``` 68 69## Basic usage 70 71*It is recommended to disable or encrypt the swap and hibernation file. Otherwise plaintext and keys stored in the main memory may be written to disk by the OS at any time.* 72 73Examples: 74 75```bash 76securefs --help 77securefs create ~/Secret 78securefs chpass ~/Secret 79securefs mount ~/Secret ~/Mount # press Ctrl-C to unmount 80securefs m -h # m is an alias for mount, -h tell you all the flags 81``` 82 83## Lite and full mode 84 85There are two categories of filesystem format. 86 87The **lite** format simply encrypts filenames and file contents separately, similar to how `encfs` operates, although with more security. 88 89The **full** format maps files, directory and symlinks in the virtual filesystem all to regular files in the underlying filesystem. The directory structure is flattened and recorded as B-trees in files. 90 91The lite format has become the default on Unix-like operating systems as it is much faster and features easier conflict resolution, especially when used with DropBox, Google Drive, etc. The full format, however, leaks fewer information about the filesystem hierarchy, runs relatively independent of the features of the underlying filesystem, and is in general more secure. 92 93To request full format, which is no longer the default, run `securefs create --format 2`. 94 95## Design and algorithms 96 97See [here](docs/design.md). 98 99## Caveat 100 101If you store `securefs` encrypted files on iCloud Drive, it might cause Spotlight Search on iOS to stop working. It is a bug in iOS, not in `securefs`. 102 103To work around that bug, you can disable the indexing of *Files* app in Settings -> Siri & Suggestions. 104