1061 lines
30 KiB
Groff
1061 lines
30 KiB
Groff
.\" Copyright (c) 2005-2011 Pawel Jakub Dawidek <pawel@dawidek.net>
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd June 18, 2014
|
|
.Dt GELI 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm geli
|
|
.Nd "control utility for the cryptographic GEOM class"
|
|
.Sh SYNOPSIS
|
|
To compile GEOM_ELI into your kernel, add the following lines to your kernel
|
|
configuration file:
|
|
.Bd -ragged -offset indent
|
|
.Cd "device crypto"
|
|
.Cd "options GEOM_ELI"
|
|
.Ed
|
|
.Pp
|
|
Alternatively, to load the GEOM_ELI module at boot time, add the following line
|
|
to your
|
|
.Xr loader.conf 5 :
|
|
.Bd -literal -offset indent
|
|
geom_eli_load="YES"
|
|
.Ed
|
|
.Pp
|
|
Usage of the
|
|
.Nm
|
|
utility:
|
|
.Pp
|
|
.Nm
|
|
.Cm init
|
|
.Op Fl bPv
|
|
.Op Fl a Ar aalgo
|
|
.Op Fl B Ar backupfile
|
|
.Op Fl e Ar ealgo
|
|
.Op Fl i Ar iterations
|
|
.Op Fl J Ar newpassfile
|
|
.Op Fl K Ar newkeyfile
|
|
.Op Fl l Ar keylen
|
|
.Op Fl s Ar sectorsize
|
|
.Op Fl V Ar version
|
|
.Ar prov
|
|
.Nm
|
|
.Cm label - an alias for
|
|
.Cm init
|
|
.Nm
|
|
.Cm attach
|
|
.Op Fl dprv
|
|
.Op Fl j Ar passfile
|
|
.Op Fl k Ar keyfile
|
|
.Ar prov
|
|
.Nm
|
|
.Cm detach
|
|
.Op Fl fl
|
|
.Ar prov ...
|
|
.Nm
|
|
.Cm stop - an alias for
|
|
.Cm detach
|
|
.Nm
|
|
.Cm onetime
|
|
.Op Fl d
|
|
.Op Fl a Ar aalgo
|
|
.Op Fl e Ar ealgo
|
|
.Op Fl l Ar keylen
|
|
.Op Fl s Ar sectorsize
|
|
.Ar prov
|
|
.Nm
|
|
.Cm configure
|
|
.Op Fl bB
|
|
.Ar prov ...
|
|
.Nm
|
|
.Cm setkey
|
|
.Op Fl pPv
|
|
.Op Fl i Ar iterations
|
|
.Op Fl j Ar passfile
|
|
.Op Fl J Ar newpassfile
|
|
.Op Fl k Ar keyfile
|
|
.Op Fl K Ar newkeyfile
|
|
.Op Fl n Ar keyno
|
|
.Ar prov
|
|
.Nm
|
|
.Cm delkey
|
|
.Op Fl afv
|
|
.Op Fl n Ar keyno
|
|
.Ar prov
|
|
.Nm
|
|
.Cm kill
|
|
.Op Fl av
|
|
.Op Ar prov ...
|
|
.Nm
|
|
.Cm backup
|
|
.Op Fl v
|
|
.Ar prov
|
|
.Ar file
|
|
.Nm
|
|
.Cm restore
|
|
.Op Fl fv
|
|
.Ar file
|
|
.Ar prov
|
|
.Nm
|
|
.Cm suspend
|
|
.Op Fl v
|
|
.Fl a | Ar prov ...
|
|
.Nm
|
|
.Cm resume
|
|
.Op Fl pv
|
|
.Op Fl j Ar passfile
|
|
.Op Fl k Ar keyfile
|
|
.Ar prov
|
|
.Nm
|
|
.Cm resize
|
|
.Op Fl v
|
|
.Fl s Ar oldsize
|
|
.Ar prov
|
|
.Nm
|
|
.Cm version
|
|
.Op Ar prov ...
|
|
.Nm
|
|
.Cm clear
|
|
.Op Fl v
|
|
.Ar prov ...
|
|
.Nm
|
|
.Cm dump
|
|
.Op Fl v
|
|
.Ar prov ...
|
|
.Nm
|
|
.Cm list
|
|
.Nm
|
|
.Cm status
|
|
.Nm
|
|
.Cm load
|
|
.Nm
|
|
.Cm unload
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
utility is used to configure encryption on GEOM providers.
|
|
.Pp
|
|
The following is a list of the most important features:
|
|
.Pp
|
|
.Bl -bullet -offset indent -compact
|
|
.It
|
|
Utilizes the
|
|
.Xr crypto 9
|
|
framework, so when there is crypto hardware available,
|
|
.Nm
|
|
will make use of it automatically.
|
|
.It
|
|
Supports many cryptographic algorithms (currently
|
|
.Nm AES-XTS ,
|
|
.Nm AES-CBC ,
|
|
.Nm Blowfish-CBC ,
|
|
.Nm Camellia-CBC
|
|
and
|
|
.Nm 3DES-CBC ) .
|
|
.It
|
|
Can optionally perform data authentication (integrity verification) utilizing
|
|
one of the following algorithms:
|
|
.Nm HMAC/MD5 ,
|
|
.Nm HMAC/SHA1 ,
|
|
.Nm HMAC/RIPEMD160 ,
|
|
.Nm HMAC/SHA256 ,
|
|
.Nm HMAC/SHA384
|
|
or
|
|
.Nm HMAC/SHA512 .
|
|
.It
|
|
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
|
|
Strengthens the passphrase component of the User Key with:
|
|
.Rs
|
|
.%A B. Kaliski
|
|
.%T "PKCS #5: Password-Based Cryptography Specification, Version 2.0."
|
|
.%R RFC
|
|
.%N 2898
|
|
.Re
|
|
.It
|
|
Allows the use of two independent User Keys (e.g., a
|
|
.Qq "user key"
|
|
and a
|
|
.Qq "company key" ) .
|
|
.It
|
|
It is fast -
|
|
.Nm
|
|
performs simple sector-to-sector encryption.
|
|
.It
|
|
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
|
|
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 Master Key -
|
|
useful for swap partitions and temporary file systems.
|
|
.It
|
|
Allows verification of data integrity (data authentication).
|
|
.It
|
|
Allows suspending and resuming encrypted devices.
|
|
.El
|
|
.Pp
|
|
The first argument to
|
|
.Nm
|
|
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, Data Key length,
|
|
etc.
|
|
The last sector of the provider is used to store metadata.
|
|
The
|
|
.Cm init
|
|
subcommand also automatically writes metadata backups to
|
|
.Pa /var/backups/<prov>.eli
|
|
file.
|
|
The metadata can be recovered with the
|
|
.Cm restore
|
|
subcommand described below.
|
|
.Pp
|
|
Additional options include:
|
|
.Bl -tag -width ".Fl J Ar newpassfile"
|
|
.It Fl a Ar aalgo
|
|
Enable data integrity verification (authentication) using the given algorithm.
|
|
This will reduce the size of storage available 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.
|
|
The recommended algorithm is
|
|
.Nm HMAC/SHA256 .
|
|
.It Fl b
|
|
Ask for the passphrase on boot, before the root partition is mounted.
|
|
This makes it possible to use an encrypted root partition.
|
|
One will still need bootable unencrypted storage with a
|
|
.Pa /boot/
|
|
directory, which can be a CD-ROM disc or USB pen-drive, that can be removed
|
|
after boot.
|
|
.It Fl B Ar backupfile
|
|
File name to use for metadata backup instead of the default
|
|
.Pa /var/backups/<prov>.eli .
|
|
To inhibit backups, you can use
|
|
.Pa none
|
|
as the
|
|
.Ar backupfile .
|
|
.It Fl e Ar ealgo
|
|
Encryption algorithm to use.
|
|
Currently supported algorithms are:
|
|
.Nm AES-XTS ,
|
|
.Nm AES-CBC ,
|
|
.Nm Blowfish-CBC ,
|
|
.Nm Camellia-CBC ,
|
|
.Nm 3DES-CBC ,
|
|
and
|
|
.Nm NULL .
|
|
The default and recommended algorithm is
|
|
.Nm AES-XTS .
|
|
.Nm NULL
|
|
is unencrypted.
|
|
.It Fl i Ar iterations
|
|
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 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, 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 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, which has the effect of
|
|
reassembling a single keyfile split across multiple keyfile parts.
|
|
.It Fl l Ar keylen
|
|
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 Camellia-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 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,
|
|
because encryption/decryption which requires an initialization vector
|
|
is done per sector; fewer sectors means less computational work.
|
|
.It Fl V Ar version
|
|
Metadata version to use.
|
|
This option is helpful when creating a provider that may be used by older
|
|
.Nm FreeBSD/GELI
|
|
versions.
|
|
Consult the
|
|
.Sx HISTORY
|
|
section to find which metadata version is supported by which FreeBSD version.
|
|
Note that using an older version of metadata may limit the number of
|
|
features available.
|
|
.El
|
|
.It Cm attach
|
|
Attach the given provider.
|
|
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
|
|
Additional options include:
|
|
.Bl -tag -width ".Fl j Ar passfile"
|
|
.It Fl d
|
|
If specified, a decrypted provider will be detached automatically on last close.
|
|
This can help with scarce memory so the user does not have to remember to detach the
|
|
provider after unmounting the file system.
|
|
It only works when the provider was opened for writing, so it will not work if
|
|
the file system on the provider is mounted read-only.
|
|
Probably a better choice is the
|
|
.Fl l
|
|
option for the
|
|
.Cm detach
|
|
subcommand.
|
|
.It Fl j Ar passfile
|
|
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 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 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 Master Key and Data Keys from memory.
|
|
.Pp
|
|
Additional options include:
|
|
.Bl -tag -width ".Fl f"
|
|
.It Fl f
|
|
Force detach - detach even if the provider is open.
|
|
.It Fl l
|
|
Mark provider to detach on last close.
|
|
If this option is specified, the provider will not be detached
|
|
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 a random, one-time (ephemeral) Master Key.
|
|
The command can be used to encrypt swap partitions or temporary file systems.
|
|
.Pp
|
|
Additional options include:
|
|
.Bl -tag -width ".Fl a Ar sectorsize"
|
|
.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
|
|
subcommand.
|
|
.It Fl d
|
|
Detach on last close.
|
|
Note: this option is not usable for temporary file systems as the provider will
|
|
be detached after creating the file system on it.
|
|
It still can (and should be) used for swap partitions.
|
|
For more information, see the description of the
|
|
.Cm attach
|
|
subcommand.
|
|
.It Fl l Ar keylen
|
|
Data Key length to use with the given cryptographic algorithm.
|
|
For more information, see the description of the
|
|
.Cm init
|
|
subcommand.
|
|
.It Fl s Ar sectorsize
|
|
Change decrypted provider's sector size.
|
|
For more information, see the description of the
|
|
.Cm init
|
|
subcommand.
|
|
.El
|
|
.It Cm configure
|
|
Change configuration of the given providers.
|
|
.Pp
|
|
Additional options include:
|
|
.Bl -tag -width ".Fl b"
|
|
.It Fl b
|
|
Set the BOOT flag on the given providers.
|
|
For more information, see the description of the
|
|
.Cm init
|
|
subcommand.
|
|
.It Fl B
|
|
Remove the BOOT flag from the given providers.
|
|
.El
|
|
.It Cm setkey
|
|
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 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 existing passphrase/keyfile.
|
|
.Pp
|
|
Additional options include:
|
|
.Bl -tag -width ".Fl J Ar newpassfile"
|
|
.It Fl i Ar iterations
|
|
Number of iterations to use with PKCS#5v2.
|
|
If 0 is given, PKCS#5v2 will not be used.
|
|
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 passphrase component of a current User Key
|
|
(or part of it).
|
|
.It Fl J Ar newpassfile
|
|
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 the keyfile component of a current User Key
|
|
(or part of it).
|
|
.It Fl K Ar newkeyfile
|
|
Specifies a file which contains the keyfile component of the new User Key
|
|
(or part of it).
|
|
.It Fl n Ar keyno
|
|
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 first Master Key copy to be successfully
|
|
decrypted with the provided User Key passphrase/keyfile will be changed.
|
|
.It Fl p
|
|
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 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 Master Key copy.
|
|
If one is destroying keys for an attached provider, the provider
|
|
will not be detached even if all copies of the Master Key are destroyed.
|
|
It can even be rescued with the
|
|
.Cm setkey
|
|
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 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 copy of the Master Key.
|
|
.It Fl n Ar keyno
|
|
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
|
|
has to be given.
|
|
.El
|
|
.It Cm kill
|
|
This command should be used only in emergency situations.
|
|
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
|
|
.Fl r
|
|
flag, the keys will not be destroyed, only the provider will be detached.
|
|
.Pp
|
|
Additional options include:
|
|
.Bl -tag -width ".Fl a"
|
|
.It Fl a
|
|
If specified, all currently attached providers will be killed.
|
|
.El
|
|
.It Cm backup
|
|
Backup metadata from the given provider to the given file.
|
|
.It Cm restore
|
|
Restore metadata from the given file to the given provider.
|
|
.Pp
|
|
Additional options include:
|
|
.Bl -tag -width ".Fl f"
|
|
.It Fl f
|
|
Metadata contains the size of the provider to ensure that the correct
|
|
partition or slice is attached.
|
|
If an attempt is made to restore metadata to a provider that has a different
|
|
size,
|
|
.Nm
|
|
will refuse to restore the data unless the
|
|
.Fl f
|
|
switch is used.
|
|
If the partition or slice has been grown, the
|
|
.Cm resize
|
|
subcommand should be used rather than attempting to relocate the metadata
|
|
through
|
|
.Cm backup
|
|
and
|
|
.Cm restore .
|
|
.El
|
|
.It Cm suspend
|
|
Suspend device by waiting for all inflight requests to finish, clearing all
|
|
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
|
|
laptop, one does not want to leave an encrypted device attached.
|
|
Instead of closing all files and directories opened from a file system located
|
|
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 Master Key is
|
|
reloaded through the
|
|
.Cm resume
|
|
subcommand.
|
|
Thus there is no need to close nor unmount anything.
|
|
The
|
|
.Cm suspend
|
|
subcommand does not work with devices created with the
|
|
.Cm onetime
|
|
subcommand.
|
|
Please note that sensitive data might still be present in memory after
|
|
suspending an encrypted device due to the file system cache, etc.
|
|
.Pp
|
|
Additional options include:
|
|
.Bl -tag -width ".Fl a"
|
|
.It Fl a
|
|
Suspend all
|
|
.Nm
|
|
devices.
|
|
.El
|
|
.It Cm resume
|
|
Resume previously suspended device.
|
|
The caller must ensure that executing this subcommand does not access the
|
|
suspended device, leading to a deadlock.
|
|
For example suspending a device which contains the file system where the
|
|
.Nm
|
|
utility is stored is bad idea.
|
|
.Pp
|
|
Additional options include:
|
|
.Bl -tag -width ".Fl j Ar passfile"
|
|
.It Fl j Ar passfile
|
|
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 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 a passphrase as a component of the User Key.
|
|
Cannot be combined with the
|
|
.Fl j
|
|
option.
|
|
.El
|
|
.It Cm resize
|
|
Inform
|
|
.Nm
|
|
that the provider has been resized.
|
|
The old metadata block is relocated to the correct position at the end of the
|
|
provider and the provider size is updated.
|
|
.Pp
|
|
Additional options include:
|
|
.Bl -tag -width ".Fl s Ar oldsize"
|
|
.It Fl s Ar oldsize
|
|
The size of the provider before it was resized.
|
|
.El
|
|
.It Cm version
|
|
If no arguments are given, the
|
|
.Cm version
|
|
subcommand will print the version of
|
|
.Nm
|
|
userland utility as well as the version of the
|
|
.Nm ELI
|
|
GEOM class.
|
|
.Pp
|
|
If GEOM providers are specified, the
|
|
.Cm version
|
|
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
|
|
See
|
|
.Xr geom 8 .
|
|
.It Cm status
|
|
See
|
|
.Xr geom 8 .
|
|
.It Cm load
|
|
See
|
|
.Xr geom 8 .
|
|
.It Cm unload
|
|
See
|
|
.Xr geom 8 .
|
|
.El
|
|
.Pp
|
|
Additional options include:
|
|
.Bl -tag -width ".Fl v"
|
|
.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
|
|
variables can be used to control the behavior of the
|
|
.Nm ELI
|
|
GEOM class.
|
|
The default value is shown next to each variable.
|
|
Some variables can also be set in
|
|
.Pa /boot/loader.conf .
|
|
.Bl -tag -width indent
|
|
.It Va kern.geom.eli.version
|
|
Version number of the
|
|
.Nm ELI
|
|
GEOM class.
|
|
.It Va kern.geom.eli.debug : No 0
|
|
Debug level of the
|
|
.Nm ELI
|
|
GEOM class.
|
|
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.
|
|
.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 are attached on boot
|
|
(before the root file system is mounted).
|
|
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
|
|
with random values when it is destroyed.
|
|
After this operation it is filled with zeros.
|
|
.It Va kern.geom.eli.visible_passphrase : No 0
|
|
If set to 1, the passphrase entered on boot (before the root
|
|
file system is mounted) will be visible.
|
|
This alternative should be used with caution as the entered
|
|
passphrase can be logged and exposed via
|
|
.Xr dmesg 8 .
|
|
This variable should be set in
|
|
.Pa /boot/loader.conf .
|
|
.It Va kern.geom.eli.threads : No 0
|
|
Specifies how many kernel threads should be used for doing software
|
|
cryptography.
|
|
Its purpose is to increase performance on SMP systems.
|
|
If set to 0, a CPU-pinned thread will be started for every active CPU.
|
|
.It Va kern.geom.eli.batch : No 0
|
|
When set to 1, can speed-up crypto operations by using batching.
|
|
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 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 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 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
|
|
.Sh EXIT STATUS
|
|
Exit status is 0 on success, and 1 if the command fails.
|
|
.Sh EXAMPLES
|
|
Initialize a provider which is going to be encrypted with a
|
|
passphrase and random data from a file on the user's pen drive.
|
|
Use 4kB sector size.
|
|
Attach the provider, create a file system, and mount it.
|
|
Do the work.
|
|
Unmount the provider and detach it:
|
|
.Bd -literal -offset indent
|
|
# dd if=/dev/random of=/mnt/pendrive/da2.key bs=64 count=1
|
|
# geli init -s 4096 -K /mnt/pendrive/da2.key /dev/da2
|
|
Enter new passphrase:
|
|
Reenter new passphrase:
|
|
# geli attach -k /mnt/pendrive/da2.key /dev/da2
|
|
Enter passphrase:
|
|
# dd if=/dev/random of=/dev/da2.eli bs=1m
|
|
# newfs /dev/da2.eli
|
|
# mount /dev/da2.eli /mnt/secret
|
|
\&...
|
|
# umount /mnt/secret
|
|
# geli detach da2.eli
|
|
.Ed
|
|
.Pp
|
|
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 is not a tragedy if the employee
|
|
.Qq accidentally
|
|
forgets his passphrase):
|
|
.Bd -literal -offset indent
|
|
# geli init /dev/da2
|
|
Enter new passphrase: (enter security officer's passphrase)
|
|
Reenter new passphrase:
|
|
# geli setkey -n 1 /dev/da2
|
|
Enter passphrase: (enter security officer's passphrase)
|
|
Enter new passphrase: (let your employee enter his passphrase ...)
|
|
Reenter new passphrase: (... twice)
|
|
.Ed
|
|
.Pp
|
|
You are the security officer in your company.
|
|
Create an encrypted provider for use by the user, but remember that users
|
|
forget their passphrases, so backup the Master Key with your own random key:
|
|
.Bd -literal -offset indent
|
|
# dd if=/dev/random of=/mnt/pendrive/keys/`hostname` bs=64 count=1
|
|
# geli init -P -K /mnt/pendrive/keys/`hostname` /dev/ada0s1e
|
|
# geli backup /dev/ada0s1e /mnt/pendrive/backups/`hostname`
|
|
(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/ada0s1e
|
|
(allow the user to enter his passphrase)
|
|
Enter new passphrase:
|
|
Reenter new passphrase:
|
|
.Ed
|
|
.Pp
|
|
Encrypted swap partition setup:
|
|
.Bd -literal -offset indent
|
|
# dd if=/dev/random of=/dev/ada0s1b bs=1m
|
|
# geli onetime -d -e 3des ada0s1b
|
|
# swapon /dev/ada0s1b.eli
|
|
.Ed
|
|
.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 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
|
|
# dd if=/dev/random of=/boot/keys/da0.key1 bs=32k count=1
|
|
# dd if=/dev/random of=/boot/keys/da0.key2 bs=32k count=1
|
|
# geli init -b -K /boot/keys/da0.key0 -K /boot/keys/da0.key1 -K /boot/keys/da0.key2 da0
|
|
Enter new passphrase:
|
|
Reenter new passphrase:
|
|
# dd if=/dev/random of=/dev/da1s3a bs=1m
|
|
# dd if=/dev/random of=/boot/keys/da1s3a.key bs=128k count=1
|
|
# geli init -b -P -K /boot/keys/da1s3a.key da1s3a
|
|
.Ed
|
|
.Pp
|
|
The providers are initialized, now we have to add these lines to
|
|
.Pa /boot/loader.conf :
|
|
.Bd -literal -offset indent
|
|
geli_da0_keyfile0_load="YES"
|
|
geli_da0_keyfile0_type="da0:geli_keyfile0"
|
|
geli_da0_keyfile0_name="/boot/keys/da0.key0"
|
|
geli_da0_keyfile1_load="YES"
|
|
geli_da0_keyfile1_type="da0:geli_keyfile1"
|
|
geli_da0_keyfile1_name="/boot/keys/da0.key1"
|
|
geli_da0_keyfile2_load="YES"
|
|
geli_da0_keyfile2_type="da0:geli_keyfile2"
|
|
geli_da0_keyfile2_name="/boot/keys/da0.key2"
|
|
|
|
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
|
|
.Pp
|
|
.Cm geli
|
|
writes the metadata backup by default to the
|
|
.Pa /var/backups/<prov>.eli
|
|
file.
|
|
If the metadata is lost in any way (e.g., by accidental overwrite), it can be restored.
|
|
Consider the following situation:
|
|
.Bd -literal -offset indent
|
|
# geli init /dev/da0
|
|
Enter new passphrase:
|
|
Reenter new passphrase:
|
|
|
|
Metadata backup can be found in /var/backups/da0.eli and
|
|
can be restored with the following command:
|
|
|
|
# geli restore /var/backups/da0.eli /dev/da0
|
|
|
|
# geli clear /dev/da0
|
|
# geli attach /dev/da0
|
|
geli: Cannot read metadata from /dev/da0: Invalid argument.
|
|
# geli restore /var/backups/da0.eli /dev/da0
|
|
# geli attach /dev/da0
|
|
Enter passphrase:
|
|
.Ed
|
|
.Pp
|
|
If an encrypted file system is extended, it is necessary to relocate and
|
|
update the metadata:
|
|
.Bd -literal -offset indent
|
|
# gpart create -s GPT ada0
|
|
# gpart add -s 1g -t freebsd-ufs -i 1 ada0
|
|
# geli init -K keyfile -P ada0p1
|
|
# gpart resize -s 2g -i 1 ada0
|
|
# geli resize -s 1g ada0p1
|
|
# geli attach -k keyfile -p ada0p1
|
|
.Ed
|
|
.Pp
|
|
Initialize provider with the passphrase split into two files.
|
|
The provider can be attached using those two files or by entering
|
|
.Dq foobar
|
|
as the passphrase at the
|
|
.Nm
|
|
prompt:
|
|
.Bd -literal -offset indent
|
|
# echo foo > da0.pass0
|
|
# echo bar > da0.pass1
|
|
# geli init -J da0.pass0 -J da0.pass1 da0
|
|
# geli attach -j da0.pass0 -j da0.pass1 da0
|
|
# geli detach da0
|
|
# geli attach da0
|
|
Enter passphrase: foobar
|
|
.Ed
|
|
.Pp
|
|
Suspend all
|
|
.Nm
|
|
devices on a laptop, suspend the laptop, then resume devices one by one after
|
|
resuming the laptop:
|
|
.Bd -literal -offset indent
|
|
# geli suspend -a
|
|
# zzz
|
|
<resume your laptop>
|
|
# geli resume -p -k keyfile gpt/secret
|
|
# geli resume gpt/private
|
|
Enter passphrase:
|
|
.Ed
|
|
.Sh ENCRYPTION MODES
|
|
.Nm
|
|
supports two encryption modes:
|
|
.Nm XTS ,
|
|
which was standardized as
|
|
.Nm IEEE P1619
|
|
and
|
|
.Nm CBC
|
|
with unpredictable IV.
|
|
The
|
|
.Nm CBC
|
|
mode used by
|
|
.Nm
|
|
is very similar to the mode
|
|
.Nm ESSIV .
|
|
.Sh DATA AUTHENTICATION
|
|
.Nm
|
|
can verify data integrity when an authentication algorithm is specified.
|
|
When data corruption/modification is detected,
|
|
.Nm
|
|
will not return any data, but instead will return an error
|
|
.Pq Er EINVAL .
|
|
The offset and size of the corrupted data will be printed on the console.
|
|
It is important to know against which attacks
|
|
.Nm
|
|
provides protection for your data.
|
|
If data is modified in-place or copied from one place on the disk
|
|
to another even without modification,
|
|
.Nm
|
|
should be able to detect such a change.
|
|
If an attacker can remember the encrypted data, he can overwrite any future
|
|
changes with the data he owns without it being noticed.
|
|
In other words
|
|
.Nm
|
|
will not protect your data against replay attacks.
|
|
.Pp
|
|
It is recommended to write to the whole provider before first use,
|
|
in order to make sure that all sectors and their corresponding
|
|
checksums are properly initialized into a consistent state.
|
|
One can safely ignore data authentication errors that occur immediately
|
|
after the first time a provider is attached and before it is
|
|
initialized in this way.
|
|
.Sh SEE ALSO
|
|
.Xr crypto 4 ,
|
|
.Xr gbde 4 ,
|
|
.Xr geom 4 ,
|
|
.Xr loader.conf 5 ,
|
|
.Xr gbde 8 ,
|
|
.Xr geom 8 ,
|
|
.Xr crypto 9
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
utility appeared in
|
|
.Fx 6.0 .
|
|
Support for the
|
|
.Nm Camellia
|
|
block cipher is implemented by Yoshisato Yanagisawa in
|
|
.Fx 7.0 .
|
|
.Pp
|
|
Highest
|
|
.Nm GELI
|
|
metadata version supported by the given FreeBSD version:
|
|
.Bl -column -offset indent ".Sy FreeBSD" ".Sy version"
|
|
.It Sy FreeBSD Ta Sy GELI
|
|
.It Sy version Ta Sy version
|
|
.Pp
|
|
.It Li 6.0 Ta 0
|
|
.It Li 6.1 Ta 0
|
|
.It Li 6.2 Ta 3
|
|
.It Li 6.3 Ta 3
|
|
.It Li 6.4 Ta 3
|
|
.Pp
|
|
.It Li 7.0 Ta 3
|
|
.It Li 7.1 Ta 3
|
|
.It Li 7.2 Ta 3
|
|
.It Li 7.3 Ta 3
|
|
.It Li 7.4 Ta 3
|
|
.Pp
|
|
.It Li 8.0 Ta 3
|
|
.It Li 8.1 Ta 3
|
|
.It Li 8.2 Ta 5
|
|
.Pp
|
|
.It Li 9.0 Ta 6
|
|
.Pp
|
|
.It Li 10.0 Ta 7
|
|
.El
|
|
.Sh AUTHORS
|
|
.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org
|