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 |