certificates

The certificates clause defines named X.509 certificate and private key objects that other parts of the configuration reference (for example TLS listeners, EAP‑TLS / PEAP / TTLS methods, management HTTPS, RADIUS/TLS, or internal components requiring a certificate/key pair). Centralizing these definitions avoids repeating file paths and eases rotation.

A definition is purely a reference wrapper around on‑disk PEM files; the server loads and holds them in memory after parsing.

Structure

certificates {
    x509 "SERVER_CERT" {
        filename "/etc/radiator/certs/server.pem";
    }

  x509-directory "CLIENT_CA_DIRECTORY" {
    directory "/etc/radiator/certs/clients";
    interval 30m;
  }

    key "SERVER_KEY" {
        filename "/etc/radiator/private/server-key.pem";
        # password "correcthorsebatterystaple";
    }
}

You can define any number of certificate (x509), certificate directory (x509-directory), and private key (key) blocks. Names are case sensitive. Reusing a name will cause a configuration error.

Blocks and Statements

Relative paths are resolved relative to the working directory of the running process (typically the directory where you start the server). Prefer absolute paths for production.

Certificate directories

Use x509-directory for CA bundles that are maintained as individual PEM files in a directory. Radiator rescans the directory periodically and reloads the certificates without requiring a configuration change. If interval is omitted, the directory is rescanned every 1m.

certificates {
  x509-directory "CLIENT_CA_DIRECTORY" {
    directory "/etc/radiator/certs/clients";
    interval 30m;
  }
}

For interval syntax and supported forms, see interval.

Usage in Other Clauses

Example: EAP‑TLS inside an AAA handler:

authentication {
    backend "USERS";
    eap {
        eap-tls {
            tls {
                certificate "SERVER_CERT";
                certificate_key "SERVER_KEY";
                # client_ca_certificate "CLIENTS_CA";
                # require_client_certificate true;
            }
        }
    }
}

Example: TLS listener (shape depends on the server protocol block):

servers {
    radius "auth-tls" {
        listen {
            protocol tls;
            port 2083;
            ip 0.0.0.0;
        }
        # certificate/key reference occurs in the TLS sub-block for the listener
        policy "DEFAULT";
    }
}

(Refer to the server / EAP method documentation for the exact statement names and where to reference certificate and certificate_key.)

Directory-backed CA bundles can be referenced anywhere a CA certificate object is accepted:

certificates {
  x509-directory "CLIENT_CA_DIRECTORY" {
    directory "/etc/radiator/certs/clients";
    interval 30m;
  }
}

authentication {
  eap {
    eap-tls {
      tls {
        client_ca_certificate "CLIENT_CA_DIRECTORY";
      }
    }
  }
}

Debug Logging

When debug logging is enabled (RADIATOR_LOG_LEVEL=debug or --debug), the server logs certificate details as each certificate is added to a TLS context. This helps verify correct certificate loading and troubleshoot TLS configuration issues.

Example log entry in JSON format:

{
  "level": "DEBUG",
  "namespace": ["configuration", "certificates"],
  "message": "Certificate added to TLS context",
  "fields": {
    "tls_context": "server_cert_chain",
    "cert_config": "SERVER_CERT",
    "chain_position": "0",
    "subject": "c=AU,cn=test.server.example.com",
    "issuer": "c=AU,cn=Example CA",
    "san": "ip:10.20.30.101, dns:test.server.example.com",
    "not_before": "2025-01-01T00:00:00Z",
    "not_after": "2027-01-01T00:00:00Z",
    "serial": "20:25:01:01:00:01"
    ...
  }
}

The tls_context field indicates where the certificate is used:

• server_cert_chain - Server certificate and chain
• server_client_ca - CA certificates for client verification
• client_cert_chain - Client certificate and chain (for outbound TLS)
• client_server_ca - CA certificates for server verification (for outbound TLS)

Certificate Revocation Lists (CRL)

Radiator can reject peer certificates that have been revoked by their issuing CA. The recommended way to publish CRLs to Radiator is a crl-directory, which is a directory of CRL files on the server filesystem that Radiator rescans in the background. For static deployments where the CRL never changes, a single crl block can be used instead; a single crl block is only re-read on a configuration reload, so it is not suitable for deployments where revocations are added over time.

certificates {
    crl-directory "ALL_CRLS" {
        directory "/etc/radiator/certs/crls";
        interval 1h;
    }

    crl "ISSUER_CRL" {
        filename "/etc/radiator/certs/issuer.crl";
    }
}

Freshness and allow-stale

crl-directory supports the shared interval forms documented in interval, including cron schedules and optional random jitter.

Each CRL carries a nextUpdate timestamp from its issuer. Once that time has passed Radiator considers the CRL stale and, by default, rejects any peer whose chain it covers with expired CRL. This is the secure default: a stale CRL cannot prove that a certificate is still valid.

Set allow-stale yes; on a crl or crl-directory block to relax this and fall back to accepting the peer when the CRL is past nextUpdate. Use this only when CRL distribution is unreliable and the operational risk of brief over-acceptance is acceptable; revoked certificates that appear in a stale CRL are still rejected.

Live updates

CRL directory contents are reloaded on the configured interval without requiring a configuration reload. New connections pick up the latest snapshot on their next handshake. Already-established TLS sessions are not renegotiated; see server TLS - session resumption and CRL enforcement for the recommended settings when prompt revocation is required.

Referencing a CRL

Reference a crl or crl-directory from a TLS block via the crl statement (repeatable). Both single-file CRLs and CRL directories are valid targets:

servers {
    radius "RADSEC" {
        listen {
            protocol tls;
            port 2083;
            tls {
                certificate "RADSEC_CERT";
                certificate_key "RADSEC_KEY";
                server_ca_certificate "RADSEC_SERVER_CA";
                require_client_certificate true;
                client_ca_certificate "RADSEC_CLIENT_CA";
                crl "ALL_CRLS";
            }
        }
    }
}