372 lines
10 KiB
Groff
372 lines
10 KiB
Groff
.\" $NetBSD: cgdconfig.8,v 1.14 2003/06/27 23:02:16 wiz 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.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the NetBSD
|
|
.\" Foundation, Inc. and its contributors.
|
|
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
|
|
.\" contributors may be used to endorse or promote products derived
|
|
.\" from this software without specific prior written permission.
|
|
.\"
|
|
.\" 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 March 24, 2003
|
|
.Dt CGDCONFIG 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm cgdconfig
|
|
.Nd configuration utility for the cryptographic disk driver
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl nv
|
|
.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 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: encblkno).
|
|
.It Fl k Ar kgmeth
|
|
Specify the key generation method (default: pkcs5_pbkdf2).
|
|
.It Fl o Ar outfile
|
|
When generating a
|
|
.Ar paramsfile ,
|
|
store it in
|
|
.Ar outfile .
|
|
.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 indentxxxxxx
|
|
.It pkcs5_pbkdf2
|
|
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 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 storedkey
|
|
This method stores its key in the parameters file.
|
|
.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.
|
|
.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 iterations Ar integer
|
|
The number of iterations. Only used for pkcs5_pbkdf2.
|
|
.It salt Ar base64
|
|
The salt. Only used for 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 encblkno
|
|
(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 none
|
|
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 none cgd0 /dev/wd0e
|
|
/dev/wd0e'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 encblkno;
|
|
keylength 128;
|
|
verify_method none;
|
|
keygen pkcs5_pbkdf2 {
|
|
iterations 39361;
|
|
salt AAAAgMoHiYonye6Kog \\
|
|
dYJAobCHE=;
|
|
};
|
|
.Ed
|
|
.Pp
|
|
An example parameters file which stores its key locally:
|
|
.Bd -literal
|
|
algorithm aes-cbc;
|
|
iv-method encblkno;
|
|
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 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.
|