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 [-v] [-V vmeth] [-i ivmeth] [-k kgmeth] [-o outfile] alg [keylen]

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.
-t: Generate the key and print it to standard output encoded in base64.
-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 standard output.
-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: Read the key (nb: not the passphrase) from stdin.
-U: Unconfigure all the devices listed in the cgd configuration 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 follows:

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 initialization.
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 survive a reboot. It is also handy to facilitate overwriting 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 following 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.
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.

/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 semicolon 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 statements:

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 generation 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

If the keygen block without this statement would generate a key k, then the key generated by this keygen block is derived from k by the key derivation function kdf with the subkey index info.

The only supported key derivation function is hkdf-hmac-sha256 which uses HKDF-Expand of RFC 5869, instantiated with SHA-256.

The name is used by the -C option to share work for key generation between multiple disks: If multiple parameter files share the same keygen blocks with shared statements, except for the info subkey index which must be unique the file, cgdconfig will do the main key generation work once — e.g., computing Argon2id, or running a shell command to draw a key from a hardware token — and then reuse it to configure multiple disks with per-disk subkeys.

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 paramsfiles.
/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 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 /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 frequency scaling technology. Ensure that the processor clock frequency remains static throughout the program's execution.

HISTORY

The cgdconfig utility appeared in NetBSD 2.0.

argon2id support appeared in NetBSD 10.0.

BUGS

Pass phrases are limited to 1023 bytes.