FreeBSD Manual Pages
PEFS(8) System Manager's Manual PEFS(8) NAME pefs -- configure pefs file systems SYNOPSIS pefs mount [-o options] [from filesystem] pefs unmount [-fv] filesystem pefs addkey [-cCpv] [-a alg] [-i iterations] [-j passfile] [-k keyfile] filesystem pefs delkey [-cCpv] [-i iterations] [-j passfile] [-k keyfile] filesystem pefs flushkeys filesystem pefs getkey [-t] file pefs setkey [-cCpvx] [-a alg] [-i iterations] [-j passfile] [-k keyfile] directory pefs showkeys [-t] filesystem pefs addchain [-fpPvZ] [-a alg] [-i iterations] [-j passfile] [-k keyfile] [-A alg] [-I iterations] [-J passfile] [-K keyfile] filesystem pefs delchain [-fFpv] [-i iterations] [-j passfile] [-k keyfile] filesystem pefs randomchain [-fv] [-i iterations] [-j passfile] [-k keyfile] filesystem pefs showchains [-fp] [-i iterations] [-j passfile] [-k keyfile] filesystem pefs showalgs DESCRIPTION The pefs utility is the user interface for configuring stacked crypto- graphic file system. The following is a list of the most important file system features: • Kernel level file system, no user level daemons needed. Transparently runs on top of existing file systems. • Random per file tweak value used for encryption, which guar- anties different cipher texts for the same encrypted files. • Saves metadata only in encrypted file name, but not in file itself. • Supports arbitrary number of keys per file system, default directory key, mixing files encrypted with different keys in same directory. • Allows defining key chains, can be used to add/delete several keys by specifying only master key. • Uses modern cryptographic algorithms: AES and Camellia in XTS mode, PKCS#5v2 and HKDF for key generation. First argument of pefs utility indicates the command to be performed (see the "COMMAND OPTIONS" section for information on options): mount Mount file system. Encryption keys should be specified sepa- rately after mounting the file system. If no argument speci- fied prints all mounted pefs file systems. See mount(8) for more information. unmount filesystem Unmount filesystem. -f and -v options can be specified to force unmount or enable verbose mode respectively. See umount(8) for more information. addkey filesystem Add key to the filesystem delkey filesystem Delete key from filesystem. Command doesn't accept -a alg ar- gument because the key fingerprint generated from the key doesn't depend on encryption algorithm. getkey file Print fingerprint of the key used by file. flushkeys filesystem Delete all keys from filesystem. After the command all opened files would become unavailable. setkey directory 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 sys- tem. 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 isn't found. showkeys filesystem Print fingerprints if all active keys. addchain filesystem 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 con- sisting 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. delchain filesystem Delete key chain element defined by parent key. Use -F option to delete all elements from the chain. randomchain filesystem The command is deprecated and will not be available in future versions. Create random key chain elements. Minimum and maxi- mum number of elements is controlled by -n min and -N max op- tions. The command can be used to add false elements into key chain database, which may complicate analysis of key usage pat- terns by attacker. showchains filesystem Print all elements of the key chain staring with given parent key. showalgs Print list of all supported algorithms. COMMAND OPTIONS 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 multi- ple files. Cannot be combined with the -p option. -J passfile Specifies a file which contains the passphrase for sec- ondary/child key. Cannot be combined with -P option. -f Forces operation. Use to force unmount or to disable file sys- tem 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 CHAINS 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 data- base. Chaining is achieved by reusing child key fingerprint as next index. CONFIGURATION FILE 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 op- tion for pam_pefs(8) or default algorithm, if one adds/removes keys of- ten without using key chain database. SYSCTL VARIABLES 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 doesn't recycle vnodes as early as possible, but expects kernel to recycle vn- odes 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 it's 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. EXAMPLES 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 it's 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 DATA AUTHENTICATION pefs provides no data integrity checking. Thus it's strongly advised to use additional data integrity checking tools. FILES <filesystem>/.pefs.conf Configuration file (symbolic link). <filesystem>/.pefs.db Key chain database file. SEE ALSO kenv(1), crypto(4), nullfs(5), geli(8), mount(8), sysctl(8) umount(8) HISTORY The pefs utility appeared in FreeBSD x.0. AUTHORS Gleb Kurtsou <gleb@FreeBSD.org> FreeBSD Ports 14.quarterly December 1, 2009 PEFS(8)
NAME | SYNOPSIS | DESCRIPTION | SYSCTL VARIABLES | EXAMPLES | DATA AUTHENTICATION | FILES | SEE ALSO | HISTORY | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=pefs&sektion=8&manpath=FreeBSD+Ports+14.3.quarterly>