radius

README

radius

A commercial-grade RADIUS protocol library implemented in Go, with full support for the core RADIUS RFCs plus a command-line tool supporting both client and server modes.

Supported RFCs

RFC	Title
2865	Remote Authentication Dial In User Service (RADIUS)
2866	RADIUS Accounting
2867	RADIUS Accounting Modifications for Tunnel Protocol Support
2868	RADIUS Attributes for Tunnel Protocol Support
2869	RADIUS Extensions
3162	RADIUS and IPv6
5176	Dynamic Authorization Extensions to RADIUS
6613	RADIUS over TCP
6614	RADIUS over TLS
6929	RADIUS Protocol Extensions
7360	RADIUS over DTLS
9445	RADIUS Extensions for DHCP-Configured Services

Status

Stable v1.1.0. The core packet, crypto, transport (UDP/TCP/TLS/DTLS), protocol, client, server, dictionary parser/generator, and vendor sub-package layers are complete and tested against the RFCs listed above. The public API follows semantic versioning; breaking changes will be reserved for v2. See CHANGELOG.md for the full change history.

Installation

go get github.com/wxccs/radius@v1.1.0

Quick Start

Client (UDP)

package main

import (
    "context"
    "log"
    "net"
    "time"

    "github.com/wxccs/radius/client"
    "github.com/wxccs/radius/packet"
    "github.com/wxccs/radius/protocol"
    "github.com/wxccs/radius/types"
)

func main() {
    c, err := client.NewUDPClient(
        &net.UDPAddr{IP: net.IPv4(127, 0, 0, 1), Port: 1812},
        []byte("shared-secret"),
        client.Config{Timeout: 5 * time.Second},
    )
    if err != nil {
        log.Fatal(err)
    }
    defer c.Close()

    resp, err := c.Authenticate(context.Background(), &protocol.AccessRequest{
        Attributes: []packet.Attribute{
            packet.NewString(types.AttrUserName, "alice"),
            packet.NewString(types.AttrUserPassword, "hunter2"),
        },
        Method: protocol.AuthPAP,
    })
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("reply: %s", resp.Code)
}

Server (UDP)

package main

import (
    "context"
    "log"
    "net"

    "github.com/wxccs/radius/packet"
    "github.com/wxccs/radius/server"
    "github.com/wxccs/radius/types"
)

func main() {
    handler := server.HandlerFunc(func(_ context.Context, req *server.Request) (*packet.Packet, error) {
        // Replace with real credential lookup.
        return &packet.Packet{
            Code:          types.AccessAccept,
            Identifier:    req.Identifier,
            Authenticator: req.Authenticator,
        }, nil
    })
    srv, err := server.NewUDPServer("udp4",
        &net.UDPAddr{IP: net.IPv4(0, 0, 0, 0), Port: 1812},
        handler, server.StaticSecret([]byte("shared-secret")))
    if err != nil {
        log.Fatal(err)
    }
    if err := srv.Serve(context.Background()); err != nil {
        log.Fatal(err)
    }
}

Accounting, CoA, Disconnect

The protocol.Client exposes Account, SendCoA, and SendDisconnect methods mirroring Authenticate; the server-side Handler receives the raw *server.Request and can branch on req.Code. See the package docs for the full API.

Transports

The transport/ package exposes four transports, all of which use the existing 2-byte Length field at offset 2..3 of the RADIUS header for framing (RFC 6613 §2.1):

Transport	Listener / Dialer	RFC
UDP	ListenUDP, DialUDP	2865, 3162
TCP	ListenTCP, DialTCP	6613
TLS	ListenTLS, DialTLS	6614
DTLS	ListenDTLS, DialDTLS	7360

// TLS server
ln, err := transport.ListenTLS("tcp4", laddr, tlsConfig)
// TLS client
client, err := transport.DialTLS("tcp4", server, tlsConfig)

// DTLS server (pion options API)
ln, err := transport.ListenDTLS("udp4", laddr,
    piondtls.WithCertificates(cert), piondtls.WithFlightInterval(100*time.Millisecond))
// DTLS client
client, err := transport.DialDTLS("udp4", server,
    piondtls.WithInsecureSkipVerify(true))

Vendor-Specific Attributes

The vendors/ package provides typed constructors for common vendor sub-attributes, each in its own sub-package keyed by SMI Private Enterprise Code:

Sub-package	Vendor	Code
vendors/cisco	Cisco	9
vendors/h3c	H3C	2011
vendors/juniper	Juniper	2636
vendors/alcatel	Alcatel	800
vendors/redback	Redback	2352
vendors/microsoft	Microsoft	311

// Microsoft MS-CHAP2-Success VSA, computed from MS-CHAPv2 inputs.
attr := microsoft.NewMSCHAP2SuccessFromAuth(
    authChallenge, peerChallenge, ntResponse, "alice", "password")

Shared helpers vendors.NewVSA, vendors.DecodeVSA, and vendors.MatchVSA implement the RFC 2865 §5.26 wire format for vendors not covered by a dedicated sub-package.

Dictionary Support

The dictionary/parser/ package parses FreeRADIUS dictionary files ($INCLUDE, ATTRIBUTE, VALUE, VENDOR, BEGIN-VENDOR/END-VENDOR, ALIAS, BEGIN-TLV, BEGIN-ENUM) and returns a *parser.Dict that can be registered at runtime via (*Dictionary).RegisterFromDict.

The dictionary/gen/ package and the cmd/dict-gen CLI emit typed Go source (constants + accessor pairs) from a parsed dictionary, so you can reference attributes by name at compile time:

go install ./cmd/dict-gen
dict-gen --in dictionary.freeradius --out attrs.go --pkg attrs

// In your application:
attrs.AddUserName(p, "alice")
if v, ok := attrs.GetNASPort(p); ok { /* ... */ }

Command-Line Tool

The radius-tool binary supports client mode (access, account, coa, disconnect) and a lightweight test server mode. Build it with:

go build -o radius-tool ./cmd/radius-tool
./radius-tool --help

License

Licensed under the MIT License. See LICENSE for the full text.

Third-party dependencies are listed in THIRD_PARTY_LICENSES.md.

Documentation

Overview

Package radius is the top-level entry point for the wxccs/radius library. It re-exports the most commonly used symbols from the protocol, packet, server, client, and types packages so that applications can use the library with a single import:

c, err := radius.NewUDPClient(addr, secret, radius.Config{Timeout: 5 * time.Second})
resp, err := c.Authenticate(ctx, radius.NewAccessRequest().PAP("alice", "pw").Build())

The subpackages remain the source of truth for richer APIs (dictionary, crypto, transport, integration helpers). Symbols not re-exported here can be reached by importing the corresponding subpackage directly; no symbol is hidden — this package only re-exports, never wraps.

Index

• Constants
• Variables
• type AccessRequestBuilder
• type AccountingRequestBuilder
• type Attribute
• type AuthMethod
• type CoARequestBuilder
• type Code
• type Config
• type DisconnectRequestBuilder
• type Handler
• type HandlerFunc
• type Mux
• type Packet
• type Request
• type SecretLookup
• type TCPClient
• type TCPServer
• type UDPClient
• type UDPServer

Constants

const (
	AccessRequest      = types.AccessRequest
	AccessAccept       = types.AccessAccept
	AccessReject       = types.AccessReject
	AccountingRequest  = types.AccountingRequest
	AccountingResponse = types.AccountingResponse
	AccessChallenge    = types.AccessChallenge
	CoARequest         = types.CoARequest
	CoAACK             = types.CoAACK
	CoANAK             = types.CoANAK
	DisconnectRequest  = types.DisconnectRequest
	DisconnectACK      = types.DisconnectACK
	DisconnectNAK      = types.DisconnectNAK
)

Packet codes from RFC 2865, RFC 2866, and RFC 5176.

const (
	AttrUserName             = types.AttrUserName
	AttrUserPassword         = types.AttrUserPassword
	AttrCHAPPassword         = types.AttrCHAPPassword
	AttrNASIPAddress         = types.AttrNASIPAddress
	AttrNASPort              = types.AttrNASPort
	AttrServiceType          = types.AttrServiceType
	AttrFramedIPAddress      = types.AttrFramedIPAddress
	AttrFramedIPNetmask      = types.AttrFramedIPNetmask
	AttrFilterID             = types.AttrFilterID
	AttrReplyMessage         = types.AttrReplyMessage
	AttrState                = types.AttrState
	AttrClass                = types.AttrClass
	AttrVendorSpecific       = types.AttrVendorSpecific
	AttrSessionTimeout       = types.AttrSessionTimeout
	AttrIdleTimeout          = types.AttrIdleTimeout
	AttrCalledStationID      = types.AttrCalledStationID
	AttrCallingStationID     = types.AttrCallingStationID
	AttrNASIdentifier        = types.AttrNASIdentifier
	AttrProxyState           = types.AttrProxyState
	AttrNASPortType          = types.AttrNASPortType
	AttrAcctStatusType       = types.AttrAcctStatusType
	AttrAcctDelayTime        = types.AttrAcctDelayTime
	AttrAcctInputOctets      = types.AttrAcctInputOctets
	AttrAcctOutputOctets     = types.AttrAcctOutputOctets
	AttrAcctSessionID        = types.AttrAcctSessionID
	AttrAcctAuthentic        = types.AttrAcctAuthentic
	AttrAcctSessionTime      = types.AttrAcctSessionTime
	AttrAcctInputPackets     = types.AttrAcctInputPackets
	AttrAcctOutputPackets    = types.AttrAcctOutputPackets
	AttrAcctTerminateCause   = types.AttrAcctTerminateCause
	AttrAcctMultiSessionID   = types.AttrAcctMultiSessionID
	AttrEAPMessage           = types.AttrEAPMessage
	AttrMessageAuthenticator = types.AttrMessageAuthenticator
	AttrNASPortID            = types.AttrNASPortID
	AttrAcctInterimInterval  = types.AttrAcctInterimInterval
	AttrNASIPv6Address       = types.AttrNASIPv6Address
	AttrFramedIPv6Prefix     = types.AttrFramedIPv6Prefix
	AttrFramedIPv6Pool       = types.AttrFramedIPv6Pool
	AttrErrorCause           = types.AttrErrorCause
)

Commonly-used attribute type numbers from RFC 2865 / 2866 / 2869 / 3162 / 5176. The full list lives in the types package.

const (
	PortAuth       = types.PortAuth
	PortAccounting = types.PortAccounting
	PortCoA        = types.PortCoA
	PortTCP        = types.PortTCP
)

UDP and TCP ports for RADIUS services (RFC 2865, RFC 2866, RFC 5176, RFC 6613).

const (
	AuthPAP = protocol.AuthPAP
	AuthEAP = protocol.AuthEAP
)

Authentication methods.

const AuthenticatorLength = types.AuthenticatorLength

AuthenticatorLength is the fixed length in bytes of the Request/Response Authenticator field.

Variables

var (
	NewString         = packet.NewString
	NewInteger        = packet.NewInteger
	NewIPAddr         = packet.NewIPAddr
	NewIPv6Addr       = packet.NewIPv6Addr
	NewOctets         = packet.NewOctets
	NewVendorSpecific = packet.NewVendorSpecific
)

Attribute and packet constructors re-exported from the packet package.

var (
	NewAccessRequest     = protocol.NewAccessRequest
	NewAccountingRequest = protocol.NewAccountingRequest
	NewCoARequest        = protocol.NewCoARequest
	NewDisconnectRequest = protocol.NewDisconnectRequest
)

Request builders. NewAccessRequest returns a fluent builder whose Build method yields a *protocol.AccessRequest suitable for Client.Authenticate. The other builders behave analogously for Account, SendCoA, and SendDisconnect.

The response struct types (protocol.AccessResponse, protocol.CoAResponse, etc.) are intentionally NOT re-exported here: the names AccessRequest, AccountingRequest, CoARequest, DisconnectRequest, and AccountingResponse refer to the RADIUS packet Code constants from the types package, and Go does not permit a type and a const to share a name. Callers receive the response via short variable declaration (resp, err := c.Authenticate(...)) or import the protocol package directly when a named type is required.

var (
	NewUDPClient = client.NewUDPClient
	NewTCPClient = client.NewTCPClient
)

NewUDPClient dials a UDP socket to a RADIUS server and returns a ready Client. NewTCPClient dials a single TCP connection (RFC 6613) instead.

var (
	NewUDPServer = server.NewUDPServer
	NewTCPServer = server.NewTCPServer
	StaticSecret = server.StaticSecret
	SecretMap    = server.SecretMap
	NewMux       = server.NewMux
)

Server constructors and helpers.

Types

type AccessRequestBuilder

type AccessRequestBuilder = protocol.AccessRequestBuilder

Builder types re-exported so callers can declare variables of these types.

type AccountingRequestBuilder

type AccountingRequestBuilder = protocol.AccountingRequestBuilder

Builder types re-exported so callers can declare variables of these types.

type Attribute

type Attribute = packet.Attribute

Attribute is a single RADIUS TLV (Type, Length, Value).

type AuthMethod

type AuthMethod = protocol.AuthMethod

AuthMethod selects how the Access-Request carries user credentials.

type CoARequestBuilder

type CoARequestBuilder = protocol.CoARequestBuilder

Builder types re-exported so callers can declare variables of these types.

type Code

type Code = types.Code

Code identifies a RADIUS packet code (RFC 2865 §3, RFC 5176 §2.1).

type Config

type Config = client.Config

Client configuration and constructors.

type DisconnectRequestBuilder

type DisconnectRequestBuilder = protocol.DisconnectRequestBuilder

Builder types re-exported so callers can declare variables of these types.

type Handler

type Handler = server.Handler

Server-side handler types.

type HandlerFunc

type HandlerFunc = server.HandlerFunc

Server-side handler types.

type Mux

type Mux = server.Mux

Server-side handler types.

type Packet

type Packet = packet.Packet

Packet is a RADIUS protocol data unit.

type Request

type Request = server.Request

Server-side handler types.

type SecretLookup

type SecretLookup = server.SecretLookup

Server-side handler types.

type TCPClient

type TCPClient = client.TCPClient

Client configuration and constructors.

type TCPServer

type TCPServer = server.TCPServer

Server-side handler types.

type UDPClient

type UDPClient = client.UDPClient

Client configuration and constructors.

type UDPServer

type UDPServer = server.UDPServer

Server-side handler types.