Document geli(8) data authentication.

Supported by:	Wheel Sp. z o.o. (http://www.wheel.pl)

1 files changed, 116 insertions, 12 deletions

diff --git a/sbin/geom/class/eli/geli.8 b/sbin/geom/class/eli/geli.8
index d465099..31cf59e 100644
--- a/sbin/geom/class/eli/geli.8
+++ b/sbin/geom/class/eli/geli.8
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd February 11, 2006
+.Dd June 5, 2006
 .Dt GELI 8
 .Os
 .Sh NAME
@@ -52,7 +52,8 @@ utility:
 .Nm
 .Cm init
 .Op Fl bPv
-.Op Fl a Ar algo
+.Op Fl a Ar aalgo
+.Op Fl e Ar ealgo
 .Op Fl i Ar iterations
 .Op Fl K Ar newkeyfile
 .Op Fl l Ar keylen
@@ -76,7 +77,8 @@ utility:
 .Nm
 .Cm onetime
 .Op Fl d
-.Op Fl a Ar algo
+.Op Fl a Ar aalgo
+.Op Fl e Ar ealgo
 .Op Fl l Ar keylen
 .Op Fl s Ar sectorsize
 .Ar prov ...
@@ -144,6 +146,17 @@ Supports many cryptographic algorithms (currently
 and
 .Nm 3DES ) .
 .It
+Can optionally perform data authentication (integrity verification) with one of
+the
+.Nm HMAC/MD5 ,
+.Nm HMAC/SHA1 ,
+.Nm HMAC/RIPEMD160 ,
+.Nm HMAC/SHA256 ,
+.Nm HMAC/SHA384
+or
+.Nm HMAC/SHA512
+algorithms.
+.It
 Can create a key from a couple of components (user entered passphrase, random
 bits from a file, etc.).
 .It
@@ -177,6 +190,8 @@ the file systems).
 .It
 Allows to attach a provider with a random, one-time key - useful for swap
 partitions and temporary file systems.
+.It
+Allows to verify data integrity (data authentication).
 .El
 .Pp
 The first argument to
@@ -189,8 +204,23 @@ Here you can set up the 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
+.Bl -tag -width ".Fl a Ar aalgo"
+.It Fl a Ar aalgo
+Enable data integrity verification (authentication) using the given algorithm.
+This will reduce size of available storage and also reduce speed.
+For example, when using 4096 bytes sector and
+.Nm HMAC/SHA256
+algorithm, 89% of the original provider storage will be available for use.
+Currently supported algorithms are:
+.Nm HMAC/MD5 ,
+.Nm HMAC/SHA1 ,
+.Nm HMAC/RIPEMD160 ,
+.Nm HMAC/SHA256 ,
+.Nm HMAC/SHA384
+and
+.Nm HMAC/SHA512 .
+If the option is not given, there will be no authentication, only encryption.
+.It Fl e Ar ealgo
 Encryption algorithm to use.
 Currently supported algorithms are:
 .Nm AES ,
@@ -289,8 +319,13 @@ Attach the given providers with 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
+.Bl -tag -width ".Fl a Ar aalgo"
+.It Fl a Ar aalgo
+Enable data integrity verification (authentication).
+For more information, see the description of the
+.Cm init
+subcommand.
+.It Fl e Ar ealgo
 Encryption algorithm to use.
 For more information, see the description of the
 .Cm init
@@ -408,6 +443,39 @@ Additional options include:
 .It Fl v
 Be more verbose.
 .El
+.Sh COMPONENTS
+.Ss User derived key (Derived-Key).
+This is a SHA-512 hash calculated from concatenated components: data from
+specified keyfiles and user's passphrase.
+Passphrase is by default strengthen with PKCS#5v2/SHA-1 before it goes through
+SHA-512.
+There could be up to two such keys based on independed passphrases and keyfiles.
+This key is used to protect (encrypt) the
+.Sy Master-Key
+stored on provider (inside metadata).
+.Ss Master-Key.
+This is 128 bytes long random data. First 64 bytes are used as the
+.Sy Data-Key
+and the second 64 bytes are used as the
+.Sy IV-Key .
+There is also another 64 bytes after the Master-Key, which are reserved for
+.Fn HMAC_SHA512 "HMAC_SHA512(Derived-Key, 0)" "Master-Key"
+(used to verify correctness of the
+.Sy Derived-Key ) .
+The entire
+.Sy Master-Key
+and
+.Fn HMAC
+result is encrypted with the given encryption algorithm.
+Key for encryption is
+.Fn HMAC_SHA512 "Derived-Key" "1"
+.Ss Data-Key.
+This is the key used to encrypt every single sector with the given algorithm in
+CBC mode.
+.Ss IV-Key.
+This is the key used for creating IV.
+IV is calculated with: SHA-256(IV-Key + sector-byte-offset).
+.\" TODO
 .Sh SYSCTL VARIABLES
 The following
 .Xr sysctl 8
@@ -415,6 +483,8 @@ variables can be used to control the behavior of the
 .Nm ELI
 GEOM class.
 The default value is shown next to each variable.
+All variables can also be set in
+.Pa /boot/loader.conf .
 .Bl -tag -width indent
 .It Va kern.geom.eli.debug : No 0
 Debug level of the
@@ -424,8 +494,6 @@ 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.
-This variable could be set in
-.Pa /boot/loader.conf .
 .It Va kern.geom.eli.tries : No 3
 Number of times a user is asked for the passphrase.
 This is only used for providers which should be attached on boot
@@ -451,8 +519,11 @@ 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.
-This variable could be set in
-.Pa /boot/loader.conf .
+.It Va kern.geom.eli.batch : No 0
+When set to 1, can speed-up crypto operations by using batching.
+Batching allows to reduce number of interrupts by responding on a group of
+crypto requests with one interrupt.
+The crypto card and the driver has to support this feature.
 .El
 .Sh EXIT STATUS
 Exit status is 0 on success, and 1 if the command fails.
@@ -508,7 +579,7 @@ Reenter new passphrase:
 Encrypted swap partition setup:
 .Bd -literal -offset indent
 # dd if=/dev/random of=/dev/ad0s1b bs=1m
-# geli onetime -d -a 3des ad0s1b
+# geli onetime -d -e 3des ad0s1b
 # swapon /dev/ad0s1b.eli
 .Ed
 .Pp
@@ -546,6 +617,39 @@ geli_da1s3a_keyfile0_load="YES"
 geli_da1s3a_keyfile0_type="da1s3a:geli_keyfile0"
 geli_da1s3a_keyfile0_name="/boot/keys/da1s3a.key"
 .Ed
+.Pp
+Not only configure encryption, but also data integrity verification using
+.Nm HMAC/SHA256.
+.Bd -literal -offset indent
+# 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
+.Ed
+.Sh DATA AUTHENTICATION
+.Nm
+can verify data integrity when authentication algorithm is specified.
+When data corruption/modification is detected,
+.Nm
+will not return any data, instead will return an error
+.Er ( EINVAL ) .
+The offset and size of corrupted data will be printed on the console.
+It is important to know against which attacks
+.Nm
+can protect your data. If data is modified or copied from one place on the disk
+to another,
+.Nm
+should be able to detect such modification.
+If an attacker can remember the encrypted data, he can write them back to the
+same place and this won't be detected even if the data was legally modified
+between attacker read and write.
+.Nm
+won't protect your data against replay attacks.
+.Ed
 .Sh SEE ALSO
 .Xr crypto 4 ,
 .Xr gbde 4 ,