Add GEOM_ELI class which provides GEOM providers encryption.

For features list and usage see manual page: geli(8).

Sponsored by:	Wheel Sp. z o.o.
		http://www.wheel.pl
MFC after:	1 week

1 files changed, 511 insertions, 0 deletions

diff --git a/sbin/geom/class/eli/geli.8 b/sbin/geom/class/eli/geli.8
new file mode 100644
index 0000000..edf11e7
--- /dev/null
+++ b/sbin/geom/class/eli/geli.8
@@ -0,0 +1,511 @@
+.\" Copyright (c) 2005 Pawel Jakub Dawidek <pjd@FreeBSD.org>
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd April 11, 2005
+.Dt GELI 8
+.Os
+.Sh NAME
+.Nm geli
+.Nd "control utility for cryptographic GEOM class"
+.Sh SYNOPSIS
+To compile GEOM_ELI into your kernel, place the following lines in your kernel
+configuration file:
+.Bd -ragged -offset indent
+.Cd "device crypto"
+.Cd "device cryptodev"
+.Cd "options GEOM_ELI"
+.Ed
+.Pp
+Alternately, to load the GEOM_ELI module at boot time, place the following line
+in your
+.Xr loader.conf 5 :
+.Bd -literal -offset indent
+geom_eli_load="YES"
+.Ed
+.Pp
+Usage of the
+.Xr geli 8
+utility:
+.Pp
+.Nm
+.Cm init
+.Op Fl bPv
+.Op Fl a Ar algo
+.Op Fl i Ar iterations
+.Op Fl K Ar newkeyfile
+.Op Fl l Ar keylen
+.Op Fl s Ar sectorsize
+.Ar prov
+.Nm
+.Cm label - an alias for
+.Cm init
+.Nm
+.Cm attach
+.Op Fl dpv
+.Op Fl k Ar keyfile
+.Ar prov
+.Nm
+.Cm detach
+.Op Fl fl
+.Ar prov ...
+.Nm
+.Cm stop - an alias for
+.Cm detach
+.Nm
+.Cm onetime
+.Op Fl d
+.Op Fl a Ar algo
+.Op Fl l Ar keylen
+.Op Fl s Ar sectorsize
+.Ar prov ...
+.Nm
+.Cm setkey
+.Op Fl pPv
+.Op Fl k Ar keyfile
+.Op Fl K Ar newkeyfile
+.Op Fl n Ar keyno
+.Ar prov
+.Nm
+.Cm delkey
+.Op Fl afv
+.Op Fl n Ar keyno
+.Ar prov
+.Nm
+.Cm kill
+.Op Fl av
+.Op Ar prov ...
+.Nm
+.Cm backup
+.Op Fl v
+.Ar prov
+.Ar file
+.Nm
+.Cm restore
+.Op Fl v
+.Ar file
+.Ar prov
+.Nm
+.Cm clear
+.Op Fl v
+.Ar prov ...
+.Nm
+.Cm dump
+.Op Fl v
+.Ar prov ...
+.Nm
+.Cm list
+.Nm
+.Cm status
+.Nm
+.Cm load
+.Nm
+.Cm unload
+.Sh DESCRIPTION
+The
+.Nm
+utility is used to configure encryption on GEOM providers.
+.Pp
+Here is the list of the most important features:
+.Pp
+.Bl -bullet -offset indent -compact
+.It
+Utilize the
+.Xr crypto 9
+framework, so when there is a crypto hardware available,
+.Nm
+will make use of it automatically.
+If cryptography needs to be done in software,
+a dedicated kernel thread will be started to do the crypto work in there.
+.It
+Supports many cryptographic algorithms (currently
+.Nm AES ,
+.Nm Blowfish
+and
+.Nm 3DES ) .
+.It
+Can create a key from a couple of components (user entered passphrase, random
+bits from a file, etc.).
+.It
+Allows to encrypt root partition - user will be asked for the passphrase before
+root file system is mounted.
+.It
+User's passphrase is strengthen with:
+.Rs 
+.%A B. Kaliski
+.%T "PKCS #5: Password-Based Cryptography Specification, Version 2.0."
+.%R RFC
+.%N 2898
+.Re
+.It
+Allows to use two independent keys (e.g.
+.Qq "user key"
+and
+.Qq "company key" ) .
+.It
+It is fast - 
+.Nm
+performs simple sector-to-sector encryption.
+.It
+Allows to backup/restore Master Keys, so when user have to quickly destroy keys,
+it is able to get the data back by restoring keys from the backup.
+.It
+Provider can be configured to automatically detach on last close (so user don't
+have to remember to detach provider after unmounting file system).
+.It
+Allows to attach provider with a random, one-time keys - useful for swap
+partitions and temporary file systems.
+.El
+.Pp
+The first argument to
+.Nm
+indicates an action to be performed:
+.Bl -tag -width ".Cm onetime"
+.It Cm init
+Initialize provider which needs to be encrypted.
+Here you can setup cryptographic algorithm to use, key length, etc.
+The last provider's sector is used to store metadata.
+.Pp
+Additional options include:
+.Bl -tag -width ".Fl a Ar algo"
+.It Fl a Ar algo
+Encryption algorithm to use.
+Currently supported algorithms are:
+.Nm AES ,
+.Nm Blowfish
+and
+.Nm 3DES .
+The default is
+.Nm AES .
+.It Fl b
+Ask for the passphrase on boot, before root partition is mounted.
+This allows to use encrypted root partition.
+One will still need bootable unencrypted storage with
+.Pa /boot/
+directory, which can be a CD-ROM disc or USB pen-drive, which can be removed
+after boot.
+.It Fl i Ar iterations
+Number of iterations to use with PKCS#5v2.
+If this option is not specified
+.Nm
+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.
+.It Fl K Ar newkeyfile
+Specifies a file which contains part of the key.
+If
+.Ar newkeyfile
+is given as -, standard input will be used.
+Here is how more than one file with the key component can be used:
+.Bd -literal -offset indent
+# cat key1 key2 key3 | geli init -K - /dev/da0
+.Ed
+.It Fl l Ar keylen
+Key length to use with the given cryptographic algorithm.
+If not given, the default key length for the given algorithm is used, which is:
+128 for
+.Nm AES ,
+128 for
+.Nm Blowfish
+and 192 for
+.Nm 3DES .
+.It Fl s Ar sectorsize
+Change decrypted provider's sector size.
+Increasing sector size allows to increase performance, because we need to
+generate IV and do encrypt/decrypt for every single sector - less number
+of sectors means less work to do.
+.It Fl P
+Do not use passphrase as the key component.
+.El
+.It Cm 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
+.Qq .eli
+suffix.
+.Pp
+Additional options include:
+.Bl -tag -width ".Fl a Ar algo"
+.It Fl d
+If specified, decrypted provider will be detached automatically on last close.
+This can help with short memory - user doesn't have to remember to detach
+provider after unmounting file system.
+It only works when provider was opened for writing, so it will not work if
+file system on the provider is mounted read-only.
+Probably better choice is the
+.Fl l
+option for the
+.Cm detach
+subcommand.
+.It Fl k Ar keyfile
+Specifies a file which contains part of the key.
+For more information see description of
+.Fl K
+option for the
+.Cm init
+subcommand.
+.It Fl p
+Do not use passphrase as the key component.
+.El
+.It Cm detach
+Detach the given providers, which means remove devfs entry and clear the keys
+from memory.
+.Pp
+Additional options include:
+.Bl -tag -width ".Fl a Ar algo"
+.It Fl f
+Force detach - detach even if provider is open.
+.It Fl l
+Mark provider to detach on last close.
+If this option is specified 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).
+.El
+.It Cm onetime
+Attach the given providers with a random, one-time keys.
+The command can be used to encrypt swap partitions or temporary file systems.
+.Pp
+Additional options include:
+.Bl -tag -width ".Fl a Ar algo"
+.It Fl a Ar algo
+Encryption algorithm to use.
+For more information see description of the
+.Cm init
+subcommand.
+.It Fl d
+Detach on last close.
+Note, the option is not usable for temporary file system, because provider will
+be detached after creating file system on it.
+It still can (and should be) used for swap partitions.
+For more information see description of the
+.Cm attach
+subcommand.
+.It Fl l Ar keylen
+Key length to use with the given cryptographic algorithm.
+For more information see description of the
+.Cm init
+subcommand.
+.It Fl s Ar sectorsize
+Change decrypted provider's sector size.
+For more information see description of the
+.Cm init
+subcommand.
+.El
+.It Cm 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
+.Cm init
+subcommand only key number 0 is initialized.
+The key can be always changed: for attached provider, for detached provider or
+on the backup file.
+When provider is attached, user don't have to provide an old passphrase/keyfile.
+.Pp
+Additional options include:
+.Bl -tag -width ".Fl a Ar algo"
+.It Fl k Ar keyfile
+Specifies a file which contains part of the old key.
+.It Fl K Ar newkeyfile
+Specifies a file which contains part of the new key.
+.It Fl n Ar keyno
+Specifies number of the key to change (could be 0 or 1).
+If provider is attached and no key number is given, the key used for attaching
+provider will be changed.
+If provider is detached (or we're operating on a backup file) and no key number
+is given, the key decrypted with passphrase/keyfile will be changed.
+.It Fl p
+Do not use passphrase as the old key component.
+.It Fl P
+Do not use passphrase as the new key component.
+.El
+.It Cm delkey
+Destroy (overwrite with random data) selected key.
+If one is destroying keys for an attached provider, provider won't be detached
+even if all keys will be destroyed.
+It can be even rescued with the
+.Cm setkey
+subcommand.
+.Bl -tag -width ".Fl a Ar algo"
+.It Fl a
+Destroy all keys (doesn't need
+.Fl f
+option).
+.It Fl f
+Force key destruction. This option is needed to destroy the last key.
+.It Fl n Ar keyno
+Specifies the key number.
+If provider is attached and no key number is given, the key used for attaching
+provider will be destroyed.
+If provider is detached (or we're operating on a backup file) the key number
+has to be given.
+.El
+.It Cm kill
+The 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 one-way command - if you don't have metadata backup, your data
+is gone for good.
+.Bl -tag -width ".Fl a Ar algo"
+.It Fl a
+If specified, all currently attached providers will be killed.
+.El
+.It Cm backup
+Backup metadata from the given provider to the given file.
+.It Cm restore
+Restore metadata from the given file to the given provider.
+.It Cm clear
+Clear metadata from the given providers.
+.It Cm dump
+Dump metadata stored on the given providers.
+.It Cm list
+See
+.Xr geom 8 .
+.It Cm status
+See
+.Xr geom 8 .
+.It Cm load
+See
+.Xr geom 8 .
+.It Cm unload
+See
+.Xr geom 8 .
+.El
+.Pp
+Additional options include:
+.Bl -tag -width ".Fl v"
+.It Fl v
+Be more verbose.
+.El
+.Sh SYSCTL VARIABLES
+The following
+.Xr sysctl 8
+variables can be used to control the behavior of the
+.Nm ELI
+GEOM class.
+The default value is shown next to each variable.
+.Bl -tag -width indent
+.It Va kern.geom.eli.debug : No 0
+Debug level of the
+.Nm ELI
+GEOM class.
+This can be set to a number between 0 and 3 inclusive.
+If set to 0 minimal debug information is printed, and if set to 3 the
+maximum amount of debug information is printed.
+This variable could be set in
+.Pa /boot/loader.conf .
+.It Va kern.geom.eli.tries : No 3
+Number of times user is asked for the passphrase.
+This is only used for providers which should be attached on boot (before root
+file system is mounted).
+If set to 0, attaching providers on boot will be disabled.
+This variable should be set in
+.Pa /boot/loader.conf .
+.It Va kern.geom.eli.overwrites : No 5
+Specifies how many times Master-Key will be overwriten with random values when
+it is destroyed. After this operation it is filled with zeros.
+.It Va kern.geom.eli.visible_passphrase : No 0
+If set to 1, passphrase entered on boot (before root file system is mounted)
+will be visible.
+This possibility should be used with caution as entered passphrase can be logged
+and exposed via
+.Xr dmesg 8 .
+This variable should be set in
+.Pa /boot/loader.conf .
+.It Va kern.geom.eli.threads : No 1
+Specifies how many kernel threads should be used for doing software
+cryptography.
+It's purpose is to increase performance on SMP systems.
+This variable could be set in
+.Pa /boot/loader.conf .
+.El
+.Sh EXIT STATUS
+Exit status is 0 on success, and 1 if the command fails.
+.Sh EXAMPLES
+Initialize 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 provider and detach it:
+.Bd -literal -offset indent
+# 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
+.Ed
+.Pp
+Create encrypted provider, but use two key: one for your girlfriend and one for
+you (so there will be no tragedy if she forget her passphrase):
+.Bd -literal -offset indent
+# 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 to enter her passphrase ...)
+Reenter new passphrase:	(... twice)
+.Ed
+.Pp
+You are security-person in your company.
+Create encrypted provider for use by the user, but remember that users forget
+their passphrases, so backup Master Key with your own random key:
+.Bd -literal -offset indent
+# 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 encrypted Master Key by you will be overwriten)
+# geli setkey -n 0 -k /mnt/pendrive/keys/`hostname` /dev/ad0s1e
+(allow the user to enter his passphrase)
+Enter new passphrase:
+Reenter new passphrase:
+.Ed
+.Pp
+Encrypted swap partition setup:
+.Bd -literal -offset indent
+# dd if=/dev/random of=/dev/ad0s1b bs=1m
+# geli onetime -d -a 3des ad0s1b
+# swapon /dev/ad0s1b.eli
+.Ed
+.Sh SEE ALSO
+.Xr crypto 4 ,
+.Xr crypto 9 ,
+.Xr gbde 4 ,
+.Xr gbde 8 ,
+.Xr geom 4 ,
+.Xr geom 8
+.Sh HISTORY
+The
+.Nm
+utility appeared in
+.Fx 5.5 .
+.Sh AUTHORS
+.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org