1.\" $NetBSD: cgdconfig.8,v 1.59 2024/10/09 19:44:17 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 May 12, 2024 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 zfs 274scan for a valid ZFS vdev label (if compiled with MKZFS). 275.It re-enter 276prompt for passphrase twice, and ensure entered passphrases are 277identical. 278This method only works with the argon2id, pkcs5_pbkdf2/sha1, and 279pkcs5_pbkdf2 key generators. 280.El 281.Pp 282If a wrong key is generated, e.g. if the passphrase is entered 283incorrectly, the disk content will appear to be randomized. 284Assuming uniform random disk content, each verification method has some 285probability of falsely accepting a wrong key anyway. 286The probability for each method is as follows: 287.Bl -column "disklabel" "matching \*(Ge160-bit hashes" "1 - (1 - 1/2^80)^1946 < 1/6e20" 288.It Sy method Ta Sy verifies Ta Sy "P(false accept)" 289.It Li none Ta No nothing Ta "1" Ta 290.\" disklabel: 291.\" - scans SCANSIZE=8192 bytes with disklabel_scan, which... 292.\" - checks {0, 4, 8, 12, ..., SCANSIZE=8192 - sizeof(struct 293.\" disklabel)=408}, 1946 options total, for a matching 64-bit 294.\" quantity (d_magic=DISKMAGIC, d_magic2=DISKMAGIC) plus a matching 295.\" 16-bit cksum (plus a plausible d_npartitions but let's ignore 296.\" that) 297.\" Pr[false accept] = Pr[exists i. scan[i] matches 80-bit magic/cksum] 298.\" = 1 - Pr[not exists i. scan[i] does not match 80-bit magic/cksum] 299.\" = 1 - Pr[forall i. scan[i] does not match 80-bit magic/cksum] 300.\" = 1 - \prod_i Pr[scan[i] does not match 80-bit magic/cksum] 301.\" = 1 - \prod_i (1 - Pr[scan[i] matches 80-bit magic/cksum]) 302.\" = 1 - \prod_i (1 - 1/2^80) 303.\" = 1 - (1 - 1/2^80)^1946 304.\" = 1 - exp(1946*log(1 - 1/2^80)) 305.\" = -expm1(1946*log1p(-1/2^80)) 306.\" <= 1/621e18 <= 1/6e20 (one in six hundred quintillion) 307.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" 308.\" mbr: 309.\" - checks exactly one location 310.\" - checks for exactly one magic 16-bit constant 311.\" Pr[false accept] = 1/2^16 = 1/65536 312.It Li mbr Ta No 16-bit magic string Ta "1/65536" 313.\" gpt: 314.\" - scans SCANSIZE=8192 bytes 315.\" - checks blksizes DEV_BSIZE=512, 1024, 2048, 4096 316.\" - checks for 64-bit sig, 32-bit rev, 32-bit size, 32-bit cksum 317.\" Pr[false accept] 318.\" = Pr[exists blksz. hdr[blksz] matches 160-bit magic/cksum] 319.\" = 1 - Pr[not exists blksz. hdr[blksz] matches 160-bit magic/cksum] 320.\" = 1 - Pr[forall blksz. hdr[blksz] does not match 160-bit magic/cksum] 321.\" = 1 - \prod_blksz Pr[hdr[blksz] does not match 160-bit magic/cksum] 322.\" = 1 - \prod_blksz (1 - Pr[hdr[blksz] matches 160-bit magic/cksum]) 323.\" = 1 - \prod_blksz (1 - 1/2^160) 324.\" = 1 - (1 - 1/2^160)^4 325.\" = 1 - exp(4*log(1 - 1/2^160)) 326.\" = -expm1(4*log1p(-1/2^160)) 327.\" <= 1/3e47 328.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 329.\" ffs: 330.\" - checks four locations in SBLOCKSEARCH (sblock_try) 331.\" - checks for any of six magic 32-bit constants 332.\" Pr[false accept] = Pr[exists i. sblock_try[i] in {magic[0], ..., magic[5]}] 333.\" = 1 - Pr[not exists i. sblock_try[i] in {magic[0], ..., magic[5]}] 334.\" = 1 - Pr[forall i. sblock_try[i] not in {magic[0], ..., magic[5]}] 335.\" = 1 - \prod_i Pr[sblock_try[i] not in {magic[0], ..., magic[5]}] 336.\" = 1 - \prod_i (1 - Pr[sblock_try[i] in {magic[0], ..., magic[5]}]) 337.\" = 1 - \prod_i (1 - 6/2^32) 338.\" = 1 - (1 - 6/2^32)^4 339.\" = 1 - exp(4*log(1 - 6/2^32)) 340.\" = -expm1(4*log1p(-6/2^32)) 341.\" <= 1/178e6 <= 1/1e8 (one in a hundred million) 342.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 343.\" zfs: 344.\" - checks four locations (VDEV_LABELS) 345.\" - checks for any of two magic 64-bit constants (ZEC_MAGIC or bswap) 346.\" - checks for 256-bit SHA256 hash 347.\" Pr[false accept] = Pr[exists i. label[i] matches 320-bit magic/cksum] 348.\" = 1 - Pr[not exists i. label[i] matches 320-bit magic/cksum] 349.\" = 1 - Pr[forall i. label[i] does not match 320-bit magic/cksum] 350.\" = 1 - \prod_i Pr[label[i] does not match 320-bit magic/cksum] 351.\" = 1 - \prod_i (1 - Pr[label[i] does matches 320-bit magic/cksum]) 352.\" = 1 - \prod_i (1 - 2/2^230) 353.\" = 1 - (1 - 2/2^230)^4 354.\" = -expm1(4*log1p(-2/2^230)) 355.\" <= 1/2e68 356.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" 357.\" re-enter: 358.\" - checks whether >=160-bit hash matches 359.\" Pr[false accept] = Pr[H(pw1) = H(pw2) | pw1 != pw2] <= 1/2^160 < 1/1e48 360.It Li re-enter Ta No matching \*(Ge160-bit hashes Ta "\*(Le 1/2^160 < 1/1e48" 361.El 362.Pp 363Note that aside from the 364.Ql none 365method, which accepts any key unconditionally, the 366.Ql mbr 367method and to a lesser extent the 368.Ql ffs 369method also accept a wrong key with a much higher probability than 370cryptography normally deals in. 371.Pp 372This is not a security vulnerability in the confidentiality of 373.Xr cgd 4 374against an adversary, but it may be alarming for a user if a disk is 375configured with a mistyped passphrase, 376.Nm 377.Em accepts the wrong key , 378and the content appears to be garbage \(em for example, fsck may fail 379with scary warnings, and any writes to the disk configured with the 380wrong key will corrupt the original plaintext content under the right 381key. 382.Ss /etc/cgd/cgd.conf 383The file 384.Pa /etc/cgd/cgd.conf 385is used to configure 386.Nm 387if either of 388.Fl C 389or 390.Fl U 391are specified. 392Each line of the file is composed of either two or three 393tokens: cgd, target, and optional paramsfile. 394.Pp 395A 396.Sq \&# 397character is interpreted as a comment and indicates that the 398rest of the line should be ignored. 399A 400.Sq \e 401at the end of a line indicates that the next line is a continuation of 402the current line. 403.Pp 404If the second field is of the form 405.Dq NAME=<value> 406then all the 407.Xr dk 4 408wedge partitions are searched for one that has a wedge name equal to 409.Ar <value> 410and the device corresponding to it is selected. 411.Pp 412If the second field starts with the prefix 413.Dq ROOT. 414the prefix is replaced with 415.Dq /dev/[root_device] , 416where 417.Bq root_device 418is the value of the 419.Dq kern.root_device 420sysctl. 421.Pp 422See 423.Sx EXAMPLES 424for an example of 425.Pa /etc/cgd/cgd.conf . 426.Ss Parameters File 427The Parameters File contains the required information to generate the 428key and configure a device. 429These files are typically generated by the 430.Fl g 431flag and not edited by hand. 432When a device is configured the default parameters file is constructed 433by taking the basename of the target disk and prepending 434.Pa /etc/cgd/ 435to it. 436E.g., if the target is 437.Pa /dev/sd0h , 438then the default parameters file will be 439.Pa /etc/cgd/sd0h . 440.Pp 441It is possible to have more than one parameters file for a given 442disk which use different key generation methods but will generate 443the same key. 444To create a parameters file that is equivalent to an existing parameters 445file, use 446.Nm 447with the 448.Fl G 449flag. 450See 451.Sx EXAMPLES 452for an example of this usage. 453.Pp 454The parameters file contains a list of statements each terminated 455with a semi-colon. 456Some statements can contain statement-blocks which are either a 457single unadorned statement, or a brace-enclosed list of semicolon 458terminated statements. 459Three types of data are understood: 460.Pp 461.Bl -tag -compact -width integerxx 462.It integer 463a 32 bit signed integer. 464.It string 465a string. 466.It base64 467a length-encoded base64 string. 468.El 469.Pp 470The following statements are defined: 471.Bl -tag -width indentxx 472.It algorithm Ar string 473Defines the cryptographic algorithm. 474.It iv-method Ar string 475Defines the IV generation method. 476This should always be 477.Sq encblkno1 478except when dealing with disks written with a very old version of 479.Xr cgd 4 480from before 481.Nx 5.0 , 482released in 2010; see 483.Xr cgd 4 484for details. 485.It keylength Ar integer 486Defines the length of the key. 487.It verify_method Ar string 488Defines the verification method. 489.It keygen Ar string Ar statement_block 490Defines a key generation method. 491The 492.Ar statement_block 493contains statements that are specific to the key generation method. 494.El 495.Pp 496The keygen statement's statement block may contain the following statements: 497.Bl -tag -width indentxx 498.It key Ar string 499The key. 500Only used for the storedkey key generation method. 501.It cmd Ar string 502The command to execute. 503Only used for the shell_cmd key generation method. 504.It iterations Ar integer 505The number of iterations. 506Only used for argon2id, pkcs5_pbkdf2/sha1, and pkcs5_pbkdf2. 507.It salt Ar base64 508The salt. 509Only used for argon2id, pkcs5_pbkdf2/sha1, and pkcs5_pbkdf2. 510.It memory Ar integer 511Memory consumption in kilobytes. 512Only used for argon2id. 513.It parallelism Ar integer 514Number of threads to use to compute the password hash. 515Should be equivalent to the number of CPUs/hardware threads. 516Only used for argon2id. 517.It version Ar integer 518Version of Argon2 to use. 519Should be the most recent version, currently 520.Dv 19 . 521Only used for argon2id. 522.It shared Ar name No algorithm Ar kdf No subkey Ar info 523Makes the key generation take an extra step to derive a subkey from the 524main key using the key derivation function 525.Ar kdf 526with input 527.Ar info . 528.Pp 529This enables a single password entry, for example, to decrypt multiple 530disks that use different keys, each derived as a subkey from the main 531key generated from the password. 532.Bl -tag -width 6n 533.It Ar name 534A string used to identify the same main key generation shared between 535parameters files for different disks listed in a single 536.Pa cgd.conf 537configuration file. 538.It Ar kdf 539The name of a key derivation function used to derive a subkey from the 540main key. 541Supported values: 542.Bl -tag -width 6n -offset indent 543.It Li hkdf-hmac-sha256 544The HKDF-Expand function of RFC 5869, instantiated with SHA-256. 545.El 546.It Ar info 547A base64 length-encoded string to distinguish different subkeys derived 548from a shared main key. 549Need not be secret. 550For example, it could be a nickname, or the disk's World-Wide Name, or 551a UUID generated for the disk, or just a random string. 552.El 553.Pp 554It is an error to reuse a shared key 555.Ar name 556with different keygen blocks, other than the 557.Ar info 558parameter, 559between parameters files used by a single 560.Pa cgd.conf 561configuration file. 562.El 563.Sh FILES 564.Bl -tag -width indentxxxxxxxxxxxxxxxxxx -compact 565.It Pa /etc/cgd/ 566configuration directory, used to store paramsfiles. 567.It Pa /etc/cgd/cgd.conf 568cgd configuration file. 569.El 570.Sh EXAMPLES 571To set up and configure a cgd that uses adiantum, which takes a 256-bit 572key: 573.Bd -literal 574 # cgdconfig -g -k argon2id -o /etc/cgd/wd0e adiantum 256 575 # cgdconfig cgd0 /dev/wd0e 576 /dev/wd0e's passphrase: 577.Ed 578.Pp 579When using verification methods, the first time that we configure the 580disk the verification method will fail. 581We overcome this by supplying 582.Fl V Ar re-enter 583when we configure the first time to set up the disk. 584Here is the 585sequence of commands that is recommended: 586.Bd -literal 587 # cgdconfig -g -k argon2id -o /etc/cgd/dk3 -V gpt adiantum 588 # cgdconfig -V re-enter cgd0 /dev/dk3 589 /dev/dk3's passphrase: 590 re-enter device's passphrase: 591 # gpt create cgd0 592 # cgdconfig -u cgd0 593 # cgdconfig cgd0 /dev/dk3 594 /dev/dk3's passphrase: 595.Ed 596.Pp 597To scrub data from a disk before setting up a cgd: 598.Bd -literal 599 # cgdconfig -s cgd0 /dev/sd0e adiantum 256 < /dev/urandom 600 # dd if=/dev/zero of=/dev/rcgd0d bs=32k progress=512 601 # cgdconfig -u cgd0 602.Ed 603.Pp 604To create a new parameters file that will generate the same key as an old 605parameters file: 606.Bd -literal 607 # cgdconfig -G -o newparamsfile oldparamsfile 608 old file's passphrase: 609 new file's passphrase: 610.Ed 611.Pp 612To create parameters files for three disks with subkeys derived from a 613shared password-based key: 614.Bd -literal 615 # cgdconfig -g -S -k argon2id -o /etc/cgd/wd0 -V gpt adiantum 616 # cgdconfig -g -S -P /etc/cgd/wd0 -o /etc/cgd/ld1 \e 617 -V disklabel aes-cbc 256 618.Ed 619.Pp 620Listing these in the same 621.Pa /etc/cgd/cgd.conf 622will allow you to enter a password once to decrypt both disks with 623.Cm cgdconfig -C . 624.Pp 625To configure a cgd that uses aes-cbc with a 192 bit key that it 626reads from stdin: 627.Bd -literal 628 # cgdconfig -s cgd0 /dev/sd0h aes-cbc 192 629.Ed 630.Pp 631An example parameters file which uses PKCS#5 PBKDF2: 632.Bd -literal 633 algorithm aes-cbc; 634 iv-method encblkno1; 635 keylength 128; 636 verify_method none; 637 keygen pkcs5_pbkdf2/sha1 { 638 iterations 39361; 639 salt AAAAgMoHiYonye6Kog \e 640 dYJAobCHE=; 641 }; 642.Ed 643.Pp 644An example parameters file which stores its key locally: 645.Bd -literal 646 algorithm adiantum; 647 iv-method encblkno1; 648 keylength 256; 649 verify_method none; 650 keygen storedkey key AAABAK3QO6d7xzLfrXTdsgg4 \e 651 ly2TdxkFqOkYYcbyUKu/f60L; 652.Ed 653.Pp 654An example pair of configuration files which use shared keys so they 655can be derived from a single passphrase entry, with the 64-bit 656World-Wide Name of each disk (base64 length-encoded) as its subkey 657info: 658.Bl -tag -offset indent -width 6n 659.It Pa /etc/cgd/wd0a 660.Bd -literal 661algorithm adiantum; 662iv-method encblkno1; 663keylength 256; 664verify_method gpt; 665keygen argon2id { 666 iterations 32; 667 memory 5214; 668 parallelism 2; 669 version 19; 670 salt AAAAgLZ5QgleU2m/Ib6wiPYxz98=; 671 shared "my laptop" algorithm hkdf-hmac-sha256 \e 672 subkey AAAAQEGELNr3bj3I; 673}; 674.Ed 675.It Pa /etc/cgd/wd1a 676.Bd -literal 677algorithm adiantum; 678iv-method encblkno1; 679keylength 256; 680verify_method gpt; 681keygen argon2id { 682 iterations 32; 683 memory 5214; 684 parallelism 2; 685 version 19; 686 salt AAAAgLZ5QgleU2m/Ib6wiPYxz98=; 687 shared "my laptop" algorithm hkdf-hmac-sha256 \e 688 subkey AAAAQHSC15pr1Pe4; 689}; 690.Ed 691.El 692.Pp 693An example 694.Pa /etc/cgd/cgd.conf : 695.Bd -literal 696 # 697 # /etc/cgd/cgd.conf 698 # Configuration file for cryptographic disk devices 699 # 700 701 # cgd target [paramsfile] 702 cgd0 /dev/wd0e 703 cgd1 NAME=mycgd /usr/local/etc/cgd/mycgd 704.Ed 705.Pp 706Note the first entry will store the parameters file as 707.Pa /etc/cgd/wd0e . 708And use the entered passphrase to generate the key. 709.Pp 710Although not required, the partition type 711.Ar cgd 712should be used in the disklabel or GPT type field for the cgd partition. 713.Sh DIAGNOSTICS 714.Bl -diag 715.It "cgdconfig: could not calibrate pkcs5_pbkdf2" 716An error greater than 5% in calibration occurred. 717This could be the result of dynamic processor frequency scaling technology. 718Ensure that the processor clock frequency remains static throughout the 719program's execution. 720.El 721.Sh SEE ALSO 722.Xr cgd 4 , 723.Xr dk 4 , 724.Xr fstab 5 , 725.Xr disklabel 8 , 726.Xr gpt 8 727.Rs 728.%T "Argon2: the memory-hard function for password hashing and other applications" 729.%A Alex Biryukov 730.%A Daniel Dinu 731.%A Dmitry Khovratovich 732.%D 2017 733.%I University of Luxembourg 734.%U https://www.password-hashing.net/ 735.Re 736.Rs 737.%A H. Krawczyk 738.%A P. Eronen 739.%T HMAC-based Extract-and-Expand Key Derivation Function (HKDF) 740.%I Internet Engineering Task Force 741.%U https://www.rfc-editor.org/rfc/rfc5869.html 742.%N RFC 5869 743.%D May 2010 744.Re 745.Pp 746.Dq PKCS #5 v2.0: Password-Based Cryptography Standard , 747RSA Laboratories, March 25, 1999. 748.Sh HISTORY 749The 750.Nm 751utility appeared in 752.Nx 2.0 . 753.Pp 754Support for 755.Li argon2id 756and for shared keys appeared in 757.Nx 10.0 . 758.Sh BUGS 759Pass phrases are limited to 1023 bytes. 760