Introduction

radcli is a C library for adding RADIUS authentication and accounting to an application in roughly 50 lines of code. All server addresses, credentials, and transport choices (UDP, TCP, TLS, DTLS) live in a single configuration file; the calling application needs no transport-specific code.

Quick start

The normal call sequence is three steps:

Load configuration — parses the config file and initialises the transport:
rc_handle *rh = rc_read_config("/etc/radiusclient/radiusclient.conf");

rc_read_config
rc_handle * rc_read_config(char const *filename)
Read the global config file.
Definition config.c:676
Build an attribute list — attach the attributes you want to send:
VALUE_PAIR *send = NULL;

rc_avpair_add(rh, &send, PW_USER_NAME, username, -1, 0);

rc_avpair_add(rh, &send, PW_USER_PASSWORD, password, -1, 0);

rc_avpair_add
VALUE_PAIR * rc_avpair_add(rc_handle const *rh, VALUE_PAIR **list, uint32_t attrid, void const *pval, int len, uint32_t vendorspec)
Adds an attribute-value pair to the given list.
Definition avpair.c:46

PW_USER_NAME
@ PW_USER_NAME
Its type is string.
Definition radcli.h:151

PW_USER_PASSWORD
@ PW_USER_PASSWORD
Its type is string.
Definition radcli.h:152
Send the request — rc_auth() handles retries, failover, and response validation automatically:
VALUE_PAIR *received = NULL;

int result = rc_auth(rh, 0, send, &received, NULL);

// result == OK_RC on success

rc_avpair_free(send);

rc_avpair_free(received);

rc_destroy(rh);

rc_auth
int rc_auth(rc_handle *rh, uint32_t nas_port, VALUE_PAIR *send, VALUE_PAIR **received, char *msg)
Builds an authentication request for port id nas_port with the value_pairs send and submits it to a s...
Definition buildreq.c:303

rc_destroy
void rc_destroy(rc_handle *rh)
Destroys Radius Client handle reclaiming all memory.
Definition config.c:1249

rc_avpair_free
void rc_avpair_free(VALUE_PAIR *pair)
Frees all value_pairs in the list.
Definition avpair.c:584

The transport is selected entirely in the config file (serv-type = udp, tcp, tls, or dtls); no code changes are required to switch. TLS and DTLS additionally require certificate or PSK credentials to be set in the config file (tls-ca-file, tls-cert-file, tls-key-file). See radexample.c for a complete compilable example.

For accounting requests that must not block (e.g. sending Accounting-Stop for open sessions while an application is shutting down), use rc_acct_async() instead of rc_acct(): it addresses every configured accounting server without waiting for a reply.

Operation without a config file

Programmatic configuration (without a file) is also possible using rc_new(), rc_config_init(), rc_add_config(), and rc_apply_config().

Background

RADIUS (Remote Authentication Dial In User Service, RFC 2865/2866) is a protocol for carrying authentication, authorisation, and accounting information between a Network Access Server and a shared Authentication Server. radcli implements the client side, and is source-compatible with freeradius-client and radiusclient-ng.