Updated: 2021/Apr/14


CGD(4)                       Device Drivers Manual                      CGD(4)

NAME
     cgd - cryptographic disk driver

SYNOPSIS
     pseudo-device cgd

DESCRIPTION
     The cgd driver, configured with the cgdconfig(8) tool, implements a
     logical disk device by encrypting or decrypting disk sectors on their way
     to and from a physical backing disk or partition.

   Security model
     As long as you keep the key secret, cgd keeps the content of the disk
     secret from a passive adversary, such as a thief who steals your disk or
     a border patrol agent who detains you and takes a snapshot of your
     laptop's disk while you are crossing a border.

     cgd does not detect tampering by an active adversary who can modify the
     content of the backing store, such as a man-in-the-middle between you and
     an iSCSI target, or after the border patrol returns your laptop to you.

   Ciphers
     The following ciphers are supported:

     adiantum (key size: 256 bits)
           The Adiantum tweakable wide-block cipher.  The Adiantum tweak for
           each disk sector is taken to be the little-endian encoding of the
           disk sector number.

           Adiantum provides the best security by encrypting entire disk
           sectors at a time (512 bytes), and generally provides the best
           performance on machines without CPU support for accelerating AES.

     aes-cbc (key sizes: 128, 192, or 256 bits)
           AES in CBC mode.  The CBC initialization vector for each disk
           sector is chosen to be the encryption under AES of the little-
           endian encoding of the disk sector number.  The default key length
           is 128 bits.

     aes-xts (key sizes: 256 or 512 bits)
           AES in XTS mode.  The XTS tweak for each disk sector is chosen to
           be the little-endian encoding of the disk sector number.  AES-XTS
           uses a 256-bit or 512-bit key, composed of a pair of AES-128 or
           AES-256 keys.  The default key length is 256, meaning AES-128.

   Obsolete Ciphers
     The following obsolete ciphers are supported for compatibility with old
     disks.

     WARNING: These obsolete ciphers are implemented without timing side
     channel protection, so, for example, JavaScript code in a web browser
     that can measure the timing of disk activity may be able to recover the
     secret key.  These are also based on 64-bit block ciphers and are
     therefore unsafe for disks much larger than a gigabyte.  You should not
     use these except where compatibility with old disks is necessary.

     3des-cbc (key size: 192 bits)
           3DES (Triple DES with EDE3) in CBC mode.  The CBC initialization
           vector for each disk sector is chosen to be the encryption under
           3DES of the little-endian encoding of the disk sector number.

           Note: Internally, the `parity bits' of the 192-bit key are ignored,
           so there are only 168 bits of key material, and owing to generic
           attacks on 64-bit block ciphers and to meet-in-the-middle attacks
           on compositions of ciphers as in EDE3 the security is much lower
           than one might expect even for a 168-bit key.

     blowfish-cbc (key sizes: 40, 48, 56, 64, ..., 432, 440, or 448 bits)
           Blowfish in CBC mode.  The CBC initialization vector for each disk
           sector is chosen to be the encryption under Blowfish of the little-
           endian encoding of the disk sector number.  It is strongly
           encouraged that keys be at least 128 bits long.  There are no
           performance advantages of using shorter keys.  The default key
           length is 128 bits.

   IV Methods
     A very early version of cgd had a bug in the CBC-based ciphers aes-cbc,
     3des-cbc, and blowfish-cbc: the CBC initialization vector was chosen to
     be the eight-fold encryption under the block cipher of the little-endian
     encoding of the disk sector number, which has no impact on security but
     reduces performance.  For compatibility with such disks, the `IV method'
     must be set to encblkno8.  Otherwise the `IV method' should always be
     encblkno1.  The parameter is meaningless for adiantum and aes-xts.

IOCTLS
     A cgd responds to all of the standard disk ioctl(2) calls defined in
     sd(4), and also defines the following:

     CGDIOCSET  Configure the cgd.  This ioctl(2) sets up the encryption
                parameters and points the cgd at the underlying disk.

     CGDIOCCLR  Unconfigure the cgd.

     CGDIOCGET  Get info about the cgd.

     These ioctl(2)'s and their associated data structures are defined in
     <dev/cgdvar.h> header.

WARNINGS
     It goes without saying that if you forget the passphrase that you used to
     configure a cgd, then you have irrevocably lost all of the data on the
     disk.  Please ensure that you are using an appropriate backup strategy.

FILES
     /dev/{,r}cgd*      cgd device special files.

SEE ALSO
     config(1), ioctl(2), sd(4), cgdconfig(8), MAKEDEV(8)

     Roland C. Dowdeswell and John Ioannidis, "The CryptoGraphic Disk Driver",
     Proceedings of the FREENIX Track: 2003 USENIX Annual Technical
     Conference, USENIX Association,
     https://www.usenix.org/event/usenix03/tech/freenix03/full_papers/dowdeswell/dowdeswell.pdf,
     179-186, June 9-14, 2003.

     Paul Crowley and Eric Biggers, "Adiantum: length-preserving encryption
     for entry-level processors", International Association of Cryptologic
     Research, Transactions on Symmetric Cryptology, 4, 2018,
     https://doi.org/10.13154/tosc.v2018.i4.39-61, 39-61.

     FIPS PUB 46-3: Data Encryption Standard (DES), National Institute of
     Standards and Technology,
     https://csrc.nist.gov/publications/detail/fips/46/3/archive/1999-10-25,
     United States Department of Commerce, October 25, 1999, withdrawn May 19,
     2005.

     FIPS PUB 197: Advanced Encryption Standard (AES), National Institute of
     Standards and Technology,
     https://csrc.nist.gov/publications/detail/fips/197/final, United States
     Department of Commerce, November 2001.

     Morris Dworkin, Recommendation for Block Cipher Modes of Operation:
     Methods and Techniques, National Institute of Standards and Technology,
     https://csrc.nist.gov/publications/detail/sp/800-38a/final, United States
     Department of Commerce, December 2001, NIST Special Publication 800-38A.

     Morris Dworkin, Recommendation for Block Cipher Modes of Operation: the
     XTS-AES Mode for Confidentiality on Storage Devices, National Institute
     of Standards and Technology,
     https://csrc.nist.gov/publications/detail/sp/800-38e/final, United States
     Department of Commerce, January 2010, NIST Special Publication 800-38E.

     Bruce Schneier, The Blowfish Encryption Algorithm,
     https://www.schneier.com/academic/blowfish, superseded by Twofish,
     superseded by Threefish.

     Karthikeyan Bhargavan and Ga"etan Leurent, Sweet32: Birthday attacks on
     64-bit block ciphers in TLS and OpenVPN, https://sweet32.info.

HISTORY
     The cgd driver was written by Roland C. Dowdeswell for NetBSD.  The cgd
     driver originally appeared in NetBSD 2.0.  The aes-xts cipher was added
     in NetBSD 8.0.  The adiantum cipher was added in NetBSD 10.0.

NetBSD 9.99                     August 16, 2020                    NetBSD 9.99