CGD(4)

📦 version 11.0, in nixpkgs unstable

🎀 CGD(4) 🎀

okay so bestie, you're looking at the CGD(4) page from the Kernel Interfaces Manual — manual name folded in near the top, exactly the vibe — and it's all about cgd, the cryptographic disk driver. iconic behavior only 💅✨

🌸 NAME 🌸

cgd — cryptographic disk driver

🦋 SYNOPSIS 🦋

pseudo-device cgd

✨ DESCRIPTION ✨

okay so the cgd driver is configured with the cgdconfig(8) tool, and it implements a logical disk device by encrypting or decrypting disk sectors on their way to and from a physical backing disk or partition. literally main character disk energy 🫶

🔐 Security model 🔐

as long as you keep the key secret, cgd keeps the content of the disk secret from a passive adversary — think 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're crossing a border. no cap, that's the whole point 💖

cgd does not detect tampering by an active adversary who can modify the content of the backing store — like a man-in-the-middle between you and an iSCSI target, or after the border patrol returns your laptop to you. so yeah, that's the limit, bestie 😭

🧚 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. obsessed with the whole-sector glow-up 💜
  • 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. CBC mode is expected to provide marginally better theoretical security than XTS mode. cute and classic 🎀
  • 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. XTS mode is expected to provide marginally better theoretical performance than CBC mode. performance girlie behavior ⭐

💀 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. not the flex you think it is 💀
  • 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. old-school fish energy 🐟

🌈 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. iykyk 🌀

🔥 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 the <dev/cgdvar.h> header. slay ✨

🚨 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. like, seriously bestie, back it up 😭💖

🍓 FILES 🍓

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

🦋 SEE ALSO 🦋

👑 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. periodt, we stan a legacy 💅👑

okay bye bestie 💖 this page is from Debian, dated September 27, 2024, and it's the CGD(4) page. mwah 💋🌈

📦 where this page comes from