|mount||Mount file system. Encryption keys should be specified separately after mounting the file system. If no agrumnt specified prints all mounted pefs file systems. See mount(8) for more information.|
|Unmount filesystem. -f and -v options can be specified to force unmount or enable verbose mode respectively. See umount(8) for more information.|
|Add key to the filesystem|
|Delete key from filesystem. Command doesnt accept -a alg argument because the key fingerprint generated from the key doesnt depend on encryption algorithm.|
|Print fingerprint of the key used by file.|
|Delete all keys from filesystem. After the command all opened files would become unavailable.|
|Change default key for the directory. Default key is used as a new key for files and directories created in the directory. Technically just a rename takes place on underlaying file system. Keys for entries in the directory are not changed and no data is re-encrypted with new key. -x option can be used to add a new key to file system if it isnt found.|
|Print fingerprints if all active keys.|
|Add a new key chain element. Element consists of parent and child keys. Parent key is defined by -a -, -i and -p options and child key by equivalent -A -, -I and -P options. Element consisting only of a parent key can be constructed by specifying -Z option. -f option disables file system type checks making manipulation on key chains possible without mounting pefs file system. See KEY CHAINS section for more information.|
|Delete key chain element defined by parent key. Use -F option to delete all elements from the chain.|
|The command is deprecated and will not be available in future versions. Create random key chain elements. Minimum and maximum number of elements is controlled by -n min and -N max options. The command can be used to add false elements into key chain database, which may complicate analysis of key usage patterns by attacker.|
|Print all elements of the key chain staring with given parent key.|
|Print list of all supported algorithms.|
The following options are available when invoking pefs:
-a alg Encryption algorithm to use. Use showalgs command to get list of supported algorithms. The default algorithm is AES-128. -A alg Specifies algorithm for the secondary/child key. -c Forces key chain lookup. Error returned if chain is not found for the key. By default lookup errors are silently ignored. -C Disables key chain lookup. By default if chain is found, keys it consists of are also used for operation. -i iterations Number of iterations to use with PKCS#5v2. If this option is not specified default value of 50000 is used. -I iterations Specifies number of iterations for the secondary/child key. -j passfile Specifies a file which contains the passphrase. If passfile is given as -, standard input will be used. Only the first line (excluding new-line character) is taken from the given file. This argument can be specified multiple times, which has the effect of reassembling a single passphrase split across multiple files. Cannot be combined with the -p option. -J passfile Specifies a file which contains the passphrase for secondary/child key. Cannot be combined with -P option. -f Forces operation. Use to force unmount or to disable file system type check for key chain commands. -F Used with delchain command to delete all elements from a key chain. -k keyfile Specifies a file which contains part of the key. If keyfile is given as -, standard input will be used. -K keyfile Specifies a file which contains part of the secondary/child key. -o options Mount options passed to mount(8) utility. -p Do not ask for passphrase. -P Do not ask for passphrase for secondary/child key. -t Test-only mode. Do not perform actual operation but check if it can be performed. Usable for scripting. -v Verbose mode. -x Used with setkey command. Forces adding of the key if it is not specified for the file system. -Z Create chain with zero child key. Can be useful for addkey-c command to verify the key before adding it.
Key chain consists of one or several elements. Each element is defined by a parent key and a child key. All elements are stored encrypted in a database file.
Parent key fingerprint is used as an index to access child key in database. Chaining is achieved by reusing child key fingerprint as next index.
In addition to command line options some options can be specified in per file system configuration file: <filesystem>/.pefs.conf. .pefs.conf is not a regular file, but a symbolic link. "Name" of the file referenced by the link consists of a list of options separated by colon. Supported option list is the following:algorithm:iterations
Note that key chain database entries already contain algorithm used, and expected use of the configuration file is to specify iterations option for pam_pefs(8) or default algorithm, if one adds/removes keys often without using key chain database.
The following sysctl(8) variables can be used to control the behavior of pefs file systems or monitor them.
vfs.pefs.nodes Number of active nodes. Unlike nullfs(8) pefs doesnt recycle vnodes as early as possible, but expects kernel to recycle vnodes when necessary. vfs.pefs.dircache.enable Enable directory content caching. Content caching can only be enabled for file systems that are known to properly propagate changes to upper levels, and its permanently disabled for the rest. When disabled directory cache subsystem is still used as a file name decryption cache for all underlying file systems. vfs.pefs.dircache.entries Number of entries in directory cache. Directory cache is mainly used as a file name decryption cache, but can also be used to cache directory content if underlying file system is known to propagate changes to upper levels properly. vfs.pefs.dircache.buckets Number of dircache hash table buckets. Value can be set as a kernel environment variable by specifying it in /boot/loader.conf file, or using kenv(1) utility before loading pefs kernel module.
Encrypting a directory:% mkdir ~/Private % pefs mount ~/Private ~/Private % pefs addkey ~/Private Enter passphrase: ... % pefs unmount ~/Private
In such setup one has to manually check if passphrase valid, because pefs would accept any key for a file system. Key chaining can be used to verify keys:% mkdir ~/Private % pefs addchain -fZ ~/Private Enter parent key passphrase: Reenter parent key passphrase: % pefs mount ~/Private ~/Private % pefs addkey -c ~/Private Enter passphrase: ... % pefs unmount ~/Private
In the example key chain database file (~/Private/.pefs.db) is created on unencrypted underlying file. And addkey-c is used to force key verification. Key chain database file is not encrypted by pefs, but its is internally encrypted by the utility and there should be no risk.
Set default number of PKCS#5v2 iterations to 100000 for home directory not changing default algorithm:# make sure ~/ is not encrypted % ln -s :100000 ~/.pefs.conf
pefs provides no data integrity checking. Thus its strongly advised to use additional data integrity checking tools.
<filesystem>/.pefs.conf Configuration file (symbolic link). <filesystem>/.pefs.db Key chain database file.
The pefs utility appeared in
.Fx x.0 .
.An Gleb Kurtsou Aq gleb@FreeBSD.org