cgdconfig(8) - NetBSD Manual Pages

Command:

Section:

Arch:

Collection:

>>>

CGDCONFIG(8) NetBSD System Manager's Manual CGDCONFIG(8)

NAME

cgdconfig -- configuration utility for the cryptographic disk driver

SYNOPSIS

cgdconfig [-enpv] [-V vmeth] cgd dev [paramsfile]
cgdconfig -C [-enpv] [-f configfile]
cgdconfig -G [-enpv] [-i ivmeth] [-k kgmeth] [-o outfile] paramsfile
cgdconfig -g [-Sv] [-V vmeth] [-i ivmeth] [-k kgmeth] [-o outfile]
[-P paramsfile] alg [keylen]
cgdconfig -T [-f configfile]
cgdconfig -t paramsfile
cgdconfig -l [-v[v]] [cgd]
cgdconfig -s [-nv] [-i ivmeth] cgd dev alg [keylen]
cgdconfig -U [-nv] [-f configfile]
cgdconfig -u [-nv] cgd

DESCRIPTION

cgdconfig 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 cgd(4).

The options are as follows:

-C Configure all the devices listed in the cgd configuration
file.

-e Echo the passphrase.

-f configfile Specify the configuration file explicitly, rather than
using the default configuration file /etc/cgd/cgd.conf.

-G Generate a new paramsfile (to stdout) using the values
from paramsfile which will generate the same key. This
may need to obtain multiple passphrases.

-g Generate a paramsfile (to stdout).

-i ivmeth Specify the IV method (default: encblkno1).

Setting the IV method is needed only for compatibility
with disks written with a very old version of cgd(4) from
before NetBSD 5.0, released in 2010; see cgd(4) for
details.

-k kgmeth Specify the key generation method (default:
pkcs5_pbkdf2/sha1).

-l [cgd] List state of all devices or just the one cgd device.
The verbosity level affects the output.

-n Do not actually configure or unconfigure a cryptographic
disk device, but instead report the steps that would be
taken.

-o outfile When generating a paramsfile, store it in outfile. If -o
is not given, any paramsfile content is written to stan-
dard output.

-P paramsfile With the -S option for the -g or -G actions, specify a
parameters file with a shared key to reuse for deriving
this one as a subkey.

-p Read all passphrases from stdin rather than /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.

-S When generating a parameters file with -g or -G, arrange
to use a subkey of a shared key. If -P paramsfile is
also specified, reuse the shared key of paramsfile; oth-
erwise a new one will be generated.

-s Read the key (nb: not the passphrase) from stdin.

-T Generate all keys for all the devices listed in the
cgdconfig configuration file and print them to standard
output encoded in base64.

-t Generate the key and print it to standard output encoded
in base64.

-U Unconfigure all the devices listed in the cgd configura-
tion file.

-u Unconfigure a cgd.

-V vmeth Specify the verification method (default: none).

-v Be verbose. May be specified multiple times.

For more information about the cryptographic algorithms supported, please
refer to cgd(4).

Key Generation Methods
To generate the key which it will use, cgdconfig 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 fol-
lows:

argon2id This method requires a passphrase which is entered at
configuration time. Argon2 is a memory-hard password
hashing scheme and winner of the 2013-2015 Password
Hashing Competition. It has numerous parameters
allowing its hardness to scale with the performance of
the system. Recommended for passphrase-based initial-
ization.

pkcs5_pbkdf2/sha1 This method requires a passphrase which is entered at
configuration time. It is a salted hmac-based scheme
detailed in ``PKCS#5 v2.0: Password-Based Cryptography
Standard'', RSA Laboratories, March 25, 1999, pages
8-10. PKCS #5 was also republished as RFC 2898.

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 -G option, and a new passphrase.

storedkey This method stores its key in the parameters file.

randomkey The method simply reads /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 sur-
vive a reboot. It is also handy to facilitate over-
writing the contents of a disk volume with meaningless
data prior to use.

urandomkey The method simply reads /dev/urandom and uses the
resulting bits as the key. This is similar to the
randomkey method, but it guarantees that cgdconfig
will not stall waiting for 256 bits of entropy from a
hardware RNG or seed.

shell_cmd This method executes a shell command via popen(3) and
reads the key from stdout.

Verification Method
The verification method is how cgdconfig determines if the generated key
is correct. If the newly configured disk fails to verify, then cgdconfig
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 fol-
lowing verification methods are supported:

none perform no verification.
disklabel scan for a valid disklabel.
mbr scan for a valid Master Boot Record.
gpt scan for a valid GUID partition table.
ffs scan for a valid FFS file system.
zfs scan for a valid ZFS vdev label (if compiled with MKZFS).
re-enter prompt for passphrase twice, and ensure entered passphrases
are identical. This method only works with the argon2id,
pkcs5_pbkdf2/sha1, and pkcs5_pbkdf2 key generators.

If a wrong key is generated, e.g. if the passphrase is entered incor-
rectly, the disk content will appear to be randomized. Assuming uniform
random disk content, each verification method has some probability of
falsely accepting a wrong key anyway. The probability for each method is
as follows:

method verifies P(false accept)
none nothing 1
disklabel 64-bit magic strings w/16-bit cksum in any of 1946
places 1
-
(1
-
1/2^80)^1946
<
1/6e20
mbr 16-bit magic string 1/65536
gpt 128-bit magic string w/32-bit cksum in any of 4
places 1
-
(1
-
1/2^160)^4
<
1/3e47
ffs any of 6 32-bit magic strings in any of 4
places 1
-
(1
-
6/2^32)^4
<
1/1e8
zfs any of 2 64-bit magic strings w/256-bit cksum in any of 4
places1
-
(1
-
2/2^320)^4
<
1/1e68
re-enter matching >=160-bit hashes <= 1/2^160 < 1/1e48

Note that aside from the `none' method, which accepts any key uncondi-
tionally, the `mbr' method and to a lesser extent the `ffs' method also
accept a wrong key with a much higher probability than cryptography nor-
mally deals in.

This is not a security vulnerability in the confidentiality of cgd(4)
against an adversary, but it may be alarming for a user if a disk is con-
figured with a mistyped passphrase, cgdconfig accepts the wrong key, and
the content appears to be garbage -- for example, fsck may fail with
scary warnings, and any writes to the disk configured with the wrong key
will corrupt the original plaintext content under the right key.

/etc/cgd/cgd.conf
The file /etc/cgd/cgd.conf is used to configure cgdconfig if either of -C
or -U are specified. Each line of the file is composed of either two or
three tokens: cgd, target, and optional paramsfile.

A `#' character is interpreted as a comment and indicates that the rest
of the line should be ignored. A `\' at the end of a line indicates that
the next line is a continuation of the current line.

If the second field is of the form ``NAME=<value>'' then all the dk(4)
wedge partitions are searched for one that has a wedge name equal to
<value> and the device corresponding to it is selected.

If the second field starts with the prefix ``ROOT.'' the prefix is
replaced with ``/dev/[root_device]'', where [root_device] is the value of
the ``kern.root_device'' sysctl.

See EXAMPLES for an example of /etc/cgd/cgd.conf.

Parameters File
The Parameters File contains the required information to generate the key
and configure a device. These files are typically generated by the -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 /etc/cgd/ to it. E.g., if the target is /dev/sd0h, then
the default parameters file will be /etc/cgd/sd0h.

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 cgdconfig with the -G flag. See EXAMPLES for an
example of this usage.

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 semi-
colon terminated statements. Three types of data are understood:

integer a 32 bit signed integer.
string a string.
base64 a length-encoded base64 string.

The following statements are defined:

algorithm string
Defines the cryptographic algorithm.

iv-method string
Defines the IV generation method. This should always be
`encblkno1' except when dealing with disks written with a very
old version of cgd(4) from before NetBSD 5.0, released in 2010;
see cgd(4) for details.

keylength integer
Defines the length of the key.

verify_method string
Defines the verification method.

keygen string statement_block
Defines a key generation method. The statement_block contains
statements that are specific to the key generation method.

The keygen statement's statement block may contain the following state-
ments:

key string
The key. Only used for the storedkey key generation method.

cmd string
The command to execute. Only used for the shell_cmd key gener-
ation method.

iterations integer
The number of iterations. Only used for argon2id,
pkcs5_pbkdf2/sha1, and pkcs5_pbkdf2.

salt base64
The salt. Only used for argon2id, pkcs5_pbkdf2/sha1, and
pkcs5_pbkdf2.

memory integer
Memory consumption in kilobytes. Only used for argon2id.

parallelism integer
Number of threads to use to compute the password hash. Should
be equivalent to the number of CPUs/hardware threads. Only
used for argon2id.

version integer
Version of Argon2 to use. Should be the most recent version,
currently 19. Only used for argon2id.

shared name algorithm kdf subkey info
Makes the key generation take an extra step to derive a subkey
from the main key using the key derivation function kdf with
input info.

This enables a single password entry, for example, to decrypt
multiple disks that use different keys, each derived as a sub-
key from the main key generated from the password.

name A string used to identify the same main key generation
shared between parameters files for different disks
listed in a single cgd.conf configuration file.

kdf The name of a key derivation function used to derive a
subkey from the main key. Supported values:

hkdf-hmac-sha256
The HKDF-Expand function of RFC 5869,
instantiated with SHA-256.

info A base64 length-encoded string to distinguish different
subkeys derived from a shared main key. Need not be
secret. For example, it could be a nickname, or the
disk's World-Wide Name, or a UUID generated for the
disk, or just a random string.

It is an error to reuse a shared key name with different keygen
blocks, other than the info parameter, between parameters files
used by a single cgd.conf configuration file.

FILES

/etc/cgd/ configuration directory, used to store params-
files.
/etc/cgd/cgd.conf cgd configuration file.

EXAMPLES

To set up and configure a cgd that uses adiantum, which takes a 256-bit
key:

# cgdconfig -g -k argon2id -o /etc/cgd/wd0e adiantum 256
# cgdconfig cgd0 /dev/wd0e
/dev/wd0e's passphrase:

When using verification methods, the first time that we configure the
disk the verification method will fail. We overcome this by supplying -V
re-enter when we configure the first time to set up the disk. Here is
the sequence of commands that is recommended:

# cgdconfig -g -k argon2id -o /etc/cgd/dk3 -V gpt adiantum
# cgdconfig -V re-enter cgd0 /dev/dk3
/dev/dk3's passphrase:
re-enter device's passphrase:
# gpt create cgd0
# cgdconfig -u cgd0
# cgdconfig cgd0 /dev/dk3
/dev/dk3's passphrase:

To scrub data from a disk before setting up a cgd:

# cgdconfig -s cgd0 /dev/sd0e adiantum 256 < /dev/urandom
# dd if=/dev/zero of=/dev/rcgd0d bs=32k progress=512
# cgdconfig -u cgd0

To create a new parameters file that will generate the same key as an old
parameters file:

# cgdconfig -G -o newparamsfile oldparamsfile
old file's passphrase:
new file's passphrase:

To create parameters files for three disks with subkeys derived from a
shared password-based key:

# cgdconfig -g -S -k argon2id -o /etc/cgd/wd0 -V gpt adiantum
# cgdconfig -g -S -P /etc/cgd/wd0 -o /etc/cgd/ld1 \
-V disklabel aes-cbc 256

Listing these in the same /etc/cgd/cgd.conf will allow you to enter a
password once to decrypt both disks with cgdconfig -C.

To configure a cgd that uses aes-cbc with a 192 bit key that it reads
from stdin:

# cgdconfig -s cgd0 /dev/sd0h aes-cbc 192

An example parameters file which uses PKCS#5 PBKDF2:

algorithm aes-cbc;
iv-method encblkno1;
keylength 128;
verify_method none;
keygen pkcs5_pbkdf2/sha1 {
iterations 39361;
salt AAAAgMoHiYonye6Kog \
dYJAobCHE=;
};

An example parameters file which stores its key locally:

algorithm adiantum;
iv-method encblkno1;
keylength 256;
verify_method none;
keygen storedkey key AAABAK3QO6d7xzLfrXTdsgg4 \
ly2TdxkFqOkYYcbyUKu/f60L;

An example pair of configuration files which use shared keys so they can
be derived from a single passphrase entry, with the 64-bit World-Wide
Name of each disk (base64 length-encoded) as its subkey info:

/etc/cgd/wd0a

algorithm adiantum;
iv-method encblkno1;
keylength 256;
verify_method gpt;
keygen argon2id {
iterations 32;
memory 5214;
parallelism 2;
version 19;
salt AAAAgLZ5QgleU2m/Ib6wiPYxz98=;
shared "my laptop" algorithm hkdf-hmac-sha256 \
subkey AAAAQEGELNr3bj3I;
};

/etc/cgd/wd1a

An example /etc/cgd/cgd.conf:

#
# /etc/cgd/cgd.conf
# Configuration file for cryptographic disk devices
#

# cgd target [paramsfile]
cgd0 /dev/wd0e
cgd1 NAME=mycgd /usr/local/etc/cgd/mycgd

Note the first entry will store the parameters file as /etc/cgd/wd0e.
And use the entered passphrase to generate the key.

Although not required, the partition type cgd should be used in the
disklabel or GPT type field for the cgd partition.

DIAGNOSTICS

cgdconfig: could not calibrate pkcs5_pbkdf2 An error greater than 5% in
calibration occurred. This could be the result of dynamic processor fre-
quency scaling technology. Ensure that the processor clock frequency
remains static throughout the program's execution.