GELI

All commands assume that you've setup a partition already, that isn't formatted, with the name ada0p1 (change if necessary). And for anything but init and attach we're assuming it's attached...

What is GELI?

GELI is the standard disk-encryption for FreeBSD (and ArchBSD).

GELI can use pretty much anything for encryption, as long as libcrypto can encrypt/decrypt it. This includes passphrases, key-files, parts of files, etc. It also has support for multiple keys (a user key and a company key, for example) and can also use one-time keys for e.g. swap-partitions. And, because GELI uses libcrypto as it's backend, it has crypto hardware support where available.

Why?

Same as with ZFS, multiple reasons.

1) Improved privacy (if done correctly)

2) Company rules (Loads of companies that require disk-encryption)

3) Paranoia

4) Because you can...

5) Warez & Pr0n ;)

Setting up GELI

GELI goes in between the GEOM and the FS, hence the correct order is:

gpart add...

geli init...

geli attach...

format ...

Simple encrypted partition with only passphrase

geli init ada0p1

(Enter the passphrase twice, and you're done)

Same as above but with Blowfish-CBC as the encryption (see below for supported algos)

geli init -e Blowfish-CBC ada0p1

Same as first one, but with integrity-checks (this takes up a lot of space, just FYI)

geli init -a HMAC/SHA512 ada0p1

If you're attaching this provider at boot-time, then you might want it to ask for passphrase on boot

geli init -b ada0p1

Using a key-file

geli init -K /path/to/file -s 4096 -l 256 ada0p1

where 4096 is the sectorsize (bigger sector, slower performance) and 256 is the length (number of sectors)

Using a pass-file

geli init -J /path/to/passfile ada0p1

(This one obviously doesn't work with the one below)

And finally using a key-file without a passphrase

geli init -P -K /path/to/file -s 4096 -l 256 ada0p1

Attaching a GELI-provider

Attaching a GELI-GEOM will create a new GEOM-provider named <prov>.eli, so mounting a GELI-encrypted FS on ada0p1 would look like this:

geli attach ada0p1

mount /dev/ada0p1.eli /mnt

Attaching using a key-file

geli attach -k /path/to/keyfile ada0p1

Attaching using a passphrase-file

geli attach -p /path/to/passfile ada0p1

Attach in read-only

geli attach -r ada0p1

Detaching a GELI-GEOM

Detaching can be done in several ways

Regular

geli detach ada0p1.eli

Forcefully (I.e. detach even if the provider is mounted/in-use)

geli detach -f ada0p1.eli

Marking it for detach on close (I.e. when it's unmounted/not in-use)

geli detach -l ada0p1.eli

Onetime Providers

GELI also has support for creating providers with a random one-time key. Useful for encrypting swap partitions of temporary file systems.

Using a specific encryption-algorithm

geli onetime -e Blowfish-CBC ada0p1

Using a specific data integrity-algorithm

geli onetime -a HMAC/SHA512 ada0p1

Detach on close

geli onetime -d ada0p1

Using a specific sectorsize and keylength

geli onetime -s 4096 -l 256 ada0p1

Good example would be to encrypt your swap-partition.

dd if=/dev/random of=/dev/ada0p1 bs=1m
geli onetime -d -e 3des ada0p1
swapon /dev/ada0p1.eli

Changing the boot-flag

If you've setup GELI over a 24-disk cluster, and accidentally selected the "enter passphrase on boot"-flag, here's how to make your life easy again :)

geli configure -B ada0p1.eli

And if you forgot to set the passphrase-on-boot flag, there's how to set it

geli configure -b ada0p1.eli

Setting/Changing the keys

Say that your key-files or passphrase/file got compromised and now you want to change it/them without backing up everything and do it all over. Or your setup only uses a key-file and no passphrase, or wise versa, you get the idea...

(This can be done attached or detached. If it's attached you don't have the enter the passphrase...)

This command has all the parameters that init has, and here are the extra...

(These examples assume attached providers, remove '.eli' for detached)

Setup a new key-file with no old key-file and no passphrases

geli setkey -p -P -K /path/to/newkeyfile ada0p1.eli

Change the old key-file (no old or new passphrase)

geli setkey -p -P -k /path/to/oldkeyfile -K /path/to/newkeyfile ada0p1.eli

Setup a second key-file with an old passphrase but no new passphrase

geli setkey -n 1 -P -K /path/to/newkeyfile ada0p1.eli

Change the old pass-file

geli setkey -j /path/to/oldpassfile -J /path/to/newpassfile ada0p1.eli

Deleting a key

So, you've setup a user-key and that user has gone haywire, now you want to remove his key, here how to do that

Remove the second key

geli delkey -n 1 ada0p1.eli

If you're removing the key that attached the provider you'll have to force it (no need to specify the key# when working on the key that attached it)

geli delkey -f ada0p1.eli

Destroy all keys (this is probably stupid if there's a power-outage)

geli delkey -a ada0p1.eli

(No need for -f[orce] here)

NSA is knocking on my doorstep!!! (or, How to remove all traces of the data/encryption)

So, NSA is here to pick up your warez-server and now you're gonna try and get away with it ;)

For that we have

geli kill

This command will detach the provider forcefully, destroy the keys and your data will be lost if you don't have a backup!

WARNING: You'll need a BACKUP of the METADATA when using this command our your DATA WILL BE LOST!!!

Note: how to do a backup is listed below...

Kill a specific provider

geli kill ada0p1.eli

Kill _all_ providers

geli kill -a

(In-case the provider was attached with -r[ead-only] then the keys won't be destroyed, the provider will only be detached!)

Backup/Restore

Now for the best part, backups. Always keep backups of all providers somewhere same (e.g. your mom's basement...)

Backing up metadata for a specific provider

geli backup ada0p1.eli /path/to/backup

Restoring metadata to a specific provider (safe-mode, checks if the size of the geom is the same)

geli restore ada0p1.eli /path/to/backup

Restoring metadata to a specific provider (force)

geli restore -f ada0p1.eli /path/to/backup

Suspending/Resuming

This is useful for laptops where you don't want the provider to be attached when it's put in suspend.

Note: Don't do this on the provider that has /sbin in it, as /sbin/geli has to be accessable, otherwise it will deadlock. Same goes for the key-file (is any)

Suspending specific provider

geli suspend ada0p1.eli

Suspending add providers (don't do this if /sbin or key/pass-file is in a GELI-provider)

geli suspend -a

Resuming specific provider

geli resume ada0p1.eli

Resuming provider with key-file (and manual passphrase)

geli resume -k /path/to/keyfile ada0p1.eli

Resuming provider with key-file (no passphrase)

geli resume -p -k /path/to/keyfile ada0p1.eli

Resuming provider with pass-file

geli resume -j /path/to/passfile ada0p1.eli

Resuming provider with key-file and pass-file

geli resume -k /path/to/keyfile -j /path/to/passfile ada0p1.eli

Resizing Provider

So, you've resized your GEOM and now the provider won't attach... Well, you'll have to resize the provider too.

geli resize ada0p1.eli

If you know the old size you can do this for an extra check...

geli resize -s [oldsize] ada0p1.eli

More reading

man geli

(Do I even have to tell you?)