Attachment 125468 Details for Bug 169089 – file.diff

[patch] file.diff

file.diff (text/plain), 16.89 KB, created by John W. O'Brien on 2012-06-15 04:10:02 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: John W. O'Brien

Created: 2012-06-15 04:10:02 UTC

Size: 16.89 KB

patch

obsolete

>Index: geli.8
>===================================================================
>--- geli.8	(revision 236978)
>+++ geli.8	(working copy)
>@@ -24,7 +24,7 @@
> .\"
> .\" $FreeBSD$
> .\"
>-.Dd April 28, 2012
>+.Dd June 13, 2012
> .Dt GELI 8
> .Os
> .Sh NAME
>@@ -58,7 +58,7 @@
> .Op Fl i Ar iterations
> .Op Fl J Ar newpassfile
> .Op Fl K Ar newkeyfile
>-.Op Fl l Ar keylen
>+.Op Fl l Ar datakeylen
> .Op Fl s Ar sectorsize
> .Op Fl V Ar version
> .Ar prov
>@@ -83,7 +83,7 @@
> .Op Fl d
> .Op Fl a Ar aalgo
> .Op Fl e Ar ealgo
>-.Op Fl l Ar keylen
>+.Op Fl l Ar datakeylen
> .Op Fl s Ar sectorsize
> .Ar prov
> .Nm
>@@ -186,14 +186,15 @@
> 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 @@
> .%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 @@
> .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 @@
> (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 @@
> .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,57 @@
> 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.
>+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.
>-.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 .
>+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 datakeylen
>+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,7 +359,8 @@
> .El
> .It Cm attach
> Attach the given provider.
>-The master key will be decrypted using the given
>+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
>@@ -357,28 +380,33 @@
> .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 @@
> 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:
>@@ -414,8 +442,8 @@
> 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.
>+.It Fl l Ar datakeylen
>+Data Key length to use with the given cryptographic algorithm.
> For more information, see the description of the
> .Cm init
> subcommand.
>@@ -439,15 +467,17 @@
> 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 +488,54 @@
> .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,7 +543,8 @@
> .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
>+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.
>@@ -542,8 +583,8 @@
> .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 @@
> 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 @@
> 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 @@
> 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,34 @@
> .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 +754,7 @@
> 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 +776,19 @@
> 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 +816,7 @@
> # 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 +838,7 @@
> # 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 +854,8 @@
> .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

Actions: View | Diff

Attachments on bug 169089: 125468 | 125469 | 125470