Context & Configuration

Building a radcli_ctx from a config file, or entirely programmatically, without ever including radcli.h. More...

Typedefs
typedef struct rc_conf	radcli_ctx
typedef enum radcli_opt_id	radcli_opt_id
typedef enum radcli_ctx_flags	radcli_ctx_flags
typedef enum radcli_secret_target	radcli_secret_target

Enumerations
enum	radcli_opt_id { RADCLI_OPT_COUNT }
enum	radcli_ctx_flags { RADCLI_CTX_NO_BUILTIN_DICT = 1 << 0 }
enum	radcli_secret_target { RADCLI_SECRET_AUTH = 1 << 0 , RADCLI_SECRET_ACCT = 1 << 1 }

Functions
radcli_ctx *	radcli_ctx_new (unsigned flags)
	Create an empty context, ready for radcli_ctx_set_opt_str()/ _set_opt_int() and radcli_ctx_apply() – the fully programmatic ("backup") way to configure radcli without a config file on disk.
radcli_ctx *	radcli_ctx_read_config (const char *filename, unsigned flags)
	Create a context by parsing a config file – the main, recommended way to configure radcli.
int	radcli_ctx_read_dictionary (radcli_ctx *ctx, const char *path)
	Load an additional attribute dictionary.
int	radcli_ctx_read_dictionary_from_buffer (radcli_ctx *ctx, const char *buf, size_t size)
	Load an additional attribute dictionary from an in-memory buffer.
int	radcli_ctx_apply (radcli_ctx *ctx)
	Validate the options set so far and initialise the transport.
void	radcli_ctx_free (radcli_ctx *ctx)
	Release a context.
int	radcli_ctx_set_opt_str (radcli_ctx *ctx, radcli_opt_id opt, const char *val)
	Set a string-typed configuration option.
int	radcli_ctx_set_opt_int (radcli_ctx *ctx, radcli_opt_id opt, long val)
	Set an integer-typed configuration option.
const char *	radcli_ctx_get_opt_str (const radcli_ctx *ctx, radcli_opt_id opt)
	Read back a string-typed configuration option.
int	radcli_ctx_get_opt_int (const radcli_ctx *ctx, radcli_opt_id opt, long *out)
	Read back an integer-typed configuration option.
int	radcli_ctx_set_secret (radcli_ctx *ctx, unsigned target_mask, const char *secret)
	Set the RADIUS shared secret for the configured authserver and/or acctserver.
int	radcli_ctx_set_tls_psk (radcli_ctx *ctx, const void *identity, size_t identity_len, const uint8_t *key, size_t keylen)
	Set the RFC 6614/7360 TLS-transport Pre-Shared Key credentials for the configured authserver.

Detailed Description

Building a radcli_ctx from a config file, or entirely programmatically, without ever including radcli.h.

Typedef Documentation

radcli_ctx

typedef struct rc_conf radcli_ctx

Definition at line 80 of file radcli2.h.

Enumeration Type Documentation

radcli_ctx_flags

enum radcli_ctx_flags

Flags for radcli_ctx_new() and radcli_ctx_read_config().

A bitwise OR of these is passed as the flags parameter; 0 is the common case.

Enumerator
RADCLI_CTX_NO_BUILTIN_DICT	Skip loading the built-in RFC 2865/2866/2869 dictionary.

Definition at line 104 of file radcli2.h.

radcli_opt_id

enum radcli_opt_id

Recognised configuration option identifiers.

Generated from the same X()-macro list (RC_OPTION_TABLE, radcli-defs.h) that drives radcli.h's string-based rc_add_config()/rc_read_config() grammar, so the two APIs can never recognise a different set of option names by accident. Each value here shares its ordinal position with the corresponding legacy rc_option_id, which is how radcli_ctx_set_opt_str()/_set_opt_int() reach the same underlying storage rc_add_config() does.

Definition at line 92 of file radcli2.h.

radcli_secret_target

enum radcli_secret_target

Which server(s) a radcli_ctx_set_secret() call applies to.

A bitwise OR of these is passed as radcli_ctx_set_secret()'s target_mask, so a deployment where the authserver and acctserver share one secret – the common case – can set it in a single call rather than being forced to call radcli_ctx_set_secret() twice with the same value.

Enumerator
RADCLI_SECRET_AUTH	Applies to the configured authserver (Access-Request).
RADCLI_SECRET_ACCT	Applies to the configured acctserver (Accounting-Request).

Definition at line 134 of file radcli2.h.

Function Documentation

radcli_ctx_apply()

int radcli_ctx_apply

(

radcli_ctx *

ctx

)

Validate the options set so far and initialise the transport.

Call once, after all radcli_ctx_set_opt_str()/_set_opt_int() calls for ctx have been made, to activate the configuration – ctx is not usable for a request before this succeeds. radcli_ctx_read_config() calls this internally; do not call it again on a context obtained that way.

Parameters

ctx	a context configured via radcli_ctx_set_opt_str()/_set_opt_int().

Returns

0 on success, -1 on failure (e.g. no authserver configured, or an invalid radius_timeout/radius_retries).

Definition at line 164 of file config2.c.

radcli_ctx_free()

void radcli_ctx_free

(

radcli_ctx *

ctx

)

Release a context.

Parameters

ctx	a context from radcli_ctx_new() or radcli_ctx_read_config(); NULL is accepted and ignored.

Examples

radexample-async-dae.c, and radexample.c.

Definition at line 173 of file config2.c.

radcli_ctx_get_opt_int()

int radcli_ctx_get_opt_int	(	const radcli_ctx *	ctx,
		radcli_opt_id	opt,
		long *	out )

Read back an integer-typed configuration option.

Parameters

ctx	a context from radcli_ctx_new() or radcli_ctx_read_config().
opt	the option to read; MUST be RADCLI_OPT_TYPE_INT in RC_OPTION_TABLE (e.g. #RADCLI_OPT_RADIUS_TIMEOUT, #RADCLI_OPT_RADIUS_RETRIES).
out	set to the option's value on success; unchanged on failure.

Returns

0 on success, -1 on failure (NULL ctx or out, opt out of range, opt not RADCLI_OPT_TYPE_INT, or opt unset).

Definition at line 320 of file config2.c.

radcli_ctx_get_opt_str()

const char * radcli_ctx_get_opt_str	(	const radcli_ctx *	ctx,
		radcli_opt_id	opt )

Read back a string-typed configuration option.

Unlike radcli_ctx_set_opt_str(), only valid for an RADCLI_OPT_TYPE_STR opt – #RADCLI_OPT_AUTHSERVER/#RADCLI_OPT_ACCTSERVER (RADCLI_OPT_TYPE_SRV) store a parsed server list, not a string, so are not readable through this call.

Parameters

ctx	a context from radcli_ctx_new() or radcli_ctx_read_config().
opt	the option to read; MUST be RADCLI_OPT_TYPE_STR in RC_OPTION_TABLE (e.g. #RADCLI_OPT_DEFAULT_REALM, #RADCLI_OPT_DICTIONARY).

Returns

the option's value, or NULL if unset, ctx is NULL, opt is out of range, or opt is not RADCLI_OPT_TYPE_STR.

Definition at line 303 of file config2.c.

radcli_ctx_new()

radcli_ctx * radcli_ctx_new

(

unsigned

flags

)

Create an empty context, ready for radcli_ctx_set_opt_str()/ _set_opt_int() and radcli_ctx_apply() – the fully programmatic ("backup") way to configure radcli without a config file on disk.

Allocates a context with no server, secret, or transport configured yet – radcli_ctx_apply() must succeed before it is usable for a request. Also loads the built-in RFC 2865/2866/2869 dictionary, the same one radcli_ctx_read_config() always loads, unless RADCLI_CTX_NO_BUILTIN_DICT is set in flags – so radcli_dict_lookup_num() is non-NULL for well-known attributes right away, without a separate radcli_ctx_read_dictionary() call.

Parameters

flags

a bitwise OR of radcli_ctx_flags, or 0 for the common case.

Returns

the new context, or NULL on allocation failure, an unknown flags bit, or a failure loading the built-in dictionary.

Definition at line 65 of file config2.c.

radcli_ctx_read_config()

radcli_ctx * radcli_ctx_read_config	(	const char *	filename,
		unsigned	flags )

Create a context by parsing a config file – the main, recommended way to configure radcli.

Parses filename, validates every option, initialises the transport (including the TLS/DTLS handshake for TLS/DTLS transports), and loads the built-in RFC 2865/2866/2869 dictionary plus the file's own dictionary= option, if set – radcli_ctx_read_dictionary() need not be called separately for the common case, unless RADCLI_CTX_NO_BUILTIN_DICT is set in flags. Uses the same file format and recognised options as radcli.h's rc_read_config(), so an existing radiusclient.conf written for the legacy API loads unchanged.

Parameters

filename	path to the configuration file.
flags	a bitwise OR of radcli_ctx_flags, or 0 for the common case.

Returns

the new context, or NULL on failure (missing/unreadable file, invalid option, an unknown flags bit, or transport initialisation failure).

Examples

radexample-async-dae.c, and radexample.c.

Definition at line 108 of file config2.c.

radcli_ctx_read_dictionary()

int radcli_ctx_read_dictionary	(	radcli_ctx *	ctx,
		const char *	path )

Load an additional attribute dictionary.

Parses path (ATTRIBUTE/VALUE/VENDOR lines, radcli's dictionary grammar) into ctx's dictionary. Not needed for the common case: radcli_ctx_read_config() already loads the file's own dictionary= option. Useful for the programmatic ("backup") construction path, or to load more than one supplemental dictionary.

Parameters

ctx	a context from radcli_ctx_new() or radcli_ctx_read_config().
path	path to the dictionary file.

Returns

0 on success, -1 on failure (unreadable file, or a parse error – including a conflicting redefinition of an already-loaded attribute).

Definition at line 129 of file config2.c.

radcli_ctx_read_dictionary_from_buffer()

int radcli_ctx_read_dictionary_from_buffer	(	radcli_ctx *	ctx,
		const char *	buf,
		size_t	size )

Load an additional attribute dictionary from an in-memory buffer.

The from-buffer counterpart to radcli_ctx_read_dictionary(), for a caller that has dictionary text already in memory rather than in a file (e.g. a small, program-defined supplemental dictionary) – added so a radcli2.h-only caller is not forced to reach into radcli.h's rc_read_dictionary_from_buffer() for this one operation.

Parameters

ctx	a context from radcli_ctx_new() or radcli_ctx_read_config().
buf	the dictionary text.
size	buf's length in bytes.

Returns

0 on success, -1 on failure (a parse error, including a conflicting redefinition of an already-loaded attribute).

Definition at line 148 of file config2.c.

radcli_ctx_set_opt_int()

int radcli_ctx_set_opt_int	(	radcli_ctx *	ctx,
		radcli_opt_id	opt,
		long	val )

Set an integer-typed configuration option.

Parameters

ctx	a context from radcli_ctx_new().
opt	the option to set; MUST be RADCLI_OPT_TYPE_INT in RC_OPTION_TABLE (e.g. #RADCLI_OPT_RADIUS_TIMEOUT, #RADCLI_OPT_RADIUS_RETRIES).
val	the value.

Returns

0 on success, -1 on failure (as radcli_ctx_set_opt_str()).

Definition at line 274 of file config2.c.

radcli_ctx_set_opt_str()

int radcli_ctx_set_opt_str	(	radcli_ctx *	ctx,
		radcli_opt_id	opt,
		const char *	val )

Set a string-typed configuration option.

Stores val for opt on ctx, validating it against opt's own grammar (e.g. #RADCLI_OPT_AUTHSERVER accepts the "host[:port[:secret]]" form a config file's authserver line does). Valid for any radcli_opt_id whose RC_OPTION_TABLE type is RADCLI_OPT_TYPE_STR or RADCLI_OPT_TYPE_SRV; use radcli_ctx_set_opt_int() for an RADCLI_OPT_TYPE_INT option instead.

Parameters

ctx	a context from radcli_ctx_new() or radcli_ctx_read_config().
opt	the option to set.
val	the value; for #RADCLI_OPT_AUTHSERVER/#RADCLI_OPT_ACCTSERVER, the shared secret is better set with radcli_ctx_set_secret() than embedded in this string.

Returns

0 on success, -1 on failure (NULL ctx, opt out of range, wrong type for opt, or an invalid val for opt's grammar).

Definition at line 242 of file config2.c.

radcli_ctx_set_secret()

int radcli_ctx_set_secret	(	radcli_ctx *	ctx,
		unsigned	target_mask,
		const char *	secret )

Set the RADIUS shared secret for the configured authserver and/or acctserver.

The equivalent, for the new API, of embedding a secret in the host:port:secret form of #RADCLI_OPT_AUTHSERVER/#RADCLI_OPT_ACCTSERVER's value – but as a distinct call instead of a delimited string, and able to set both server types' secret at once when they share one (the usual case) via RADCLI_SECRET_AUTH | RADCLI_SECRET_ACCT, without embedding anything in the authserver/acctserver value at all.

Parameters

ctx	a context whose #RADCLI_OPT_AUTHSERVER and/or #RADCLI_OPT_ACCTSERVER (per target_mask) is already set – via radcli_ctx_set_opt_str() or radcli_ctx_read_config() – before this call.
target_mask	a bitwise OR of one or both radcli_secret_target values.
secret	the shared secret, as a NUL-terminated string.

Returns

0 on success, -1 on failure (NULL ctx/secret, target_mask empty or carrying an unrecognised bit, or the corresponding server not yet configured).

Definition at line 378 of file config2.c.

radcli_ctx_set_tls_psk()

int radcli_ctx_set_tls_psk	(	radcli_ctx *	ctx,
		const void *	identity,
		size_t	identity_len,
		const uint8_t *	key,
		size_t	keylen )

Set the RFC 6614/7360 TLS-transport Pre-Shared Key credentials for the configured authserver.

The equivalent, for the new API, of the legacy authserver host:port:psk@username@hexkey inline form – but with identity and key as independent byte buffers instead of a delimited string, so a username containing @ cannot be misparsed (the legacy form splits on the first @ after the psk@ prefix) and the key never needs to be hex-encoded by the caller. Only meaningful when #RADCLI_OPT_SERV_TYPE is tls or dtls; takes priority over any psk@username@hexkey embedded in #RADCLI_OPT_AUTHSERVER's value, should both somehow be set.

Parameters

ctx	a context, before radcli_ctx_apply().
identity	the PSK identity; GnuTLS treats this as a NUL-terminated string once passed on, so an identity containing an embedded NUL byte is truncated there – a GnuTLS API constraint, not an ambiguity this function introduces.
identity_len	identity's length in bytes.
key	the raw PSK key bytes (not hex-encoded text).
keylen	key's length in bytes.

Returns

0 on success, -1 on failure (NULL ctx/identity/key, or keylen 0).

Definition at line 417 of file config2.c.