Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PEFS(8)			FreeBSD	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:
	   +o   Kernel level file system, no user level daemons needed.	Trans-
	       parently	runs on	top of existing	file systems.
	   +o   Random per file tweak value used	for encryption,	which guar-
	       anties different	cipher texts for the same encrypted files.
	   +o   Saves metadata only in encrypted	file name, but not in file it-
	       self.
	   +o   Supports	arbitrary number of keys per file system, default di-
	       rectory key, mixing files encrypted with	different keys in same
	       directory.
	   +o   Allows defining key chains, can be used to add/delete several
	       keys by specifying only master key.
	   +o   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 agrumnt specified
	     prints all	mounted	pefs file systems.  See	mount(8) for more in-
	     formation.

     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	argu-
	     ment 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 consist-
	     ing only of a parent key can be constructed by specifying -Z op-
	     tion.  -f option disables file system type	checks making manipu-
	     lation 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.

   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 ef-
	     fect 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	sec-
	     ondary/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 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 in-
     dex.

   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
	     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
     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 ver-
     ify 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 verifi-
     cation.  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	13.0		       December	1, 2009			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | SYSCTL VARIABLES | EXAMPLES | DATA AUTHENTICATION | FILES | SEE ALSO | HISTORY | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pefs&sektion=8&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help