FreeBSD GELI User-Key Rotation: Slot Testing, Metadata Backups, and Revocation

Changing a GELI passphrase is a key-management operation, not a rewrite of every encrypted sector. Persistent GELI providers retain a master key whose encrypted copies can occupy two metadata slots. A user key, derived from a passphrase, keyfile components, or their combination, unlocks one of those copies. Rotation changes the wrapping credentials for a slot while preserving the underlying encrypted data. That distinction explains both the speed of the operation and an important limit: an old metadata backup can retain an older way to unlock the same master key.

This workflow concerns an already initialized persistent data provider. It does not apply to one-time encrypted swap, and it does not initialize, format, or resize a disk. The commands are illustrative FreeBSD administrator operations; replace the provider identity only after inspecting the actual GEOM topology. Root-volume changes additionally require a boot-loader and rescue-console plan specific to the installed release.

Establish what is being rotated

Inventory the operating system, provider, and consumers before changing credentials:

freebsd-version -kru
gpart show -p
geli status
geli list
geli dump /dev/gpt/private-data
mount

Keep the raw provider, such as /dev/gpt/private-data, distinct from the decrypted .eli provider consumed by the filesystem. Do not assume a disk number remains stable after moving hardware. Record provider size, partition label, metadata version, filesystem or pool identity, and the recovery media needed to access them. Metadata inspection is not a passphrase validation test, and an attached filesystem is not evidence that newly entered credentials work.

Define the intent precisely: replace an employee’s passphrase, add an independent recovery credential, remove a lost keyfile, or retire a compromised credential. Each intent has different acceptance criteria. If the threat includes an attacker who has already obtained the master key or a usable historical metadata copy, merely replacing a current slot does not establish cryptographic revocation of that historical access.

Back up metadata without creating an unmanaged recovery path

GELI metadata backups are useful for recovering overwritten provider metadata. Store a pre-change copy on protected storage separate from the data provider:

umask 077
geli backup /dev/gpt/private-data /secure/offline/private-data-before.eli
sha256 /secure/offline/private-data-before.eli

The destination directory is an example of an approved recovery medium, not a recommendation to place keys in an arbitrary directory called secure. Confirm ownership, access, physical location, and backup retention. A checksum detects an unintended file change; it does not authenticate the backup if an attacker controls both the file and checksum record.

Record which credentials unlock each backup generation. Keep that information in the organization’s protected key inventory, without putting passphrases in shell history, tickets, command lines, or logs. A data backup, a GELI metadata backup, and a credential escrow record are three different objects. Successful recovery may require all three, plus compatible tools and the right provider layout.

The backup should have a lifecycle. Preserving every historical metadata generation indefinitely can undermine a policy intended to retire an old credential. At the same time, destroying all old copies before a recovery rehearsal can remove the only practical rollback path. Decide the overlap interval before the maintenance window.

Use the second slot as a controlled transition

If slot 0 is the verified current credential and slot 1 is unused, add the replacement to slot 1 explicitly:

geli setkey -n 1 /dev/gpt/private-data

Follow the prompts documented for the provider’s attached or detached state. On an attached provider, GELI already has the master key available; on a detached provider, existing credentials are needed to decrypt it. Do not assume a prompt sequence copied from another host will be identical. The -n option removes ambiguity about which slot is being replaced.

If slot 1 is already an organizational recovery key, this example would overwrite it. Stop and plan the transition around the actual slot ownership. Two slots do not permit three independently retained credentials. A temporary transition may require a separate protected metadata recovery copy, an additional data migration, or another approved design.

Avoid passphrase files for an interactive rotation unless the operational process specifically requires them. Keyfile-based deployments need a deliberate inventory of all components and boot-time consumers. A keyfile remaining accessible on the same unencrypted disk may provide availability without providing the intended separation against disk theft.

Prove the replacement works from a detached state

An active provider can continue serving reads after its metadata changes. That makes a clean detach and attach test the essential boundary check. For a standalone filesystem in a scheduled maintenance window, stop writers, close consumers, unmount it normally, and detach without force:

umount /private-data
geli detach /dev/gpt/private-data
geli attach -n 1 /dev/gpt/private-data

These commands are a sequence for an appropriate standalone data filesystem, not a universal ZFS-pool procedure. A pool spanning providers needs its own export and import process; do not unmount one dataset and assume the pool released every GEOM consumer. If detach reports busy, identify the consumer instead of forcing it. Keep the existing working session and recovery console available.

After attachment, mount or import according to the storage design and verify known files, application startup, permissions, and representative read/write operations. Record that slot 1 unlocked a detached provider. If that test fails, retain the old slot and troubleshoot the exact passphrase or keyfile components. Do not treat a retry loop as a reason to erase the last known-good credential.

For an encrypted root provider, rehearse with a clone or approved maintenance reboot. Confirm loader support, prompt behavior, keyboard layout, external key media, and rescue access. A data-provider attach test cannot validate the pre-root boot environment.

Retire the old slot only after the acceptance test

Once the replacement has passed the detached-state test, remove the obsolete slot explicitly:

geli delkey -n 0 /dev/gpt/private-data
geli backup /dev/gpt/private-data /secure/offline/private-data-after.eli

Do not add -a or -f to make a failure disappear. Those flags affect destructive key removal, including protection against deleting the last metadata copy. Test current metadata with the new credential again after retiring the old slot. In a disposable clone, verify that the old slot no longer provides access. Keep the test separate from live application writes and document exactly which metadata generation it used.

A retained pre-rotation backup can restore an old encrypted master-key copy. Treat that as an explicit recovery capability, not proof that the old passphrase is globally revoked. For a compromise that requires excluding holders of historical usable metadata, migrate data to a newly initialized encryption context under a tested recovery plan; do not advertise ordinary setkey rotation as re-encryption.

Build evidence that survives the maintenance window

The useful completion record contains provider identity, slot ownership before and after, successful offline unlock evidence, recovery-copy locations, retention decisions, and application checks. It contains no credential values. Verify backup recovery on a disposable clone of matching size rather than restoring metadata onto the live provider as a casual test. GELI’s size checks are safeguards, not obstacles to override automatically.

Also rehearse loss of one recovery component. Could another authorized operator identify the correct provider, obtain the permitted escrow material, and recover a known file without the original administrator? If the answer depends on undocumented shell state or a personal USB drive, the rotation procedure still has an availability defect. Persistent encryption is operationally sound when credential transitions, historical access, boot recovery, and verified data recovery are all accounted for.

Related:

Sources: