README.md

CryptoFS: Implementation of the Cryptomator encryption scheme. For more info about the encryption scheme, read the docs.

Features

• Access Cryptomator encrypted vaults from within your Java application
• Uses a java.nio.file.FileSystem so code written against the java.nio.file API can easily be adapted to work with encrypted data
• Open Source means: No backdoors, control is better than trust

Security Architecture

For more information on the security details, visit docs.cryptomator.org.

Audits

• Version 1.4.0 audit by Cure53

Finding	Comment
1u1-22-001	The GPG key is used exclusively for the Maven repositories, is designed for signing only and is protected by a 30-character generated password (alphabet size: 96 chars). It is iterated and salted (SHA1 with 20971520 iterations). An offline attack is also very unattractive. Apart from that, this finding has no influence on the Tresor apps1. This was not known to Cure53 at the time of reporting.
1u1-22-002	This issue is related to siv-mode.

Usage

Vault Initialization

Path storageLocation = Paths.get("/home/cryptobot/vault");
Files.createDirectories(storageLocation);
Masterkey masterkey = Masterkey.generate(csprng));
MasterkeyLoader loader = ignoredUri -> masterkey.copy(); //create a copy because the key handed over to init() method will be destroyed
CryptoFileSystemProperties fsProps = CryptoFileSystemProperties.cryptoFileSystemProperties().withKeyLoader(loader).build();
CryptoFileSystemProvider.initialize(storageLocation, fsProps, "myKeyId");

The key material used for initialization and later de- & encryption is given by the org.cryptomator.cryptolib.api.Masterkeyloader interface.

Obtaining a FileSystem Instance

You have the option to use the convenience method CryptoFileSystemProvider#newFileSystem as follows:

FileSystem fileSystem = CryptoFileSystemProvider.newFileSystem(
	storageLocation,
	CryptoFileSystemProperties.cryptoFileSystemProperties()
		.withKeyLoader(ignoredUri -> masterkey.copy())
		.withFlags(FileSystemFlags.READONLY) // readonly flag is optional of course
		.build());

or to use one of the standard methods from FileSystems#newFileSystem:

URI uri = CryptoFileSystemUri.create(storageLocation);
FileSystem fileSystem = FileSystems.newFileSystem(
		uri,
		CryptoFileSystemProperties.cryptoFileSystemProperties()
            .withKeyLoader(ignoredUri -> masterkey.copy())
			.withFlags(FileSystemFlags.READONLY) // readonly flag is optional of course
			.build());

Note: Instead of CryptoFileSystemProperties, you can always pass in a java.util.Map with entries set accordingly.

For more details on construction, have a look at the javadoc of CryptoFileSytemProvider, CryptoFileSytemProperties, and CryptoFileSytemUris.

Using the Constructed FileSystem

try (FileSystem fileSystem = ...) { // see above

	// obtain a path to a test file
	Path testFile = fileSystem.getPath("/foo/bar/test");

	// create all parent directories
	Files.createDirectories(testFile.getParent());

	// Write data to the file
	Files.write(testFile, "test".getBytes());

	// List all files present in a directory
	try (Stream<Path> listing = Files.list(testFile.getParent())) {
		listing.forEach(System.out::println);
	}

}

For more details on how to use the constructed FileSystem, you may consult the javadocs of the java.nio.file package.

Building

Dependencies

• Java 21
• Maven 3

Run Maven

mvn clean install

Contributing to CryptoFS

Please read our contribution guide if you would like to report a bug, ask a question, or help us with coding.

Code of Conduct

Help us keep Cryptomator open and inclusive. Please read and follow our Code of Conduct.

License

This project is dual-licensed under the AGPLv3 for FOSS projects as well as a commercial license derived from the LGPL for independent software vendors and resellers. If you want to use this library in applications that are not licensed under the AGPL, feel free to contact our sales team.

---

¹ The Cure53 pentesting was performed during the development of the apps for 1&1 Mail & Media GmbH.