c58794debd
For features list and usage see manual page: geli(8). Sponsored by: Wheel Sp. z o.o. http://www.wheel.pl MFC after: 1 week
512 lines
14 KiB
Groff
512 lines
14 KiB
Groff
.\" Copyright (c) 2005 Pawel Jakub Dawidek <pjd@FreeBSD.org>
|
|
.\" 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 April 11, 2005
|
|
.Dt GELI 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm geli
|
|
.Nd "control utility for cryptographic GEOM class"
|
|
.Sh SYNOPSIS
|
|
To compile GEOM_ELI into your kernel, place the following lines in your kernel
|
|
configuration file:
|
|
.Bd -ragged -offset indent
|
|
.Cd "device crypto"
|
|
.Cd "device cryptodev"
|
|
.Cd "options GEOM_ELI"
|
|
.Ed
|
|
.Pp
|
|
Alternately, to load the GEOM_ELI module at boot time, place the following line
|
|
in your
|
|
.Xr loader.conf 5 :
|
|
.Bd -literal -offset indent
|
|
geom_eli_load="YES"
|
|
.Ed
|
|
.Pp
|
|
Usage of the
|
|
.Xr geli 8
|
|
utility:
|
|
.Pp
|
|
.Nm
|
|
.Cm init
|
|
.Op Fl bPv
|
|
.Op Fl a Ar algo
|
|
.Op Fl i Ar iterations
|
|
.Op Fl K Ar newkeyfile
|
|
.Op Fl l Ar keylen
|
|
.Op Fl s Ar sectorsize
|
|
.Ar prov
|
|
.Nm
|
|
.Cm label - an alias for
|
|
.Cm init
|
|
.Nm
|
|
.Cm attach
|
|
.Op Fl dpv
|
|
.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 algo
|
|
.Op Fl l Ar keylen
|
|
.Op Fl s Ar sectorsize
|
|
.Ar prov ...
|
|
.Nm
|
|
.Cm setkey
|
|
.Op Fl pPv
|
|
.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 v
|
|
.Ar file
|
|
.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
|
|
Here is the list of the most important features:
|
|
.Pp
|
|
.Bl -bullet -offset indent -compact
|
|
.It
|
|
Utilize the
|
|
.Xr crypto 9
|
|
framework, so when there is a crypto hardware available,
|
|
.Nm
|
|
will make use of it automatically.
|
|
If cryptography needs to be done in software,
|
|
a dedicated kernel thread will be started to do the crypto work in there.
|
|
.It
|
|
Supports many cryptographic algorithms (currently
|
|
.Nm AES ,
|
|
.Nm Blowfish
|
|
and
|
|
.Nm 3DES ) .
|
|
.It
|
|
Can create a key from a couple of components (user entered passphrase, random
|
|
bits from a file, etc.).
|
|
.It
|
|
Allows to encrypt root partition - user will be asked for the passphrase before
|
|
root file system is mounted.
|
|
.It
|
|
User's passphrase is strengthen with:
|
|
.Rs
|
|
.%A B. Kaliski
|
|
.%T "PKCS #5: Password-Based Cryptography Specification, Version 2.0."
|
|
.%R RFC
|
|
.%N 2898
|
|
.Re
|
|
.It
|
|
Allows to use two independent keys (e.g.
|
|
.Qq "user key"
|
|
and
|
|
.Qq "company key" ) .
|
|
.It
|
|
It is fast -
|
|
.Nm
|
|
performs simple sector-to-sector encryption.
|
|
.It
|
|
Allows to backup/restore Master Keys, so when user have to quickly destroy keys,
|
|
it is able to get the data back by restoring keys from the backup.
|
|
.It
|
|
Provider can be configured to automatically detach on last close (so user don't
|
|
have to remember to detach provider after unmounting file system).
|
|
.It
|
|
Allows to attach provider with a random, one-time keys - useful for swap
|
|
partitions and temporary file systems.
|
|
.El
|
|
.Pp
|
|
The first argument to
|
|
.Nm
|
|
indicates an action to be performed:
|
|
.Bl -tag -width ".Cm onetime"
|
|
.It Cm init
|
|
Initialize provider which needs to be encrypted.
|
|
Here you can setup 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
|
|
Encryption algorithm to use.
|
|
Currently supported algorithms are:
|
|
.Nm AES ,
|
|
.Nm Blowfish
|
|
and
|
|
.Nm 3DES .
|
|
The default is
|
|
.Nm AES .
|
|
.It Fl b
|
|
Ask for the passphrase on boot, before root partition is mounted.
|
|
This allows to use encrypted root partition.
|
|
One will still need bootable unencrypted storage with
|
|
.Pa /boot/
|
|
directory, which can be a CD-ROM disc or USB pen-drive, which can be removed
|
|
after boot.
|
|
.It Fl i Ar iterations
|
|
Number of iterations to use with PKCS#5v2.
|
|
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.
|
|
.It Fl K Ar newkeyfile
|
|
Specifies a file which contains part of the key.
|
|
If
|
|
.Ar newkeyfile
|
|
is given as -, standard input will be used.
|
|
Here is how more than one file with the key component can be used:
|
|
.Bd -literal -offset indent
|
|
# cat key1 key2 key3 | geli init -K - /dev/da0
|
|
.Ed
|
|
.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 ,
|
|
128 for
|
|
.Nm Blowfish
|
|
and 192 for
|
|
.Nm 3DES .
|
|
.It Fl s Ar sectorsize
|
|
Change decrypted provider's sector size.
|
|
Increasing sector size allows to increase performance, because we need to
|
|
generate IV and do encrypt/decrypt for every single sector - less number
|
|
of sectors means less work to do.
|
|
.It Fl P
|
|
Do not use passphrase as the key component.
|
|
.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
|
|
.Qq .eli
|
|
suffix.
|
|
.Pp
|
|
Additional options include:
|
|
.Bl -tag -width ".Fl a Ar algo"
|
|
.It Fl d
|
|
If specified, decrypted provider will be detached automatically on last close.
|
|
This can help with short memory - user doesn't have to remember to detach
|
|
provider after unmounting file system.
|
|
It only works when provider was opened for writing, so it will not work if
|
|
file system on the provider is mounted read-only.
|
|
Probably better choice is the
|
|
.Fl l
|
|
option for the
|
|
.Cm detach
|
|
subcommand.
|
|
.It Fl k Ar keyfile
|
|
Specifies a file which contains part of the key.
|
|
For more information see description of
|
|
.Fl K
|
|
option for the
|
|
.Cm init
|
|
subcommand.
|
|
.It Fl p
|
|
Do not use passphrase as the key component.
|
|
.El
|
|
.It Cm detach
|
|
Detach the given providers, which means remove devfs entry and clear the keys
|
|
from memory.
|
|
.Pp
|
|
Additional options include:
|
|
.Bl -tag -width ".Fl a Ar algo"
|
|
.It Fl f
|
|
Force detach - detach even if provider is open.
|
|
.It Fl l
|
|
Mark provider to detach on last close.
|
|
If this option is specified provider will not be detached until it is open,
|
|
but when it will be closed last time, it will be automatically detached (even
|
|
if it was only opened for reading).
|
|
.El
|
|
.It Cm onetime
|
|
Attach the given providers with a 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
|
|
Encryption algorithm to use.
|
|
For more information see description of the
|
|
.Cm init
|
|
subcommand.
|
|
.It Fl d
|
|
Detach on last close.
|
|
Note, the option is not usable for temporary file system, because provider will
|
|
be detached after creating file system on it.
|
|
It still can (and should be) used for swap partitions.
|
|
For more information see description of the
|
|
.Cm attach
|
|
subcommand.
|
|
.It Fl l Ar keylen
|
|
Key length to use with the given cryptographic algorithm.
|
|
For more information see description of the
|
|
.Cm init
|
|
subcommand.
|
|
.It Fl s Ar sectorsize
|
|
Change decrypted provider's sector size.
|
|
For more information see description of the
|
|
.Cm init
|
|
subcommand.
|
|
.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.
|
|
With the
|
|
.Cm init
|
|
subcommand only key number 0 is initialized.
|
|
The key can be always changed: for attached provider, for detached provider or
|
|
on the backup file.
|
|
When provider is attached, user don't have to provide an old passphrase/keyfile.
|
|
.Pp
|
|
Additional options include:
|
|
.Bl -tag -width ".Fl a Ar algo"
|
|
.It Fl k Ar keyfile
|
|
Specifies a file which contains part of the old key.
|
|
.It Fl K Ar newkeyfile
|
|
Specifies a file which contains part of the new key.
|
|
.It Fl n Ar keyno
|
|
Specifies number of the key to change (could be 0 or 1).
|
|
If provider is attached and no key number is given, the key used for attaching
|
|
provider will be changed.
|
|
If provider is detached (or we're operating on a backup file) and no key number
|
|
is given, the key decrypted with passphrase/keyfile will be changed.
|
|
.It Fl p
|
|
Do not use passphrase as the old key component.
|
|
.It Fl P
|
|
Do not use passphrase as the new key component.
|
|
.El
|
|
.It Cm delkey
|
|
Destroy (overwrite with random data) selected key.
|
|
If one is destroying keys for an attached provider, provider won't be detached
|
|
even if all keys will be destroyed.
|
|
It can be even rescued with the
|
|
.Cm setkey
|
|
subcommand.
|
|
.Bl -tag -width ".Fl a Ar algo"
|
|
.It Fl a
|
|
Destroy all keys (doesn't need
|
|
.Fl f
|
|
option).
|
|
.It Fl f
|
|
Force key destruction. This option is needed to destroy the last key.
|
|
.It Fl n Ar keyno
|
|
Specifies the key number.
|
|
If provider is attached and no key number is given, the key used for attaching
|
|
provider will be destroyed.
|
|
If provider is detached (or we're operating on a backup file) the key number
|
|
has to be given.
|
|
.El
|
|
.It Cm kill
|
|
The command should be used in emergency situations.
|
|
It will destroy all keys on the given provider and will detach it forcibly
|
|
(if it is attached).
|
|
This is absolutely one-way command - if you don't have metadata backup, your data
|
|
is gone for good.
|
|
.Bl -tag -width ".Fl a Ar algo"
|
|
.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.
|
|
.It Cm clear
|
|
Clear metadata from the given providers.
|
|
.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 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.
|
|
.Bl -tag -width indent
|
|
.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, and 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 user is asked for the passphrase.
|
|
This is only used for providers which should be attached on boot (before 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 Master-Key will be overwriten 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, passphrase entered on boot (before root file system is mounted)
|
|
will be visible.
|
|
This possibility should be used with caution as 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 1
|
|
Specifies how many kernel threads should be used for doing software
|
|
cryptography.
|
|
It's purpose is to increase performance on SMP systems.
|
|
This variable could be set in
|
|
.Pa /boot/loader.conf .
|
|
.El
|
|
.Sh EXIT STATUS
|
|
Exit status is 0 on success, and 1 if the command fails.
|
|
.Sh EXAMPLES
|
|
Initialize 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 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 encrypted provider, but use two key: one for your girlfriend and one for
|
|
you (so there will be no tragedy if she forget her passphrase):
|
|
.Bd -literal -offset indent
|
|
# geli init /dev/da2
|
|
Enter new passphrase: (enter your passphrase)
|
|
Reenter new passphrase:
|
|
# geli setkey -n 1 /dev/da2
|
|
Enter passphrase: (enter your passphrase)
|
|
Enter new passphrase: (let your girlfriend to enter her passphrase ...)
|
|
Reenter new passphrase: (... twice)
|
|
.Ed
|
|
.Pp
|
|
You are security-person in your company.
|
|
Create encrypted provider for use by the user, but remember that users forget
|
|
their passphrases, so backup 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/ad0s1e
|
|
# geli backup /dev/ad0s1e /mnt/pendrive/backups/`hostname`
|
|
(use key number 0, so encrypted Master Key by you will be overwriten)
|
|
# geli setkey -n 0 -k /mnt/pendrive/keys/`hostname` /dev/ad0s1e
|
|
(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/ad0s1b bs=1m
|
|
# geli onetime -d -a 3des ad0s1b
|
|
# swapon /dev/ad0s1b.eli
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr crypto 4 ,
|
|
.Xr crypto 9 ,
|
|
.Xr gbde 4 ,
|
|
.Xr gbde 8 ,
|
|
.Xr geom 4 ,
|
|
.Xr geom 8
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
utility appeared in
|
|
.Fx 5.5 .
|
|
.Sh AUTHORS
|
|
.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org
|