Updated: 2021/Dec/3

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

     cgdconfig - configuration utility for the cryptographic disk driver

     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
     cgdconfig -l [-v[v]] [cgd]
     cgdconfig -s [-nv] [-i ivmeth] cgd dev alg [keylen]
     cgdconfig -U [-nv] [-f configfile]
     cgdconfig -u [-nv] cgd

     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

     -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

     -k kgmeth       Specify the key generation method (default:

     -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

     -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

     -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

     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

     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.

     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

     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

     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.

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

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

             # cgdconfig -g -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 -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 \

     An example parameters file which stores its key locally:

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

     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.

     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.

     cgd(4), dk(4), fstab(5), disklabel(8), gpt(8)

     Alex Biryukov, Daniel Dinu, and Dmitry Khovratovich, Argon2: the memory-
     hard function for password hashing and other applications, University of
     Luxembourg, https://www.password-hashing.net/, 2017.

     "PKCS #5 v2.0: Password-Based Cryptography Standard", RSA Laboratories,
     March 25, 1999.

     The cgdconfig utility appeared in NetBSD 2.0.

     argon2id support appeared in NetBSD 10.0.

     Pass phrases are limited to 1023 bytes.

NetBSD 9.99                    November 4, 2021                    NetBSD 9.99