fs_crypto_domain_lock()

Updated: April 19, 2023

Lock a domain

Synopsis:

#include <fs_crypto_api.h>
#include <sys/fs_crypto.h>

int fs_crypto_domain_lock( const char *path,
                           int domain,
                           int *preply );

Arguments:

path
The path to the filesystem's mountpoint.
domain
The number of the domain that you want to lock.
preply
A pointer to a location where the function can store additional success or error information.

Library:

libfscrypto

Use the -l fscrypto option to qcc to link against this library.

Description:

The fs_crypto_domain_lock() function locks a domain, which prevents access to the original contents of any file belonging to the specified domain, and clears the domain key from memory. When this action is complete, the state of the domain is equivalent to the usual locked state.

Because the domain key is cleared, any further I/O operations fail with EACCES. It does not clear the individual file encryption keys (FEKs). File access is not permitted because updating the file metadata requires access to the domain key.

To make sure that filesystem metadata is updated consistently before the domain is locked, this function also flushes the entire filesystem.

Note:
  • In order to use filesystem encryption, download the Encrypted Filesystem package from the QNX Software Center.
  • You must be in the group that owns the filesystem's mountpoint to lock a domain.

This function sets the variable pointed to by preply to one of the following values:

FS_CRYPTO_REPLY_ALREADY
The domain was already locked.
FS_CRYPTO_REPLY_COMPLETE
The domain is now locked.
FS_CRYPTO_REPLY_INVALID
The command wasn't completed successfully.
FS_CRYPTO_REPLY_NOENTRY
No entry was found for the given domain.
FS_CRYPTO_REPLY_UNKNOWN_TYPE
The type of encryption used for the domain is invalid.

Returns:

EOK
Success.
EINVAL
Invalid arguments.
ENOMEM
Insufficent free memory.

This function can also return any of the errors indicated by devctl() or open().

Classification:

QNX Neutrino

Safety:  
Cancellation point Yes
Interrupt handler No
Signal handler No
Thread Yes