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. Trans- parently runs on top of existing file systems. * Random per file tweak value used for encryption, which guaranties different cipher texts for the same encrypted files. * Saves metadata only in encrypted file name, but not in file it- self. * Supports arbitrary number of keys per file system, default direc- tory key, mixing files encrypted with different keys in same di- rectory. * 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 separately after mounting the file system. If no argument specified 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 argument 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. Techni- cally just a rename takes place on underlaying file system. Keys for entries in the directory are not changed and no data is re-en- crypted 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 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" sec- tion 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 ver- sions. Create random key chain elements. Minimum and maximum num- ber 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. 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 (ex- cluding new-line character) is taken from the given file. This ar- gument can be specified multiple times, which has the effect of re- assembling 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 com- mand 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 data- base 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. 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 option for pam_pefs(8) or default algorithm, if one adds/removes keys often 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 vn- odes 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 en- abled 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 de- cryption 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 ker- nel 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 verifica- tion. Key chain database file is not encrypted by pefs, but it's is inter- nally 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 15.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+15.1.quarterly>