488 lines
13 KiB
Groff
488 lines
13 KiB
Groff
.\" $NetBSD: cgdconfig.8,v 1.49 2021/04/18 19:56:09 maya Exp $
|
|
.\"
|
|
.\" Copyright (c) 2002, The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
|
.\" by Roland C. Dowdeswell.
|
|
.\"
|
|
.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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.
|
|
.\"
|
|
.Dd April 18, 2021
|
|
.Dt CGDCONFIG 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm cgdconfig
|
|
.Nd configuration utility for the cryptographic disk driver
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl enpv
|
|
.Op Fl V Ar vmeth
|
|
.Ar cgd dev
|
|
.Op Ar paramsfile
|
|
.Nm
|
|
.Fl C
|
|
.Op Fl enpv
|
|
.Op Fl f Ar configfile
|
|
.Nm
|
|
.Fl G
|
|
.Op Fl enpv
|
|
.Op Fl i Ar ivmeth
|
|
.Op Fl k Ar kgmeth
|
|
.Op Fl o Ar outfile
|
|
.Ar paramsfile
|
|
.Nm
|
|
.Fl g
|
|
.Op Fl v
|
|
.Op Fl V Ar vmeth
|
|
.Op Fl i Ar ivmeth
|
|
.Op Fl k Ar kgmeth
|
|
.Op Fl o Ar outfile
|
|
.Ar alg
|
|
.Op Ar keylen
|
|
.Nm
|
|
.Fl l
|
|
.Op Fl v Ns Op Cm v
|
|
.Op Ar cgd
|
|
.Nm
|
|
.Fl s
|
|
.Op Fl nv
|
|
.Op Fl i Ar ivmeth
|
|
.Ar cgd
|
|
.Ar dev
|
|
.Ar alg
|
|
.Op Ar keylen
|
|
.Nm
|
|
.Fl U
|
|
.Op Fl nv
|
|
.Op Fl f Ar configfile
|
|
.Nm
|
|
.Fl u
|
|
.Op Fl nv
|
|
.Ar cgd
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
is used to configure and unconfigure cryptographic disk devices (cgds)
|
|
and to maintain the configuration files that are associated with them.
|
|
For more information about cryptographic disk devices see
|
|
.Xr cgd 4 .
|
|
.Pp
|
|
The options are as follows:
|
|
.Bl -tag -width configfilexxxx
|
|
.It Fl C
|
|
Configure all the devices listed in the cgd configuration file.
|
|
.It Fl e
|
|
Echo the passphrase.
|
|
.It Fl f Ar configfile
|
|
Specify the configuration file explicitly, rather than using the default
|
|
configuration file
|
|
.Pa /etc/cgd/cgd.conf .
|
|
.It Fl G
|
|
Generate a new paramsfile (to stdout) using the values from
|
|
.Ar paramsfile
|
|
which will generate the same key.
|
|
This may need to obtain multiple passphrases.
|
|
.It Fl g
|
|
Generate a paramsfile (to stdout).
|
|
.It Fl i Ar ivmeth
|
|
Specify the IV method (default: encblkno1).
|
|
.Pp
|
|
Setting the IV method is needed only for compatibility with disks
|
|
written with a very old version of
|
|
.Xr cgd 4
|
|
from before
|
|
.Nx 5.0 ,
|
|
released in 2010; see
|
|
.Xr cgd 4
|
|
for details.
|
|
.It Fl k Ar kgmeth
|
|
Specify the key generation method (default: pkcs5_pbkdf2/sha1).
|
|
.It Fl l Op Ar cgd
|
|
List state of all devices or just the one
|
|
.Ar cgd
|
|
device.
|
|
The verbosity level affects the output.
|
|
.It Fl n
|
|
Do not actually configure or unconfigure a cryptographic disk
|
|
device, but instead report the steps that would be taken.
|
|
.It Fl o Ar outfile
|
|
When generating a
|
|
.Ar paramsfile ,
|
|
store it in
|
|
.Ar outfile .
|
|
If
|
|
.Fl o
|
|
is not given, any paramsfile content is written to standard output.
|
|
.It Fl p
|
|
Read all passphrases from stdin rather than
|
|
.Pa /dev/tty .
|
|
Passphrases are separated by newlines.
|
|
Users of this flag must be able to predict the order in which passphrases
|
|
are prompted.
|
|
If this flag is specified then verification errors will cause the device
|
|
in question to be unconfigured rather than prompting for the passphrase
|
|
again.
|
|
.It Fl s
|
|
Read the key (nb: not the passphrase) from stdin.
|
|
.It Fl U
|
|
Unconfigure all the devices listed in the cgd configuration file.
|
|
.It Fl u
|
|
Unconfigure a cgd.
|
|
.It Fl V Ar vmeth
|
|
Specify the verification method (default: none).
|
|
.It Fl v
|
|
Be verbose.
|
|
May be specified multiple times.
|
|
.El
|
|
.Pp
|
|
For more information about the cryptographic algorithms supported,
|
|
please refer to
|
|
.Xr cgd 4 .
|
|
.Ss Key Generation Methods
|
|
To generate the key which it will use,
|
|
.Nm
|
|
evaluates all of the key generation methods in the parameters file
|
|
and uses the exclusive-or of the outputs of all the methods.
|
|
The methods and descriptions are as follows:
|
|
.Bl -tag -width indentxxxxxxxxxxx
|
|
.It pkcs5_pbkdf2/sha1
|
|
This method requires a passphrase which is entered at configuration
|
|
time.
|
|
It is a salted hmac-based scheme detailed in
|
|
.Dq PKCS#5 v2.0: Password-Based Cryptography Standard ,
|
|
RSA Laboratories, March 25, 1999, pages 8-10.
|
|
PKCS #5 was also republished as RFC 2898.
|
|
.It pkcs5_pbkdf2
|
|
This is an earlier, slightly incorrect and deprecated implementation
|
|
of the above algorithm.
|
|
It is retained for backwards compatibility with existing parameters
|
|
files, and will be removed.
|
|
Existing parameters files should be
|
|
converted to use the correct method using the
|
|
.Fl G
|
|
option, and a new passphrase.
|
|
.It storedkey
|
|
This method stores its key in the parameters file.
|
|
.It randomkey
|
|
The method simply reads
|
|
.Pa /dev/random
|
|
and uses the resulting bits as the key.
|
|
It does not require a passphrase to be entered.
|
|
This method is typically used to present disk devices that do not
|
|
need to survive a reboot.
|
|
It is also handy to facilitate overwriting the contents of
|
|
a disk volume with meaningless data prior to use.
|
|
.It urandomkey
|
|
The method simply reads
|
|
.Pa /dev/urandom
|
|
and uses the resulting bits as the key.
|
|
This is similar to the
|
|
.Pa randomkey
|
|
method, but it guarantees that
|
|
.Nm
|
|
will not stall waiting for 256 bits of entropy from a hardware RNG
|
|
or seed.
|
|
.It shell_cmd
|
|
This method executes a shell command via
|
|
.Xr popen 3
|
|
and reads the key from stdout.
|
|
.El
|
|
.Ss Verification Method
|
|
The verification method is how
|
|
.Nm
|
|
determines if the generated key is correct.
|
|
If the newly configured disk fails to verify, then
|
|
.Nm
|
|
will regenerate the key and re-configure the device.
|
|
It only makes sense to specify a verification method if at least one of the
|
|
key generation methods is error prone, e.g., uses a user-entered passphrase.
|
|
The following verification methods are supported:
|
|
.Pp
|
|
.Bl -tag -width indentxxx -compact
|
|
.It none
|
|
perform no verification.
|
|
.It disklabel
|
|
scan for a valid disklabel.
|
|
.It mbr
|
|
scan for a valid Master Boot Record.
|
|
.It gpt
|
|
scan for a valid GUID partition table.
|
|
.It ffs
|
|
scan for a valid FFS file system.
|
|
.It re-enter
|
|
prompt for passphrase twice, and ensure entered passphrases are
|
|
identical.
|
|
This method only works with the pkcs5_pbkdf2/sha1 and pkcs5_pbkdf2 key
|
|
generators.
|
|
.El
|
|
.Ss /etc/cgd/cgd.conf
|
|
The file
|
|
.Pa /etc/cgd/cgd.conf
|
|
is used to configure
|
|
.Nm
|
|
if either of
|
|
.Fl C
|
|
or
|
|
.Fl U
|
|
are specified.
|
|
Each line of the file is composed of either two or three
|
|
tokens: cgd, target, and optional paramsfile.
|
|
.Pp
|
|
A
|
|
.Sq \&#
|
|
character is interpreted as a comment and indicates that the
|
|
rest of the line should be ignored.
|
|
A
|
|
.Sq \e
|
|
at the end of a line indicates that the next line is a continuation of
|
|
the current line.
|
|
.Pp
|
|
If the second field is of the form
|
|
.Dq NAME=<value>
|
|
then all the
|
|
.Xr dk 4
|
|
wedge partitions are searched for one that has a wedge name equal to
|
|
.Ar <value>
|
|
and the device corresponding to it is selected.
|
|
.Pp
|
|
If the second field starts with the prefix
|
|
.Dq ROOT.
|
|
the prefix is replaced with
|
|
.Dq /dev/[root_device] ,
|
|
where
|
|
.Bq root_device
|
|
is the value of the
|
|
.Dq kern.root_device
|
|
sysctl.
|
|
.Pp
|
|
See
|
|
.Sx EXAMPLES
|
|
for an example of
|
|
.Pa /etc/cgd/cgd.conf .
|
|
.Ss Parameters File
|
|
The Parameters File contains the required information to generate the
|
|
key and configure a device.
|
|
These files are typically generated by the
|
|
.Fl g
|
|
flag and not edited by hand.
|
|
When a device is configured the default parameters file is constructed
|
|
by taking the basename of the target disk and prepending
|
|
.Pa /etc/cgd/
|
|
to it.
|
|
E.g., if the target is
|
|
.Pa /dev/sd0h ,
|
|
then the default parameters file will be
|
|
.Pa /etc/cgd/sd0h .
|
|
.Pp
|
|
It is possible to have more than one parameters file for a given
|
|
disk which use different key generation methods but will generate
|
|
the same key.
|
|
To create a parameters file that is equivalent to an existing parameters
|
|
file, use
|
|
.Nm
|
|
with the
|
|
.Fl G
|
|
flag.
|
|
See
|
|
.Sx EXAMPLES
|
|
for an example of this usage.
|
|
.Pp
|
|
The parameters file contains a list of statements each terminated
|
|
with a semi-colon.
|
|
Some statements can contain statement-blocks which are either a
|
|
single unadorned statement, or a brace-enclosed list of semicolon
|
|
terminated statements.
|
|
Three types of data are understood:
|
|
.Pp
|
|
.Bl -tag -compact -width integerxx
|
|
.It integer
|
|
a 32 bit signed integer.
|
|
.It string
|
|
a string.
|
|
.It base64
|
|
a length-encoded base64 string.
|
|
.El
|
|
.Pp
|
|
The following statements are defined:
|
|
.Bl -tag -width indentxx
|
|
.It algorithm Ar string
|
|
Defines the cryptographic algorithm.
|
|
.It iv-method Ar string
|
|
Defines the IV generation method.
|
|
This should always be
|
|
.Sq encblkno1
|
|
except when dealing with disks written with a very old version of
|
|
.Xr cgd 4
|
|
from before
|
|
.Nx 5.0 ,
|
|
released in 2010; see
|
|
.Xr cgd 4
|
|
for details.
|
|
.It keylength Ar integer
|
|
Defines the length of the key.
|
|
.It verify_method Ar string
|
|
Defines the verification method.
|
|
.It keygen Ar string Ar statement_block
|
|
Defines a key generation method.
|
|
The
|
|
.Ar statement_block
|
|
contains statements that are specific to the key generation method.
|
|
.El
|
|
.Pp
|
|
The keygen statement's statement block may contain the following statements:
|
|
.Bl -tag -width indentxx
|
|
.It key Ar string
|
|
The key.
|
|
Only used for the storedkey key generation method.
|
|
.It cmd Ar string
|
|
The command to execute.
|
|
Only used for the shell_cmd key generation method.
|
|
.It iterations Ar integer
|
|
The number of iterations.
|
|
Only used for pkcs5_pbkdf2/sha1 and pkcs5_pbkdf2.
|
|
.It salt Ar base64
|
|
The salt.
|
|
Only used for pkcs5_pbkdf2/sha1 and pkcs5_pbkdf2.
|
|
.El
|
|
.Sh FILES
|
|
.Bl -tag -width indentxxxxxxxxxxxxxxxxxx -compact
|
|
.It Pa /etc/cgd/
|
|
configuration directory, used to store paramsfiles.
|
|
.It Pa /etc/cgd/cgd.conf
|
|
cgd configuration file.
|
|
.El
|
|
.Sh EXAMPLES
|
|
To set up and configure a cgd that uses adiantum, which takes a 256-bit
|
|
key:
|
|
.Bd -literal
|
|
# cgdconfig -g -o /etc/cgd/wd0e adiantum 256
|
|
# cgdconfig cgd0 /dev/wd0e
|
|
/dev/wd0e's passphrase:
|
|
.Ed
|
|
.Pp
|
|
When using verification methods, the first time that we configure the
|
|
disk the verification method will fail.
|
|
We overcome this by supplying
|
|
.Fl V Ar re-enter
|
|
when we configure the first time to set up the disk.
|
|
Here is the
|
|
sequence of commands that is recommended:
|
|
.Bd -literal
|
|
# cgdconfig -g -o /etc/cgd/wd0e -V disklabel adiantum
|
|
# cgdconfig -V re-enter cgd0 /dev/wd0e
|
|
/dev/wd0e's passphrase:
|
|
re-enter device's passphrase:
|
|
# disklabel -e -I cgd0
|
|
# cgdconfig -u cgd0
|
|
# cgdconfig cgd0 /dev/wd0e
|
|
/dev/wd0e's passphrase:
|
|
.Ed
|
|
.Pp
|
|
To scrub data from a disk before setting up a cgd:
|
|
.Bd -literal
|
|
# cgdconfig -s cgd0 /dev/sd0e adiantum 256 < /dev/urandom
|
|
# dd if=/dev/zero of=/dev/rcgd0d bs=32k progress=512
|
|
# cgdconfig -u cgd0
|
|
.Ed
|
|
.Pp
|
|
To create a new parameters file that will generate the same key as an old
|
|
parameters file:
|
|
.Bd -literal
|
|
# cgdconfig -G -o newparamsfile oldparamsfile
|
|
old file's passphrase:
|
|
new file's passphrase:
|
|
.Ed
|
|
.Pp
|
|
To configure a cgd that uses aes-cbc with a 192 bit key that it
|
|
reads from stdin:
|
|
.Bd -literal
|
|
# cgdconfig -s cgd0 /dev/sd0h aes-cbc 192
|
|
.Ed
|
|
.Pp
|
|
An example parameters file which uses PKCS#5 PBKDF2:
|
|
.Bd -literal
|
|
algorithm aes-cbc;
|
|
iv-method encblkno1;
|
|
keylength 128;
|
|
verify_method none;
|
|
keygen pkcs5_pbkdf2/sha1 {
|
|
iterations 39361;
|
|
salt AAAAgMoHiYonye6Kog \e
|
|
dYJAobCHE=;
|
|
};
|
|
.Ed
|
|
.Pp
|
|
An example parameters file which stores its key locally:
|
|
.Bd -literal
|
|
algorithm adiantum;
|
|
iv-method encblkno1;
|
|
keylength 256;
|
|
verify_method none;
|
|
keygen storedkey key AAABAK3QO6d7xzLfrXTdsgg4 \e
|
|
ly2TdxkFqOkYYcbyUKu/f60L;
|
|
.Ed
|
|
.Pp
|
|
An example
|
|
.Pa /etc/cgd/cgd.conf :
|
|
.Bd -literal
|
|
#
|
|
# /etc/cgd/cgd.conf
|
|
# Configuration file for cryptographic disk devices
|
|
#
|
|
|
|
# cgd target [paramsfile]
|
|
cgd0 /dev/wd0e
|
|
cgd1 NAME=mycgd /usr/local/etc/cgd/mycgd
|
|
.Ed
|
|
.Pp
|
|
Note the first entry will store the parameters file as
|
|
.Pa /etc/cgd/wd0e .
|
|
And use the entered passphrase to generate the key.
|
|
.Pp
|
|
Although not required, the partition type
|
|
.Ar cgd
|
|
should be used in the disklabel or GPT type field for the cgd partition.
|
|
.Sh DIAGNOSTICS
|
|
.Bl -diag
|
|
.It "cgdconfig: could not calibrate pkcs5_pbkdf2"
|
|
An error greater than 5% in calibration occurred.
|
|
This could be the result of dynamic processor frequency scaling technology.
|
|
Ensure that the processor clock frequency remains static throughout the
|
|
program's execution.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr cgd 4 ,
|
|
.Xr dk 4 ,
|
|
.Xr fstab 5 ,
|
|
.Xr disklabel 8 ,
|
|
.Xr gpt 8
|
|
.Pp
|
|
.Dq PKCS #5 v2.0: Password-Based Cryptography Standard ,
|
|
RSA Laboratories, March 25, 1999.
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
utility appeared in
|
|
.Nx 2.0 .
|
|
.Sh BUGS
|
|
Pass phrases are limited to 1023 bytes.
|