16. Network Device Administration: Moving to TACACS+ over TLS

Scenario: the TACACS+ of chapter 6 obfuscates packet contents with the shared secret, which uses only MD5 and cannot stop someone who can capture traffic on the management network: administrators’ passwords and every command they ran can be decoded. Newer devices support TACACS+ over TLS (RFC 9887): the whole connection goes inside TLS 1.3, and devices and the server verify each other by certificate.

Devices are not all replaced in a day, so there is a period where both run side by side:

  • Core routers already support it: they move to the TLS port, each with its own certificate.
  • Access switches still have old firmware: they keep using the shared secret port.
  • Once everything has moved, the port without TLS is closed.

This chapter reuses the accounts, roles and command records of chapter 6, and covers only TLS and the migration.

Example directory: rradius-server/examples/scenarios/device-admin-tls/

FileContents
rradius.toml[tacacs] plus [tacacs.tls], two kinds of client, one authorization group
make-certs.shCreates a demo device CA, a server certificate and three device certificates
core.secret, access.secretShared secrets for the two groups of devices

The script and tables are chapter 6’s ../device-admin/tacacs.lua and ../device-admin/migrations/, so the two directories must be kept together.

Two ports

Port without TLSTLS port
Setting[tacacs] port, 49 by default[tacacs.tls] port, 300 by default
ProtectionObfuscation with the shared secret (MD5)TLS 1.3, and devices must present a certificate
How devices are recognisedSource addressSource address, plus certificate
Shared secretMust match the deviceNot used (still required in the configuration)

Once connected, authentication, authorization and accounting are handled exactly the same way: the same chains, scripts and authorization groups.

Steps

1. Create the certificates

cd rradius-server/examples/scenarios/device-admin-tls
./make-certs.sh

certs/ then holds ca.pem, the server’s server.pem/server.key (name tacacs.mgmt.example.net), and three device certificates: core-rtr-1, core-rtr-2 and spare. For testing only.

2. Start

49 and 300 are both below 1024, which ordinary accounts cannot bind. For local testing, change them to 4949 and 4300 first; for production, see “Before going live” in chapter 6. For local testing, change the address of core-rtr-1 to 127.0.0.1.

cd ../../..
./target/release/rradius-server --config examples/scenarios/device-admin-tls/rradius.toml

The log has two lines, TACACS+ Server listening on ... and TACACS+ over TLS listening on ....

3. Check the handshake

cd examples/scenarios/device-admin-tls
openssl s_client -connect 127.0.0.1:4300 -tls1_3 -servername tacacs.mgmt.example.net \
  -CAfile certs/ca.pem -cert certs/core-rtr-1.pem -key certs/core-rtr-1.key

Verify return code: 0 (ok) means the certificate part works. openssl can only check the handshake; logins and authorization have to come from a device that supports RFC 9887. The automated test plays the device in code and checks the following:

SituationResult
core-rtr-1’s certificate, from its address: netadmin1 logs inPASS
Same connection: wrong passwordFAIL
Same connection: netadmin1 starts a shellPASS, priv-lvl=15 (decided by the script from the role)
Same connection: noc1 runs configure terminalFAIL
A packet not marked “unobfuscated”ERROR, connection closed
core-rtr-2’s certificate, from core-rtr-1’s addressClosed after the handshake: the certificate is not valid for this device’s tls_name
A certificate belonging to no device (spare)Closed after the handshake
A client that only speaks TLS 1.2Handshake fails
core-rtr-1 connecting to the port without TLS insteadConnection closed: a device with tls_name set can only use TLS
Access switch with the shared secret: starts a shellPASS, priv-lvl=1 (the authorization group’s rule)
Access switch: show running-configFAIL

The configuration explained

[tacacs]
port = 49
enable = "deny"

[tacacs.tls]
port = 300
cert_file = "certs/server.pem"
key_file = "certs/server.key"
client_ca_file = "certs/ca.pem"
tls_only = false
  • client_ca_file is the CA that issues device certificates. Only it is trusted, not the system’s root certificates. Use a CA dedicated to network devices: if this CA also signs certificates for other purposes, those could be used to impersonate devices (see tls_name below).
  • TLS 1.3 only, and devices must have a certificate. A device with no certificate, the wrong certificate, or only TLS 1.2 fails the handshake.
  • The address comes from [tacacs] bind; both ports bind the same address. The connection limit and idle timeout are shared too.

Binding certificates to devices with tls_name

[[tacacs.clients]]
name = "core-rtr-1"
address = "10.50.0.1"
tls_name = "core-rtr-1.mgmt.example.net"
secret_file = "core.secret"

[[tacacs.clients]]
name = "access-switches"
address = "10.60.0.0/22"
secret_file = "access.secret"
authorize_group = "readonly"

A device is always first matched to its [[tacacs.clients]] entry by source address, and connections from sources not on the list are closed before the handshake. Then tls_name is looked at:

Client settingTLS portPort without TLS
Single address, no tls_nameYes. Any certificate from the CA can connect from this addressYes
Single address, with tls_nameYes; the certificate must be valid for this nameNo
Range, no tls_nameNo; closed after the handshake, logging needs tls_nameYes
Range, with tls_nameYes; the certificate must be valid for this name (a wildcard certificate can be used)No
  • tls_name is matched against the DNS names in the certificate’s SAN.
  • Setting tls_name declares “this device has moved”: it can no longer use the port without TLS. Even someone who has the old shared secret and spoofs its address cannot get in.
  • secret is still required; the TLS port does not use it.

Authorization is unchanged

The example’s core routers do not set authorize_group, so authorization goes to chapter 6’s script and is decided by the user’s role. The access switches set authorize_group = "readonly", so rules decide, regardless of user: even netadmin1 gets only priv-lvl=1 on the access switches. For the difference between the two, see chapter 6.

The order of the migration

  1. Prepare the CA and certificates. One per device, named with its management host name. The server certificate’s name must be the name filled in on the devices.

  2. Add [tacacs.tls] and restart. Adding this section needs a restart; SIGHUP alone is not enough. At this point every device still uses port 49, with no effect at all.

  3. Move devices one at a time:

    1. Install the certificate and the CA on the device, and configure it to reach rradius over TLS.
    2. Confirm it connects (see “Which port each device uses” below).
    3. Add tls_name to its [[tacacs.clients]] and send SIGHUP. From then on it can only use TLS.

    Step 3 comes after step 2. Adding tls_name first means the device is refused on port 49 before its TLS is set up; that is when the device’s local emergency account earns its keep.

  4. Devices that were covered by one range (access-switches in the example): as they move, give each moved device its own single-address entry (longest prefix wins, overriding the range), with tls_name.

  5. Once everything has moved, set tls_only = true and send SIGHUP. The port without TLS stops serving at once: new connections, and open connections at their next packet, are closed, logging tls_only takes TACACS+ over TLS only. After the next restart, that port is not opened at all. Changing back from true to false needs a restart.

RFC 9887 recommends keeping the period where both run side by side as short as possible.

Which port each device uses

  • The authentication log has one line per login, with the device’s name as client. Setting [log] level to debug shows every TACACS+ connection.
  • Try tightening: add tls_name to a device that has moved. If it is in fact still using port 49, its next request fails, the device falls back to its local accounts, and you notice at once.
  • rradius_tacacs_connections_total does not distinguish ports; connections on both are counted together.

Revoking and renewing certificates

  • Revocation lists: set crl_file, with one for every CA in the chain. Send SIGHUP after updating.
  • OCSP: set ocsp = "soft" or "hard", the same way as in chapter 15.
  • Open connections are checked again: once more than 60 seconds have passed since the last check, the certificate is checked again (CA, revocation list, expiry, tls_name) before the next packet is handled. A connection that fails is closed. An idle connection is checked only when it sends its next packet.
  • Replace the server certificate before it expires and send SIGHUP: new connections use the new one, and open ones are unaffected.
  • When a device’s certificate expires, that device cannot log in, and only its local accounts work. Monitor certificate expiry dates.

Before going live

  • Devices must keep a local emergency account, as in chapter 6. An expired certificate, a changed CA or a wrong clock all stop TLS from connecting.
  • Device clocks must be right. Certificates have start and expiry times, and a clock that is far off fails the handshake. This is especially likely when logging in after a device reboot, before it has synchronised its clock.
  • Firewall: open port 300 to the devices’ management range. Close 49 when the migration is over.
  • No session resumption. Every connection does a full handshake and certificate check; devices that keep a long-lived connection (single-connection) need fewer handshakes.
  • Not yet tested on real devices, only with a program (a rustls client). RFC 9887 was published in December 2025; check with vendors first which devices and versions support it. Device configuration commands differ by vendor, and this chapter does not include them.
  • The other items of chapter 6’s “Before going live” (permissions for port 49, keeping records) still apply.

Common problems

SymptomCause
Startup fails, mentioning the certificates of tacacs.tlsmake-certs.sh has not been run, or the private key does not match the certificate
Startup fails, mentioning tls_nametls_name is set but there is no [tacacs.tls], or that client has no address
A device connecting to port 300 fails the handshakeThe device presented no certificate, the certificate is not signed by client_ca_file, it is revoked or expired, or the device only speaks TLS 1.2
The handshake succeeds but the connection drops at once, with needs tls_name in the logThis device’s client is a range without tls_name. Give it its own entry with tls_name
The handshake succeeds but the connection drops at onceThe certificate is not valid for this client’s tls_name: the wrong certificate is installed, or the name is not among the DNS names in the SAN
After adding tls_name, that device cannot log inIt is still using port 49. Move the device to TLS first
Every request gets ERROR and the connection dropsThe device still sends obfuscated packets over TLS (not marked unobfuscated). The device’s TLS mode is not set correctly
After setting tls_only = true, no old device can log inSome devices have not moved yet. Change it back to false and restart
Built with Hugo
Theme Stack designed by Jimmy