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