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 aalgo] [-e ealgo] [-i	iterations] [-K	newkeyfile]
	   [-l keylen] [-s sectorsize] prov
     geli label	- an alias for init
     geli attach [-dprv] [-k keyfile] prov
     geli detach [-fl] prov ...
     geli stop - an alias for detach
     geli onetime [-d] [-a aalgo] [-e ealgo] [-l keylen] [-s sectorsize] prov
	   ...
     geli configure [-bB] 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, Camellia and 3DES).
	   +o   Can optionally perform data authentication (integrity verifica-
	       tion) utilizing one of the following algorithms:	HMAC/MD5,
	       HMAC/SHA1, HMAC/RIPEMD160, HMAC/SHA256, HMAC/SHA384 or
	       HMAC/SHA512.
	   +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.
	   +o   Allows to verify	data integrity (data authentication).

     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 aalgo  Enable data integrity	verification (authentication)
			  using	the given algorithm.  This will	reduce size of
			  available storage and	also reduce speed.  For	exam-
			  ple, when using 4096 bytes sector and	HMAC/SHA256
			  algorithm, 89% of the	original provider storage will
			  be available for use.	 Currently supported algo-
			  rithms are: HMAC/MD5,	HMAC/SHA1, HMAC/RIPEMD160,
			  HMAC/SHA256, HMAC/SHA384 and HMAC/SHA512.  If	the
			  option is not	given, there will be no	authentica-
			  tion,	only encryption.

		-e ealgo  Encryption algorithm to use.	Currently supported
			  algorithms are: AES, Blowfish, Camellia and 3DES.
			  The default is AES.

		-b	  Ask for the passphrase on boot, before the root par-
			  tition is mounted.  This makes it possible to	use an
			  encrypted root partition.  One will still need
			  bootable unencrypted storage with a /boot/ direc-
			  tory,	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,	128 for	Camellia 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"
		suffix.

		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	writ-
			 ing, 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.

		-r	 Attach	read-only provider.  It	will not be opened for
			 writing.

		-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
		command	can be used to encrypt swap partitions or temporary
		file systems.

		Additional options include:

		-a aalgo  Enable data integrity	verification (authentication).
			  For more information,	see the	description of the
			  init subcommand.

		-e ealgo  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 par-
			  titions.  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.

     configure	Change configuration of	the given providers.

		Additional options include:

		-b  Set	the BOOT flag on the given providers.  For more	infor-
		    mation, see	the description	of the init subcommand.

		-B  Remove the BOOT flag from the given	providers.

     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
		initialized.  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
		command	- if you do not	have a metadata	backup,	your data is
		gone for good.	In case	the provider was attached with the -r
		flag, the keys will not	be destroyed, only the provider	will
		be detached.

		-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.
     All variables can also be set in /boot/loader.conf.

     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.

     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.

     kern.geom.eli.batch: 0
	     When set to 1, can	speed-up crypto	operations by using batching.
	     Batching allows to	reduce number of interrupts by responding on a
	     group of crypto requests with one interrupt.  The crypto card and
	     the driver	has to support this feature.

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 -e	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"

     Not only configure	encryption, but	also data integrity verification using
     HMAC/SHA256.

	   # geli init -a hmac/sha256 -s 4096 /dev/da0
	   Enter new passphrase:
	   Reenter new passphrase:
	   # geli attach /dev/da0
	   Enter passphrase:
	   # dd	if=/dev/random of=/dev/da0.eli bs=1m
	   # newfs /dev/da0.eli
	   # mount /dev/da0.eli	/mnt/secret

DATA AUTHENTICATION
     geli can verify data integrity when an authentication algorithm is	speci-
     fied.  When data corruption/modification is detected, geli	will not
     return any	data, but instead will return an error (EINVAL).  The offset
     and size of the corrupted data will be printed on the console.  It	is
     important to know against which attacks geli provides protection for your
     data.  If data is modified	in-place or copied from	one place on the disk
     to	another	even without modification, geli	should be able to detect such
     a change.	If an attacker can remember the	encrypted data,	he can over-
     write any future changes with the data he owns without notice.  In	other
     words geli	will not protect your data against replay attacks.

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.	Support	for Camellia block
     cipher is implemented by Yoshisato	Yanagisawa in FreeBSD 7.0.

AUTHORS
     Pawel Jakub Dawidek <pjd@FreeBSD.org>

FreeBSD	9.3		      September	16, 2006		   FreeBSD 9.3

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

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

home | help