All posts Security

NetDefense Agent 1.31.0: Check SSL Verification Before You Upgrade

SECURITY 6 MIN READ NETDEFENSE TEAM

From NetDefense agent 1.31.0, the agent always verifies its connections to NetDefense: registration and the control channel, the one-time trust-key fetch, and the relay for remote sessions. SSL Verification, TOFU Key Fetch SSL Verification and Pathfinder SSL Verification no longer turn that off. A new setting, TLS Mode, chooses what the agent trusts.

Most firewalls need nothing. A few do, and they need it before they upgrade.

TL;DR

  • A firewall that relied on SSL Verification being off to reach a NetDefense server with a private-CA or self-signed certificate stops connecting when it upgrades, and stays offline until TLS Mode is set to Custom CA with that CA in CA File.
  • TLS Mode arrives with the upgrade, so it can’t be set earlier. Save the CA file on the firewall before, set Custom CA right after, on the firewall itself.
  • A firewall behind a TLS-inspection proxy that had SSL Verification off instead of Extra CA File disconnects too, until the proxy’s CA is in Extra CA File.
  • A hosted firewall with no inspection proxy, one with verification already on, and one that already trusts its CA through Extra CA File, need nothing.

Who needs to act

Firewalls installed from the NetDefense repository get 1.31.0 with their first OPNsense update after its release, scheduled updates included, so it can arrive without anyone choosing it. Prepare the firewalls below before their next update, and watch for them going offline if they update on their own.

Nothing to do:

  • A firewall on the hosted NetDefense service with no TLS-inspection proxy in the way.
  • A firewall with SSL Verification and its two related settings on.
  • A firewall that already trusts a private CA or a proxy’s CA through Extra CA File, with SSL Verification on.

Must act:

  • A firewall that relied on SSL Verification being off to reach a NetDefense server with a private-CA or self-signed certificate.
  • A firewall behind a TLS-inspection proxy that had SSL Verification off instead of the proxy’s CA in Extra CA File.
  • A firewall where only Pathfinder SSL Verification was off, for a relay with a private-CA certificate. This one stays online, but its remote sessions fail.

Private-CA or self-signed NetDefense server

Such a firewall disconnects when it upgrades and stays offline until it is fixed on the firewall itself. A NetDefense remote session can’t reach a device while it’s offline, so the fix can’t be pushed. TLS Mode is part of the upgrade, so you can’t set it earlier. The order is:

  1. Before the upgrade, save the CA file on the firewall, where only root can change it. It holds the CA that issued the server’s certificate, or the certificate itself if it is self-signed. If the relay for remote sessions is on another server, add the relay’s CA to the same file, or remote sessions fail. The file must meet the rules under CA File. For example:
firewall root shell bash
# install -o root -g wheel -m 644 ./private-ca.pem /usr/local/etc/ndagent-ca.pem
  1. Right after the upgrade, set TLS Mode to Custom CA under Services > NetDefense > Settings, Advanced Settings, Control Plane. Enter the file’s path in CA File and click Apply. If SSL Verification is still off, turn it back on in the same step.
  2. Do it on the firewall itself, through its web interface or a root shell. Upgrade such a firewall when you can reach it that way.

Behind a TLS-inspection proxy

Keep TLS Mode on System and the proxy’s CA in Extra CA File, as since 1.21.0. A firewall behind such a proxy that had SSL Verification off instead disconnects after the upgrade, until the proxy’s CA is in Extra CA File. Do it before the upgrade if you can, otherwise right after it, on the firewall itself.

Custom CA ignores Extra CA File

If you choose Custom CA behind a TLS-inspection proxy, put the proxy’s CA in CA File as well. Custom CA and SPKI pinned ignore Extra CA File.

Only the relay was unverified

If only Pathfinder SSL Verification was off, for a relay with a private-CA certificate, the firewall stays online after the upgrade but remote sessions fail. Keep TLS Mode on System and add the relay’s CA to Extra CA File.

What TLS Mode does

TLS Mode chooses what every connection to NetDefense is verified against. One mode covers all of them, and no mode turns verification off.

  • System (the default): the root certificates built into the agent plus Extra CA File, never the firewall’s own certificate store. This is what a firewall with verification on already had.
  • Custom CA: only the CAs in CA File, for a NetDefense server with a private-CA or self-signed certificate.
  • SPKI pinned: only the server keys listed in SPKI Hashes. Use it only for keys you control, the relay’s included: a certificate from a public CA usually comes with a new key at each renewal.

Fail-closed under Custom CA and SPKI pinned

Under Custom CA and SPKI pinned, a CA File or pin list that is missing or refused means every connection to NetDefense is refused until it is fixed on the firewall. There is no fallback to System. The agent keeps running, logs the reason, and shows it in a red notice on its settings page. Under System nothing fails closed: an Extra CA File the agent can’t use is logged, and the built-in roots carry on.

Also in 1.31.0

  • Settings that no longer work are flagged. While SSL Verification or one of its two related settings is off, the agent logs a warning at startup, its settings page shows a notice, and most task results end with a sentence that names the setting. Turn it back on and click Apply to clear it.
  • Clearer refusals. A refused connection’s error names the setting to fix and what the server presented. Behind an inspection proxy, the issuer it names is the CA that belongs in Extra CA File. See SSL Certificate Errors.

When your firewalls are ready

Upgrade under System > Firmware > Updates, or let your scheduled updates do it. Upgrade a firewall that needs a setting after the upgrade from its own web interface, so you can set it right away. Any other firewall can also upgrade with Install plugin on the web app’s Run page, or ndcli run plugin-install --device <name>.

The steps are on Agent 1.31.0 and SSL Verification, and Updating the agent lists every way to update.

Related reading

Security Direct-Peer Remote Sessions: a Straight Line to Your Firewall
Feature WebAdmin Through Connect Now Loads Faster
Guide How to Back Up OPNsense Firewall Configurations to Your Own S3 Bucket

Enjoyed this post? Explore more in the documentation.