NAME

SYNOPSIS

DESCRIPTION

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.

showalgs

Print list of all supported algorithms.

algorithm:iterations

SYSCTL VARIABLES

vfs.pefs.nodes

Number of active nodes. Unlike nullfs(8) pefs doesn't 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 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

% 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

FILES

<filesystem>/.pefs.conf

Configuration file (symbolic link).

<filesystem>/.pefs.db

Key chain database file.

SEE ALSO

HISTORY

AUTHORS