<a href='./README.md'>EN</a> | <a href='./README_zh-CN.md'>中文</a>

cppcryptfs

cppcryptfs is based on the design of gocryptfs, an encrypted overlay filesystem written in Go.

cppcryptfs is an implementation of the gocryptfs filesystem in C++ for Windows. cppcryptfs is compatible with gocryptfs. Filesystems created with one can generally be mounted (and synced) with the other. Please see the statement on compatibility near the end of this document.

cppcrypts provides on-the-fly, at-rest and in-the-cloud encryption of files and file names in a virtual filesystem. It uses the Dokany driver and library to provide a virtual filesystem in user mode under Windows.

IMPORTANT: As per this discussion, you should only store the created gocryptfs.conf in the cloud if your password is strong. If an attacker obtains your gocryptfs.conf, then they will be able to throw whatever resources they have at a brute force attack on your encrypted password. Increasing scryptn will slow them down (see below) The developer keeps his gocryptfs.conf in the cloud and uses a very strong password.

You can use cppcryptfs to create an encrypted filesystem in a folder. The encrypted filesystem is protected with a password that you choose.

When you use cppcryptfs to mount the encrypted filesystem by providing the password, then you have a new drive letter in Windows. This virtual drive letter gives you an unencrypted view of your files. The encryption and decryption are done on the fly and are transparent to applications that use the files on that virtual drive.

After you tell cppcryptfs to dismount the virtual drive letter, then there is no way to get at your unencrypted data unless the filesystem is re-mounted again using your password.

Shutting down your computer automatically dismounts all cppcryptfs drive letters.

If the folder where the encrypted files are kept is being synced with a cloud service, then only the encrypted files with encrypted file names will be uploaded to the cloud service.

This way, neither the employees of the cloud service nor anybody who hacks into the cloud service can use your files.

Also, if someone steals your computer and the encrypted filesystem is not mounted, then the thief cannot use your files.

Because the encryption is done on a per-file basis instead of using a container file to store the data, you do not have to decide ahead of time how much encrypted storage you will need. cppcryptfs has very minimal storage overhead, and your encrypted filesystem can grow dynamically limited only by the amount of free space on the physical drive on which the encrypted filesystem is located.

Another advantage of per-file encryption over container-based encryption is that per-file encryption syncs very quickly and efficiently with cloud-based services.

Current Status

The developer has been using cppcryptfs in forward (normal) mode for over three years and hasn't lost any data. At least one other person is using it.

Reverse mode has undergone only limited testing by the developer.

Binary releases signed by the developer, Bailey Brown Jr, are on the releases page.

It is always prudent to keep backups of your data in case something goes wrong.

Testing

cppcryptfs passes 506/506 tests in winfstest when run as administrator. Without administrator privileges, cppcryptfs passes 500/506 tests. This winfstest is forked from the version used by the Dokany project. The Dokany team added additional tests.

The tests that cppcryptfs fails when run without administrator privileges have to do with operations on DACLs (Discretionary Access Control Lists). cppcryptfs must be run as administrator for these operations to work. Running without administrator privileges doesn't seem to affect the normal usage of cppcryptfs.

Note: It appears that Windows 10 Version 1909 (OS Build 18363.1016) allows cppcryptfs to pass all 506 tests without having to be run as administrator.

Build Requirements

Microsoft Visual Studio 2022 Community Edition, perl, nasm, and git (all free)
OpenSSL - https://github.com/openssl/openssl (static build required)
RapidJSON - https://github.com/miloyip/rapidjson (for parsing gocryptfs.conf)
Dokany - https://github.com/dokan-dev/dokany

For Dokany, you probably want to use the binary distribution from here:
	https://github.com/dokan-dev/dokany/releases
(be sure to select "install development files" in the installer options)

There are detailed build instructions in INSTALL.md.

cppcryptfs is currently up-to-date with Dokany 2.3.1.1000

Use

cppcryptfs doesn't require administrator privileges to run, but if it is not running as administrator, then it won't be able to acquire the SE_SECURITY_NAME privilege. SE_SECURITY_NAME is needed for some operations performed by the Windows API functions SetFileSecurity() and GetFileSecurity().

cppcryptfs seems to work without SE_SECURITY_NAME. If you do run into problems, then you can try running cppcryptfs as adminstrator and see if that helps.

On Windows, you should encrypt the pagefile to avoid leaking sensitive data on disk. Run the following command in CMD.exe as administrator: fsutil behavior set EncryptPagingFile 1 first.

To make a new encrypted virtual filesystem, first click the "Create" tab.

You need to find or create a directory to be the root of your filesystem. You can create a directory in the directory selector in the UI.

If you are using normal (forward) mode, then this directory must be empty.

If you are using reverse mode, then the directory need not be empty (see the section on Reverse Mode in this document which follows this section).

It is strongly recommended that this directory reside on an NTFS filesystem.

Then you need to choose a (hopefully strong) password and repeat it. The dialog box will accept at most 255 characters for the password.

The password field class treats one character as special. This character looks like a small x, but not the same. It's unicode 215 which is 0xd7 in hex.

The result is you cannot use that character in a password.

You can choose to have your file names encryped using AES256-EME or not to encrypt the file names (plain text).

If "Long file names" is checked, then the names of files and directories can be up to 255 characters long when encrypted file names are used. This option has no effect if plain text file names are used (plain text file names can be up to 255 characters long). See the section "File name and path length limits" near the end of this document for more information.

If a "Long name max" value that is less than 255 is selected (minimum value is 62), then cppcryptfs will limit filename length. Even when 62 is selected, file names created will be up to 67 characters long. This option is useful when using cloud services that have problems with filenames that are above a certain length.

If "Deterministic names" is checked, then cppcryptfs will not use DirIV files. The folowing explanation is lifted from the gocryptfs man page:

Disable file name randomisation and creation of gocryptfs.diriv files. This can prevent sync conflicts conflicts when synchronising files, but leaks information about identical file names across directories ("Identical names leak" in https://nuetzlich.net/gocryptfs/comparison/#file-names ).

The resulting gocryptfs.conf has "DirIV" missing from "FeatureFlags".

You can choose between AES256-GCM or AES256-SIV (RFC 5297) for file data encryption. The default is AES256-GCM which is recommended. GCM is about twice as fast as SIV for streaming reads and writes. SIV was implemented in order to support reverse mode.

Note: In the gocryptfs documentation, the SIV mode is referred to as AES-512-SIV, which is the proper name for this mode of operation. However, it is called AES256-SIV in cppcryptfs because the 512-bit SIV key is derived from the 256-bit master key (as is the case with gocryptfs). Also, the developer of cppcryptfs doesn't want to call it AES512-SIV in the user interface because that might cause users to think that it is more secure than AES256-GCM.

If you check Reverse then you will be creating a Reverse Mode filesystem. See the section in this document about Reverse Mode for more information.

If you wish, you can specifiy a config file. This is the file that contains the settings for the filesystem and also the random 256-bit AES master key that is encrypted using your password. The config file file can be kept outside the encrypted filesystem for an extra degree of security.

When you click on the "Create" button, config file will be created. It will be created as gocryptfs.conf in the root directory of the encrypted filesystem unless you specified an alternate config file. Unless you choose to use plain text file names, a gocryptfs.diriv will also be created there. Be sure to back up these files in case they get lost or corrupted. You won't be able to access any of your data if something happens to gocryptfs.conf. gocryptfs.conf will never change for the life of your filesystem unless you change the volume label (see bellow).

If you choose to give the volume a label, then the label will be encrypted in gocryptfs.conf. The maximum volume label length is 32 characters.

The volume label is AES256-GCM encrypted using the master key and a 128-bit random initialization vector and 8 zero bytes of auth data. Then it is ba