1.\" $NetBSD: cgd.4,v 1.25 2024/09/27 12:49:41 nia Exp $ 2.\" 3.\" Copyright (c) 2002, 2003 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 September 27, 2024 31.Dt CGD 4 32.Os 33.Sh NAME 34.Nm cgd 35.Nd cryptographic disk driver 36.Sh SYNOPSIS 37.Cd pseudo-device cgd 38.Sh DESCRIPTION 39The 40.Nm 41driver, configured with the 42.Xr cgdconfig 8 43tool, implements a logical disk device by encrypting or decrypting disk 44sectors on their way to and from a physical backing disk or partition. 45.Ss Security model 46As long as you keep the key secret, 47.Nm 48keeps the content of the disk secret from a 49.Em passive 50adversary, such as a thief who steals your disk or a border patrol 51agent who detains you and takes a snapshot of your laptop's disk while 52you are crossing a border. 53.Pp 54.Nm 55.Em does not 56detect tampering by an 57.Em active 58adversary who can modify the content of the backing store, such as a 59man-in-the-middle between you and an 60.Tn iSCSI 61target, or after the border patrol returns your laptop to you. 62.Ss Ciphers 63The following ciphers are supported: 64.Bl -tag -width "abcd" 65.It Li "adiantum" (key size: 256 bits) 66The Adiantum tweakable wide-block cipher. 67The Adiantum tweak for each disk sector is taken to be the 68little-endian encoding of the disk sector number. 69.Pp 70Adiantum provides the best security by encrypting entire disk sectors 71at a time (512 bytes), and generally provides the best performance on 72machines without CPU support for accelerating 73.Tn AES . 74.It Li "aes-cbc" (key sizes: 128, 192, or 256 bits) 75.Tn AES 76in 77.Tn CBC 78mode. 79The 80.Tn CBC 81initialization vector for each disk sector is chosen to be the 82encryption under 83.Tn AES 84of the little-endian encoding of the disk sector number. 85The default key length is 128 bits. 86.Tn CBC 87mode is expected to provide marginally better theoretical security than 88.Tn XTS 89mode. 90.It Li "aes-xts" (key sizes: 256 or 512 bits) 91.Tn AES 92in 93.Tn XTS 94mode. 95The 96.Tn XTS 97tweak for each disk sector is chosen to be the little-endian encoding 98of the disk sector number. 99.Tn AES-XTS 100uses a 256-bit or 512-bit key, composed of a pair of 101.Tn AES-128 102or 103.Tn AES-256 104keys. 105The default key length is 256, meaning 106.Tn AES-128. 107.Tn XTS 108mode is expected to provide marginally better theoretical performance than 109.Tn CBC 110mode. 111.El 112.Ss Obsolete Ciphers 113The following obsolete ciphers are supported for compatibility with 114old disks. 115.Pp 116.Sy WARNING: 117These obsolete ciphers are implemented without timing side channel 118protection, so, for example, JavaScript code in a web browser that can 119measure the timing of disk activity may be able to recover the secret 120key. 121These are also based on 64-bit block ciphers and are therefore unsafe 122for disks much larger than a gigabyte. 123You should not use these except where compatibility with old disks is 124necessary. 125.Bl -tag -width "abcd" 126.It Li "3des-cbc" (key size: 192 bits) 127.Tn 3DES 128.Po 129Triple 130.Tn DES 131with 132.Tn EDE3 133.Pc 134in 135.Tn CBC 136mode. 137The 138.Tn CBC 139initialization vector for each disk sector is chosen to be the 140encryption under 141.Tn 3DES 142of the little-endian encoding of the disk sector number. 143.Pp 144Note: Internally, the 145.Sq parity bits 146of the 192-bit key are ignored, so there are only 168 bits of key 147material, and owing to generic attacks on 64-bit block ciphers and to 148meet-in-the-middle attacks on compositions of ciphers as in 149.Tn EDE3 150the security is much lower than one might expect even for a 168-bit 151key. 152.It Li "blowfish-cbc" (key sizes: 40, 48, 56, 64, ..., 432, 440, or 448 bits) 153Blowfish in 154.Tn CBC 155mode. 156The 157.Tn CBC 158initialization vector for each disk sector is chosen to be the 159encryption under Blowfish of the little-endian encoding of the disk 160sector number. 161It is strongly encouraged that keys be at least 128 bits long. 162There are no performance advantages of using shorter keys. 163The default key length is 128 bits. 164.El 165.Ss IV Methods 166A very early version of 167.Nm 168had a bug in the 169.Tn CBC Ns -based 170ciphers 171.Li "aes-cbc" , 172.Li "3des-cbc" , 173and 174.Li "blowfish-cbc" : 175the 176.Tn CBC 177initialization vector was chosen to be the 178.Em eight-fold 179encryption under the block cipher of the little-endian encoding of the 180disk sector number, which has no impact on security but reduces 181performance. 182For compatibility with such disks, the 183.Sq IV method 184must be set to 185.Li encblkno8 . 186Otherwise the 187.Sq IV method 188should always be 189.Li encblkno1 . 190The parameter is meaningless for 191.Li adiantum 192and 193.Li aes-xts . 194.Sh IOCTLS 195A 196.Nm 197responds to all of the standard disk 198.Xr ioctl 2 199calls defined in 200.Xr sd 4 , 201and also defines the following: 202.Bl -tag -width CGDIOCSET 203.It Dv CGDIOCSET 204Configure the 205.Nm . 206This 207.Xr ioctl 2 208sets up the encryption parameters and points the 209.Nm 210at the underlying disk. 211.It Dv CGDIOCCLR 212Unconfigure the 213.Nm . 214.It Dv CGDIOCGET 215Get info about the 216.Nm . 217.El 218.Pp 219These 220.Xr ioctl 2 Ns 's 221and their associated data structures are defined in 222.In dev/cgdvar.h 223header. 224.Sh WARNINGS 225It goes without saying that if you forget the passphrase that you used 226to configure a 227.Nm , 228then you have irrevocably lost all of the data on the disk. 229Please ensure that you are using an appropriate backup strategy. 230.Sh FILES 231.Bl -tag -width indentxxxxxxxxxxx 232.It /dev/{,r}cgd* 233.Nm 234device special files. 235.El 236.Sh SEE ALSO 237.Xr config 1 , 238.Xr ioctl 2 , 239.Xr sd 4 , 240.Xr cgdconfig 8 , 241.Xr MAKEDEV 8 242.Rs 243.%A Roland C. Dowdeswell 244.%A John Ioannidis 245.%T The CryptoGraphic Disk Driver 246.%I USENIX Association 247.%B Proceedings of the FREENIX Track: 2003 USENIX Annual Technical Conference 248.%P 179-186 249.%D June 9-14, 2003 250.%U https://www.usenix.org/event/usenix03/tech/freenix03/full_papers/dowdeswell/dowdeswell.pdf 251.Re 252.Rs 253.%A Paul Crowley 254.%A Eric Biggers 255.%T Adiantum: length-preserving encryption for entry-level processors 256.%I International Association of Cryptologic Research 257.%J Transactions on Symmetric Cryptology 258.%V 2018 259.%N 4 260.%P 39-61 261.%U https://doi.org/10.13154/tosc.v2018.i4.39-61 262.Re 263.Rs 264.%T FIPS PUB 46-3: Data Encryption Standard (DES) 265.%Q United States Department of Commerce 266.%I National Institute of Standards and Technology 267.%O withdrawn May 19, 2005 268.%D October 25, 1999 269.%U https://csrc.nist.gov/publications/detail/fips/46/3/archive/1999-10-25 270.Re 271.Rs 272.%T FIPS PUB 197: Advanced Encryption Standard (AES) 273.%Q United States Department of Commerce 274.%I National Institute of Standards and Technology 275.%D November 2001 276.%U https://csrc.nist.gov/publications/detail/fips/197/final 277.Re 278.Rs 279.%A Morris Dworkin 280.%T Recommendation for Block Cipher Modes of Operation: Methods and Techniques 281.%D December 2001 282.%Q United States Department of Commerce 283.%I National Institute of Standards and Technology 284.%O NIST Special Publication 800-38A 285.%U https://csrc.nist.gov/publications/detail/sp/800-38a/final 286.Re 287.Rs 288.%A Morris Dworkin 289.%T Recommendation for Block Cipher Modes of Operation: the XTS-AES Mode for Confidentiality on Storage Devices 290.%D January 2010 291.%Q United States Department of Commerce 292.%I National Institute of Standards and Technology 293.%O NIST Special Publication 800-38E 294.%U https://csrc.nist.gov/publications/detail/sp/800-38e/final 295.Re 296.Rs 297.%A Bruce Schneier 298.%T The Blowfish Encryption Algorithm 299.%O superseded by Twofish, superseded by Threefish 300.%U https://www.schneier.com/academic/blowfish 301.Re 302.Rs 303.%A Karthikeyan Bhargavan 304.%A Ga\(:etan Leurent 305.%T Sweet32: Birthday attacks on 64-bit block ciphers in TLS and OpenVPN 306.%U https://sweet32.info 307.Re 308.Sh HISTORY 309The 310.Nm 311driver was written by Roland C. Dowdeswell for 312.Nx . 313The 314.Nm 315driver originally appeared in 316.Nx 2.0 . 317The 318.Li aes-xts 319cipher was added in 320.Nx 8.0 . 321The 322.Li adiantum 323cipher was added in 324.Nx 10.0 . 325