From a79e05219daec49e78769738e234b5922bcaa3b9 Mon Sep 17 00:00:00 2001 From: pjd Date: Mon, 5 Jun 2006 21:43:51 +0000 Subject: Document geli(8) data authentication. Supported by: Wheel Sp. z o.o. (http://www.wheel.pl) --- sbin/geom/class/eli/geli.8 | 128 ++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 116 insertions(+), 12 deletions(-) (limited to 'sbin/geom/class') 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 , -- cgit v1.1