.\" $NetBSD: cgdconfig.8,v 1.57.2.1 2024/10/11 08:54:39 martin 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 May 12, 2024 .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 Sv .Op Fl V Ar vmeth .Op Fl i Ar ivmeth .Op Fl k Ar kgmeth .Op Fl o Ar outfile .Op Fl P Ar paramsfile .Ar alg .Op Ar keylen .Nm .Fl T .Op Fl f Ar configfile .Nm .Fl t .Ar paramsfile .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 Ar paramsfile With the .Fl S option for the .Fl g or .Fl G actions, specify a parameters file with a shared key to reuse for deriving this one as a subkey. .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 When generating a parameters file with .Fl g or .Fl G , arrange to use a subkey of a shared key. If .Fl P Ar paramsfile is also specified, reuse the shared key of .Ar paramsfile ; otherwise a new one will be generated. .It Fl s Read the key (nb: not the passphrase) from stdin. .It Fl T Generate all keys for all the devices listed in the .Nm configuration file and print them to standard output encoded in base64. .It Fl t Generate the key and print it to standard output encoded in base64. .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 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. .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 zfs scan for a valid ZFS vdev label (if compiled with MKZFS). .It 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. .El .Pp If a wrong key is generated, e.g. if the passphrase is entered incorrectly, 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: .Bl -column "disklabel" "matching \*(Ge160-bit hashes" "1 - (1 - 1/2^80)^1946 < 1/6e20" .It Sy method Ta Sy verifies Ta Sy "P(false accept)" .It Li none Ta No nothing Ta "1" Ta .\" disklabel: .\" - scans SCANSIZE=8192 bytes with disklabel_scan, which... .\" - checks {0, 4, 8, 12, ..., SCANSIZE=8192 - sizeof(struct .\" disklabel)=408}, 1946 options total, for a matching 64-bit .\" quantity (d_magic=DISKMAGIC, d_magic2=DISKMAGIC) plus a matching .\" 16-bit cksum (plus a plausible d_npartitions but let's ignore .\" that) .\" Pr[false accept] = Pr[exists i. scan[i] matches 80-bit magic/cksum] .\" = 1 - Pr[not exists i. scan[i] does not match 80-bit magic/cksum] .\" = 1 - Pr[forall i. scan[i] does not match 80-bit magic/cksum] .\" = 1 - \prod_i Pr[scan[i] does not match 80-bit magic/cksum] .\" = 1 - \prod_i (1 - Pr[scan[i] matches 80-bit magic/cksum]) .\" = 1 - \prod_i (1 - 1/2^80) .\" = 1 - (1 - 1/2^80)^1946 .\" = 1 - exp(1946*log(1 - 1/2^80)) .\" = -expm1(1946*log1p(-1/2^80)) .\" <= 1/621e18 <= 1/6e20 (one in six hundred quintillion) .It Li disklabel Ta No 64-bit magic strings w/16-bit cksum in any of 1946 places Ta "1 - (1 - 1/2^80)^1946 < 1/6e20" .\" mbr: .\" - checks exactly one location .\" - checks for exactly one magic 16-bit constant .\" Pr[false accept] = 1/2^16 = 1/65536 .It Li mbr Ta No 16-bit magic string Ta "1/65536" .\" gpt: .\" - scans SCANSIZE=8192 bytes .\" - checks blksizes DEV_BSIZE=512, 1024, 2048, 4096 .\" - checks for 64-bit sig, 32-bit rev, 32-bit size, 32-bit cksum .\" Pr[false accept] .\" = Pr[exists blksz. hdr[blksz] matches 160-bit magic/cksum] .\" = 1 - Pr[not exists blksz. hdr[blksz] matches 160-bit magic/cksum] .\" = 1 - Pr[forall blksz. hdr[blksz] does not match 160-bit magic/cksum] .\" = 1 - \prod_blksz Pr[hdr[blksz] does not match 160-bit magic/cksum] .\" = 1 - \prod_blksz (1 - Pr[hdr[blksz] matches 160-bit magic/cksum]) .\" = 1 - \prod_blksz (1 - 1/2^160) .\" = 1 - (1 - 1/2^160)^4 .\" = 1 - exp(4*log(1 - 1/2^160)) .\" = -expm1(4*log1p(-1/2^160)) .\" <= 1/3e47 .It Li gpt Ta No 128-bit magic string w/32-bit cksum in any of 4 places Ta "1 - (1 - 1/2^160)^4 < 1/3e47" Ta .\" ffs: .\" - checks four locations in SBLOCKSEARCH (sblock_try) .\" - checks for any of six magic 32-bit constants .\" Pr[false accept] = Pr[exists i. sblock_try[i] in {magic[0], ..., magic[5]}] .\" = 1 - Pr[not exists i. sblock_try[i] in {magic[0], ..., magic[5]}] .\" = 1 - Pr[forall i. sblock_try[i] not in {magic[0], ..., magic[5]}] .\" = 1 - \prod_i Pr[sblock_try[i] not in {magic[0], ..., magic[5]}] .\" = 1 - \prod_i (1 - Pr[sblock_try[i] in {magic[0], ..., magic[5]}]) .\" = 1 - \prod_i (1 - 6/2^32) .\" = 1 - (1 - 6/2^32)^4 .\" = 1 - exp(4*log(1 - 6/2^32)) .\" = -expm1(4*log1p(-6/2^32)) .\" <= 1/178e6 <= 1/1e8 (one in a hundred million) .It Li ffs Ta No any of 6 32-bit magic strings in any of 4 places Ta "1 - (1 - 6/2^32)^4 < 1/1e8" Ta .\" zfs: .\" - checks four locations (VDEV_LABELS) .\" - checks for any of two magic 64-bit constants (ZEC_MAGIC or bswap) .\" - checks for 256-bit SHA256 hash .\" Pr[false accept] = Pr[exists i. label[i] matches 320-bit magic/cksum] .\" = 1 - Pr[not exists i. label[i] matches 320-bit magic/cksum] .\" = 1 - Pr[forall i. label[i] does not match 320-bit magic/cksum] .\" = 1 - \prod_i Pr[label[i] does not match 320-bit magic/cksum] .\" = 1 - \prod_i (1 - Pr[label[i] does matches 320-bit magic/cksum]) .\" = 1 - \prod_i (1 - 2/2^230) .\" = 1 - (1 - 2/2^230)^4 .\" = -expm1(4*log1p(-2/2^230)) .\" <= 1/2e68 .It Li zfs Ta No any of 2 64-bit magic strings w/256-bit cksum in any of 4 places Ta "1 - (1 - 2/2^320)^4 < 1/1e68" .\" re-enter: .\" - checks whether >=160-bit hash matches .\" Pr[false accept] = Pr[H(pw1) = H(pw2) | pw1 != pw2] <= 1/2^160 < 1/1e48 .It Li re-enter Ta No matching \*(Ge160-bit hashes Ta "\*(Le 1/2^160 < 1/1e48" .El .Pp Note that aside from the .Ql none method, which accepts any key unconditionally, the .Ql mbr method and to a lesser extent the .Ql ffs method also accept a wrong key with a much higher probability than cryptography normally deals in. .Pp This is not a security vulnerability in the confidentiality of .Xr cgd 4 against an adversary, but it may be alarming for a user if a disk is configured with a mistyped passphrase, .Nm .Em accepts the wrong key , and the content appears to be garbage \(em 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. .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= then all the .Xr dk 4 wedge partitions are searched for one that has a wedge name equal to .Ar 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 argon2id, pkcs5_pbkdf2/sha1, and pkcs5_pbkdf2. .It salt Ar base64 The salt. Only used for argon2id, pkcs5_pbkdf2/sha1, and pkcs5_pbkdf2. .It memory Ar integer Memory consumption in kilobytes. Only used for argon2id. .It parallelism Ar 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. .It version Ar integer Version of Argon2 to use. Should be the most recent version, currently .Dv 19 . Only used for argon2id. .It shared Ar name No algorithm Ar kdf No subkey Ar info Makes the key generation take an extra step to derive a subkey from the main key using the key derivation function .Ar kdf with input .Ar info . .Pp This enables a single password entry, for example, to decrypt multiple disks that use different keys, each derived as a subkey from the main key generated from the password. .Bl -tag -width 6n .It Ar name A string used to identify the same main key generation shared between parameters files for different disks listed in a single .Pa cgd.conf configuration file. .It Ar kdf The name of a key derivation function used to derive a subkey from the main key. Supported values: .Bl -tag -width 6n -offset indent .It Li hkdf-hmac-sha256 The HKDF-Expand function of RFC 5869, instantiated with SHA-256. .El .It Ar 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. .El .Pp It is an error to reuse a shared key .Ar name with different keygen blocks, other than the .Ar info parameter, between parameters files used by a single .Pa cgd.conf configuration file. .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 -k argon2id -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 -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: .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 create parameters files for three disks with subkeys derived from a shared password-based key: .Bd -literal # cgdconfig -g -S -k argon2id -o /etc/cgd/wd0 -V gpt adiantum # cgdconfig -g -S -P /etc/cgd/wd0 -o /etc/cgd/ld1 \e -V disklabel aes-cbc 256 .Ed .Pp Listing these in the same .Pa /etc/cgd/cgd.conf will allow you to enter a password once to decrypt both disks with .Cm cgdconfig -C . .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 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: .Bl -tag -offset indent -width 6n .It Pa /etc/cgd/wd0a .Bd -literal 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 \e subkey AAAAQEGELNr3bj3I; }; .Ed .It Pa /etc/cgd/wd1a .Bd -literal 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 \e subkey AAAAQHSC15pr1Pe4; }; .Ed .El .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 .Rs .%T "Argon2: the memory-hard function for password hashing and other applications" .%A Alex Biryukov .%A Daniel Dinu .%A Dmitry Khovratovich .%D 2017 .%I University of Luxembourg .%U https://www.password-hashing.net/ .Re .Rs .%A H. Krawczyk .%A P. Eronen .%T HMAC-based Extract-and-Expand Key Derivation Function (HKDF) .%I Internet Engineering Task Force .%U https://www.rfc-editor.org/rfc/rfc5869.html .%N RFC 5869 .%D May 2010 .Re .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 . .Pp Support for .Li argon2id and for shared keys appeared in .Nx 10.0 . .Sh BUGS Pass phrases are limited to 1023 bytes.