Document geli(8) data authentication.
Supported by: Wheel Sp. z o.o. (http://www.wheel.pl)
This commit is contained in:
Pawel Jakub Dawidek
parent
4e98d97992
commit
198eeec116
@ -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 ,
|
||||
|
||||
Loading…
Reference in New Issue
Block a user