GBDE(8)

🌸 GBDE(8) — the manual page, bestie edition 🌸

okay so real quick: this is the gbde(8) page from the System Manager's Manual, and it's about the Geom Based Disk Encryption utility. sit down, hydrate, and let's get into it 💅

---

✨ NAME ✨

gbde — the operation and management utility for Geom Based Disk Encryption. that's the whole vibe 🫶

---

🎀 SYNOPSIS 🎀

gbde attach destination [-k keyfile] [-l lockfile] [-p pass-phrase]
gbde detach destination
gbde init destination [-i] [-f filename] [-K new-keyfile]
     [-L new-lockfile] [-P new-pass-phrase]
gbde setkey destination [-n key] [-k keyfile] [-l lockfile]
     [-p pass-phrase] [-K new-keyfile] [-L new-lockfile]
     [-P new-pass-phrase]
gbde nuke destination [-n key] [-k keyfile] [-l lockfile]
     [-p pass-phrase]
gbde destroy destination [-k keyfile] [-l lockfile] [-p pass-phrase]

---

💖 DESCRIPTION 💖

NOTICE: please be aware that this code has not yet received much review and analysis by qualified cryptographers and therefore should be considered a slightly suspect experimental facility. bestie i'm just the messenger 😭

we cannot at this point guarantee that the on-disk format will not change in response to reviews or bug-fixes, so potential users are advised to be prepared that dump(8)/restore(8) based migrations may be called for in the future. so like… pack light? 🙈

the gbde utility is the only official operation and management interface for the gbde(4) GEOM based disk encryption kernel facility. the interaction between the gbde utility and the kernel part is not a published interface — it's giving situationship, honestly 💀

the operational aspect consists of two subcommands: one to open and attach a device to the in-kernel cryptographic gbde module (attach), and one to close and detach a device (detach). iconic duo, no notes 👑

the management part allows initialization of the master key and lock sectors on a device (init), initialization and replacement of pass-phrases (setkey), and key invalidation (nuke) and blackening (destroy) functions. it's giving full life cycle 🌈

the -l lockfile argument is used to supply the lock selector data. if no -l option is specified, the first sector is used for this purpose. lowkey the default just does its thing ✨

the -L new-lockfile argument specifies the lock selector file for the key initialized with the init subcommand or modified with the setkey subcommand. 🎀

the -n key argument can be used to specify to which of the four keys the operation applies. a value of 1 to 4 selects the specified key, a value of 0 (the default) means “this key” (i.e., the key used to gain access to the device) and a value of -1 means “all keys”. four keys, one girl, we love options 💅

the -f filename specifies an optional parameter file for use under initialization. 📄

alternatively, the -i option toggles an interactive mode where a template file with descriptions of the parameters can be interactively edited. yes bestie you get to edit, it's very main character energy ✍️

the -p pass-phrase argument specifies the pass-phrase used for opening the device. if not specified, the controlling terminal will be used to prompt the user for the pass-phrase. be aware that using this option may expose the pass-phrase to other users who happen to run ps(1) or similar while the command is running. not the whole process list seeing your secrets 😭🙈

the -P new-pass-phrase argument can be used to specify the new pass-phrase to the init and setkey subcommands. if not specified, the user is prompted for the new pass-phrase on the controlling terminal. be aware that using this option may expose the pass-phrase to other users who happen to run ps(1) or similar while the command is running. same warning, same energy, protect ur secrets fr fr 🫶

the -k keyfile argument specifies a key file to be used in combination with the pass-phrase (whether the pass-phrase is specified on the command line or entered from the terminal) for opening the device. the device will only be opened if the contents of the key file and the pass-phrase are both correct. two-factor before two-factor was cool 🔥

the -K new-keyfile argument can be used to specify a new key file to the init and setkey subcommands. if not specified, no key file will be used (even if one was previously used). the way that it just drops the old one 💀

---

🦋 EXAMPLES 🦋

to initialize a device, using default parameters:

gbde init /dev/ada0s1f -L /etc/ada0s1f.lock

to attach an encrypted device:

gbde attach ada0s1f -l /etc/ada0s1f.lock

the encrypted device has the suffix .bde so a typical command to create and mount a file system would be:

newfs /dev/ada0s1f.bde
mount /dev/ada0s1f.bde /secret

to detach an encrypted device:

gbde detach ada0s1f

please notice that detaching an encrypted device corresponds to physically removing it — do not forget to unmount the file system first. bestie i am begging you, unmount first 😭🙏

to initialize the second key using a detached lockfile and a trivial pass-phrase:

gbde setkey ada0s1f -n 2 -P foo -L key2.lockfile

to invalidate your own masterkey:

gbde nuke ada0s1f

this will overwrite your masterkey sector with zeros, and results in a diagnostic if you try to use the key again. you can also destroy the other three copies of the masterkey with the -n argument. zeros where the key used to be, so dramatic 💀

you can also invalidate your masterkey without leaving a tell-tale sector full of zeros:

gbde destroy ada0s1f

this will overwrite the information fields in your masterkey sector, encrypt it and write it back. you get a (different) diagnostic if you try to use it. stealth mode activated 🧚✨

---

🌈 SEE ALSO 🌈

gbde(4), geom(4)

---

⭐ HISTORY ⭐

this software was developed for the FreeBSD Project by Poul-Henning Kamp and NAI Labs, the Security Research Division of Network Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 (“CBOSS”), as part of the DARPA CHATS research program. gbde first appeared in FreeBSD 5.0. an icon, a legend, a whole era 👑

---

💜 AUTHORS 💜

Poul-Henning Kamp <phk@FreeBSD.org>

---

🍓 BUGS 🍓

the cryptographic algorithms and the overall design have not been attacked mercilessly for over 10 years by a gang of cryptoanalysts. so like… nobody's tried to break it that hard yet, which is not the flex you'd hope for 😭🔥

---

okay that's the whole page, you're officially educated 💖 this was the Debian build, dated October 3, 2016 — go forth and encrypt responsibly, bestie, mwah 🫶✨🎀