Improve description of various key used by GELI.
PR: docs/169089 Submitted by: John W. O'Brien <john@saltant.com> MFC after: 3 days
This commit is contained in:
Pawel Jakub Dawidek
parent
457bbc4f3a
commit
a894d53ea0
@ -24,7 +24,7 @@
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd April 28, 2012
|
||||
.Dd June 18, 2012
|
||||
.Dt GELI 8
|
||||
.Os
|
||||
.Sh NAME
|
||||
@ -186,14 +186,15 @@ one of the following algorithms:
|
||||
or
|
||||
.Nm HMAC/SHA512 .
|
||||
.It
|
||||
Can create a key from a couple of components (user entered passphrase, random
|
||||
bits from a file, etc.).
|
||||
Can create a User Key from up to two, piecewise components: a passphrase
|
||||
entered via prompt or read from one or more passfiles; a keyfile read from
|
||||
one or more files.
|
||||
.It
|
||||
Allows encryption of the root partition.
|
||||
The user will be asked for the
|
||||
passphrase before the root file system is mounted.
|
||||
.It
|
||||
The passphrase of the user is strengthened with:
|
||||
Strengthens the passphrase component of the User Key with:
|
||||
.Rs
|
||||
.%A B. Kaliski
|
||||
.%T "PKCS #5: Password-Based Cryptography Specification, Version 2.0."
|
||||
@ -201,7 +202,7 @@ The passphrase of the user is strengthened with:
|
||||
.%N 2898
|
||||
.Re
|
||||
.It
|
||||
Allows the use of two independent keys (e.g., a
|
||||
Allows the use of two independent User Keys (e.g., a
|
||||
.Qq "user key"
|
||||
and a
|
||||
.Qq "company key" ) .
|
||||
@ -210,8 +211,8 @@ It is fast -
|
||||
.Nm
|
||||
performs simple sector-to-sector encryption.
|
||||
.It
|
||||
Allows Master Keys to be backed up and restored,
|
||||
so that if a user has to quickly destroy his keys,
|
||||
Allows the encrypted Master Key to be backed up and restored,
|
||||
so that if a user has to quickly destroy key material,
|
||||
it is possible to get the data back by restoring keys from
|
||||
backup.
|
||||
.It
|
||||
@ -219,8 +220,8 @@ Providers can be configured to automatically detach on last close
|
||||
(so users do not have to remember to detach providers after unmounting
|
||||
the file systems).
|
||||
.It
|
||||
Allows attaching a provider with a random, one-time key - useful for swap
|
||||
partitions and temporary file systems.
|
||||
Allows attaching a provider with a random, one-time Master Key -
|
||||
useful for swap partitions and temporary file systems.
|
||||
.It
|
||||
Allows verification of data integrity (data authentication).
|
||||
.It
|
||||
@ -233,7 +234,8 @@ indicates an action to be performed:
|
||||
.Bl -tag -width ".Cm configure"
|
||||
.It Cm init
|
||||
Initialize the provider which needs to be encrypted.
|
||||
Here you can set up the cryptographic algorithm to use, key length, etc.
|
||||
Here you can set up the cryptographic algorithm to use, Data Key length,
|
||||
etc.
|
||||
The last sector of the provider is used to store metadata.
|
||||
The
|
||||
.Cm init
|
||||
@ -289,37 +291,58 @@ and
|
||||
The default and recommended algorithm is
|
||||
.Nm AES-XTS .
|
||||
.It Fl i Ar iterations
|
||||
Number of iterations to use with PKCS#5v2.
|
||||
Number of iterations to use with PKCS#5v2 when processing User Key
|
||||
passphrase component.
|
||||
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.
|
||||
PKCS#5v2 processing is performed once, after all parts of the passphrase
|
||||
component have been read.
|
||||
.It Fl J Ar newpassfile
|
||||
Specifies a file which contains the passphrase or its part.
|
||||
Specifies a file which contains the passphrase component of the User Key
|
||||
(or part of it).
|
||||
If
|
||||
.Ar newpassfile
|
||||
is given as -, standard input will be used.
|
||||
Only the first line (excluding new-line character) is taken from the given file.
|
||||
This argument can be specified multiple times.
|
||||
This argument can be specified multiple times, which has the effect of
|
||||
reassembling a single passphrase split across multiple files.
|
||||
Cannot be combined with the
|
||||
.Fl P
|
||||
option.
|
||||
.It Fl K Ar newkeyfile
|
||||
Specifies a file which contains part of the key.
|
||||
Specifies a file which contains the keyfile component of the User Key
|
||||
(or part of it).
|
||||
If
|
||||
.Ar newkeyfile
|
||||
is given as -, standard input will be used.
|
||||
This argument can be specified multiple times.
|
||||
This argument can be specified multiple times, which has the effect of
|
||||
reassembling a single keyfile split across multiple keyfile parts.
|
||||
.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-XTS ,
|
||||
.Nm AES-CBC ,
|
||||
.Nm Blowfish-CBC
|
||||
and
|
||||
.Nm Camellia-CBC
|
||||
and 192 for
|
||||
.Nm 3DES-CBC .
|
||||
Data Key length to use with the given cryptographic algorithm.
|
||||
If the length is not specified, the selected algorithm uses its
|
||||
.Em default
|
||||
key length.
|
||||
.Bl -ohang -offset indent
|
||||
.It Nm AES-XTS
|
||||
.Em 128 ,
|
||||
256
|
||||
.It Nm AES-CBC , Nm Camilla-CBC
|
||||
.Em 128 ,
|
||||
192,
|
||||
256
|
||||
.It Nm Blowfish-CBC
|
||||
.Em 128
|
||||
+ n * 32, for n=[0..10]
|
||||
.It Nm 3DES-CBC
|
||||
.Em 192
|
||||
.El
|
||||
.It Fl P
|
||||
Do not use passphrase as the key component.
|
||||
Do not use a passphrase as a component of the User Key.
|
||||
Cannot be combined with the
|
||||
.Fl J
|
||||
option.
|
||||
.It Fl s Ar sectorsize
|
||||
Change decrypted provider's sector size.
|
||||
Increasing the sector size allows increased performance,
|
||||
@ -337,9 +360,9 @@ Note that using older metadata version may limit numer of features available.
|
||||
.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
|
||||
The encrypted Master Key will be loaded from the metadata and 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
|
||||
@ -357,28 +380,33 @@ option for the
|
||||
.Cm detach
|
||||
subcommand.
|
||||
.It Fl j Ar passfile
|
||||
Specifies a file which contains the passphrase or its part.
|
||||
Specifies a file which contains the passphrase component of the User Key
|
||||
(or part of it).
|
||||
For more information see the description of the
|
||||
.Fl J
|
||||
option for the
|
||||
.Cm init
|
||||
subcommand.
|
||||
.It Fl k Ar keyfile
|
||||
Specifies a file which contains part of the key.
|
||||
Specifies a file which contains the keyfile component of the User Key
|
||||
(or part of it).
|
||||
For more information see the description of the
|
||||
.Fl K
|
||||
option for the
|
||||
.Cm init
|
||||
subcommand.
|
||||
.It Fl p
|
||||
Do not use passphrase as the key component.
|
||||
Do not use a passphrase as a component of the User Key.
|
||||
Cannot be combined with the
|
||||
.Fl j
|
||||
option.
|
||||
.It Fl r
|
||||
Attach read-only provider.
|
||||
It will not be opened for writing.
|
||||
.El
|
||||
.It Cm detach
|
||||
Detach the given providers, which means remove the devfs entry
|
||||
and clear the keys from memory.
|
||||
and clear the Master Key and Data Keys from memory.
|
||||
.Pp
|
||||
Additional options include:
|
||||
.Bl -tag -width ".Fl f"
|
||||
@ -391,7 +419,7 @@ while it is open, but will be automatically detached when it is closed for the
|
||||
last time even if it was only opened for reading.
|
||||
.El
|
||||
.It Cm onetime
|
||||
Attach the given providers with random, one-time keys.
|
||||
Attach the given providers with a random, one-time (ephemeral) Master Key.
|
||||
The command can be used to encrypt swap partitions or temporary file systems.
|
||||
.Pp
|
||||
Additional options include:
|
||||
@ -415,7 +443,7 @@ For more information, see the description of the
|
||||
.Cm attach
|
||||
subcommand.
|
||||
.It Fl l Ar keylen
|
||||
Key length to use with the given cryptographic algorithm.
|
||||
Data Key length to use with the given cryptographic algorithm.
|
||||
For more information, see the description of the
|
||||
.Cm init
|
||||
subcommand.
|
||||
@ -439,15 +467,18 @@ subcommand.
|
||||
Remove the BOOT flag from the given providers.
|
||||
.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.
|
||||
Install a copy of the Master Key into the selected slot, encrypted with
|
||||
a new User Key.
|
||||
If the selected slot is populated, replace the existing copy.
|
||||
A provider has one Master Key, which can be stored in one or both slots,
|
||||
each encrypted with an independent User Key.
|
||||
With the
|
||||
.Cm init
|
||||
subcommand, only key number 0 is initialized.
|
||||
The key can always be changed: for an attached provider,
|
||||
The User Key can be changed at any time: for an attached provider,
|
||||
for a detached provider, or on the backup file.
|
||||
When a provider is attached, the user does not have to provide
|
||||
an old passphrase/keyfile.
|
||||
an existing passphrase/keyfile.
|
||||
.Pp
|
||||
Additional options include:
|
||||
.Bl -tag -width ".Fl J Ar newpassfile"
|
||||
@ -458,44 +489,54 @@ To be able to use this option with the
|
||||
.Cm setkey
|
||||
subcommand, only one key has to be defined and this key must be changed.
|
||||
.It Fl j Ar passfile
|
||||
Specifies a file which contains the old passphrase or its part.
|
||||
Specifies a file which contains the passphrase component of a current User Key
|
||||
(or part of it).
|
||||
.It Fl J Ar newpassfile
|
||||
Specifies a file which contains the new passphrase or its part.
|
||||
Specifies a file which contains the passphrase component of the new User Key
|
||||
(or part of it).
|
||||
.It Fl k Ar keyfile
|
||||
Specifies a file which contains part of the old key.
|
||||
Specifies a file which contains the keyfile component of a current User Key
|
||||
(or part of it).
|
||||
.It Fl K Ar newkeyfile
|
||||
Specifies a file which contains part of the new key.
|
||||
Specifies a file which contains the keyfile component of the new User Key
|
||||
(or part of it).
|
||||
.It Fl n Ar keyno
|
||||
Specifies the number of the key to change (could be 0 or 1).
|
||||
Specifies the index number of the Master Key copy to change (could be 0 or 1).
|
||||
If the provider is attached and no key number is given, the key
|
||||
used for attaching the provider will be changed.
|
||||
If the provider is detached (or we are operating on a backup file)
|
||||
and no key number is given, the key decrypted with the passphrase/keyfile
|
||||
will be changed.
|
||||
and no key number is given, the first Master Key copy to be successfully
|
||||
decrypted with the provided User Key passphrase/keyfile will be changed.
|
||||
.It Fl p
|
||||
Do not use passphrase as the old key component.
|
||||
Do not use a passphrase as a component of the current User Key.
|
||||
Cannot be combined with the
|
||||
.Fl j
|
||||
option.
|
||||
.It Fl P
|
||||
Do not use passphrase as the new key component.
|
||||
Do not use a passphrase as a component of the new User Key.
|
||||
Cannot be combined with the
|
||||
.Fl J
|
||||
option.
|
||||
.El
|
||||
.It Cm delkey
|
||||
Destroy (overwrite with random data) the selected key.
|
||||
Destroy (overwrite with random data) the selected Master Key copy.
|
||||
If one is destroying keys for an attached provider, the provider
|
||||
will not be detached even if all keys are destroyed.
|
||||
will not be detached even if all copies of the Master Key are destroyed.
|
||||
It can even be rescued with the
|
||||
.Cm setkey
|
||||
subcommand.
|
||||
subcommand because the Master Key is still in memory.
|
||||
.Pp
|
||||
Additional options include:
|
||||
.Bl -tag -width ".Fl a Ar keyno"
|
||||
.It Fl a
|
||||
Destroy all keys (does not need
|
||||
Destroy all copies of the Master Key (does not need
|
||||
.Fl f
|
||||
option).
|
||||
.It Fl f
|
||||
Force key destruction.
|
||||
This option is needed to destroy the last key.
|
||||
This option is needed to destroy the last copy of the Master Key.
|
||||
.It Fl n Ar keyno
|
||||
Specifies the key number.
|
||||
Specifies the index number of the Master Key copy.
|
||||
If the provider is attached and no key number is given, the key
|
||||
used for attaching the provider will be destroyed.
|
||||
If provider is detached (or we are operating on a backup file) the key number
|
||||
@ -503,8 +544,8 @@ has to be given.
|
||||
.El
|
||||
.It Cm kill
|
||||
This command should be used only in emergency situations.
|
||||
It will destroy all the keys on a given provider and will detach it forcibly
|
||||
(if it is attached).
|
||||
It will destroy all copies of the Master Key on a given provider and will
|
||||
detach it forcibly (if it is attached).
|
||||
This is absolutely a one-way command - if you do not have a metadata
|
||||
backup, your data is gone for good.
|
||||
In case the provider was attached with the
|
||||
@ -542,8 +583,8 @@ and
|
||||
.El
|
||||
.It Cm suspend
|
||||
Suspend device by waiting for all inflight requests to finish, clearing all
|
||||
sensitive information (like keys) from kernel memory, and blocking all
|
||||
further I/O requests until the
|
||||
sensitive information (like the Master Key and Data Keys) from kernel memory,
|
||||
and blocking all further I/O requests until the
|
||||
.Cm resume
|
||||
subcommand is executed.
|
||||
This functionality is useful for laptops: when one wants to suspend a
|
||||
@ -553,8 +594,8 @@ on an encrypted device, unmounting the file system, and detaching the device,
|
||||
the
|
||||
.Cm suspend
|
||||
subcommand can be used.
|
||||
Any access to the encrypted device will be blocked until the keys are
|
||||
recovered through the
|
||||
Any access to the encrypted device will be blocked until the Master Key is
|
||||
reloaded through the
|
||||
.Cm resume
|
||||
subcommand.
|
||||
Thus there is no need to close nor unmount anything.
|
||||
@ -584,21 +625,26 @@ utility is stored is bad idea.
|
||||
Additional options include:
|
||||
.Bl -tag -width ".Fl j Ar passfile"
|
||||
.It Fl j Ar passfile
|
||||
Specifies a file which contains the passphrase or its part.
|
||||
Specifies a file which contains the passphrase component of the User Key
|
||||
(or part of it).
|
||||
For more information see the description of the
|
||||
.Fl J
|
||||
option for the
|
||||
.Cm init
|
||||
subcommand.
|
||||
.It Fl k Ar keyfile
|
||||
Specifies a file which contains part of the key.
|
||||
Specifies a file which contains the keyfile component of the User Key
|
||||
(or part of it).
|
||||
For more information see the description of the
|
||||
.Fl K
|
||||
option for the
|
||||
.Cm init
|
||||
subcommand.
|
||||
.It Fl p
|
||||
Do not use passphrase as the key component.
|
||||
Do not use a passphrase as a component of the User Key.
|
||||
Cannot be combined with the
|
||||
.Fl j
|
||||
option.
|
||||
.El
|
||||
.It Cm resize
|
||||
Inform
|
||||
@ -626,6 +672,9 @@ If GEOM providers are specified, the
|
||||
subcommand will print metadata version used by each of them.
|
||||
.It Cm clear
|
||||
Clear metadata from the given providers.
|
||||
.Em WARNING :
|
||||
This will erase with zeros the encrypted Master Key copies stored in the
|
||||
metadata.
|
||||
.It Cm dump
|
||||
Dump metadata stored on the given providers.
|
||||
.It Cm list
|
||||
@ -647,6 +696,36 @@ Additional options include:
|
||||
.It Fl v
|
||||
Be more verbose.
|
||||
.El
|
||||
.Sh KEY SUMMARY
|
||||
.Ss Master Key
|
||||
Upon
|
||||
.Cm init ,
|
||||
the
|
||||
.Nm
|
||||
utility generates a random Master Key for the provider.
|
||||
The Master Key never changes during the lifetime of the provider.
|
||||
Each copy of the provider metadata, active or backed up to a file, can store
|
||||
up to two, independently-encrypted copies of the Master Key.
|
||||
.Ss User Key
|
||||
Each stored copy of the Master Key is encrypted with a User Key, which
|
||||
is generated by the
|
||||
.Nm
|
||||
utility from a passphrase and/or a keyfile.
|
||||
The
|
||||
.Nm
|
||||
utility first reads all parts of the keyfile in the order specified on the
|
||||
command line, then reads all parts of the stored passphrase in the order
|
||||
specified on the command line.
|
||||
If no passphrase parts are specified, the system prompts the user to enter
|
||||
the passphrase.
|
||||
The passphrase is optionally strengthened by PKCS#5v2.
|
||||
The User Key is a digest computed over the concatenated keyfile and passphrase.
|
||||
.Ss Data Key
|
||||
During operation, one or more Data Keys are deterministically derived by
|
||||
the kernel from the Master Key and cached in memory.
|
||||
The number of Data Keys used by a given provider, and the way they are
|
||||
derived, depend on the GELI version and whether the provider is configured to
|
||||
use data authentication.
|
||||
.Sh SYSCTL VARIABLES
|
||||
The following
|
||||
.Xr sysctl 8
|
||||
@ -677,7 +756,7 @@ 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 the Master-Key will be overwritten
|
||||
Specifies how many times the Master Key will be overwritten
|
||||
with random values when it is destroyed.
|
||||
After this operation it is filled with zeros.
|
||||
.It Va kern.geom.eli.visible_passphrase : No 0
|
||||
@ -699,18 +778,19 @@ Batching reduces the number of interrupts by responding to a group of
|
||||
crypto requests with one interrupt.
|
||||
The crypto card and the driver has to support this feature.
|
||||
.It Va kern.geom.eli.key_cache_limit : No 8192
|
||||
Specifies how many encryption keys to cache.
|
||||
Specifies how many Data Keys to cache.
|
||||
The default limit
|
||||
(8192 keys) will allow caching of all keys for a 4TB provider with 512 byte
|
||||
sectors and will take around 1MB of memory.
|
||||
.It Va kern.geom.eli.key_cache_hits
|
||||
Reports how many times we were looking up a key and it was already in cache.
|
||||
This sysctl is not updated for providers that need less keys than the limit
|
||||
specified in
|
||||
Reports how many times we were looking up a Data Key and it was already in
|
||||
cache.
|
||||
This sysctl is not updated for providers that need fewer Data Keys than
|
||||
the limit specified in
|
||||
.Va kern.geom.eli.key_cache_limit .
|
||||
.It Va kern.geom.eli.key_cache_misses
|
||||
Reports how many times we were looking up a key and it was not in cache.
|
||||
This sysctl is not updated for providers that need fewer keys than the limit
|
||||
Reports how many times we were looking up a Data Key and it was not in cache.
|
||||
This sysctl is not updated for providers that need fewer Data Keys than the limit
|
||||
specified in
|
||||
.Va kern.geom.eli.key_cache_limit .
|
||||
.El
|
||||
@ -738,7 +818,7 @@ Enter passphrase:
|
||||
# geli detach da2.eli
|
||||
.Ed
|
||||
.Pp
|
||||
Create an encrypted provider, but use two keys:
|
||||
Create an encrypted provider, but use two User Keys:
|
||||
one for your employee and one for you as the company's security officer
|
||||
(so it's not a tragedy if the employee
|
||||
.Qq accidentally
|
||||
@ -760,7 +840,7 @@ forget their passphrases, so backup the Master Key with your own random key:
|
||||
# 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 the encrypted Master Key will be overwritten by this)
|
||||
(use key number 0, so the encrypted Master Key will be re-encrypted by this)
|
||||
# geli setkey -n 0 -k /mnt/pendrive/keys/`hostname` /dev/ad0s1e
|
||||
(allow the user to enter his passphrase)
|
||||
Enter new passphrase:
|
||||
@ -776,8 +856,8 @@ Encrypted swap partition setup:
|
||||
.Pp
|
||||
The example below shows how to configure two providers which will be attached
|
||||
on boot (before the root file system is mounted).
|
||||
One of them is using passphrase and three keyfiles and the other is using only a
|
||||
keyfile:
|
||||
One of them is using passphrase and three keyfile parts and the other is
|
||||
using only a keyfile in one part:
|
||||
.Bd -literal -offset indent
|
||||
# dd if=/dev/random of=/dev/da0 bs=1m
|
||||
# dd if=/dev/random of=/boot/keys/da0.key0 bs=32k count=1
|
||||
|
||||
Loading…
Reference in New Issue
Block a user