1.\" $NetBSD: cgd.4,v 1.18 2013/12/01 00:17:14 christos 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 November 30, 2013 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 provides the capability of encrypting blocks on their way 42to and from a disk or partition. 43.Pp 44In order to compile support for the 45.Nm 46into your kernel, you must add the driver to your kernel configuration 47file. 48To do this, add a line similar to: 49.Bd -unfilled -offset indent 50pseudo-device cgd # cryptographic disk driver 51.Ed 52.Pp 53The 54.Nm 55devices are allocated as needed. 56.Ss Encryption Algorithms 57Currently the following cryptographic algorithms are supported: 58.Bl -tag -width indentxxxxxxx 59.It Ic aes-cbc 60.Tn AES 61in 62.Tn CBC 63mode. 64.Tn AES 65uses a 128 bit blocksize and can accept keys of length 128, 192, or 256. 66The default key length is 128. 67.It Ic 3des-cbc 68Triple 69.Tn DES 70in 71.Tn CBC 72mode. 73Triple 74.Tn DES 75uses a 64 bit blocksize and is performed in 76.Tn EDE3 77mode with a 168 bit key. 78The key passed to the kernel is 192 bits but the parity bits are ignored. 79.It Ic blowfish-cbc 80Blowfish in 81.Tn CBC 82mode. 83Blowfish uses a 64 bit blocksize and can accept keys between 40 and 84448 bits in multiples of 8. 85It is strongly encouraged that keys be at least 128 bits long. 86There are no performance advantages of using shorter keys. 87The default key length is 128 bits. 88.El 89.Ss IV Methods 90Currently, the following 91.Tn IV 92Methods are supported: 93.Bl -tag -width encblkno1 94.It Ic encblkno1 95This method encrypts the block number of the physical disk block once with 96the cipher and key provided and uses the result as the 97.Tn IV 98for 99.Tn CBC 100mode. 101This method should ensure that each block has a different 102.Tn IV 103and that the 104.Tn IV 105is reasonably unpredictable. 106This is the default method used by 107.Xr cgdconfig 8 108when configuring a new 109.Nm . 110.It Ic encblkno8 111This is the original 112.Tn IV 113method used by 114.Nm 115and provided for backward compatibility. 116It repeatedly encrypts the block number of the physical disk block 117eight times and uses the result as the 118.Tn IV 119for 120.Tn CBC 121mode. 122This method should ensure that each block has a different 123.Tn IV 124and that the 125.Tn IV 126is reasonably unpredictable. 127The eightfold encryption was not intended and causes a notable 128performance loss with little (if any) increase in security over a 129single encryption. 130.El 131.Ss IOCTLS 132A 133.Nm 134responds to all of the standard disk 135.Xr ioctl 2 136calls defined in 137.Xr sd 4 , 138and also defines the following: 139.Bl -tag -width CGDIOCSET -offset indent 140.It Dv CGDIOCSET 141Configure the 142.Nm . 143This 144.Xr ioctl 2 145sets up the encryption parameters and points the 146.Nm 147at the underlying disk. 148.It Dv CGDIOCCLR 149Unconfigure the 150.Nm . 151.It Dv CGDIOCGET 152Get info about the 153.Nm . 154.El 155.Pp 156These 157.Xr ioctl 2 Ns 's 158and their associated data structures are defined in 159.In dev/cgdvar.h 160header. 161.Sh WARNINGS 162It goes without saying that if you forget the passphrase that you used 163to configure a 164.Nm , 165then you have irrevocably lost all of the data on the disk. 166Please ensure that you are using an appropriate backup strategy. 167.Sh FILES 168.Bl -tag -width indentxxxxxxxxxxx 169.It /dev/{,r}cgd* 170.Nm 171device special files. 172.El 173.Sh SEE ALSO 174.Xr config 1 , 175.Xr ioctl 2 , 176.Xr sd 4 , 177.Xr cgdconfig 8 , 178.Xr MAKEDEV 8 179.Rs 180.%A Roland C. Dowdeswell 181.%A John Ioannidis 182.%T The CryptoGraphic Disk Driver 183.%I USENIX Association 184.%B Proceedings of the FREENIX Track: 2003 USENIX Annual Technical Conference 185.%P 179-186 186.%D June 9-14, 2003 187.%U http://www.usenix.org/event/usenix03/tech/freenix03/full_papers/dowdeswell/dowdeswell.pdf 188.Re 189.Sh HISTORY 190The 191.Nm 192driver was written by Roland C. Dowdeswell for 193.Nx . 194The 195.Nm 196driver originally appeared in 197.Nx 2.0 . 198