NetBSD/sbin/cgdconfig/cgdconfig.8

.\" $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.