1.\" $NetBSD: cgdconfig.8,v 1.57 2022/08/12 10:49:47 riastradh Exp $ 2.\" 3.\" Copyright (c) 2002, The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Roland C. Dowdeswell. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd November 4, 2021 31.Dt CGDCONFIG 8 32.Os 33.Sh NAME 34.Nm cgdconfig 35.Nd configuration utility for the cryptographic disk driver 36.Sh SYNOPSIS 37.Nm 38.Op Fl enpv 39.Op Fl V Ar vmeth 40.Ar cgd dev 41.Op Ar paramsfile 42.Nm 43.Fl C 44.Op Fl enpv 45.Op Fl f Ar configfile 46.Nm 47.Fl G 48.Op Fl enpv 49.Op Fl i Ar ivmeth 50.Op Fl k Ar kgmeth 51.Op Fl o Ar outfile 52.Ar paramsfile 53.Nm 54.Fl g 55.Op Fl Sv 56.Op Fl V Ar vmeth 57.Op Fl i Ar ivmeth 58.Op Fl k Ar kgmeth 59.Op Fl o Ar outfile 60.Op Fl P Ar paramsfile 61.Ar alg 62.Op Ar keylen 63.Nm 64.Fl T 65.Op Fl f Ar configfile 66.Nm 67.Fl t 68.Ar paramsfile 69.Nm 70.Fl l 71.Op Fl v Ns Op Cm v 72.Op Ar cgd 73.Nm 74.Fl s 75.Op Fl nv 76.Op Fl i Ar ivmeth 77.Ar cgd 78.Ar dev 79.Ar alg 80.Op Ar keylen 81.Nm 82.Fl U 83.Op Fl nv 84.Op Fl f Ar configfile 85.Nm 86.Fl u 87.Op Fl nv 88.Ar cgd 89.Sh DESCRIPTION 90.Nm 91is used to configure and unconfigure cryptographic disk devices (cgds) 92and to maintain the configuration files that are associated with them. 93For more information about cryptographic disk devices see 94.Xr cgd 4 . 95.Pp 96The options are as follows: 97.Bl -tag -width configfilexxxx 98.It Fl C 99Configure all the devices listed in the cgd configuration file. 100.It Fl e 101Echo the passphrase. 102.It Fl f Ar configfile 103Specify the configuration file explicitly, rather than using the default 104configuration file 105.Pa /etc/cgd/cgd.conf . 106.It Fl G 107Generate a new paramsfile (to stdout) using the values from 108.Ar paramsfile 109which will generate the same key. 110This may need to obtain multiple passphrases. 111.It Fl g 112Generate a paramsfile (to stdout). 113.It Fl i Ar ivmeth 114Specify the IV method (default: encblkno1). 115.Pp 116Setting the IV method is needed only for compatibility with disks 117written with a very old version of 118.Xr cgd 4 119from before 120.Nx 5.0 , 121released in 2010; see 122.Xr cgd 4 123for details. 124.It Fl k Ar kgmeth 125Specify the key generation method (default: pkcs5_pbkdf2/sha1). 126.It Fl l Op Ar cgd 127List state of all devices or just the one 128.Ar cgd 129device. 130The verbosity level affects the output. 131.It Fl n 132Do not actually configure or unconfigure a cryptographic disk 133device, but instead report the steps that would be taken. 134.It Fl o Ar outfile 135When generating a 136.Ar paramsfile , 137store it in 138.Ar outfile . 139If 140.Fl o 141is not given, any paramsfile content is written to standard output. 142.It Fl P Ar paramsfile 143With the 144.Fl S 145option for the 146.Fl g 147or 148.Fl G 149actions, specify a parameters file with a shared key to reuse for 150deriving this one as a subkey. 151.It Fl p 152Read all passphrases from stdin rather than 153.Pa /dev/tty . 154Passphrases are separated by newlines. 155Users of this flag must be able to predict the order in which passphrases 156are prompted. 157If this flag is specified then verification errors will cause the device 158in question to be unconfigured rather than prompting for the passphrase 159again. 160.It Fl S 161When generating a parameters file with 162.Fl g 163or 164.Fl G , 165arrange to use a subkey of a shared key. 166If 167.Fl P Ar paramsfile 168is also specified, reuse the shared key of 169.Ar paramsfile ; 170otherwise a new one will be generated. 171.It Fl s 172Read the key (nb: not the passphrase) from stdin. 173.It Fl T 174Generate all keys for all the devices listed in the 175.Nm 176configuration file and print them to standard output encoded in 177base64. 178.It Fl t 179Generate the key and print it to standard output encoded in base64. 180.It Fl U 181Unconfigure all the devices listed in the cgd configuration file. 182.It Fl u 183Unconfigure a cgd. 184.It Fl V Ar vmeth 185Specify the verification method (default: none). 186.It Fl v 187Be verbose. 188May be specified multiple times. 189.El 190.Pp 191For more information about the cryptographic algorithms supported, 192please refer to 193.Xr cgd 4 . 194.Ss Key Generation Methods 195To generate the key which it will use, 196.Nm 197evaluates all of the key generation methods in the parameters file 198and uses the exclusive-or of the outputs of all the methods. 199The methods and descriptions are as follows: 200.Bl -tag -width indentxxxxxxxxxxx 201.It argon2id 202This method requires a passphrase which is entered at configuration 203time. 204Argon2 is a memory-hard password hashing scheme and winner of the 2052013-2015 Password Hashing Competition. 206It has numerous parameters allowing its hardness to scale with the 207performance of the system. 208Recommended for passphrase-based initialization. 209.It pkcs5_pbkdf2/sha1 210This method requires a passphrase which is entered at configuration 211time. 212It is a salted hmac-based scheme detailed in 213.Dq PKCS#5 v2.0: Password-Based Cryptography Standard , 214RSA Laboratories, March 25, 1999, pages 8-10. 215PKCS #5 was also republished as RFC 2898. 216.It pkcs5_pbkdf2 217This is an earlier, slightly incorrect and deprecated implementation 218of the above algorithm. 219It is retained for backwards compatibility with existing parameters 220files, and will be removed. 221Existing parameters files should be 222converted to use the correct method using the 223.Fl G 224option, and a new passphrase. 225.It storedkey 226This method stores its key in the parameters file. 227.It randomkey 228The method simply reads 229.Pa /dev/random 230and uses the resulting bits as the key. 231It does not require a passphrase to be entered. 232This method is typically used to present disk devices that do not 233need to survive a reboot. 234It is also handy to facilitate overwriting the contents of 235a disk volume with meaningless data prior to use. 236.It urandomkey 237The method simply reads 238.Pa /dev/urandom 239and uses the resulting bits as the key. 240This is similar to the 241.Pa randomkey 242method, but it guarantees that 243.Nm 244will not stall waiting for 256 bits of entropy from a hardware RNG 245or seed. 246.It shell_cmd 247This method executes a shell command via 248.Xr popen 3 249and reads the key from stdout. 250.El 251.Ss Verification Method 252The verification method is how 253.Nm 254determines if the generated key is correct. 255If the newly configured disk fails to verify, then 256.Nm 257will regenerate the key and re-configure the device. 258It only makes sense to specify a verification method if at least one of the 259key generation methods is error prone, e.g., uses a user-entered passphrase. 260The following verification methods are supported: 261.Pp 262.Bl -tag -width indentxxx -compact 263.It none 264perform no verification. 265.It disklabel 266scan for a valid disklabel. 267.It mbr 268scan for a valid Master Boot Record. 269.It gpt 270scan for a valid GUID partition table. 271.It ffs 272scan for a valid FFS file system. 273.It re-enter 274prompt for passphrase twice, and ensure entered passphrases are 275identical. 276This method only works with the argon2id, pkcs5_pbkdf2/sha1, and 277pkcs5_pbkdf2 key generators. 278.El 279.Ss /etc/cgd/cgd.conf 280The file 281.Pa /etc/cgd/cgd.conf 282is used to configure 283.Nm 284if either of 285.Fl C 286or 287.Fl U 288are specified. 289Each line of the file is composed of either two or three 290tokens: cgd, target, and optional paramsfile. 291.Pp 292A 293.Sq \&# 294character is interpreted as a comment and indicates that the 295rest of the line should be ignored. 296A 297.Sq \e 298at the end of a line indicates that the next line is a continuation of 299the current line. 300.Pp 301If the second field is of the form 302.Dq NAME=<value> 303then all the 304.Xr dk 4 305wedge partitions are searched for one that has a wedge name equal to 306.Ar <value> 307and the device corresponding to it is selected. 308.Pp 309If the second field starts with the prefix 310.Dq ROOT. 311the prefix is replaced with 312.Dq /dev/[root_device] , 313where 314.Bq root_device 315is the value of the 316.Dq kern.root_device 317sysctl. 318.Pp 319See 320.Sx EXAMPLES 321for an example of 322.Pa /etc/cgd/cgd.conf . 323.Ss Parameters File 324The Parameters File contains the required information to generate the 325key and configure a device. 326These files are typically generated by the 327.Fl g 328flag and not edited by hand. 329When a device is configured the default parameters file is constructed 330by taking the basename of the target disk and prepending 331.Pa /etc/cgd/ 332to it. 333E.g., if the target is 334.Pa /dev/sd0h , 335then the default parameters file will be 336.Pa /etc/cgd/sd0h . 337.Pp 338It is possible to have more than one parameters file for a given 339disk which use different key generation methods but will generate 340the same key. 341To create a parameters file that is equivalent to an existing parameters 342file, use 343.Nm 344with the 345.Fl G 346flag. 347See 348.Sx EXAMPLES 349for an example of this usage. 350.Pp 351The parameters file contains a list of statements each terminated 352with a semi-colon. 353Some statements can contain statement-blocks which are either a 354single unadorned statement, or a brace-enclosed list of semicolon 355terminated statements. 356Three types of data are understood: 357.Pp 358.Bl -tag -compact -width integerxx 359.It integer 360a 32 bit signed integer. 361.It string 362a string. 363.It base64 364a length-encoded base64 string. 365.El 366.Pp 367The following statements are defined: 368.Bl -tag -width indentxx 369.It algorithm Ar string 370Defines the cryptographic algorithm. 371.It iv-method Ar string 372Defines the IV generation method. 373This should always be 374.Sq encblkno1 375except when dealing with disks written with a very old version of 376.Xr cgd 4 377from before 378.Nx 5.0 , 379released in 2010; see 380.Xr cgd 4 381for details. 382.It keylength Ar integer 383Defines the length of the key. 384.It verify_method Ar string 385Defines the verification method. 386.It keygen Ar string Ar statement_block 387Defines a key generation method. 388The 389.Ar statement_block 390contains statements that are specific to the key generation method. 391.El 392.Pp 393The keygen statement's statement block may contain the following statements: 394.Bl -tag -width indentxx 395.It key Ar string 396The key. 397Only used for the storedkey key generation method. 398.It cmd Ar string 399The command to execute. 400Only used for the shell_cmd key generation method. 401.It iterations Ar integer 402The number of iterations. 403Only used for argon2id, pkcs5_pbkdf2/sha1, and pkcs5_pbkdf2. 404.It salt Ar base64 405The salt. 406Only used for argon2id, pkcs5_pbkdf2/sha1, and pkcs5_pbkdf2. 407.It memory Ar integer 408Memory consumption in kilobytes. 409Only used for argon2id. 410.It parallelism Ar integer 411Number of threads to use to compute the password hash. 412Should be equivalent to the number of CPUs/hardware threads. 413Only used for argon2id. 414.It version Ar integer 415Version of Argon2 to use. 416Should be the most recent version, currently 417.Dv 19 . 418Only used for argon2id. 419.It shared Ar name No algorithm Ar kdf No subkey Ar info 420Makes the key generation take an extra step to derive a subkey from the 421main key using the key derivation function 422.Ar kdf 423with input 424.Ar info . 425.Pp 426This enables a single password entry, for example, to decrypt multiple 427disks that use different keys, each derived as a subkey from the main 428key generated from the password. 429.Bl -tag -width 6n 430.It Ar name 431A string used to identify the same main key generation shared between 432parameters files for different disks listed in a single 433.Pa cgd.conf 434configuration file. 435.It Ar kdf 436The name of a key derivation function used to derive a subkey from the 437main key. 438Supported values: 439.Bl -tag -width 6n -offset indent 440.It Li hkdf-hmac-sha256 441The HKDF-Expand function of RFC 5869, instantiated with SHA-256. 442.El 443.It Ar info 444A base64 length-encoded string to distinguish different subkeys derived 445from a shared main key. 446Need not be secret. 447For example, it could be a nickname, or the disk's World-Wide Name, or 448a UUID generated for the disk, or just a random string. 449.El 450.Pp 451It is an error to reuse a shared key 452.Ar name 453with different keygen blocks, other than the 454.Ar info 455parameter, 456between parameters files used by a single 457.Pa cgd.conf 458configuration file. 459.El 460.Sh FILES 461.Bl -tag -width indentxxxxxxxxxxxxxxxxxx -compact 462.It Pa /etc/cgd/ 463configuration directory, used to store paramsfiles. 464.It Pa /etc/cgd/cgd.conf 465cgd configuration file. 466.El 467.Sh EXAMPLES 468To set up and configure a cgd that uses adiantum, which takes a 256-bit 469key: 470.Bd -literal 471 # cgdconfig -g -k argon2id -o /etc/cgd/wd0e adiantum 256 472 # cgdconfig cgd0 /dev/wd0e 473 /dev/wd0e's passphrase: 474.Ed 475.Pp 476When using verification methods, the first time that we configure the 477disk the verification method will fail. 478We overcome this by supplying 479.Fl V Ar re-enter 480when we configure the first time to set up the disk. 481Here is the 482sequence of commands that is recommended: 483.Bd -literal 484 # cgdconfig -g -k argon2id -o /etc/cgd/dk3 -V gpt adiantum 485 # cgdconfig -V re-enter cgd0 /dev/dk3 486 /dev/dk3's passphrase: 487 re-enter device's passphrase: 488 # gpt create cgd0 489 # cgdconfig -u cgd0 490 # cgdconfig cgd0 /dev/dk3 491 /dev/dk3's passphrase: 492.Ed 493.Pp 494To scrub data from a disk before setting up a cgd: 495.Bd -literal 496 # cgdconfig -s cgd0 /dev/sd0e adiantum 256 < /dev/urandom 497 # dd if=/dev/zero of=/dev/rcgd0d bs=32k progress=512 498 # cgdconfig -u cgd0 499.Ed 500.Pp 501To create a new parameters file that will generate the same key as an old 502parameters file: 503.Bd -literal 504 # cgdconfig -G -o newparamsfile oldparamsfile 505 old file's passphrase: 506 new file's passphrase: 507.Ed 508.Pp 509To create parameters files for three disks with subkeys derived from a 510shared password-based key: 511.Bd -literal 512 # cgdconfig -g -S -k argon2id -o /etc/cgd/wd0 -V gpt adiantum 513 # cgdconfig -g -S -P /etc/cgd/wd0 -o /etc/cgd/ld1 \e 514 -V disklabel aes-cbc 256 515.Ed 516.Pp 517Listing these in the same 518.Pa /etc/cgd/cgd.conf 519will allow you to enter a password once to decrypt both disks with 520.Cm cgdconfig -C . 521.Pp 522To configure a cgd that uses aes-cbc with a 192 bit key that it 523reads from stdin: 524.Bd -literal 525 # cgdconfig -s cgd0 /dev/sd0h aes-cbc 192 526.Ed 527.Pp 528An example parameters file which uses PKCS#5 PBKDF2: 529.Bd -literal 530 algorithm aes-cbc; 531 iv-method encblkno1; 532 keylength 128; 533 verify_method none; 534 keygen pkcs5_pbkdf2/sha1 { 535 iterations 39361; 536 salt AAAAgMoHiYonye6Kog \e 537 dYJAobCHE=; 538 }; 539.Ed 540.Pp 541An example parameters file which stores its key locally: 542.Bd -literal 543 algorithm adiantum; 544 iv-method encblkno1; 545 keylength 256; 546 verify_method none; 547 keygen storedkey key AAABAK3QO6d7xzLfrXTdsgg4 \e 548 ly2TdxkFqOkYYcbyUKu/f60L; 549.Ed 550.Pp 551An example pair of configuration files which use shared keys so they 552can be derived from a single passphrase entry, with the 64-bit 553World-Wide Name of each disk (base64 length-encoded) as its subkey 554info: 555.Bl -tag -offset indent -width 6n 556.It Pa /etc/cgd/wd0a 557.Bd -literal 558algorithm adiantum; 559iv-method encblkno1; 560keylength 256; 561verify_method gpt; 562keygen argon2id { 563 iterations 32; 564 memory 5214; 565 parallelism 2; 566 version 19; 567 salt AAAAgLZ5QgleU2m/Ib6wiPYxz98=; 568 shared "my laptop" algorithm hkdf-hmac-sha256 \e 569 subkey AAAAQEGELNr3bj3I; 570}; 571.Ed 572.It Pa /etc/cgd/wd1a 573.Bd -literal 574algorithm adiantum; 575iv-method encblkno1; 576keylength 256; 577verify_method gpt; 578keygen argon2id { 579 iterations 32; 580 memory 5214; 581 parallelism 2; 582 version 19; 583 salt AAAAgLZ5QgleU2m/Ib6wiPYxz98=; 584 shared "my laptop" algorithm hkdf-hmac-sha256 \e 585 subkey AAAAQHSC15pr1Pe4; 586}; 587.Ed 588.El 589.Pp 590An example 591.Pa /etc/cgd/cgd.conf : 592.Bd -literal 593 # 594 # /etc/cgd/cgd.conf 595 # Configuration file for cryptographic disk devices 596 # 597 598 # cgd target [paramsfile] 599 cgd0 /dev/wd0e 600 cgd1 NAME=mycgd /usr/local/etc/cgd/mycgd 601.Ed 602.Pp 603Note the first entry will store the parameters file as 604.Pa /etc/cgd/wd0e . 605And use the entered passphrase to generate the key. 606.Pp 607Although not required, the partition type 608.Ar cgd 609should be used in the disklabel or GPT type field for the cgd partition. 610.Sh DIAGNOSTICS 611.Bl -diag 612.It "cgdconfig: could not calibrate pkcs5_pbkdf2" 613An error greater than 5% in calibration occurred. 614This could be the result of dynamic processor frequency scaling technology. 615Ensure that the processor clock frequency remains static throughout the 616program's execution. 617.El 618.Sh SEE ALSO 619.Xr cgd 4 , 620.Xr dk 4 , 621.Xr fstab 5 , 622.Xr disklabel 8 , 623.Xr gpt 8 624.Rs 625.%T "Argon2: the memory-hard function for password hashing and other applications" 626.%A Alex Biryukov 627.%A Daniel Dinu 628.%A Dmitry Khovratovich 629.%D 2017 630.%I University of Luxembourg 631.%U https://www.password-hashing.net/ 632.Re 633.Rs 634.%A H. Krawczyk 635.%A P. Eronen 636.%T HMAC-based Extract-and-Expand Key Derivation Function (HKDF) 637.%I Internet Engineering Task Force 638.%U https://www.rfc-editor.org/rfc/rfc5869.html 639.%N RFC 5869 640.%D May 2010 641.Re 642.Pp 643.Dq PKCS #5 v2.0: Password-Based Cryptography Standard , 644RSA Laboratories, March 25, 1999. 645.Sh HISTORY 646The 647.Nm 648utility appeared in 649.Nx 2.0 . 650.Pp 651Support for 652.Li argon2id 653and for shared keys appeared in 654.Nx 10.0 . 655.Sh BUGS 656Pass phrases are limited to 1023 bytes. 657