422 lines
12 KiB
Groff
422 lines
12 KiB
Groff
.\" $NetBSD: cgdconfig.8,v 1.28 2008/09/12 16:51:55 christos 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 September 12, 2008
|
|
.Dt CGDCONFIG 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm cgdconfig
|
|
.Nd configuration utility for the cryptographic disk driver
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl npv
|
|
.Op Fl V Ar vmeth
|
|
.Ar cgd dev
|
|
.Op Ar paramsfile
|
|
.Nm
|
|
.Fl C
|
|
.Op Fl nv
|
|
.Op Fl f Ar configfile
|
|
.Nm
|
|
.Fl U
|
|
.Op Fl nv
|
|
.Op Fl f Ar configfile
|
|
.Nm
|
|
.Fl G
|
|
.Op Fl nv
|
|
.Op Fl i Ar ivmeth
|
|
.Op Fl k Ar kgmeth
|
|
.Op Fl o Ar outfile
|
|
.Ar paramsfile
|
|
.Nm
|
|
.Fl g
|
|
.Op Fl nv
|
|
.Op Fl i Ar ivmeth
|
|
.Op Fl k Ar kgmeth
|
|
.Op Fl o Ar outfile
|
|
.Ar alg
|
|
.Op Ar keylen
|
|
.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
|
|
.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 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 prompt for multiple passphrases.
|
|
.It Fl g
|
|
Generate a paramsfile (to stdout).
|
|
.It Fl i Ar ivmeth
|
|
Specify the IV method (default: encblkno1).
|
|
.It Fl k Ar kgmeth
|
|
Specify the key generation method (default: pkcs5_pbkdf2/sha1).
|
|
.It Fl o Ar outfile
|
|
When generating a
|
|
.Ar paramsfile ,
|
|
store it in
|
|
.Ar outfile .
|
|
.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 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 and IV methods
|
|
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, such as the swap partition.
|
|
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 cgdconfig will not stall waiting for
|
|
hard-random bits (useful when configuring a cgd for swap at boot time).
|
|
Note, however, that some or all of the bits used to generate the
|
|
key may be obtained from a pseudo-random number generator,
|
|
which may not be as secure as the entropy based hard-random
|
|
number generator.
|
|
.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 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 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
|
|
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.
|
|
.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 AES with a 192 bit key
|
|
in CBC mode with the IV Method
|
|
.Sq encblkno1
|
|
(encrypted block number):
|
|
.Bd -literal
|
|
# cgdconfig -g -o /etc/cgd/wd0e aes-cbc 192
|
|
# 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 aes-cbc
|
|
# 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 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 Blowfish with a 200 bit key that it
|
|
reads from stdin:
|
|
.Bd -literal
|
|
# cgdconfig -s cgd0 /dev/sd0h blowfish-cbc 200
|
|
.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 \\
|
|
dYJAobCHE=;
|
|
};
|
|
.Ed
|
|
.Pp
|
|
An example parameters file which stores its key locally:
|
|
.Bd -literal
|
|
algorithm aes-cbc;
|
|
iv-method encblkno1;
|
|
keylength 256;
|
|
verify_method none;
|
|
keygen storedkey key AAABAK3QO6d7xzLfrXTdsgg4 \\
|
|
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 /dev/sd0h /usr/local/etc/cgd/sd0h
|
|
.Ed
|
|
.Pp
|
|
Note that this will store the parameters file as
|
|
.Pa /etc/cgd/wd0e .
|
|
And use the entered passphrase to generate the key.
|
|
.Sh DIAGNOSTICS
|
|
.Bl -diag
|
|
.It "cgdconfig: could not calibrate pkcs5_pbkdf2"
|
|
An error greater than 5% in calibration occured.
|
|
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
|
|
.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
|
|
Since
|
|
.Nm
|
|
uses
|
|
.Xr getpass 3
|
|
to read in the passphrase, it is limited to 128 characters.
|