fs_crypto_domain_hard_lock()

Updated: April 19, 2023

Lock a domain

Synopsis:

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

int fs_crypto_domain_hard_lock(
    const char *path,
    int domain,
    int *preply,
    unsigned flags)

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.
flags
Flags associated with the hard lock request. The flags must contain an action specifier, which describes the hard lock action to take.
Valid action flags include :
  • FS_CRYPTO_HARD_LOCK_ACTION_CANCEL — Cancel a queued hard lock. This effectively disables the whitelist that controls access to the domain when a hard lock is pending. If a hard lock has not been queued, this action has no effect. This implies that the lock state isn't changed by this action. For example, if the domain is already locked, this doesn't unlock the domain since a hard lock can't be queued on a locked domain.
  • FS_CRYPTO_HARD_LOCK_ACTION_ENFORCE — Enforce a hard lock of the domain immediately. All filesystem clients are denied access to the keys associated with the domain.
  • FS_CRYPTO_HARD_LOCK_ACTION_QUEUE — Queue the locking of the domain. All filesystem clients that have not been whitelisted are denied access to the keys associated with the domain. A queued hard lock can be enforced at a later time by sending an additional hard lock request with FS_CRYPTO_HARD_LOCK_ENFORCE used as the enforcement flag. If no enforcement flag is specified, this is the default behavior.

Library:

libfscrypto

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

Description:

The fs_crypto_domain_hard_lock() function locks a domain. The behavior is determined by when the hard lock (controlled by the FS_CRYPTO_HARD_LOCK_ACTION_ENFORCE flag) takes place.

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 in order to lock a domain.

If FS_CRYPTO_HARD_LOCK_ACTION_ENFORCE isn't set, the hard lock is deferred until a later time (triggered or enforced by invoking this function with FS_CRYPTO_HARD_LOCK_ACTION_ENFORCE set) at the discretion of the client. A deferred hard lock activates the use of a whitelist that controls access to domain keys. Only clients that appear on the whitelist can access the domain and file keys, and thus all file content that the keys protect. Clients that do not appear on the whitelist are denied access to both the domain and file keys, and thus all file content that they protect.

If FS_CRYPTO_HARD_LOCK_ACTION_ENFORCE is set, the hard lock is enforced immediately. All domain and file keys are securely cleared from memory, which means all clients (including those that appear on the whitelist) are denied access to the file content that the keys protect. When this action is complete, the state of the domain is equivalent to the usual locked state.

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

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