fs_crypto_domain_hard_lock()

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 controlling 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 differs based on when the hard lock will take place, which is controlled by the FS_CRYPTO_HARD_LOCK_ACTION_ENFORCE flag. The function prevents all I/O, even on existing descriptors (subject to the whitelist rules). It leaves the individual file encryption keys (FEKs) in RAM until the file is closed.

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 at the discretion of the client. A deferred hard lock can be triggered or enforced by invoking this function with FS_CRYPTO_HARD_LOCK_ACTION_ENFORCE set. 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 protected by such keys. All other clients that do not appear on the whitelist are denied access to both the domain and file keys, and thus all file content protected by such keys.

If FS_CRYPTO_HARD_LOCK_ACTION_ENFORCE is set, the hard lock is enforced immediately. All clients, including those appearing on the white list, are denied access to the domain and file keys, and thus all file content protected by such keys. All domain and file keys are securely wiped from memory. Once complete, the state of the domain is equivalent to the usual locked state.

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