Package org.cryptomator.cryptofs

Class CryptoFileSystemProvider

java.lang.Object

java.nio.file.spi.FileSystemProvider

org.cryptomator.cryptofs.CryptoFileSystemProvider

public class CryptoFileSystemProvider
extends FileSystemProvider

A FileSystemProvider for CryptoFileSystems.

All FileSystem instances created by CryptoFileSystemProvider are instances of CryptoFileSystem. Usage

It is recommended to use newFileSystem(Path, CryptoFileSystemProperties) to create a CryptoFileSystem. To do this:

 Path storageLocation = Paths.get("/home/cryptobot/vault");
 FileSystem fileSystem = CryptoFileSystemProvider.newFileSystem(
        storageLocation,
    cryptoFileSystemProperties()
                .withPassword("password")
                .withFlags(FileSystemFlags.READONLY)
                .build());
 

Afterwards you can use the created FileSystem to create paths, do directory listings, create files and so on.

To create a new FileSystem from a URI using FileSystems.newFileSystem(URI, Map) you may have a look at CryptoFileSystemUri.

See Also:

CryptoFileSystemUri, CryptoFileSystemProperties, FileSystems, FileSystem

Constructor Summary

Constructors

Constructor	Description
CryptoFileSystemProvider()

Method Summary

Modifier and Type	Method	Description
static void	changePassphrase(Path pathToVault, String masterkeyFilename, byte[] pepper, CharSequence oldPassphrase, CharSequence newPassphrase)	Changes the passphrase of a vault at the given path.
static void	changePassphrase(Path pathToVault, String masterkeyFilename, CharSequence oldPassphrase, CharSequence newPassphrase)	Changes the passphrase of a vault at the given path.
void	checkAccess(Path cleartextPath, AccessMode... modes)
static boolean	containsVault(Path pathToVault, String masterkeyFilename)	Checks if the folder represented by the given path exists and contains a valid vault structure.
void	copy(Path cleartextSource, Path cleartextTarget, CopyOption... options)
void	createDirectory(Path cleartextDir, FileAttribute<?>... attrs)
void	createSymbolicLink(Path cleartextPath, Path target, FileAttribute<?>... attrs)
void	delete(Path cleartextPath)
static byte[]	exportRawKey(Path pathToVault, String masterkeyFilename, byte[] pepper, CharSequence passphrase)	Exports the raw key for backup purposes or external key management.
<V extends FileAttributeView> V	getFileAttributeView(Path cleartextPath, Class<V> type, LinkOption... options)
FileStore	getFileStore(Path cleartextPath)
CryptoFileSystem	getFileSystem(URI uri)
Path	getPath(URI uri)
String	getScheme()
static void	initialize(Path pathToVault, String masterkeyFilename, byte[] pepper, CharSequence passphrase)	Creates a new vault at the given directory path.
static void	initialize(Path pathToVault, String masterkeyFilename, CharSequence passphrase)	Creates a new vault at the given directory path.
boolean	isHidden(Path cleartextPath)
boolean	isSameFile(Path cleartextPath, Path cleartextPath2)
void	move(Path cleartextSource, Path cleartextTarget, CopyOption... options)
AsynchronousFileChannel	newAsynchronousFileChannel(Path cleartextPath, Set<? extends OpenOption> options, ExecutorService executor, FileAttribute<?>... attrs)
SeekableByteChannel	newByteChannel(Path cleartextPath, Set<? extends OpenOption> options, FileAttribute<?>... attrs)
DirectoryStream<Path>	newDirectoryStream(Path cleartextDir, DirectoryStream.Filter<? super Path> filter)
FileChannel	newFileChannel(Path cleartextPath, Set<? extends OpenOption> optionsSet, FileAttribute<?>... attrs)
CryptoFileSystem	newFileSystem(URI uri, Map<String,?> rawProperties)
static CryptoFileSystem	newFileSystem(Path pathToVault, CryptoFileSystemProperties properties)	Typesafe alternative to FileSystems.newFileSystem(URI, Map).
<A extends BasicFileAttributes> A	readAttributes(Path cleartextPath, Class<A> type, LinkOption... options)
Map<String,Object>	readAttributes(Path cleartextPath, String attributes, LinkOption... options)
Path	readSymbolicLink(Path cleartextPath)
static void	restoreRawKey(Path pathToVault, String masterkeyFilename, byte[] rawKey, byte[] pepper, CharSequence passphrase)	Imports a raw key from backup or external key management.
void	setAttribute(Path cleartextPath, String attribute, Object value, LinkOption... options)

Methods inherited from class java.nio.file.spi.FileSystemProvider

createLink, deleteIfExists, installedProviders, newFileSystem, newInputStream, newOutputStream

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CryptoFileSystemProvider

public CryptoFileSystemProvider()

Method Detail

newFileSystem

public static CryptoFileSystem newFileSystem(Path pathToVault,
                                             CryptoFileSystemProperties properties)
                                      throws FileSystemNeedsMigrationException,
                                             IOException

Typesafe alternative to FileSystems.newFileSystem(URI, Map). Default way to retrieve a CryptoFS instance.

Parameters:

pathToVault - Path to this vault's storage location

properties - Parameters used during initialization of the file system

Returns:

a new file system

Throws:

FileSystemNeedsMigrationException - if the vault format needs to get updated and properties did not contain a flag for implicit migration.

FileSystemCapabilityChecker.MissingCapabilityException - If the underlying filesystem lacks features required to store a vault

IOException - if an I/O error occurs creating the file system

initialize

public static void initialize(Path pathToVault,
                              String masterkeyFilename,
                              CharSequence passphrase)
                       throws NotDirectoryException,
                              IOException

Creates a new vault at the given directory path.

Parameters:

pathToVault - Path to a not yet existing directory

masterkeyFilename - Name of the masterkey file

passphrase - Passphrase that should be used to unlock the vault

Throws:

NotDirectoryException - If the given path is not an existing directory.

FileSystemCapabilityChecker.MissingCapabilityException - If the underlying filesystem lacks features required to store a vault

IOException - If the vault structure could not be initialized due to I/O errors

Since:

1.3.0

initialize

public static void initialize(Path pathToVault,
                              String masterkeyFilename,
                              byte[] pepper,
                              CharSequence passphrase)
                       throws NotDirectoryException,
                              IOException

Creates a new vault at the given directory path.

Parameters:

pathToVault - Path to a not yet existing directory

masterkeyFilename - Name of the masterkey file

pepper - Application-specific pepper used during key derivation

passphrase - Passphrase that should be used to unlock the vault

Throws:

NotDirectoryException - If the given path is not an existing directory.

FileSystemCapabilityChecker.MissingCapabilityException - If the underlying filesystem lacks features required to store a vault

IOException - If the vault structure could not be initialized due to I/O errors

Since:

1.3.2

containsVault

public static boolean containsVault(Path pathToVault,
                                    String masterkeyFilename)

Checks if the folder represented by the given path exists and contains a valid vault structure.

Parameters:

pathToVault - A directory path

masterkeyFilename - Name of the masterkey file

Returns:

true if the directory seems to contain a vault.

Since:

1.1.0

changePassphrase

public static void changePassphrase(Path pathToVault,
                                    String masterkeyFilename,
                                    CharSequence oldPassphrase,
                                    CharSequence newPassphrase)
                             throws org.cryptomator.cryptolib.api.InvalidPassphraseException,
                                    FileSystemNeedsMigrationException,
                                    IOException

Changes the passphrase of a vault at the given path.

Parameters:

pathToVault - Vault directory

masterkeyFilename - Name of the masterkey file

oldPassphrase - Current passphrase

newPassphrase - Future passphrase

Throws:

org.cryptomator.cryptolib.api.InvalidPassphraseException - If oldPassphrase can not be used to unlock the vault.

FileSystemNeedsMigrationException - if the vault format needs to get updated.

IOException - If the masterkey could not be read or written.

Since:

1.1.0

See Also:

changePassphrase(Path, String, byte[], CharSequence, CharSequence)

changePassphrase

public static void changePassphrase(Path pathToVault,
                                    String masterkeyFilename,
                                    byte[] pepper,
                                    CharSequence oldPassphrase,
                                    CharSequence newPassphrase)
                             throws org.cryptomator.cryptolib.api.InvalidPassphraseException,
                                    FileSystemNeedsMigrationException,
                                    IOException

Changes the passphrase of a vault at the given path.

Parameters:

pathToVault - Vault directory

masterkeyFilename - Name of the masterkey file

pepper - An application-specific pepper added to the salt during key-derivation (if applicable)

oldPassphrase - Current passphrase

newPassphrase - Future passphrase

Throws:

org.cryptomator.cryptolib.api.InvalidPassphraseException - If oldPassphrase can not be used to unlock the vault.

FileSystemNeedsMigrationException - if the vault format needs to get updated.

IOException - If the masterkey could not be read or written.

Since:

1.4.0

exportRawKey

public static byte[] exportRawKey(Path pathToVault,
                                  String masterkeyFilename,
                                  byte[] pepper,
                                  CharSequence passphrase)
                           throws org.cryptomator.cryptolib.api.InvalidPassphraseException,
                                  IOException

Exports the raw key for backup purposes or external key management.

Parameters:

pathToVault - Vault directory

masterkeyFilename - Name of the masterkey file

pepper - An application-specific pepper added to the salt during key-derivation (if applicable)

passphrase - Current passphrase

Returns:

A 64 byte array consisting of 32 byte aes key and 32 byte mac key

Throws:

org.cryptomator.cryptolib.api.InvalidPassphraseException

IOException

Since:

1.9.0

restoreRawKey

public static void restoreRawKey(Path pathToVault,
                                 String masterkeyFilename,
                                 byte[] rawKey,
                                 byte[] pepper,
                                 CharSequence passphrase)
                          throws org.cryptomator.cryptolib.api.InvalidPassphraseException,
                                 IOException

Imports a raw key from backup or external key management.

Parameters:

pathToVault - Vault directory

masterkeyFilename - Name of the masterkey file

pepper - An application-specific pepper added to the salt during key-derivation (if applicable)

passphrase - Future passphrase

Throws:

org.cryptomator.cryptolib.api.InvalidPassphraseException

IOException

Since:

1.9.0

getScheme

public String getScheme()

Specified by:

getScheme in class FileSystemProvider

newFileSystem

public CryptoFileSystem newFileSystem(URI uri,
                                      Map<String,?> rawProperties)
                               throws IOException

Specified by:

newFileSystem in class FileSystemProvider

Throws:

IOException

getFileSystem

public CryptoFileSystem getFileSystem(URI uri)

Specified by:

getFileSystem in class FileSystemProvider

getPath

public Path getPath(URI uri)

Specified by:

getPath in class FileSystemProvider

newAsynchronousFileChannel

public AsynchronousFileChannel newAsynchronousFileChannel(Path cleartextPath,
                                                          Set<? extends OpenOption> options,
                                                          ExecutorService executor,
                                                          FileAttribute<?>... attrs)
                                                   throws IOException

Overrides:

newAsynchronousFileChannel in class FileSystemProvider

Throws:

IOException

newFileChannel

public FileChannel newFileChannel(Path cleartextPath,
                                  Set<? extends OpenOption> optionsSet,
                                  FileAttribute<?>... attrs)
                           throws IOException

Overrides:

newFileChannel in class FileSystemProvider

Throws:

IOException

newByteChannel

public SeekableByteChannel newByteChannel(Path cleartextPath,
                                          Set<? extends OpenOption> options,
                                          FileAttribute<?>... attrs)
                                   throws IOException

Specified by:

newByteChannel in class FileSystemProvider

Throws:

IOException

newDirectoryStream

public DirectoryStream<Path> newDirectoryStream(Path cleartextDir,
                                                DirectoryStream.Filter<? super Path> filter)
                                         throws IOException

Specified by:

newDirectoryStream in class FileSystemProvider

Throws:

IOException

createDirectory

public void createDirectory(Path cleartextDir,
                            FileAttribute<?>... attrs)
                     throws IOException

Specified by:

createDirectory in class FileSystemProvider

Throws:

IOException

delete

public void delete(Path cleartextPath)
            throws IOException

Specified by:

delete in class FileSystemProvider

Throws:

IOException

copy

public void copy(Path cleartextSource,
                 Path cleartextTarget,
                 CopyOption... options)
          throws IOException

Specified by:

copy in class FileSystemProvider

Throws:

IOException

move

public void move(Path cleartextSource,
                 Path cleartextTarget,
                 CopyOption... options)
          throws IOException

Specified by:

move in class FileSystemProvider

Throws:

IOException

isSameFile

public boolean isSameFile(Path cleartextPath,
                          Path cleartextPath2)
                   throws IOException

Specified by:

isSameFile in class FileSystemProvider

Throws:

IOException

isHidden

public boolean isHidden(Path cleartextPath)
                 throws IOException

Specified by:

isHidden in class FileSystemProvider

Throws:

IOException

getFileStore

public FileStore getFileStore(Path cleartextPath)
                       throws IOException

Specified by:

getFileStore in class FileSystemProvider

Throws:

IOException

checkAccess

public void checkAccess(Path cleartextPath,
                        AccessMode... modes)
                 throws IOException

Specified by:

checkAccess in class FileSystemProvider

Throws:

IOException

createSymbolicLink

public void createSymbolicLink(Path cleartextPath,
                               Path target,
                               FileAttribute<?>... attrs)
                        throws IOException

Overrides:

createSymbolicLink in class FileSystemProvider

Throws:

IOException

readSymbolicLink

public Path readSymbolicLink(Path cleartextPath)
                      throws IOException

Overrides:

readSymbolicLink in class FileSystemProvider

Throws:

IOException

getFileAttributeView

public <V extends FileAttributeView> V getFileAttributeView(Path cleartextPath,
                                                            Class<V> type,
                                                            LinkOption... options)

Specified by:

getFileAttributeView in class FileSystemProvider

readAttributes

public <A extends BasicFileAttributes> A readAttributes(Path cleartextPath,
                                                        Class<A> type,
                                                        LinkOption... options)
                                                 throws IOException

Specified by:

readAttributes in class FileSystemProvider

Throws:

IOException

readAttributes

public Map<String,Object> readAttributes(Path cleartextPath,
                                               String attributes,
                                               LinkOption... options)
                                        throws IOException

Specified by:

readAttributes in class FileSystemProvider

Throws:

IOException

setAttribute

public void setAttribute(Path cleartextPath,
                         String attribute,
                         Object value,
                         LinkOption... options)
                  throws IOException

Specified by:

setAttribute in class FileSystemProvider

Throws:

IOException