info.guardianproject.iocipher

Class VirtualFileSystem

java.lang.Object

info.guardianproject.iocipher.VirtualFileSystem

public class VirtualFileSystem
extends java.lang.Object

A virtual file system container. Open and mount a virtual file system container backed by a SQLCipher database for full encrypted file storage.

Method Summary

Modifier and Type	Method and Description
void	beginTransaction() Call this function before performance sensitive write operations to increase performance
void	completeTransaction() Call this function after performance sensitive write operations complete
void	createNewContainer(byte[] key) Create a new VFS container file at the path given in setContainerPath(String) and key.
void	createNewContainer(javax.crypto.SecretKey key) Create a new VFS container file at the path given in setContainerPath(String) and key.
void	createNewContainer(java.lang.String password) Create a new VFS container file at the path given from setContainerPath(String) and password.
void	createNewContainer(java.lang.String containerPath, byte[] key) Create a new VFS container file using the path and key given.
void	createNewContainer(java.lang.String containerPath, javax.crypto.SecretKey key) Create a new VFS container file using the path and key given.
void	createNewContainer(java.lang.String containerPath, java.lang.String password) Create a new VFS container file using the path and password given.
boolean	deleteContainer() Delete all files associated with the container itself, i.e.
boolean	deleteContainer(java.lang.String containerPath) Delete all files associated with the container itself, i.e.
void	detachThread() If accessing an IOCipher container in any thread separate from where mount(byte[]) was called, that thread will have its own IOCipher state.
static VirtualFileSystem	get() Get the instance of the VirtualFileSystem.
java.lang.String	getContainerPath() Get the full path to the file used as the virtual file system container.
boolean	isMounted()
void	mount(byte[] key) Open and mount a virtual file system container encrypted with the provided key.
void	mount(javax.crypto.SecretKey key) Open and mount a virtual file system container encrypted with the provided key.
void	mount(java.lang.String password) Open and mount a virtual file system container encrypted with the provided password as a String.
void	mount(java.lang.String containerPath, byte[] key) Open and mount a virtual file system container encrypted with the provided key.
void	mount(java.lang.String containerPath, javax.crypto.SecretKey key) Open and mount a virtual file system container encrypted with the provided key.
void	mount(java.lang.String containerPath, java.lang.String password) Open and mount a virtual file system container encrypted with the provided password as a String.
void	setContainerPath(java.lang.String containerPath) Set the path to the container file that is the virtual file system.
void	unmount() Unmount the file system.

Methods inherited from class java.lang.Object

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

Method Detail

get

public static VirtualFileSystem get()

Get the instance of the VirtualFileSystem.

Returns:

the single instance of VirtualFileSystem

setContainerPath

public void setContainerPath(java.lang.String containerPath)
                      throws java.lang.IllegalArgumentException

Set the path to the container file that is the virtual file system. This is specified as a String to avoid confusion between File and File.

Parameters:

{@code - containerPath} the physical disk file that serves as the VFS container

Throws:

{@link - IllegalArgumentException} if the containing directory does not exist or is not readable

java.lang.IllegalArgumentException

getContainerPath

public java.lang.String getContainerPath()

Get the full path to the file used as the virtual file system container.

Returns:

the path to the VFS container file

createNewContainer

public void createNewContainer(java.lang.String password)
                        throws java.lang.IllegalArgumentException

Create a new VFS container file at the path given from setContainerPath(String) and password.

If the container path was not set does not exist, it will throw an IllegalArgumentException.

Parameters:

{@code - password} the password to set in the new VFS container

Throws:

{@link - IllegalArgumentException}

java.lang.IllegalArgumentException

createNewContainer

public void createNewContainer(byte[] key)
                        throws java.lang.IllegalArgumentException

Create a new VFS container file at the path given in setContainerPath(String) and key.

If the container path was not set does not exist, it will throw an IllegalArgumentException.

Parameters:

{@code - key} the raw AES key to set in the new VFS container

Throws:

{@link - IllegalArgumentException}

java.lang.IllegalArgumentException

createNewContainer

public void createNewContainer(javax.crypto.SecretKey key)
                        throws java.lang.IllegalArgumentException

Create a new VFS container file at the path given in setContainerPath(String) and key.

If the container path was not set does not exist, it will throw an IllegalArgumentException.

Parameters:

{@code - key} the raw AES key to set in the new VFS container

Throws:

{@link - IllegalArgumentException}

java.lang.IllegalArgumentException

createNewContainer

public void createNewContainer(java.lang.String containerPath,
                               java.lang.String password)
                        throws java.lang.IllegalArgumentException

Create a new VFS container file using the path and password given.

If the container path given does not exist or is not read/write, it will throw an IllegalArgumentException.

Parameters:

{@code - containerPath} the physical disk file that serves as the VFS container

Throws:

{@link - IllegalArgumentException} if the containing directory does not exist or is not readable

java.lang.IllegalArgumentException

createNewContainer

public void createNewContainer(java.lang.String containerPath,
                               byte[] key)
                        throws java.lang.IllegalArgumentException

Create a new VFS container file using the path and key given.

If the container path given does not exist or is not read/write, it will throw an IllegalArgumentException.

Parameters:

{@code - containerPath} the physical disk file that serves as the VFS container

{@code - key} the raw AES key to set in the new VFS container

Throws:

{@link - IllegalArgumentException} if the containing directory does not exist or is not readable

java.lang.IllegalArgumentException

createNewContainer

public void createNewContainer(java.lang.String containerPath,
                               javax.crypto.SecretKey key)
                        throws java.lang.IllegalArgumentException

Create a new VFS container file using the path and key given.

If the container path given does not exist or is not read/write, it will throw an IllegalArgumentException.

Parameters:

{@code - containerPath} the physical disk file that serves as the VFS container

{@code - key} the raw AES key to set in the new VFS container

Throws:

{@link - IllegalArgumentException} if the containing directory does not exist or is not readable

java.lang.IllegalArgumentException

deleteContainer

public boolean deleteContainer()

Delete all files associated with the container itself, i.e. the sqlfs database, the SQLite WAL log file, and the SQLite SHM file.

Returns:

true if all related files were deleted, false otherwise

deleteContainer

public boolean deleteContainer(java.lang.String containerPath)

Delete all files associated with the container itself, i.e. the sqlfs database, the SQLite WAL log file, and the SQLite SHM file.

Parameters:

containerPath - the path to the sqlfs database file

Returns:

true if all related files were deleted, false otherwise

mount

public void mount(java.lang.String password)
           throws java.lang.IllegalArgumentException

Open and mount a virtual file system container encrypted with the provided password as a String. This String is then used to derive the AES key using SQLCipher's key derivation method. This method is the least preferred option because it is not possible to clear the password from memory since String instances are immutable.

If the vfs is already mounted, it will throw an IllegalStateException. If the file does not exist or the password is wrong, it will throw an IllegalArgumentException.

Parameters:

password - the password to unlock the VFS container

Throws:

IllegalArgumentException, - IllegalStateException

java.lang.IllegalArgumentException

mount

public void mount(java.lang.String containerPath,
                  java.lang.String password)

Open and mount a virtual file system container encrypted with the provided password as a String. This String is then used to derive the AES key using SQLCipher's key derivation method. This method is the least preferred option because it is not possible to clear the password from memory since String instances are immutable.

If the vfs is already mounted, it will throw an IllegalStateException. If the file does not exist or the password is wrong, it will throw an IllegalArgumentException.

Parameters:

containerPath - the path to the file to mount

password - the password to unlock the VFS container

Throws:

IllegalArgumentException, - IllegalStateException

mount

public void mount(byte[] key)
           throws java.lang.IllegalArgumentException

Open and mount a virtual file system container encrypted with the provided key. This expects the raw AES key as a SecretKey instance here to be passed directly to the underlying database layer. It is not a password that will then be used to derive a key, like with mount(String). This method only accepts raw byte values, if you need to send a Unicode string, use mount(String). Also, a byte[] can be zeroed out when it is no longer needed. This method and mount(SecretKey) were designed to be used with the CacheWord library.

If the vfs is already mounted, it will throw an IllegalStateException. If the file does not exist or the key is wrong, it will throw an IllegalArgumentException.

Parameters:

{@code - key} the container's raw AES key

Throws:

IllegalArgumentException, - IllegalStateException

java.lang.IllegalArgumentException

mount

public void mount(java.lang.String containerPath,
                  byte[] key)

Open and mount a virtual file system container encrypted with the provided key. This expects the raw AES key as a SecretKey instance here to be passed directly to the underlying database layer. It is not a password that will then be used to derive a key, like with mount(String). This method only accepts raw byte values, if you need to send a Unicode string, use mount(String). Also, a byte[] can be zeroed out when it is no longer needed. This method and mount(SecretKey) were designed to be used with the CacheWord library.

If the vfs is already mounted, it will throw an IllegalStateException. If the file does not exist or the key is wrong, it will throw an IllegalArgumentException.

Parameters:

containerPath - the path to the file to mount

{@code - key} the container's raw AES key

Throws:

IllegalArgumentException, - IllegalStateException

mount

public void mount(javax.crypto.SecretKey key)

Open and mount a virtual file system container encrypted with the provided key. This expects the raw AES key as a SecretKey instance here to be passed directly to the underlying database layer. It is not a password that will then be used to derive a key, like with mount(String). This method and mount(byte[]) were designed to be used with the CacheWord library.

If the vfs is already mounted, it will throw an IllegalStateException. If the file does not exist or the key is wrong, it will throw an IllegalArgumentException.

Parameters:

{@code - key} the container's raw AES key

Throws:

IllegalArgumentException, - IllegalStateException

mount

public void mount(java.lang.String containerPath,
                  javax.crypto.SecretKey key)

Open and mount a virtual file system container encrypted with the provided key. This expects the raw AES key as a SecretKey instance here to be passed directly to the underlying database layer. It is not a password that will then be used to derive a key, like with mount(String). This method and mount(byte[]) were designed to be used with the CacheWord library.

If the vfs is already mounted, it will throw an IllegalStateException. If the file does not exist or the key is wrong, it will throw an IllegalArgumentException.

Parameters:

containerPath - the path to the file to mount

{@code - key} the container's raw AES key

Throws:

IllegalArgumentException, - IllegalStateException

unmount

public void unmount()
             throws java.lang.IllegalStateException

Unmount the file system. It will throw an IllegalStateException if the vfs is not mounted, or if it cannot be unmounted because it is busy (some threads are still active on it).

Throws:

java.lang.IllegalStateException

isMounted

public boolean isMounted()

Returns:

whether the VFS is mounted or not

detachThread

public void detachThread()

If accessing an IOCipher container in any thread separate from where mount(byte[]) was called, that thread will have its own IOCipher state. For threads that do not quit when complete or are reused, like Android's AsyncTask or any "thread pool" model, this method must be called when each thread is finished using the container. Otherwise, that thread will keep its connection to the container open, and it will not be possible to unmount() successfully.

beginTransaction

public void beginTransaction()

Call this function before performance sensitive write operations to increase performance

completeTransaction

public void completeTransaction()

Call this function after performance sensitive write operations complete