Library Design Draft

Error handling

Functions returning handles will return nullptr on failure. Other functions will return true (successful) or false (failure). The kind of error can then be seen using the following two functions:

enum Cryfs_Error_Code {...};
Cryfs_Error_Code cryfs_last_error();
const char *cryfs_last_error_message();

Load file system (this doesn't mount yet):

cryfs_load_handle *cryfs_load_init(const char *basedir);

bool cryfs_load_set_password(cryfs_load_handle *handle, const char *password, size_t password);
bool cryfs_load_set_externalconfig(cryfs_load_handle *handle, const char *configfile);

// Returns nullptr if file system doesn't exist.
cryfs_mount_handle *cryfs_load(cryfs_load_handle *handle);

Create new file system (also doesn't mount yet):

// Create a file system
cryfs_create_handle *cryfs_create_init(const char *basedir);

// Set options
bool cryfs_create_set_password(cryfs_create_handle *handle, const char *password, size_t password_len);
bool cryfs_create_set_externalconfig(cryfs_create_handle *handle, const char *configfile);
bool cryfs_create_set_ciphername(cryfs_create_handle *handle, const char *ciphername);
... (to be extended in future versions)

// Create it
cryfs_mount_handle *cryfs_create(cryfs_create_handle *handle);

Mount a loaded/created file system:

// This can be used to check that the cipher is the one you expect
const char *cryfs_mount_get_ciphername(cryfs_filesystem_handle *handle);
... (add more functions returning information about the file system)

// Set mount options
bool cryfs_mount_set_logfile(cryfs_mount_handle *handle, const char *logfile);
bool cryfs_mount_set_unmount_idle(cryfs_mount_handle *handle, uint32_t unmount_idle_sec);
... (to be extended in future versions)

// Mount it
bool cryfs_mount(cryfs_mount_handle *handle, const char *mountdir);

Unmounting:

bool cryfs_unmount(const char *mountdir);

Ownership

When a function returns a handle to you (e.g. cryfs_create_init, you have ownership of this handle. When you pass it into another library function (e.g. cryfs_create), you loose ownership of this handle. You always loose it, no matter whether the function call succeeds or fails. In case you're left with a handle you don't use (say you call cryfs_create_init, but don't want to call cryfs_mount later, because your application wants to create a new file system without mounting it), you can call one of the following functions:

bool cryfs_create_free(cryfs_create_handle *handle);
bool cryfs_load_free(cryfs_load_handle *handle);
bool cryfs_mount_free(cryfs_mount_handle *handle);