DGNum/hostapd
6
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions

Improved Doxygen documentation for RADIUS client code

Browse source
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
Show stats Download patch file Download diff file Expand all files Collapse all files

204
src/radius/radius_client.c
View file

@ -1,6 +1,6 @@
/*
* hostapd / RADIUS client
* Copyright (c) 2002-2005, Jouni Malinen <j@w1.fi>
* RADIUS client
* Copyright (c) 2002-2009, Jouni Malinen <j@w1.fi>
*
* 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
@ -20,18 +20,50 @@
#include "eloop.h"
/* 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
* before entry is removed from retransmit
* list */
#define RADIUS_CLIENT_MAX_ENTRIES 30 /* maximum number of entries in retransmit
* list (oldest will be removed, if this
* limit is exceeded) */
#define RADIUS_CLIENT_NUM_FAILOVER 4 /* try to change RADIUS server after this
* many failed retry attempts */
/**
* RADIUS_CLIENT_FIRST_WAIT - RADIUS client timeout for first retry in seconds
*/
#define RADIUS_CLIENT_FIRST_WAIT 3
/**
* RADIUS_CLIENT_MAX_WAIT - RADIUS client maximum retry timeout in seconds
*/
#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 {
RadiusRxResult (*handler)(struct radius_msg *msg,
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 {
u8 addr[ETH_ALEN]; /* STA/client address; used to find RADIUS messages
* 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 {
/**
* ctx - Context pointer for hostapd_logger() callbacks
*/
void *ctx;
/**
* conf - RADIUS client configuration (list of RADIUS servers to use)
*/
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 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;
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,
RadiusType msg_type,
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,
struct radius_msg *msg, RadiusType msg_type,
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)
{
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)
{
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 *
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)
{
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;
@ -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,
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 *
radius_client_reconfig(struct radius_client_data *old, void *ctx,
struct hostapd_radius_servers *oldconf,

208
src/radius/radius_client.h
View file

@ -1,6 +1,6 @@
/*
* hostapd / RADIUS client
* Copyright (c) 2002-2005, Jouni Malinen <j@w1.fi>
* RADIUS client
* Copyright (c) 2002-2009, Jouni Malinen <j@w1.fi>
*
* 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
@ -19,59 +19,204 @@
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 {
/* MIB prefix for shared variables:
* @ = radiusAuth or radiusAcc depending on the type of the server */
struct hostapd_ip_addr addr; /* @ServerAddress */
int port; /* @ClientServerPortNumber */
/**
* addr - radiusAuthServerAddress or radiusAccServerAddress
*/
struct hostapd_ip_addr addr;
/**
* port - radiusAuthClientServerPortNumber or radiusAccClientServerPortNumber
*/
int port;
/**
* shared_secret - Shared secret for authenticating RADIUS messages
*/
u8 *shared_secret;
/**
* shared_secret_len - Length of shared_secret in octets
*/
size_t shared_secret_len;
/* Dynamic (not from configuration file) MIB data */
int index; /* @ServerIndex */
int round_trip_time; /* @ClientRoundTripTime; in hundredths of a
* second */
u32 requests; /* @Client{Access,}Requests */
u32 retransmissions; /* @Client{Access,}Retransmissions */
u32 access_accepts; /* radiusAuthClientAccessAccepts */
u32 access_rejects; /* radiusAuthClientAccessRejects */
u32 access_challenges; /* radiusAuthClientAccessChallenges */
u32 responses; /* radiusAccClientResponses */
u32 malformed_responses; /* @ClientMalformed{Access,}Responses */
u32 bad_authenticators; /* @ClientBadAuthenticators */
u32 timeouts; /* @ClientTimeouts */
u32 unknown_types; /* @ClientUnknownTypes */
u32 packets_dropped; /* @ClientPacketsDropped */
/* @ClientPendingRequests: length of hapd->radius->msgs for matching
* msg_type */
/**
* index - radiusAuthServerIndex or radiusAccServerIndex
*/
int index;
/**
* round_trip_time - radiusAuthClientRoundTripTime or radiusAccClientRoundTripTime
* Round-trip time in hundredths of a second.
*/
int round_trip_time;
/**
* requests - radiusAuthClientAccessRequests or radiusAccClientRequests
*/
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 {
/* 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;
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;
/**
* 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;
/**
* acct_interim_interval - Interim accounting update interval
*
* This parameter is not used inside RADIUS client code.
*/
int acct_interim_interval;
/**
* msg_dumps - Whether RADIUS message details are shown in stdout
*/
int msg_dumps;
/**
* client_addr - Client (local) address to use if force_client_addr
*/
struct hostapd_ip_addr client_addr;
/**
* force_client_addr - Whether to force client (local) address
*/
int force_client_addr;
};
/**
* RadiusType - RADIUS server type for RADIUS client
*/
typedef enum {
/**
* RADIUS authentication
*/
RADIUS_AUTH,
/**
* RADIUS_ACCT - RADIUS accounting
*/
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
* before sending the new interim update */
/**
* RADIUS_ACCT_INTERIM - RADIUS interim accounting message
*
* 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;
/**
* RadiusRxResult - RADIUS client RX handler result
*/
typedef enum {
RADIUS_RX_PROCESSED,
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,
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 *
radius_client_init(void *ctx, struct hostapd_radius_servers *conf);
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,
size_t buflen);
#endif /* CONFIG_NO_RADIUS */