Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  PEFS (8)


pefs - configure pefs file systems


     Command Options
     Key Chains
     Configuration File
Sysctl Variables
Data Authentication
See Also


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


The pefs utility is the user interface for configuring stacked cryptographic 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 guaranties 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 separately after mounting the file system. If no agrumnt 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. 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 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 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 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.
showchains filesystem
  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:


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.
  Number of active nodes. Unlike nullfs(8) pefs doesn’t recycle vnodes as early as possible, but expects kernel to recycle vnodes when necessary.
  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.
  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.
  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 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


pefs provides no data integrity checking. Thus it’s strongly advised to use additional data integrity checking tools.


  Configuration file (symbolic link).
<filesystem>/.pefs.db Key chain database file.


kenv(1), crypto(4), nullfs(5), geli(8), mount(8), sysctl(8) umount(8)


The pefs utility appeared in
.Fx x.0 .


.An Gleb Kurtsou Aq
Search for    or go to Top of page |  Section 8 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.