fs_crypto_domain_hard

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