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 following 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 automati

cally.; +o Supports many cryptographic algorithms (currently

AES

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 de
tach 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 sys; tems.
The first argument to geli indicates an action to be per
formed:
init Initialize provider which needs to be encrypt
ed. 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 sup
ported algorithms are: AES,

Blowfish

3DES. The default is AES.
-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 un; encrypted
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
crypto: graphic algorithm. If not giv; en, the default
key length for the given algo; rithm is used,
which is: 128 for AES, 128 for

Blowfish

192 for 3DES.
-s sectorsize Change decrypted provider's sec
tor 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 - us

er 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: command can be used to encrypt swap partitions; or temporary
file systems.; Additional options include:; -a algo Encryption algorithm to use.; For more infor
mation, 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
crypto: graphic algorithm. For more in; formation, see
the description of the init sub; command.
-s sectorsize Change decrypted provider's sec
tor size. For: more information, see the de; scription of the
init subcommand.
setkey Change or setup (if not yet initialized) se
lected key.: There is one master key, which can be encrypted; with two
independent user keys. With the init subcom; mand, 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 de; crypted with the
passphrase/keyfile will be; changed.
-p Do not use passphrase as the old
key compo: nent.
-P Do not use passphrase as the new
key compo: nent.
delkey Destroy (overwrite with random data) the se
lected 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 op; tion 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 de; tached (or we
are operating on a backup file); the key number has to be given.
kill This command should be used in emergency situa
tions. It: will destroy all keys on the given provider and; will detach
it forcibly (if it is attached). This is abso; lutely a oneway command - if you do not have a metadata; backup, your
data is gone for good.; -a If specified, all currently at; tached
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 de; bug information is printed. If set to 3, the maximum amount of; debug information 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, attach; ing 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 op; eration 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 possibili; ty 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 per; formance on SMP
systems. If hardware acceleration is available, on; ly 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 en
crypted 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/`host; name`
(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 us
ing 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"

HISTORY

The geli utility appeared in FreeBSD 6.0.

AUTHORS

Pawel Jakub Dawidek <pjd@FreeBSD.org>
BSD February 11, 2006

docs.sk

comprehensive documentation repository

See also

geli(8)

NAME

SYNOPSIS

DESCRIPTION

AES

Blowfish

Blowfish

SYSCTL VARIABLES

EXIT STATUS

EXAMPLES

SEE ALSO

HISTORY

AUTHORS