[IMPORTANT] .Project status — 27 April 2026

This shard is being deprecated in favour of crystal-clevis-zfs.

Why the change? — comparative analysis of GELI vs ZFS native encryption for the Aloli use case (FreeBSD + ZFS):

Performance: ZFS native encryption wins by a wide margin on compressible data (logs, databases, JSON, source code) because ZFS compression runs before encryption. With GELI, ZFS sees cryptographic noise and compression becomes useless.
Boot simplicity: a single ZFS pool with encrypted child datasets, two commands (zpool import + zfs load-key) instead of an N × geli attach + N × zpool import chain.
Snapshots / send-recv: ZFS native supports zfs send -w which exports encrypted snapshots as-is — off-site backups without the key become possible.

clevis-geli v0.1 is still functional and tested (QEMU FreeBSD 15 aarch64 bench). The code is not archived until crystal-clevis-zfs is delivered and working — you can keep using it during the transition.

Planned migration: Aloli users move to crystal-clevis-zfs at each server's next re-bootstrap. No forced in-place migration.

Reference: see https://github.com/aloli-crystal/beryl/blob/production/crystal-clevis-zfs-specs.adoc[crystal-clevis-zfs-specs.adoc] in beryl for the successor specs, and https://github.com/aloli-crystal/beryl/blob/production/boot-and-mount-plan.adoc[boot-and-mount-plan.adoc] § « Pivot GELI → ZFS native » for the detailed rationale.

For the FreeBSD community: if you have a Tang+GELI use case (Tang+UFS, Tang+ext4 portable, etc.) that doesn't translate to Tang+ZFS, this shard remains usable and open source. Forks are welcome.

FreeBSD GELI counterpart of https://github.com/latchset/clevis[latchset/clevis].

clevis-geli implements the Tang client protocol (Network-Bound Disk Encryption — NBDE) so that GELI-encrypted volumes can be unlocked at boot, with no human intervention, by interrogating one or more Tang servers.

This brick does not exist anywhere in the FreeBSD ecosystem today. That is the gap this shard fills.

French version: link:README.fr.adoc[README.fr.adoc].

== Architecture

[source]

              ┌────────────────────────────────┐
              │    clevis-geli (this)  │
              │                                │
              │  bind / recover  ── geli setkey│
              │  Tang HTTP/JOSE                │
              └─────────────┬──────────────────┘
                            │
                            │ HTTP + JOSE
                            ▼
                   ┌────────────────┐
                   │ Tang server(s) │
                   │ (FreeBSD pkg)  │
                   └────────────────┘

== Usage (planned)

[source,shell]

Bind a GELI volume to two Tang servers (threshold 2 of 2):

clevis-geli bind
--device /dev/ada0p4
--tang http://tang-nas.local
--tang http://tang-ovh.example.com

Unlock a bound GELI volume at boot (called from rc.d):

clevis-geli unlock --device /dev/ada0p4

== Status

v0.1: Tang client protocol (advertise, recover) on top of jose. JOSE primitives validated against latchset/jose.
v0.1: GELI binding via geli(8) shell-out.
v0.2 (later): Shamir threshold across multiple Tang servers (sss à la Clevis).

== Installation