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

FreeBSD Manual Pages

  
 
  

home | help
GELI(8)			    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 fol-
       lowing line in your loader.conf(5):

	     geom_eli_load="YES"

       Usage of	the geli(8) utility:

       geli init [-bPv]	[-a aalgo] [-B backupfile] [-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:

	     	 Utilizes  the	crypto(9)  framework,  so when there is	crypto
		 hardware available, geli will make use	of it automatically.
	     	 Supports  many	 cryptographic	algorithms   (currently	  AES,
		 Blowfish, Camellia and	3DES).
	     	 Can optionally	perform	data authentication (integrity verifi-
		 cation)  utilizing one	of the following algorithms: HMAC/MD5,
		 HMAC/SHA1,  HMAC/RIPEMD160,   HMAC/SHA256,   HMAC/SHA384   or
		 HMAC/SHA512.
	     	 Can  create  a	 key from a couple of components (user entered
		 passphrase, random bits from a	file, etc.).
	     	 Allows	to encrypt the root partition -	the user will be asked
		 for the passphrase before the root file system	is mounted.
	     	 The passphrase	of the user is strengthened with: B.  Kaliski,
		 PKCS  #5:  Password-Based Cryptography	Specification, Version
		 2.0., RFC, 2898.
	     	 Allows	to use two independent	keys  (e.g.   "user  key"  and
		 "company key").
	     	 It  is	 fast  - geli performs simple sector-to-sector encryp-
		 tion.
	     	 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.
	     	 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).
	     	 Allows	 to  attach  a	provider with a	random,	one-time key -
		 useful	for swap partitions and	temporary file systems.
	     	 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.
		  The  init  subcommand	also automatically backups metadata in
		  /var/backups/<prov>.eli file.	 The metadata can be recovered
		  with the restore subcommand described	below.

		  Additional options include:

		  -a aalgo  Enable data	 integrity  verification  (authentica-
			    tion) using	the given algorithm.  This will	reduce
			    size  of  available	storage	and also reduce	speed.
			    For	example, when  using  4096  bytes  sector  and
			    HMAC/SHA256	  algorithm,   89%   of	 the  original
			    provider storage will be available for use.	  Cur-
			    rently   supported	 algorithms   are:   HMAC/MD5,
			    HMAC/SHA1,	    HMAC/RIPEMD160,	  HMAC/SHA256,
			    HMAC/SHA384	and HMAC/SHA512.  If the option	is not
			    given,  there  will	be no authentication, only en-
			    cryption.	 The	recommended    algorithm    is
			    HMAC/SHA256.

		  -b	    Ask	 for  the  passphrase on boot, before the root
			    partition 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.

		  -B backupfile
			    File name to use for metadata  backup  instead  of
			    the	 default  /var/backups/<prov>.eli.  To inhibit
			    backups, you can use none as the backupfile.

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

		  -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 al-
			    gorithm.  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.

		  -P	    Do not use passphrase as the key component.

		  -s sectorsize
			    Change decrypted provider's	sector size.  Increas-
			    ing	 sector	 size  allows to increase performance,
			    because we need to	generate  an  IV  and  do  en-
			    crypt/decrypt  for every single sector - less num-
			    ber	of sectors means less work to do.

       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  sys-
			   tem.	  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 sub-
			   command.

		  -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.

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

       detach	  Detach the given providers, which means remove the devfs en-
		  try 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 op-
			   tion	 is  specified,	 the  provider will not	be de-
			   tached 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 (authentica-
			    tion).  For	more information, see the  description
			    of the init	subcommand.

		  -e ealgo  Encryption	algorithm  to  use.  For more informa-
			    tion, see the description of the init subcommand.

		  -d	    Detach on last close.  Note, the option is not us-
			    able 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  de-
			    scription of the attach subcommand.

		  -l keylen
			    Key	length to use with the given cryptographic al-
			    gorithm.   For  more information, see the descrip-
			    tion of the	init subcommand.

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

       configure  Change configuration of the given providers.

		  Additional options include:

		  -b  Set  the BOOT flag on the	given providers.  For more in-
		      formation, 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 in-
		  dependent  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  de-
			   tached  (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 de-
		  stroyed.  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 at-
			   tached 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 vari-
       able.  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  in-
	       formation 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  (be-
	       fore  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
	       software	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	batch-
	       ing.   Batching	allows	to  reduce number of interrupts	by re-
	       sponding	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
       keyfile:

	     # 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 us-
       ing 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

       geli  backups  metadata by default to the /var/backups/<prov>.eli file.
       If metadata is lost in any way (eg. by accidental overwrite), it	can be
       restored.  Consider the following situation:

	     # geli init /dev/da0
	     Enter new passphrase:
	     Reenter new passphrase:

	     Metadata backup can be found in /var/backups/da0.eli and
	     can be restored with the following	command:

		     # geli restore /var/backups/da0.eli /dev/da0

	     # geli clear /dev/da0
	     # geli attach /dev/da0
	     geli: Cannot read metadata	from /dev/da0: Invalid argument.
	     # geli restore /var/backups/da0.eli /dev/da0
	     # geli attach /dev/da0
	     Enter passphrase:

DATA AUTHENTICATION
       geli can	verify data integrity  when  an	 authentication	 algorithm  is
       specified.   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 overwrite 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>

GNU				August 29, 2008			       GELI(8)

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

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

home | help