10. RadSec: NAS Across Untrusted Networks

Scenario: the internet, or a stretch of network you do not trust, lies between the NAS and rradius. RADIUS over UDP protects only part of its contents, with the shared secret and MD5, and is not fit to cross such a network directly. Use RadSec instead (RADIUS over TLS, RFC 6614): the whole packet is inside TLS, and both sides verify each other by certificate.

  • The wireless controller at headquarters has a fixed address and is recognised by certificate plus address.
  • The branch gateways are behind NAT with no fixed address, and are recognised by certificate alone.
  • To disconnect a user at a branch, rradius cannot reach the gateway behind NAT, so the request travels over the RadSec connection the gateway opened itself.
  • The management system at headquarters also connects in over RadSec, and sends disconnect requests on the same connection.

Example directory: rradius-server/examples/scenarios/radsec/

FileContents
rradius.toml[radius.tls], three kinds of client, [radius.coa]
make-certs.shCreates a demo CA, a server certificate and three client certificates
migrations/Accounts (same structure as the quick start) and the demo account alice
hq-wlc.secret, helpdesk.secretThe shared secret for the controller over UDP, and the shared secret the help desk uses to send CoA

How it differs from UDP

UDPRadSec
Portsauthentication 1812, accounting 1813One TCP port, 2083; authentication, accounting and Status-Server share one connection
How the NAS is recognisedSource addressSource address, certificate, or both
Shared secretEach NAS’s ownFixed as radsec (set by the RFC); protection comes from TLS
Message-Authenticator settingsApplyDo not apply; TLS guarantees integrity

Once connected, requests take exactly the same path as over UDP: the same authentication chains, scripts, EAP, forwarding by realm and accounting spool.

Steps

1. Create the certificates

cd rradius-server/examples/scenarios/radsec
./make-certs.sh

certs/ then holds ca.pem, the server’s server.pem/server.key (name radius.example.net), and three client certificates: hq-wlc, branch-gw and noc. For testing only. In production, use a private CA dedicated to issuing NAS certificates (see “Before going live” below).

2. Start

cd ../../..   # back to rradius-server
./target/release/rradius-server --config examples/scenarios/radsec/rradius.toml

The log shows RadSec listening on 0.0.0.0:2083.

3. Check the handshake

Before any NAS is available, connect once with openssl using the branch gateway’s certificate to confirm the certificate part works:

cd examples/scenarios/radsec
openssl s_client -connect 127.0.0.1:2083 -servername radius.example.net \
  -CAfile certs/ca.pem -cert certs/branch-gw.pem -key certs/branch-gw.key
  • Verify return code: 0 (ok) means both sides’ certificates passed. Press Ctrl+C to finish.
  • result="accepted" in curl -s http://127.0.0.1:9812/metrics | grep rradius_radsec_connections increases by 1.
  • Connect again with the hq-wlc certificate: the handshake succeeds, but the connection is closed at once, and the log says its certificate fits no client. The hq-wlc client has an address, so it only accepts connections from 10.30.0.10, and none of the clients recognised by certificate alone has that name.

openssl can only check the handshake. Real logins have to come from a NAS or proxy that speaks RadSec; the automated test does this part in code: it connects with the branch-gw certificate, logs alice in (Access-Accept with Filter-Id = "staff") and sends accounting.

4. NAS configuration

Every NAS is configured differently, but the items to set are the same:

ItemValue
Server address and portrradius’s address, TCP 2083
TransportRadSec, RADIUS over TLS, or “TLS”
Trusted CAThe CA that issues rradius’s server certificate (ca.pem in the example)
Server nameThe name on the server certificate (radius.example.net in the example)
Client certificate and private keyThis NAS’s own (branch-gw.pem, branch-gw.key in the example)
Shared secretradsec

The configuration explained

[radius.tls]
bind = "0.0.0.0"
port = 2083
cert_file = "certs/server.pem"
key_file = "certs/server.key"
client_ca_file = "certs/ca.pem"
min_tls_version = "1.2"
network_clients_need_tls_name = true
  • client_ca_file is the CA that issues NAS certificates. rradius trusts only it, not the system’s root certificates. A NAS with no certificate, or one not signed by it, fails the handshake.
  • min_tls_version is "1.2" by default. When every NAS supports TLS 1.3, it can be "1.3".
  • [radius] is required; RadSec is a section under it. UDP ports 1812 and 1813 stay open as usual; to keep UDP from being reached from outside, block it with the firewall.

Three kinds of client

[[radius.clients]]
name = "hq-wlc"
address = "10.30.0.10"
tls_name = "hq-wlc.example.net"
secret_file = "hq-wlc.secret"

[[radius.clients]]
name = "branch-gw"
tls_name = "branch-gw.example.net"
secret = "unused-on-radsec-change-me"
max_radsec_connections = 4
SettingHow it matchesSuits
address onlySource address. Any certificate from the same CA can act as this clientA CA that signs only for NAS, fixed addresses
address plus tls_nameSource address, and the certificate must be valid for this nameNAS with fixed addresses, hq-wlc in the example
tls_name onlyThe certificate must be valid for this name, from an address no other entry coversNAS behind NAT whose addresses change, branch-gw in the example
  • tls_name is matched against the certificate’s DNS SAN, wildcards on the certificate included; the CN is not used.
  • The source address comes first. When the source falls inside an entry with an address, that entry handles it, and the certificate does not move the connection to another client. So the source of a NAS recognised by certificate alone must not fall inside another client’s range.
  • secret is still required. RadSec does not use it; it is used only when a client with an address comes over UDP.
  • A client with only tls_name can only use RadSec; UDP never matches it.
  • max_radsec_connections limits how many connections this client may have open at once. Without it, one certificate can use up all of [radius.tls]’s max_connections (1024 by default).
  • Be careful with range clients. When address is a range and there is no tls_name, any address in the range can connect with any certificate from this CA. The example sets network_clients_need_tls_name = true, so such clients do not accept RadSec connections (they can still use UDP).

The script knows which NAS it is

When a request comes over RadSec, the script can read the connection’s certificate: radsec_subject is the subject as text, and radsec_subject_attrs.CN[1] is one of its fields. It says who the NAS is, not who the user is. For UDP requests and replayed accounting it is nil. See usage section 4.2.

Disconnects over the NAS’s own connection

The branch gateway is behind NAT, so rradius has no address to send a Disconnect-Request to. When a client with only tls_name has a connection open, rradius sends it on the RadSec connection it opened instead.

[radius]
coa_timeout_ms = 2000

[radius.coa]
bind = "0.0.0.0"
port = 3799

[[radius.coa.clients]]
name = "helpdesk"
address = "10.30.0.50"
secret_file = "helpdesk.secret"

The help desk system (helpdesk) sends the request over UDP to rradius’s port 3799, naming the NAS with NAS-Identifier:

echo 'User-Name=alice,NAS-Identifier=branch-gw,Acct-Session-Id=rs-1' \
  | radclient 127.0.0.1:3799 disconnect helpdesk-coa-secret-change-me

(For local testing, change the address of helpdesk to 127.0.0.1 first.)

  • How the NAS is found: the request’s NAS-IP-Address, NAS-IPv6-Address and NAS-Identifier are matched, in that order, against client addresses or names. branch-gw has no address, so its name is used.
  • It is sent once on the connection, waiting coa_timeout_ms. TCP does not lose packets, so coa_attempts is not used.
  • When the gateway has no connection open, the answer is a NAK with Error-Cause 502 (Request Not Routable). The command above gets exactly this when no gateway is connected.
  • The NAS must be willing to receive Disconnect and CoA on the connection it opened. Not every device supports this; check with the vendor first.
  • Scripts can send them too: send_disconnect('branch-gw', {...}) uses the same connection, and raises an error when there is none. The command-line rradius-server disconnect does not run inside the server and cannot reach the connection, so it cannot target this kind of client.
  • In a cluster, only the node holding that connection can send. When the gateway is connected to node1, the request must go to node1; sent to another node it gets 502.

The management system over RadSec too: coa_sender

[[radius.clients]]
name = "noc"
tls_name = "noc.example.net"
secret = "unused-on-radsec-change-me"
coa_sender = true

When the sender already connects to rradius over RadSec, set coa_sender = true and it can send Disconnect-Request and CoA-Request on the same connection, with no separate UDP or shared secret. Answers are written back on the same connection.

  • Off by default. Senders and NAS share port 2083, so a firewall cannot tell them apart; this setting is what decides who may disconnect users. Requests from clients without it are dropped, with is not a coa_sender in the log.
  • Requires [radius.coa] and [radius.tls]. When requests come only over RadSec, [[radius.coa.clients]] can be left out, but the UDP port 3799 is still opened.

For the full rules (session lookup when only a user name is given, forwarding by realm to upstreams, the various NAKs), see chapter 7 and usage section 4.8.

Revoking a NAS

Three ways, from fastest to slowest:

  1. Remove its [[radius.clients]] entry and send SIGHUP. Open connections are closed at their next packet.
  2. Revoke the certificate: set crl_file, put the new revocation list in place and send SIGHUP. The certificate then fails the handshake, and open connections are closed when they are checked again (at the SIGHUP, and once a minute after that). The revocation lists must cover every CA in the chain; missing one blocks every device.
  3. When the CA offers only OCSP, set ocsp, the same way as for EAP-TLS; see chapter 15.

Before going live

  • The CA signs only for NAS. When the CA in client_ca_file also signs users’ EAP-TLS certificates, a user’s certificate can be used to connect in as a NAS (clients with only address cannot stop it). Use a separate CA, or set tls_name on every client.
  • Limit the sources of 2083 with the firewall. With clients recognised by certificate alone, unknown connections cannot be stopped by source address before the handshake, so anyone who can reach the port can use up TLS handshakes.
  • Replace certificates before they expire. An expired certificate fails the handshake, and an open connection stays open at most one more minute. After replacing the server certificate, send SIGHUP: new connections use the new one, and open ones are unaffected.
  • Behind a load balancer, it must run in TCP mode and send a PROXY protocol header, with its addresses listed in proxy_protocol_from; TLS is still handled by rradius. See usage section 2.7.
  • Different certificates for different names on one port (multi-tenant) use [[radius.tls.certificates]]; see the same section.
  • Idle connections are closed after 300 seconds without a complete packet (idle_timeout_ms), and the NAS reconnects. A NAS that sends Status-Server regularly is not closed.
  • Not tested: RadSec with any real NAS. Interoperability tests have covered authentication, accounting and CoA with FreeRADIUS 3.2.10 as a proxy. CoA over the NAS’s own connection has only been tested with a NAS simulated in code.

Common problems

SymptomCause
The log shows RadSec handshake with ... failedThe NAS presented no certificate, the certificate is not signed by client_ca_file, it has been revoked, or the TLS versions do not match
RadSec connection from unknown clientThe source is in no client’s address, and there is no client recognised by certificate alone
The handshake succeeds but the connection drops at once, with its certificate fits no clientThe certificate’s name is not that of any client with only tls_name; or the source falls inside a client with an address and the certificate is not valid for its tls_name (the message is then is not valid for client ...'s tls_name)
has no tls_name, which network_clients_need_tls_name asks forA range client has no tls_name, and network_clients_need_tls_name is on
Connected, but no request gets a replyThe NAS’s shared secret is not radsec
A disconnect gets 502NAS-Identifier is not the client’s name, that NAS has no connection open, or it is connected to another node
A disconnect gets 505The NAS did not answer within coa_timeout_ms: it does not support receiving CoA on this connection
The connection drops every 5 minutesThe idle timeout; raise idle_timeout_ms or have the NAS send Status-Server
Built with Hugo
Theme Stack designed by Jimmy