Installing Tang on OPNsense

updated 6 min read #tutorial #security #networking

Introduction#

My Clevis clients unlock their disks against a Tang server, and the firewall is the box that is always up in my network, so that’s where Tang runs. There is no Tang plugin for OPNsense and the OPNsense repository doesn’t ship tang or jose either, so I build both from the ports tree.

Tested with OPNsense 26.7 (amd64, FreeBSD 15.1), updated to 26.7.7, tang 15 and jose 15 from the OPNsense ports tree, and a Fedora 44 client with clevis 23.

Building Tang from the ports tree#

Preparation#

Update OPNsense first (System > Firmware > Updates, or option 12 on the console). Otherwise pkg install will upgrade individual libraries out of band.

Then install the build tools that are available as packages, so they don’t have to be built from source:

pkg install gmake pkgconf ninja socat

Get the ports tree:

opnsense-code ports

The build still pulls in meson, cmake and llhttp and builds them from source. On 8 vCPUs, jose took under a minute and tang with its dependencies about six and a half minutes.

Building jose without man pages#

I don’t build man pages, because they need a2x and with it the whole asciidoc and docbook dependency chain. The jose port has a MANPAGES option for that:

cd /usr/ports/net/jose
make WITHOUT=MANPAGES BATCH=yes install clean

Building tang without man pages#

The tang port has no such option. It always lists asciidoc as a build dependency and the man pages in its packing list. Tang’s meson build skips the man pages by itself when a2x is missing, so I only remove the dependency and the three man page entries:

cd /usr/ports/security/tang
sed -i "" "s|a2x:textproc/asciidoc ||" Makefile
sed -i "" "/^share\/man\//d" pkg-plist
git diff .

The diff should look like this:

-BUILD_DEPENDS=     a2x:textproc/asciidoc \
+BUILD_DEPENDS=       \
                ${LOCALBASE}/libdata/pkgconfig/jose.pc:net/jose \
...
 libexec/tangd
-share/man/man1/tangd-rotate-keys.1.gz
-share/man/man1/tang-show-keys.1.gz
-share/man/man8/tang.8.gz
 libexec/tangd-keygen

Then build and install it:

make BATCH=yes install clean

During the configure step meson reports WARNING: Will not build man pages due to missing a2x (asciidoc) dependency!, which is expected.

Cleaning up#

Tang doesn’t need any of the build tools at runtime. The ports tree and the tools checkout can go too:

pkg remove gmake pkgconf ninja socat git
pkg autoremove
rm -rf /usr/ports /usr/tools

Only tang, jose and llhttp stay installed. Check pkg info git before removing git in case you use it for something else.

Configuring the service#

The rc.d script /usr/local/etc/rc.d/tangd belongs to the package and stays as it is; all settings go into rc.conf.d. There is no option for the listen address: tangd -l always binds to all IPv4 and IPv6 addresses, so the firewall decides who can reach it (see below).

A dedicated user#

By default tangd runs as root. I run it as its own user:

pw groupadd tang -g 740
pw useradd tang -u 740 -g tang -d /nonexistent -s /usr/sbin/nologin -c "Tang daemon"
chown -R tang:tang /var/db/tang
chmod 0700 /var/db/tang

Two details matter here:

  • The UID has to be below 2000. At boot, OPNsense deletes every local account with a UID between 2000 and 65000 that isn’t in its own configuration. 740 is not taken in the FreeBSD ports UID list.
  • The name has to be tang, because tangd-keygen and tangd-rotate-keys hard-code chown tang:tang for new keys.

rc.conf.d#

All settings go into /etc/rc.conf.d/tangd. OPNsense reads that directory when it starts the FreeBSD services at boot:

cat > /etc/rc.conf.d/tangd <<'EOF'
tangd_enable="YES"
tangd_port="7406"
tangd_user="tang"
start_precmd="tangd_prestart"
tangd_prestart()
{
	install -o tang -g tang -m 0640 /dev/null /var/log/tang
}
EOF

The tangd_prestart function creates the log file with the right owner before each start. Without it, the unprivileged daemon can’t create /var/log/tang. The rc.d script appends stderr there, one line per request. The file isn’t syslog, so the OPNsense log viewer doesn’t show it, and it is recreated empty on every start.

I use the same port as a Linux installation, where the SELinux policy assigns 7406 to tang:

sudo semanage port -l | grep tangd
tangd_port_t                   tcp      7406

Start the service and check it:

service tangd start
service tangd status
tangd is running as pid 30778.
sockstat -46l | grep tangd
tang    tangd      30778  3 tcp6  *:7406                *:*
tang    tangd      30778  4 tcp4  *:7406                *:*

tangd_enable in the file above starts it at boot. Tangd creates its signing and exchange keys in /var/db/tang on the first request, with mode 0440 and owned by tang.

Firewall#

Because tangd listens on every interface, the firewall rules are what keep it private:

  • WAN: OPNsense blocks inbound traffic by default. In my test, requests to port 7406 on the WAN address got no answer, and I don’t add a WAN rule.
  • LAN: the default “allow LAN to any” rule also allows traffic to the firewall itself, so every LAN host can reach Tang. That’s what I want for my servers’ network.
  • Other networks (guest, IoT, …): make sure their rules don’t allow traffic to “This Firewall” on port 7406. If you want it tight, add a pass rule for TCP 7406 from only the hosts that use Tang to the interface address, and block the port to “This Firewall” everywhere else.

Tang has no authentication. Anyone who can reach it and holds a copy of a client’s LUKS header can unlock that disk, so where it is reachable is the whole security model.

Testing#

From OPNsense and from every system that will use this Tang server, you should be able to get the advertisement (192.168.1.1 is the OPNsense default LAN address, use your own):

curl -s http://192.168.1.1:7406/adv | jq
{
  "payload": "eyJrZX...fVz9",
  "protected": "eyJh...biS1",
  "signature": "ALu7...30JR"
}

tang-show-keys prints the thumbprint of the signing key, which lets clients pin the server instead of trusting the advertisement interactively:

tang-show-keys 7406
gn2jqK3N1T2-s6X3IsEd28oIZ8cVMR5xBE5298c2JRQ

A quick round trip from a client:

echo test | clevis encrypt tang '{"url":"http://192.168.1.1:7406","thp":"gn2jqK3N1T2-s6X3IsEd28oIZ8cVMR5xBE5298c2JRQ"}' > test.jwe
clevis decrypt < test.jwe
test

You can now proceed to enroll NBDE Clevis clients, as described in my post about Clevis and Tang on OpenWrt.

Rotating keys#

The rotation script generates new keys and renames the old ones to hidden files. Tangd stops advertising the hidden keys but still answers recovery requests for them, so existing clients keep working:

/usr/local/libexec/tangd-rotate-keys -d /var/db/tang
ls -la /var/db/tang
-r--r-----   1 tang tang  361 .J486iuZnRGki54nqj7Bd4FYMwQexK690SCxVzXqO3R8.jwk
-r--r-----   1 tang tang  367 .gn2jqK3N1T2-s6X3IsEd28oIZ8cVMR5xBE5298c2JRQ.jwk
-r--r-----   1 tang tang  354 WiKVhj4TtfIOOABd3iKMF6-RKdOofb3uefh5IwEBa8M.jwk
-r--r-----   1 tang tang  349 mGIG3LACpmW7DIt_CI0YQdKY_Mj-Z2L9mSRaVygnNls.jwk

After that, I rebind every client to the new keys (clevis luks regen). Once they’re all rebound, I delete the old keys. From then on, bindings to the old keys fail:

rm /var/db/tang/.*.jwk

Backups and updates#

The keys in /var/db/tang are not part of the OPNsense configuration backup. If they’re lost, every client falls back to its passphrase, so I back them up separately and store the archive somewhere safe. It is as sensitive as the keys themselves:

tar -C /var/db -cpzf /root/tang-keys.tar.gz tang
chmod 600 /root/tang-keys.tar.gz

The package, the tang user, /etc/rc.conf.d/tangd and the keys all survive reboots and a minor firmware update (I tested 26.7 to 26.7.7), and the OPNsense health check stays clean. The firmware update also removes the leftover automatic build dependencies. Tang and jose are linked against the OpenSSL that OPNsense ships, so after a major upgrade I check service tangd status and the advertisement, and rebuild from the ports tree if tangd no longer starts.

cd ~/writing