| GELI(8) | MidnightBSD System Manager's Manual | GELI(8) |
geli — control
utility for the cryptographic GEOM class
To compile GEOM_ELI into your kernel, add the following lines to your kernel configuration file:
device crypto
options GEOM_ELIAlternatively, to load the GEOM_ELI module at boot time, add the following line to your loader.conf(5):
geom_eli_load="YES"
Usage of the geli
utility:
geli |
init [-bdgPTv]
[-a aalgo]
[-B backupfile]
[-e ealgo]
[-i iterations]
[-J newpassfile]
[-K newkeyfile]
[-l keylen]
[-s sectorsize]
[-V version]
prov ... |
geli |
label - an alias for
init |
geli |
attach [-Cdprv]
[-n keyno]
[-j passfile]
[-k keyfile]
prov ... |
geli |
detach [-fl]
prov ... |
geli |
stop - an alias for
detach |
geli |
onetime [-dT]
[-a aalgo]
[-e ealgo]
[-l keylen]
[-s sectorsize]
prov |
geli |
configure [-bBdDgGtT]
prov ... |
geli |
setkey [-pPv]
[-i iterations]
[-j passfile]
[-J newpassfile]
[-k keyfile]
[-K newkeyfile]
[-n keyno]
prov |
geli |
delkey [-afv]
[-n keyno]
prov |
geli |
kill [-av]
[prov ...] |
geli |
backup [-v]
prov file |
geli |
restore [-fv]
file prov |
geli |
suspend [-v]
-a | prov ... |
geli |
resume [-pv]
[-j passfile]
[-k keyfile]
prov |
geli |
resize [-v]
-s oldsize
prov |
geli |
version [prov ...] |
geli |
clear [-v]
prov ... |
geli |
dump [-v]
prov ... |
geli |
list |
geli |
status |
geli |
load |
geli |
unload |
The geli utility is used to configure
encryption on GEOM providers.
The following is a list of the most important features:
geli will make use of it automatically.AES-XTS, AES-CBC,
Blowfish-CBC, Camellia-CBC
and 3DES-CBC).HMAC/MD5, HMAC/SHA1,
HMAC/RIPEMD160,
HMAC/SHA256, HMAC/SHA384
or HMAC/SHA512.geli performs simple sector-to-sector
encryption.The first argument to geli indicates an
action to be performed:
initinit subcommand also automatically writes metadata
backups to /var/backups/<prov>.eli file. The
metadata can be recovered with the restore
subcommand described below.
Additional options include:
-a
aalgoHMAC/SHA256 algorithm, 89% of the original
provider storage will be available for use. Currently 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 encryption. The recommended algorithm
is HMAC/SHA256.-b-B
backupfile-d*’ characters.
This makes the length of the passphrase visible.-e
ealgoAES-XTS, AES-CBC,
Blowfish-CBC,
Camellia-CBC,
3DES-CBC, and NULL.
The default and recommended algorithm is
AES-XTS. NULL is
unencrypted.-g-i
iterationsgeli 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. PKCS#5v2 processing is performed once, after all parts of the
passphrase component have been read.-J
newpassfile-P option.-K
newkeyfile-l
keylen-P-J option.-s
sectorsize-TBIO_DELETE calls (i.e.,
TRIM/UNMAP). This can prevent an attacker from knowing how much space
you're actually using and which sectors contain live data, but will
also prevent the backing store (SSD, etc) from reclaiming space you're
not using, which may degrade its performance and lifespan. The
underlying provider may or may not actually obliterate the deleted
sectors when TRIM is enabled, so it should not be considered to add
any security.-V
versionFreeBSD/GELI versions. Consult the
HISTORY section to find which
metadata version is supported by which FreeBSD
version. Note that using an older version of metadata may limit the
number of features available.attachattach command if they all have the same
passphrase and keyfiles.
Additional options include:
-C-d-l option for the
detach subcommand.-n
keyno-j
passfile-J option for the init
subcommand. The same passfiles are used for all listed providers.-k
keyfile-K option for the init
subcommand. The same keyfiles are used for all listed providers.-p-j option.-rdetachAdditional options include:
-f-lonetimeAdditional options include:
-a
aalgoinit
subcommand.-e
ealgoinit subcommand.-dattach
subcommand.-l
keyleninit subcommand.-s
sectorsizeinit subcommand.-Tinit subcommand.configureAdditional options include:
-binit subcommand.-B-d*’ characters.
This makes the length of the passphrase visible.-D-g-G-tinit subcommand.-Tsetkeyinit subcommand, only key number 0 is initialized.
The User Key can be changed at any time: 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 existing passphrase/keyfile.
Additional options include:
-i
iterationssetkey subcommand, only one key has to be
defined and this key must be changed.-j
passfile-J
newpassfile-k
keyfile-K
newkeyfile-n
keyno-p-j option.-P-J option.delkeysetkey subcommand because the
Master Key is still in memory.
Additional options include:
-a-f option).-f-n
keynokill-r flag, the keys
will not be destroyed, only the provider will be detached.
Additional options include:
-abackuprestoreAdditional options include:
-fgeli will refuse to restore the data unless
the -f switch is used. If the partition or
slice has been grown, the resize subcommand
should be used rather than attempting to relocate the metadata through
backup and
restore.suspendresume subcommand is executed. This functionality
is useful for laptops. Suspending a laptop should not leave an encrypted
device attached. The suspend subcommand can be
used rather than closing all files and directories from filesystems on the
encrypted device, unmounting the filesystem, and detaching the device. Any
access to the encrypted device will be blocked until the Master Key is
reloaded through the resume subcommand. Thus there
is no need to close nor unmount anything. The
suspend subcommand does not work with devices
created with the onetime subcommand. Please note
that sensitive data might still be present in memory locations such as the
filesystem cache after suspending an encrypted device.
Additional options include:
-ageli devices.resumegeli utility is stored is a bad idea.
Additional options include:
-j
passfile-J option for the init
subcommand.-k
keyfile-K option for the init
subcommand.-p-j option.resizegeli that the provider has been resized.
The old metadata block is relocated to the correct position at the end of
the provider and the provider size is updated.
Additional options include:
-s
oldsizeversionversion subcommand
will print the version of geli userland utility as
well as the version of the ELI GEOM class.
If GEOM providers are specified, the
version subcommand will print metadata version
used by each of them.
cleardumpliststatusloadunloadAdditional options include:
-vUpon init, the
geli utility generates a random Master Key for the
provider. The Master Key never changes during the lifetime of the provider.
Each copy of the provider metadata, active or backed up to a file, can store
up to two, independently-encrypted copies of the Master Key.
Each stored copy of the Master Key is encrypted with a User Key,
which is generated by the geli utility from a
passphrase and/or a keyfile. The geli utility first
reads all parts of the keyfile in the order specified on the command line,
then reads all parts of the stored passphrase in the order specified on the
command line. If no passphrase parts are specified, the system prompts the
user to enter the passphrase. The passphrase is optionally strengthened by
PKCS#5v2. The User Key is a digest computed over the concatenated keyfile
and passphrase.
During operation, one or more Data Keys are deterministically derived by the kernel from the Master Key and cached in memory. The number of Data Keys used by a given provider, and the way they are derived, depend on the GELI version and whether the provider is configured to use data authentication.
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. Some variables can
also be set in /boot/loader.conf.
ELI GEOM class.ELI GEOM class. This can be set
to a number between 0 and 3 inclusive. If set to 0, minimal debug
information is printed. If set to 3, the maximum amount of debug
information is printed.Exit status is 0 on success, and 1 if the command fails.
Support for the Blowfish-CBC and
3DES-CBC cryptographic algorithms and
HMAC/MD5 authentication algorithm will be removed in
FreeBSD 13.0. New volumes cannot be created using
these algorithms. Existing volumes should be migrated to a new volume that
uses non-deprecated algorithms.
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 filesystem, 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 User Keys: one for your employee and one for you as the company's security officer (so it is not a tragedy if the employee "accidentally" forgets his passphrase):
# geli init /dev/da2 Enter new passphrase: (enter security officer's passphrase) Reenter new passphrase: # geli setkey -n 1 /dev/da2 Enter passphrase: (enter security officer's passphrase) Enter new passphrase: (let your employee enter his passphrase ...) Reenter new passphrase: (... twice)
You are the security officer in your company. Create an encrypted provider for use by the user, but remember that users forget their passphrases, so backup the Master Key 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/ada0s1e # geli backup /dev/ada0s1e /mnt/pendrive/backups/`hostname` (use key number 0, so the encrypted Master Key will be re-encrypted by this) # geli setkey -n 0 -k /mnt/pendrive/keys/`hostname` /dev/ada0s1e (allow the user to enter his passphrase) Enter new passphrase: Reenter new passphrase:
Encrypted swap partition setup:
# dd if=/dev/random of=/dev/ada0s1b bs=1m # geli onetime -d -e 3des ada0s1b # swapon /dev/ada0s1b.eli
The example below shows how to configure two providers which will be attached on boot, before the root filesystem is mounted. One of them is using passphrase and three keyfile parts and the other is using only a keyfile in one part:
# 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 # geli init -b -K /boot/keys/da0.key0 -K /boot/keys/da0.key1 -K /boot/keys/da0.key2 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 these 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"
If there is only one keyfile, the index might be omitted:
geli_da1s3a_keyfile_load="YES" geli_da1s3a_keyfile_type="da1s3a:geli_keyfile" geli_da1s3a_keyfile_name="/boot/keys/da1s3a.key"
By convention, these loader variables are called
geli_<device>_load.
However, the actual name prefix before _load,
_type, or _name does not matter.
At boot time, the geli module searches through all
<prefix>_type-like
variables that have a value of
“<device>:geli_keyfile”.
The paths to keyfiles are then extracted from
<prefix>_name
variables. In the example above, prefix is
“geli_da1s3a_keyfile”.
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
geli writes the metadata backup by default
to the /var/backups/<prov>.eli file. If the
metadata is lost in any way (e.g., 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:
If an encrypted filesystem is extended, it is necessary to relocate and update the metadata:
# gpart create -s GPT ada0 # gpart add -s 1g -t freebsd-ufs -i 1 ada0 # geli init -K keyfile -P ada0p1 # gpart resize -s 2g -i 1 ada0 # geli resize -s 1g ada0p1 # geli attach -k keyfile -p ada0p1
Initialize provider with the passphrase split into two files. The
provider can be attached using those two files or by entering
“foobar” as the passphrase at the geli
prompt:
# echo foo > da0.pass0 # echo bar > da0.pass1 # geli init -J da0.pass0 -J da0.pass1 da0 # geli attach -j da0.pass0 -j da0.pass1 da0 # geli detach da0 # geli attach da0 Enter passphrase: foobar
Suspend all geli devices on a laptop,
suspend the laptop, then resume devices one by one after resuming the
laptop:
# geli suspend -a # zzz <resume your laptop> # geli resume -p -k keyfile gpt/secret # geli resume gpt/private Enter passphrase:
To create a geli encrypted filesystem with
a file as storage device follow this example. First a file named private0 is
created in /usr and attached as a memory disk like
/dev/md0 for example.
# dd if=/dev/zero of=/usr/private0 bs=1m count=256 # chmod 0600 /usr/private0 # mdconfig -t vnode -f /usr/private0
It is recommended to place the following line in rc.conf(5) to have the memory disk automatically created during boot.
mdconfig_md0="-t vnode -f /usr/private0"
After /dev/md0 is created a random key has to be generated and stored in a secure location, like /root for example. This key should be protected by a passphrase, which is requested when geli init is called.
# dd if=/dev/random of=/root/private0.key bs=64 count=1 # geli init -K /root/private0.key -s 4096 /dev/md0 Enter new passphrase: Reenter new passphrase: # geli attach -k /root/private0.key /dev/md0 Enter passphrase: # dd if=/dev/random of=/dev/md0.eli bs=1m
Once the initialization of the /dev/md0.eli device is ready create a UFS filesystem and mount it for example in /private.
# newfs /dev/md0.eli # mount /dev/md0.eli /private
After a system reboot the geli device can
be mounted again with the following commands. The call of geli attach will
ask for the passphrase. It is recommended to do this procedure after the
boot, because otherwise the boot process would be waiting for the passphrase
input.
# geli attach -k /root/private0.key /dev/md0 Enter passphrase: # mount /dev/md0.eli /private
geli supports two encryption modes:
XTS, which was standardized as IEEE
P1619 and CBC with unpredictable IV. The
CBC mode used by geli is
very similar to the mode ESSIV.
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 it being noticed. In other words geli will
not protect your data against replay attacks.
It is recommended to write to the whole provider before first use, in order to make sure that all sectors and their corresponding checksums are properly initialized into a consistent state. One can safely ignore data authentication errors that occur immediately after the first time a provider is attached and before it is initialized in this way.
crypto(4), gbde(4), geom(4), loader.conf(5), gbde(8), geom(8), crypto(9)
The geli utility appeared in
FreeBSD 6.0. Support for the
Camellia block cipher was implemented by Yoshisato
Yanagisawa in FreeBSD 7.0.
Highest GELI metadata version supported by
the given FreeBSD version:
| FreeBSD | GELI |
| version | version |
6.0 |
0 |
6.1 |
0 |
6.2 |
3 |
6.3 |
3 |
6.4 |
3 |
7.0 |
3 |
7.1 |
3 |
7.2 |
3 |
7.3 |
3 |
7.4 |
3 |
8.0 |
3 |
8.1 |
3 |
8.2 |
5 |
9.0 |
6 |
10.0 |
7 |
Pawel Jakub Dawidek <pjd@FreeBSD.org>
| October 15, 2020 | midnightbsd-3.1 |