Library Design Draft

Error handling

All functions return an instance of cryfs_status, which represents success or an error code.

enum cryfs_status {0: success, error codes ...};

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

cryfs_status cryfs_load_init(cryfs_load_context **);

cryfs_status cryfs_load_set_basedir(cryfs_load_context *context, const char *basedir, size_t basedir_length);
cryfs_status cryfs_load_set_password(cryfs_load_context *context, const char *password, size_t password_length);
cryfs_status cryfs_load_set_externalconfig(cryfs_load_context *context, const char *configfile, size_t configfile_length);

// Load it. This also initializes the mount handle you pass it. You don't have ownership of the mount_handle and don't have to free it.
cryfs_status cryfs_load(cryfs_load_context *context, cryfs_mount_handle **handle);

// Use the mount_handle ...
// ... and in the end, free the context
void cryfs_load_free(cryfs_load_context *);

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

// Create a file system
cryfs_status *cryfs_create_init(cryfs_create_context **);

// Set options
cryfs_status cryfs_create_set_basedir(cryfs_create_context *context, const char *basedir, size_t basedir_length);
cryfs_status cryfs_create_set_password(cryfs_create_context *context, const char *password, size_t password_len);
cryfs_status cryfs_create_set_externalconfig(cryfs_create_context *context, const char *configfile, size_t configfile_length);
cryfs_status cryfs_create_set_ciphername(cryfs_create_context *context, const char *ciphername, size_t ciphername_length);
... (to be extended in future versions)

// Create it. This also initializes the mount handle you pass it. You don't have ownership of the mount_handle and don't have to free it.
cryfs_status *cryfs_create(cryfs_create_context *context, cryfs_mount_handle **handle);

// After you (possibly) used the mount_handle, you call
void cryfs_create_free(cryfs_create_context *);

Mount a loaded/created file system:

// This can be used to check that the cipher is the one you expect.
// *output is initialized to a string containing the cipher name.
// Ownership of this string is kept inside the library. It is valid as long as your cryfs_load_context is valid.
cryfs_status cryfs_mount_get_ciphername(cryfs_mount_handle *handle, const char **output);
... (add more functions returning information about the file system)

// Set mount options
cryfs_status cryfs_mount_set_mountdir(cryfs_mount_handle *handle, const char *mountdir, size_t mountdir_length);
cryfs_status cryfs_mount_set_logfile(cryfs_mount_handle *handle, const char *logfile, size_t logfile_length);
cryfs_status cryfs_mount_set_unmount_idle(cryfs_mount_handle *handle, uint32_t unmount_idle_sec);
... (to be extended in future versions)

// Mount it
cryfs_status cryfs_mount(cryfs_mount_handle *handle);

Unmounting:

cryfs_status cryfs_unmount(const char *mountdir, size_t mountdir_length);

Use case: Mounting a file system

cryfs_load_context *ctx;
cryfs_status status;
status = cryfs_load_init(&ctx);
if (status != cryfs_success) {...}
status = cryfs_load_set_basedir(ctx, basedir, strlen(basedir));
if (status != cryfs_success) {...}
status = cryfs_load_set_password(ctx, password, strlen(password));
if (status != cryfs_success) {...}
... (set other things)

cryfs_mount_handle *handle;
status = cryfs_load(ctx, &handle);
if (status != cryfs_success) {...}
status = cryfs_mount_set_mountdir(handle, mountdir, strlen(mountdir));
if (status != cryfs_success) {...}
status = cryfs_mount(handle);
if (status != cryfs_success) {...}

cryfs_load_free(ctx);

Use case: Creating a file system

cryfs_create_context *ctx;
cryfs_status status;
status = cryfs_create_init(&ctx);
if (status != cryfs_success) {...}
status = cryfs_create_set_basedir(ctx, basedir, strlen(basedir));
if (status != cryfs_success) {...}
status = cryfs_create_set_password(ctx, password, strlen(password));
if (status != cryfs_success) {...}
status = cryfs_create_set_cipher(ctx, cipher, strlen(cipher));
if (status != cryfs_success) {...}
... (set other things)

cryfs_mount_handle *handle;
status = cryfs_create(ctx, &handle);
if (status != cryfs_success) {...}
status = cryfs_mount_set_mountdir(handle, mountdir, strlen(mountdir));
if (status != cryfs_success) {...}
status = cryfs_mount(handle);
if (status != cryfs_success) {...}

cryfs_load_free(ctx);