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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
GELI(8)			FreeBSD	System Manager's Manual		       GELI(8)

NAME
     geli -- control utility for cryptographic GEOM class

SYNOPSIS
     To	compile	GEOM_ELI into your kernel, place the following lines in	your
     kernel configuration file:

	   device crypto
	   options GEOM_ELI

     Alternately, to load the GEOM_ELI module at boot time, place the follow-
     ing line in your loader.conf(5):

	   geom_eli_load="YES"

     Usage of the geli(8) utility:

     geli init [-bPv] [-a algo]	[-i iterations]	[-K newkeyfile]	[-l keylen]
	   [-s sectorsize] prov
     geli label	- an alias for init
     geli attach [-dpv]	[-k keyfile] prov
     geli detach [-fl] prov ...
     geli stop - an alias for detach
     geli onetime [-d] [-a algo] [-l keylen] [-s sectorsize] prov ...
     geli setkey [-pPv]	[-i iterations]	[-k keyfile] [-K newkeyfile]
	   [-n keyno] prov
     geli delkey [-afv]	[-n keyno] prov
     geli kill [-av] [prov ...]
     geli backup [-v] prov file
     geli restore [-v] file prov
     geli clear	[-v] prov ...
     geli dump [-v] prov ...
     geli list
     geli status
     geli load
     geli unload

DESCRIPTION
     The geli utility is used to configure encryption on GEOM providers.

     The following is a	list of	the most important features:

	   +o   Utilizes	the crypto(9) framework, so when there is crypto hard-
	       ware available, geli will make use of it	automatically.
	   +o   Supports	many cryptographic algorithms (currently AES, Blowfish
	       and 3DES).
	   +o   Can create a key	from a couple of components (user entered
	       passphrase, random bits from a file, etc.).
	   +o   Allows to encrypt the root partition - the user will be asked
	       for the passphrase before the root file system is mounted.
	   +o   The passphrase of the user is strengthened with:	B. Kaliski,
	       PKCS #5:	Password-Based Cryptography Specification, Version
	       2.0., RFC, 2898.
	   +o   Allows to use two independent keys (e.g.	 "user key" and
	       "company	key").
	   +o   It is fast - geli performs simple sector-to-sector encryption.
	   +o   Allows to backup/restore	Master Keys, so	when a user has	to
	       quickly destroy his keys, it is possible	to get the data	back
	       by restoring keys from the backup.
	   +o   Providers can be	configured to automatically detach on last
	       close (so users do not have to remember to detach providers
	       after unmounting	the file systems).
	   +o   Allows to attach	a provider with	a random, one-time key - use-
	       ful for swap partitions and temporary file systems.

     The first argument	to geli	indicates an action to be performed:

     init     Initialize provider which	needs to be encrypted.	Here you can
	      set up the cryptographic algorithm to use, key length, etc.  The
	      last provider's sector is	used to	store metadata.

	      Additional options include:

	      -a algo  Encryption algorithm to use.  Currently supported algo-
		       rithms are: AES,	Blowfish and 3DES.  The	default	is
		       AES.

	      -b       Ask for the passphrase on boot, before the root parti-
		       tion is mounted.	 This makes it possible	to use an
		       encrypted root partition.  One will still need bootable
		       unencrypted storage with	a /boot/ directory, which can
		       be a CD-ROM disc	or USB pen-drive, that can be removed
		       after boot.

	      -i iterations
		       Number of iterations to use with	PKCS#5v2.  If this
		       option is not specified,	geli will find the number of
		       iterations which	is equal to 2 seconds of crypto	work.
		       If 0 is given, PKCS#5v2 will not	be used.

	      -K newkeyfile
		       Specifies a file	which contains part of the key.	 If
		       newkeyfile is given as -, standard input	will be	used.
		       Here is how more	than one file with a key component can
		       be used:

			     # cat key1	key2 key3 | geli init -K - /dev/da0

	      -l keylen
		       Key length to use with the given	cryptographic algo-
		       rithm.  If not given, the default key length for	the
		       given algorithm is used,	which is: 128 for AES, 128 for
		       Blowfish	and 192	for 3DES.

	      -s sectorsize
		       Change decrypted	provider's sector size.	 Increasing
		       sector size allows to increase performance, because we
		       need to generate	an IV and do encrypt/decrypt for every
		       single sector - less number of sectors means less work
		       to do.

	      -P       Do not use passphrase as	the key	component.

     attach   Attach the given provider.  The master key will be decrypted
	      using the	given passphrase/keyfile and a new GEOM	provider will
	      be created using the given provider's name with an ".eli"	suf-
	      fix.

	      Additional options include:

	      -d       If specified, a decrypted provider will be detached
		       automatically on	last close.  This can help with	short
		       memory -	user does not have to remember to detach the
		       provider	after unmounting the file system.  It only
		       works when the provider was opened for writing, so it
		       will not	work if	the file system	on the provider	is
		       mounted read-only.  Probably a better choice is the -l
		       option for the detach subcommand.

	      -k keyfile
		       Specifies a file	which contains part of the key.	 For
		       more information	see the	description of the -K option
		       for the init subcommand.

	      -p       Do not use passphrase as	the key	component.

     detach   Detach the given providers, which	means remove the devfs entry
	      and clear	the keys from memory.

	      Additional options include:

	      -f       Force detach - detach even if the provider is open.

	      -l       Mark provider to	detach on last close.  If this option
		       is specified, the provider will not be detached until
		       it is open, but when it will be closed last time, it
		       will be automatically detached (even if it was only
		       opened for reading).

     onetime  Attach the given providers with random, one-time keys.  The com-
	      mand can be used to encrypt swap partitions or temporary file
	      systems.

	      Additional options include:

	      -a algo  Encryption algorithm to use.  For more information, see
		       the description of the init subcommand.

	      -d       Detach on last close.  Note, the	option is not usable
		       for temporary file systems as the provider will be
		       detached	after creating the file	system on it.  It
		       still can (and should be) used for swap partitions.
		       For more	information, see the description of the	attach
		       subcommand.

	      -l keylen
		       Key length to use with the given	cryptographic algo-
		       rithm.  For more	information, see the description of
		       the init	subcommand.

	      -s sectorsize
		       Change decrypted	provider's sector size.	 For more
		       information, see	the description	of the init subcom-
		       mand.

     setkey   Change or	setup (if not yet initialized) selected	key.  There is
	      one master key, which can	be encrypted with two independent user
	      keys.  With the init subcommand, only key	number 0 is initial-
	      ized.  The key can always	be changed: for	an attached provider,
	      for a detached provider or on the	backup file.  When a provider
	      is attached, the user does not have to provide an	old
	      passphrase/keyfile.

	      Additional options include:

	      -i iterations
		       Number of iterations to use with	PKCS#5v2.  If 0	is
		       given, PKCS#5v2 will not	be used.  To be	able to	use
		       this option with	setkey subcommand, only	one key	have
		       to be defined and this key has to be changed.

	      -k keyfile
		       Specifies a file	which contains part of the old key.

	      -K newkeyfile
		       Specifies a file	which contains part of the new key.

	      -n keyno
		       Specifies the number of the key to change (could	be 0
		       or 1).  If the provider is attached and no key number
		       is given, the key used for attaching the	provider will
		       be changed.  If the provider is detached	(or we are
		       operating on a backup file) and no key number is	given,
		       the key decrypted with the passphrase/keyfile will be
		       changed.

	      -p       Do not use passphrase as	the old	key component.

	      -P       Do not use passphrase as	the new	key component.

     delkey   Destroy (overwrite with random data) the selected	key.  If one
	      is destroying keys for an	attached provider, the provider	will
	      not be detached even if all keys will be destroyed.  It can be
	      even rescued with	the setkey subcommand.

	      -a       Destroy all keys	(does not need -f option).

	      -f       Force key destruction.  This option is needed to
		       destroy the last	key.

	      -n keyno
		       Specifies the key number.  If the provider is attached
		       and no key number is given, the key used	for attaching
		       the provider will be destroyed.	If provider is
		       detached	(or we are operating on	a backup file) the key
		       number has to be	given.

     kill     This command should be used in emergency situations.  It will
	      destroy all keys on the given provider and will detach it
	      forcibly (if it is attached).  This is absolutely	a one-way com-
	      mand - if	you do not have	a metadata backup, your	data is	gone
	      for good.

	      -a       If specified, all currently attached providers will be
		       killed.

     backup   Backup metadata from the given provider to the given file.

     restore  Restore metadata from the	given file to the given	provider.

     clear    Clear metadata from the given providers.

     dump     Dump metadata stored on the given	providers.

     list     See geom(8).

     status   See geom(8).

     load     See geom(8).

     unload   See geom(8).

     Additional	options	include:

     -v	 Be more verbose.

SYSCTL VARIABLES
     The following sysctl(8) variables can be used to control the behavior of
     the ELI GEOM class.  The default value is shown next to each variable.

     kern.geom.eli.debug: 0
	     Debug level of the	ELI GEOM class.	 This can be set to a number
	     between 0 and 3 inclusive.	 If set	to 0, minimal debug informa-
	     tion is printed.  If set to 3, the	maximum	amount of debug	infor-
	     mation is printed.	 This variable could be	set in
	     /boot/loader.conf.

     kern.geom.eli.tries: 3
	     Number of times a user is asked for the passphrase.  This is only
	     used for providers	which should be	attached on boot (before the
	     root file system is mounted).  If set to 0, attaching providers
	     on	boot will be disabled.	This variable should be	set in
	     /boot/loader.conf.

     kern.geom.eli.overwrites: 5
	     Specifies how many	times the Master-Key will be overwritten with
	     random values when	it is destroyed.  After	this operation it is
	     filled with zeros.

     kern.geom.eli.visible_passphrase: 0
	     If	set to 1, the passphrase entered on boot (before the root file
	     system is mounted)	will be	visible.  This possibility should be
	     used with caution as the entered passphrase can be	logged and
	     exposed via dmesg(8).  This variable should be set	in
	     /boot/loader.conf.

     kern.geom.eli.threads: 0
	     Specifies how many	kernel threads should be used for doing	soft-
	     ware cryptography.	 Its purpose is	to increase performance	on SMP
	     systems.  If hardware acceleration	is available, only one thread
	     will be started.  If set to 0, CPU-bound thread will be started
	     for every active CPU.  This variable could	be set in
	     /boot/loader.conf.

EXIT STATUS
     Exit status is 0 on success, and 1	if the command fails.

EXAMPLES
     Initialize	a provider which is going to be	encrypted with a passphrase
     and random	data from a file on the	user's pen drive.  Use 4kB sector
     size.  Attach the provider, create	a file system and mount	it.  Do	the
     work.  Unmount the	provider and detach it:

	   # dd	if=/dev/random of=/mnt/pendrive/da2.key	bs=64 count=1
	   # geli init -s 4096 -K /mnt/pendrive/da2.key	/dev/da2
	   Enter new passphrase:
	   Reenter new passphrase:
	   # geli attach -k /mnt/pendrive/da2.key /dev/da2
	   Enter passphrase:
	   # dd	if=/dev/random of=/dev/da2.eli bs=1m
	   # newfs /dev/da2.eli
	   # mount /dev/da2.eli	/mnt/secret
	   ...
	   # umount /mnt/secret
	   # geli detach da2.eli

     Create an encrypted provider, but use two keys: one for your girlfriend
     and one for you (so there will be no tragedy if she forgets her
     passphrase):

	   # geli init /dev/da2
	   Enter new passphrase:   (enter your passphrase)
	   Reenter new passphrase:
	   # geli setkey -n 1 /dev/da2
	   Enter passphrase:	   (enter your passphrase)
	   Enter new passphrase:   (let	your girlfriend	enter her passphrase ...)
	   Reenter new passphrase: (...	twice)

     You are the security-person in your company.  Create an encrypted
     provider for use by the user, but remember	that users forget their
     passphrases, so back Master Key up	with your own random key:

	   # dd	if=/dev/random of=/mnt/pendrive/keys/`hostname`	bs=64 count=1
	   # geli init -P -K /mnt/pendrive/keys/`hostname` /dev/ad0s1e
	   # geli backup /dev/ad0s1e /mnt/pendrive/backups/`hostname`
	   (use	key number 0, so the encrypted Master Key by you will be overwritten)
	   # geli setkey -n 0 -k /mnt/pendrive/keys/`hostname` /dev/ad0s1e
	   (allow the user to enter his	passphrase)
	   Enter new passphrase:
	   Reenter new passphrase:

     Encrypted swap partition setup:

	   # dd	if=/dev/random of=/dev/ad0s1b bs=1m
	   # geli onetime -d -a	3des ad0s1b
	   # swapon /dev/ad0s1b.eli

     The example below shows how to configure two providers which will be
     attached on boot (before the root file system is mounted).	 One of	them
     is	using passphrase and three keyfiles and	the other is using only	a key-
     file:

	   # dd	if=/dev/random of=/dev/da0 bs=1m
	   # dd	if=/dev/random of=/boot/keys/da0.key0 bs=32k count=1
	   # dd	if=/dev/random of=/boot/keys/da0.key1 bs=32k count=1
	   # dd	if=/dev/random of=/boot/keys/da0.key2 bs=32k count=1
	   # cat /boot/keys/da0.key0 /boot/keys/da0.key1 /boot/keys/da0.key2 | geli init -b -K - da0
	   Enter new passphrase:
	   Reenter new passphrase:
	   # dd	if=/dev/random of=/dev/da1s3a bs=1m
	   # dd	if=/dev/random of=/boot/keys/da1s3a.key	bs=128k	count=1
	   # geli init -b -P -K	/boot/keys/da1s3a.key da1s3a

     The providers are initialized, now	we have	to add those lines to
     /boot/loader.conf:

	   geli_da0_keyfile0_load="YES"
	   geli_da0_keyfile0_type="da0:geli_keyfile0"
	   geli_da0_keyfile0_name="/boot/keys/da0.key0"
	   geli_da0_keyfile1_load="YES"
	   geli_da0_keyfile1_type="da0:geli_keyfile1"
	   geli_da0_keyfile1_name="/boot/keys/da0.key1"
	   geli_da0_keyfile2_load="YES"
	   geli_da0_keyfile2_type="da0:geli_keyfile2"
	   geli_da0_keyfile2_name="/boot/keys/da0.key2"

	   geli_da1s3a_keyfile0_load="YES"
	   geli_da1s3a_keyfile0_type="da1s3a:geli_keyfile0"
	   geli_da1s3a_keyfile0_name="/boot/keys/da1s3a.key"

SEE ALSO
     crypto(4),	gbde(4), geom(4), loader.conf(5), gbde(8), geom(8), crypto(9)

HISTORY
     The geli utility appeared in FreeBSD 6.0.

AUTHORS
     Pawel Jakub Dawidek <pjd@FreeBSD.org>

FreeBSD	10.1		       February	11, 2006		  FreeBSD 10.1

NAME | SYNOPSIS | DESCRIPTION | SYSCTL VARIABLES | EXIT STATUS | EXAMPLES | SEE ALSO | HISTORY | AUTHORS

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

home | help