Improved Doxygen documentation for RADIUS client code

This commit is contained in:
Jouni Malinen 2009-11-28 23:00:29 +02:00
parent 8d5aca73bb
commit df1e24aceb
2 changed files with 363 additions and 49 deletions

View file

@ -1,6 +1,6 @@
/* /*
* hostapd / RADIUS client * RADIUS client
* Copyright (c) 2002-2005, Jouni Malinen <j@w1.fi> * Copyright (c) 2002-2009, Jouni Malinen <j@w1.fi>
* *
* This program is free software; you can redistribute it and/or modify * This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License version 2 as * it under the terms of the GNU General Public License version 2 as
@ -20,18 +20,50 @@
#include "eloop.h" #include "eloop.h"
/* Defaults for RADIUS retransmit values (exponential backoff) */ /* Defaults for RADIUS retransmit values (exponential backoff) */
#define RADIUS_CLIENT_FIRST_WAIT 3 /* seconds */
#define RADIUS_CLIENT_MAX_WAIT 120 /* seconds */ /**
#define RADIUS_CLIENT_MAX_RETRIES 10 /* maximum number of retransmit attempts * RADIUS_CLIENT_FIRST_WAIT - RADIUS client timeout for first retry in seconds
* before entry is removed from retransmit */
* list */ #define RADIUS_CLIENT_FIRST_WAIT 3
#define RADIUS_CLIENT_MAX_ENTRIES 30 /* maximum number of entries in retransmit
* list (oldest will be removed, if this /**
* limit is exceeded) */ * RADIUS_CLIENT_MAX_WAIT - RADIUS client maximum retry timeout in seconds
#define RADIUS_CLIENT_NUM_FAILOVER 4 /* try to change RADIUS server after this */
* many failed retry attempts */ #define RADIUS_CLIENT_MAX_WAIT 120
/**
* RADIUS_CLIENT_MAX_RETRIES - RADIUS client maximum retries
*
* Maximum number of retransmit attempts before the entry is removed from
* retransmit list.
*/
#define RADIUS_CLIENT_MAX_RETRIES 10
/**
* RADIUS_CLIENT_MAX_ENTRIES - RADIUS client maximum pending messages
*
* Maximum number of entries in retransmit list (oldest entries will be
* removed, if this limit is exceeded).
*/
#define RADIUS_CLIENT_MAX_ENTRIES 30
/**
* RADIUS_CLIENT_NUM_FAILOVER - RADIUS client failover point
*
* The number of failed retry attempts after which the RADIUS server will be
* changed (if one of more backup servers are configured).
*/
#define RADIUS_CLIENT_NUM_FAILOVER 4
/**
* struct radius_rx_handler - RADIUS client RX handler
*
* This data structure is used internally inside the RADIUS client module to
* store registered RX handlers. These handlers are registered by calls to
* radius_client_register() and unregistered when the RADIUS client is
* deinitizlized with a call to radius_client_deinit().
*/
struct radius_rx_handler { struct radius_rx_handler {
RadiusRxResult (*handler)(struct radius_msg *msg, RadiusRxResult (*handler)(struct radius_msg *msg,
struct radius_msg *req, struct radius_msg *req,
@ -42,7 +74,12 @@ struct radius_rx_handler {
}; };
/* RADIUS message retransmit list */ /**
* struct radius_msg_list - RADIUS client message retransmit list
*
* This data structure is used internally inside the RADIUS client module to
* store pending RADIUS requests that may still need to be retransmitted.
*/
struct radius_msg_list { struct radius_msg_list {
u8 addr[ETH_ALEN]; /* STA/client address; used to find RADIUS messages u8 addr[ETH_ALEN]; /* STA/client address; used to find RADIUS messages
* for the same STA. */ * for the same STA. */
@ -63,16 +100,47 @@ struct radius_msg_list {
}; };
/**
* struct radius_client_data - Internal RADIUS client data
*
* This data structure is used internally inside the RADIUS client module.
* External users allocate this by calling radius_client_init() and free it by
* calling radius_client_deinit(). The pointer to this opaque data is used in
* calls to other functions as an identifier for the RADIUS client instance.
*/
struct radius_client_data { struct radius_client_data {
/**
* ctx - Context pointer for hostapd_logger() callbacks
*/
void *ctx; void *ctx;
/**
* conf - RADIUS client configuration (list of RADIUS servers to use)
*/
struct hostapd_radius_servers *conf; struct hostapd_radius_servers *conf;
int auth_serv_sock; /* socket for authentication RADIUS messages */ /**
int acct_serv_sock; /* socket for accounting RADIUS messages */ * auth_serv_sock - Socket for authentication RADIUS messages
*/
int auth_serv_sock;
/**
* acct_serv_sock - Socket for accounting RADIUS messages
*/
int acct_serv_sock;
int auth_serv_sock6; int auth_serv_sock6;
int acct_serv_sock6; int acct_serv_sock6;
int auth_sock; /* currently used socket */
int acct_sock; /* currently used socket */ /**
* auth_sock - Current used socket for RADIUS authentication server
*/
int auth_sock;
/**
* acct_sock - Current used socket for RADIUS accounting server
*/
int acct_sock;
struct radius_rx_handler *auth_handlers; struct radius_rx_handler *auth_handlers;
size_t num_auth_handlers; size_t num_auth_handlers;
@ -103,6 +171,22 @@ static void radius_client_msg_free(struct radius_msg_list *req)
} }
/**
* radius_client_register - Register a RADIUS client RX handler
* @radius: RADIUS client context from radius_client_init()
* @msg_type: RADIUS client type (RADIUS_AUTH or RADIUS_ACCT)
* @handler: Handler for received RADIUS messages
* @data: Context pointer for handler callbacks
* Returns: 0 on success, -1 on failure
*
* This function is used to register a handler for processing received RADIUS
* authentication and accounting messages. The handler() callback function will
* be called whenever a RADIUS message is received from the active server.
*
* There can be multiple registered RADIUS message handlers. The handlers will
* be called in order until one of them indicates that it has processed or
* queued the message.
*/
int radius_client_register(struct radius_client_data *radius, int radius_client_register(struct radius_client_data *radius,
RadiusType msg_type, RadiusType msg_type,
RadiusRxResult (*handler)(struct radius_msg *msg, RadiusRxResult (*handler)(struct radius_msg *msg,
@ -437,6 +521,28 @@ static void radius_client_list_del(struct radius_client_data *radius,
} }
/**
* radius_client_send - Send a RADIUS request
* @radius: RADIUS client context from radius_client_init()
* @msg: RADIUS message to be sent
* @msg_type: Message type (RADIUS_AUTH, RADIUS_ACCT, RADIUS_ACCT_INTERIM)
* @addr: MAC address of the device related to this message or %NULL
* Returns: 0 on success, -1 on failure
*
* This function is used to transmit a RADIUS authentication (RADIUS_AUTH) or
* accounting request (RADIUS_ACCT or RADIUS_ACCT_INTERIM). The only difference
* between accounting and interim accounting messages is that the interim
* message will override any pending interim accounting updates while a new
* accounting message does not remove any pending messages.
*
* The message is added on the retransmission queue and will be retransmitted
* automatically until a response is received or maximum number of retries
* (RADIUS_CLIENT_MAX_RETRIES) is reached.
*
* The related device MAC address can be used to identify pending messages that
* can be removed with radius_client_flush_auth() or with interim accounting
* updates.
*/
int radius_client_send(struct radius_client_data *radius, int radius_client_send(struct radius_client_data *radius,
struct radius_msg *msg, RadiusType msg_type, struct radius_msg *msg, RadiusType msg_type,
const u8 *addr) const u8 *addr)
@ -646,6 +752,14 @@ static void radius_client_receive(int sock, void *eloop_ctx, void *sock_ctx)
} }
/**
* radius_client_get_id - Get an identifier for a new RADIUS message
* @radius: RADIUS client context from radius_client_init()
* Returns: Allocated identifier
*
* This function is used to fetch a unique (among pending requests) identifier
* for a new RADIUS message.
*/
u8 radius_client_get_id(struct radius_client_data *radius) u8 radius_client_get_id(struct radius_client_data *radius)
{ {
struct radius_msg_list *entry, *prev, *_remove; struct radius_msg_list *entry, *prev, *_remove;
@ -681,6 +795,11 @@ u8 radius_client_get_id(struct radius_client_data *radius)
} }
/**
* radius_client_flush - Flush all pending RADIUS client messages
* @radius: RADIUS client context from radius_client_init()
* @only_auth: Whether only authentication messages are removed
*/
void radius_client_flush(struct radius_client_data *radius, int only_auth) void radius_client_flush(struct radius_client_data *radius, int only_auth)
{ {
struct radius_msg_list *entry, *prev, *tmp; struct radius_msg_list *entry, *prev, *tmp;
@ -1037,6 +1156,16 @@ static int radius_client_init_acct(struct radius_client_data *radius)
} }
/**
* radius_client_init - Initialize RADIUS client
* @ctx: Callback context to be used in hostapd_logger() calls
* @conf: RADIUS client configuration (RADIUS servers)
* Returns: Pointer to private RADIUS client context or %NULL on failure
*
* The caller is responsible for keeping the configuration data available for
* the lifetime of the RADIUS client, i.e., until radius_client_deinit() is
* called for the returned context pointer.
*/
struct radius_client_data * struct radius_client_data *
radius_client_init(void *ctx, struct hostapd_radius_servers *conf) radius_client_init(void *ctx, struct hostapd_radius_servers *conf)
{ {
@ -1071,6 +1200,10 @@ radius_client_init(void *ctx, struct hostapd_radius_servers *conf)
} }
/**
* radius_client_deinit - Deinitialize RADIUS client
* @radius: RADIUS client context from radius_client_init()
*/
void radius_client_deinit(struct radius_client_data *radius) void radius_client_deinit(struct radius_client_data *radius)
{ {
if (!radius) if (!radius)
@ -1090,7 +1223,18 @@ void radius_client_deinit(struct radius_client_data *radius)
} }
void radius_client_flush_auth(struct radius_client_data *radius, u8 *addr) /**
* radius_client_flush_auth - Flush pending RADIUS messages for an address
* @radius: RADIUS client context from radius_client_init()
* @addr: MAC address of the related device
*
* This function can be used to remove pending RADIUS authentication messages
* that are related to a specific device. The addr parameter is matched with
* the one used in radius_client_send() call that was used to transmit the
* authentication request.
*/
void radius_client_flush_auth(struct radius_client_data *radius,
const u8 *addr)
{ {
struct radius_msg_list *entry, *prev, *tmp; struct radius_msg_list *entry, *prev, *tmp;
@ -1218,6 +1362,13 @@ static int radius_client_dump_acct_server(char *buf, size_t buflen,
} }
/**
* radius_client_get_mib - Get RADIUS client MIB information
* @radius: RADIUS client context from radius_client_init()
* @buf: Buffer for returning MIB data in text format
* @buflen: Maximum buf length in octets
* Returns: Number of octets written into the buffer
*/
int radius_client_get_mib(struct radius_client_data *radius, char *buf, int radius_client_get_mib(struct radius_client_data *radius, char *buf,
size_t buflen) size_t buflen)
{ {
@ -1269,6 +1420,23 @@ static int radius_servers_diff(struct hostapd_radius_server *nserv,
} }
/**
* radius_client_reconfig - Reconfigure RADIUS client
* @old: RADIUS client context from radius_client_init()
* @ctx: Callback context to be used in hostapd_logger() calls
* @oldconf: Old RADIUS client configuration (RADIUS servers)
* @newconf: New RADIUS client configuration (RADIUS servers)
* Returns: Pointer to private RADIUS client context or %NULL on failure
*
* This function can be used to conditionally change RADIUS client
* configuration. If newconf differs from oldconf, the old RADIUS client
* context is deinitialized and new one is allocated. If there is no change in
* the configuration, the old RADIUS client context will be returned.
*
* The caller is responsible for keeping the new configuration data available
* for the lifetime of the RADIUS client, i.e., until radius_client_deinit() is
* called for the returned context pointer.
*/
struct radius_client_data * struct radius_client_data *
radius_client_reconfig(struct radius_client_data *old, void *ctx, radius_client_reconfig(struct radius_client_data *old, void *ctx,
struct hostapd_radius_servers *oldconf, struct hostapd_radius_servers *oldconf,

View file

@ -1,6 +1,6 @@
/* /*
* hostapd / RADIUS client * RADIUS client
* Copyright (c) 2002-2005, Jouni Malinen <j@w1.fi> * Copyright (c) 2002-2009, Jouni Malinen <j@w1.fi>
* *
* This program is free software; you can redistribute it and/or modify * This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License version 2 as * it under the terms of the GNU General Public License version 2 as
@ -19,59 +19,204 @@
struct radius_msg; struct radius_msg;
/**
* struct hostapd_radius_server - RADIUS server information for RADIUS client
*
* This structure contains information about a RADIUS server. The values are
* mainly for MIB information. The MIB variable prefix (radiusAuth or
* radiusAcc) depends on whether this is an authentication or accounting
* server.
*
* radiusAuthClientPendingRequests (or radiusAccClientPendingRequests) is the
* length of hapd->radius->msgs for matching msg_type.
*/
struct hostapd_radius_server { struct hostapd_radius_server {
/* MIB prefix for shared variables: /**
* @ = radiusAuth or radiusAcc depending on the type of the server */ * addr - radiusAuthServerAddress or radiusAccServerAddress
struct hostapd_ip_addr addr; /* @ServerAddress */ */
int port; /* @ClientServerPortNumber */ struct hostapd_ip_addr addr;
/**
* port - radiusAuthClientServerPortNumber or radiusAccClientServerPortNumber
*/
int port;
/**
* shared_secret - Shared secret for authenticating RADIUS messages
*/
u8 *shared_secret; u8 *shared_secret;
/**
* shared_secret_len - Length of shared_secret in octets
*/
size_t shared_secret_len; size_t shared_secret_len;
/* Dynamic (not from configuration file) MIB data */ /* Dynamic (not from configuration file) MIB data */
int index; /* @ServerIndex */
int round_trip_time; /* @ClientRoundTripTime; in hundredths of a /**
* second */ * index - radiusAuthServerIndex or radiusAccServerIndex
u32 requests; /* @Client{Access,}Requests */ */
u32 retransmissions; /* @Client{Access,}Retransmissions */ int index;
u32 access_accepts; /* radiusAuthClientAccessAccepts */
u32 access_rejects; /* radiusAuthClientAccessRejects */ /**
u32 access_challenges; /* radiusAuthClientAccessChallenges */ * round_trip_time - radiusAuthClientRoundTripTime or radiusAccClientRoundTripTime
u32 responses; /* radiusAccClientResponses */ * Round-trip time in hundredths of a second.
u32 malformed_responses; /* @ClientMalformed{Access,}Responses */ */
u32 bad_authenticators; /* @ClientBadAuthenticators */ int round_trip_time;
u32 timeouts; /* @ClientTimeouts */
u32 unknown_types; /* @ClientUnknownTypes */ /**
u32 packets_dropped; /* @ClientPacketsDropped */ * requests - radiusAuthClientAccessRequests or radiusAccClientRequests
/* @ClientPendingRequests: length of hapd->radius->msgs for matching */
* msg_type */ u32 requests;
/**
* retransmissions - radiusAuthClientAccessRetransmissions or radiusAccClientRetransmissions
*/
u32 retransmissions;
/**
* access_accepts - radiusAuthClientAccessAccepts
*/
u32 access_accepts;
/**
* access_rejects - radiusAuthClientAccessRejects
*/
u32 access_rejects;
/**
* access_challenges - radiusAuthClientAccessChallenges
*/
u32 access_challenges;
/**
* responses - radiusAccClientResponses
*/
u32 responses;
/**
* malformed_responses - radiusAuthClientMalformedAccessResponses or radiusAccClientMalformedResponses
*/
u32 malformed_responses;
/**
* bad_authenticators - radiusAuthClientBadAuthenticators or radiusAccClientBadAuthenticators
*/
u32 bad_authenticators;
/**
* timeouts - radiusAuthClientTimeouts or radiusAccClientTimeouts
*/
u32 timeouts;
/**
* unknown_types - radiusAuthClientUnknownTypes or radiusAccClientUnknownTypes
*/
u32 unknown_types;
/**
* packets_dropped - radiusAuthClientPacketsDropped or radiusAccClientPacketsDropped
*/
u32 packets_dropped;
}; };
/**
* struct hostapd_radius_servers - RADIUS servers for RADIUS client
*/
struct hostapd_radius_servers { struct hostapd_radius_servers {
/* RADIUS Authentication and Accounting servers in priority order */ /**
struct hostapd_radius_server *auth_servers, *auth_server; * auth_servers - RADIUS Authentication servers in priority order
*/
struct hostapd_radius_server *auth_servers;
/**
* num_auth_servers - Number of auth_servers entries
*/
int num_auth_servers; int num_auth_servers;
struct hostapd_radius_server *acct_servers, *acct_server;
/**
* auth_server - The current Authentication server
*/
struct hostapd_radius_server *auth_server;
/**
* acct_servers - RADIUS Accounting servers in priority order
*/
struct hostapd_radius_server *acct_servers;
/**
* num_acct_servers - Number of acct_servers entries
*/
int num_acct_servers; int num_acct_servers;
/**
* acct_server - The current Accounting server
*/
struct hostapd_radius_server *acct_server;
/**
* retry_primary_interval - Retry interval for trying primary server
*
* This specifies a retry interval in sexconds for trying to return to
* the primary RADIUS server. RADIUS client code will automatically try
* to use the next server when the current server is not replying to
* requests. If this interval is set (non-zero), the primary server
* will be retried after the specified number of seconds has passed
* even if the current used secondary server is still working.
*/
int retry_primary_interval; int retry_primary_interval;
/**
* acct_interim_interval - Interim accounting update interval
*
* This parameter is not used inside RADIUS client code.
*/
int acct_interim_interval; int acct_interim_interval;
/**
* msg_dumps - Whether RADIUS message details are shown in stdout
*/
int msg_dumps; int msg_dumps;
/**
* client_addr - Client (local) address to use if force_client_addr
*/
struct hostapd_ip_addr client_addr; struct hostapd_ip_addr client_addr;
/**
* force_client_addr - Whether to force client (local) address
*/
int force_client_addr; int force_client_addr;
}; };
/**
* RadiusType - RADIUS server type for RADIUS client
*/
typedef enum { typedef enum {
/**
* RADIUS authentication
*/
RADIUS_AUTH, RADIUS_AUTH,
/**
* RADIUS_ACCT - RADIUS accounting
*/
RADIUS_ACCT, RADIUS_ACCT,
RADIUS_ACCT_INTERIM /* used only with radius_client_send(); just like
* RADIUS_ACCT, but removes any pending interim /**
* RADIUS Accounting packages for the same STA * RADIUS_ACCT_INTERIM - RADIUS interim accounting message
* before sending the new interim update */ *
* Used only with radius_client_send(). This behaves just like
* RADIUS_ACCT, but removes any pending interim RADIUS Accounting
* messages for the same STA before sending the new interim update.
*/
RADIUS_ACCT_INTERIM
} RadiusType; } RadiusType;
/**
* RadiusRxResult - RADIUS client RX handler result
*/
typedef enum { typedef enum {
RADIUS_RX_PROCESSED, RADIUS_RX_PROCESSED,
RADIUS_RX_QUEUED, RADIUS_RX_QUEUED,
@ -110,7 +255,7 @@ static inline void radius_client_deinit(struct radius_client_data *radius)
} }
static inline void radius_client_flush_auth(struct radius_client_data *radius, static inline void radius_client_flush_auth(struct radius_client_data *radius,
u8 *addr) const u8 *addr)
{ {
} }
@ -124,7 +269,8 @@ void radius_client_flush(struct radius_client_data *radius, int only_auth);
struct radius_client_data * struct radius_client_data *
radius_client_init(void *ctx, struct hostapd_radius_servers *conf); radius_client_init(void *ctx, struct hostapd_radius_servers *conf);
void radius_client_deinit(struct radius_client_data *radius); void radius_client_deinit(struct radius_client_data *radius);
void radius_client_flush_auth(struct radius_client_data *radius, u8 *addr); void radius_client_flush_auth(struct radius_client_data *radius,
const u8 *addr);
int radius_client_get_mib(struct radius_client_data *radius, char *buf, int radius_client_get_mib(struct radius_client_data *radius, char *buf,
size_t buflen); size_t buflen);
#endif /* CONFIG_NO_RADIUS */ #endif /* CONFIG_NO_RADIUS */