From 362bd35f2d3506a67a8d71e802564f22ca7d1ef4 Mon Sep 17 00:00:00 2001 From: Jouni Malinen Date: Wed, 2 Dec 2009 21:29:32 +0200 Subject: [PATCH] Add more Doxygen documentation for RADIUS server implementation --- hostapd/hostapd.conf | 4 +- src/radius/radius_server.c | 212 ++++++++++++++++++++++++++++++++++++- src/radius/radius_server.h | 154 ++++++++++++++++++++++++++- 3 files changed, 364 insertions(+), 6 deletions(-) diff --git a/hostapd/hostapd.conf b/hostapd/hostapd.conf index 796c0d6f1..aeaad2e7e 100644 --- a/hostapd/hostapd.conf +++ b/hostapd/hostapd.conf @@ -526,9 +526,9 @@ eap_server=0 # EAP-FAST authority identity (A-ID) # A-ID indicates the identity of the authority that issues PACs. The A-ID # should be unique across all issuing servers. In theory, this is a variable -# length field, but due to some existing implementations required A-ID to be +# length field, but due to some existing implementations requiring A-ID to be # 16 octets in length, it is strongly recommended to use that length for the -# field to provided interoperability with deployed peer implementation. This +# field to provid interoperability with deployed peer implementations. This # field is configured in hex format. #eap_fast_a_id=101112131415161718191a1b1c1d1e1f diff --git a/src/radius/radius_server.c b/src/radius/radius_server.c index 7c8c525f5..635143f04 100644 --- a/src/radius/radius_server.c +++ b/src/radius/radius_server.c @@ -1,6 +1,6 @@ /* - * hostapd / RADIUS authentication server - * Copyright (c) 2005-2008, Jouni Malinen + * RADIUS authentication server + * Copyright (c) 2005-2009, Jouni Malinen * * 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 @@ -21,8 +21,19 @@ #include "eap_server/eap.h" #include "radius_server.h" +/** + * RADIUS_SESSION_TIMEOUT - Session timeout in seconds + */ #define RADIUS_SESSION_TIMEOUT 60 + +/** + * RADIUS_MAX_SESSION - Maximum number of active sessions + */ #define RADIUS_MAX_SESSION 100 + +/** + * RADIUS_MAX_MSG_LEN - Maximum message length for incoming RADIUS messages + */ #define RADIUS_MAX_MSG_LEN 3000 static struct eapol_callbacks radius_server_eapol_cb; @@ -30,6 +41,9 @@ static struct eapol_callbacks radius_server_eapol_cb; struct radius_client; struct radius_server_data; +/** + * struct radius_server_counters - RADIUS server statistics counters + */ struct radius_server_counters { u32 access_requests; u32 invalid_requests; @@ -43,6 +57,9 @@ struct radius_server_counters { u32 unknown_types; }; +/** + * struct radius_session - Internal RADIUS server data for a session + */ struct radius_session { struct radius_session *next; struct radius_client *client; @@ -61,6 +78,9 @@ struct radius_session { u8 last_authenticator[16]; }; +/** + * struct radius_client - Internal RADIUS server data for a client + */ struct radius_client { struct radius_client *next; struct in_addr addr; @@ -75,30 +95,190 @@ struct radius_client { struct radius_server_counters counters; }; +/** + * struct radius_server_data - Internal RADIUS server data + */ struct radius_server_data { + /** + * auth_sock - Socket for RADIUS authentication messages + */ int auth_sock; + + /** + * clients - List of authorized RADIUS clients + */ struct radius_client *clients; + + /** + * next_sess_id - Next session identifier + */ unsigned int next_sess_id; + + /** + * conf_ctx - Context pointer for callbacks + * + * This is used as the ctx argument in get_eap_user() calls. + */ void *conf_ctx; + + /** + * num_sess - Number of active sessions + */ int num_sess; + + /** + * eap_sim_db_priv - EAP-SIM/AKA database context + * + * This is passed to the EAP-SIM/AKA server implementation as a + * callback context. + */ void *eap_sim_db_priv; + + /** + * ssl_ctx - TLS context + * + * This is passed to the EAP server implementation as a callback + * context for TLS operations. + */ void *ssl_ctx; + + /** + * pac_opaque_encr_key - PAC-Opaque encryption key for EAP-FAST + * + * This parameter is used to set a key for EAP-FAST to encrypt the + * PAC-Opaque data. It can be set to %NULL if EAP-FAST is not used. If + * set, must point to a 16-octet key. + */ u8 *pac_opaque_encr_key; + + /** + * eap_fast_a_id - EAP-FAST authority identity (A-ID) + * + * If EAP-FAST is not used, this can be set to %NULL. In theory, this + * is a variable length field, but due to some existing implementations + * requiring A-ID to be 16 octets in length, it is recommended to use + * that length for the field to provide interoperability with deployed + * peer implementations. + */ u8 *eap_fast_a_id; + + /** + * eap_fast_a_id_len - Length of eap_fast_a_id buffer in octets + */ size_t eap_fast_a_id_len; + + /** + * eap_fast_a_id_info - EAP-FAST authority identifier information + * + * This A-ID-Info contains a user-friendly name for the A-ID. For + * example, this could be the enterprise and server names in + * human-readable format. This field is encoded as UTF-8. If EAP-FAST + * is not used, this can be set to %NULL. + */ char *eap_fast_a_id_info; + + /** + * eap_fast_prov - EAP-FAST provisioning modes + * + * 0 = provisioning disabled, 1 = only anonymous provisioning allowed, + * 2 = only authenticated provisioning allowed, 3 = both provisioning + * modes allowed. + */ int eap_fast_prov; + + /** + * pac_key_lifetime - EAP-FAST PAC-Key lifetime in seconds + * + * This is the hard limit on how long a provisioned PAC-Key can be + * used. + */ int pac_key_lifetime; + + /** + * pac_key_refresh_time - EAP-FAST PAC-Key refresh time in seconds + * + * This is a soft limit on the PAC-Key. The server will automatically + * generate a new PAC-Key when this number of seconds (or fewer) of the + * lifetime remains. + */ int pac_key_refresh_time; + + /** + * eap_sim_aka_result_ind - EAP-SIM/AKA protected success indication + * + * This controls whether the protected success/failure indication + * (AT_RESULT_IND) is used with EAP-SIM and EAP-AKA. + */ int eap_sim_aka_result_ind; + + /** + * tnc - Trusted Network Connect (TNC) + * + * This controls whether TNC is enabled and will be required before the + * peer is allowed to connect. Note: This is only used with EAP-TTLS + * and EAP-FAST. If any other EAP method is enabled, the peer will be + * allowed to connect without TNC. + */ int tnc; + + /** + * wps - Wi-Fi Protected Setup context + * + * If WPS is used with an external RADIUS server (which is quite + * unlikely configuration), this is used to provide a pointer to WPS + * context data. Normally, this can be set to %NULL. + */ struct wps_context *wps; + + /** + * ipv6 - Whether to enable IPv6 support in the RADIUS server + */ int ipv6; + + /** + * start_time - Timestamp of server start + */ struct os_time start_time; + + /** + * counters - Statistics counters for server operations + * + * These counters are the sum over all clients. + */ struct radius_server_counters counters; + + /** + * get_eap_user - Callback for fetching EAP user information + * @ctx: Context data from conf_ctx + * @identity: User identity + * @identity_len: identity buffer length in octets + * @phase2: Whether this is for Phase 2 identity + * @user: Data structure for filling in the user information + * Returns: 0 on success, -1 on failure + * + * This is used to fetch information from user database. The callback + * will fill in information about allowed EAP methods and the user + * password. The password field will be an allocated copy of the + * password data and RADIUS server will free it after use. + */ int (*get_eap_user)(void *ctx, const u8 *identity, size_t identity_len, int phase2, struct eap_user *user); + + /** + * eap_req_id_text - Optional data for EAP-Request/Identity + * + * This can be used to configure an optional, displayable message that + * will be sent in EAP-Request/Identity. This string can contain an + * ASCII-0 character (nul) to separate network infromation per RFC + * 4284. The actual string length is explicit provided in + * eap_req_id_text_len since nul character will not be used as a string + * terminator. + */ char *eap_req_id_text; + + /** + * eap_req_id_text_len - Length of eap_req_id_text buffer in octets + */ size_t eap_req_id_text_len; }; @@ -1026,6 +1206,15 @@ radius_server_read_clients(const char *client_file, int ipv6) } +/** + * radius_server_init - Initialize RADIUS server + * @conf: Configuration for the RADIUS server + * Returns: Pointer to private RADIUS server context or %NULL on failure + * + * This initializes a RADIUS server instance and returns a context pointer that + * will be used in other calls to the RADIUS server module. The server can be + * deinitialize by calling radius_server_deinit(). + */ struct radius_server_data * radius_server_init(struct radius_server_conf *conf) { @@ -1110,6 +1299,10 @@ radius_server_init(struct radius_server_conf *conf) } +/** + * radius_server_deinit - Deinitialize RADIUS server + * @data: RADIUS server context from radius_server_init() + */ void radius_server_deinit(struct radius_server_data *data) { if (data == NULL) @@ -1130,6 +1323,13 @@ void radius_server_deinit(struct radius_server_data *data) } +/** + * radius_server_get_mib - Get RADIUS server MIB information + * @data: RADIUS server context from radius_server_init() + * @buf: Buffer for returning the MIB data in text format + * @buflen: buf length in octets + * Returns: Number of octets written into buf + */ int radius_server_get_mib(struct radius_server_data *data, char *buf, size_t buflen) { @@ -1269,6 +1469,14 @@ static struct eapol_callbacks radius_server_eapol_cb = }; +/** + * radius_server_eap_pending_cb - Pending EAP data notification + * @data: RADIUS server context from radius_server_init() + * @ctx: Pending EAP context pointer + * + * This function is used to notify EAP server module that a pending operation + * has been completed and processing of the EAP session can proceed. + */ void radius_server_eap_pending_cb(struct radius_server_data *data, void *ctx) { struct radius_client *cli; diff --git a/src/radius/radius_server.h b/src/radius/radius_server.h index d5fb6a1e3..fafa851c3 100644 --- a/src/radius/radius_server.h +++ b/src/radius/radius_server.h @@ -1,6 +1,6 @@ /* - * hostapd / RADIUS authentication server - * Copyright (c) 2005-2007, Jouni Malinen + * RADIUS authentication server + * Copyright (c) 2005-2009, Jouni Malinen * * 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 @@ -18,26 +18,176 @@ struct radius_server_data; struct eap_user; +/** + * struct radius_server_conf - RADIUS server configuration + */ struct radius_server_conf { + /** + * auth_port - UDP port to listen to as an authentication server + */ int auth_port; + + /** + * client_file - RADIUS client configuration file + * + * This file contains the RADIUS clients and the shared secret to be + * used with them in a format where each client is on its own line. The + * first item on the line is the IPv4 or IPv6 address of the client + * with an optional address mask to allow full network to be specified + * (e.g., 192.168.1.2 or 192.168.1.0/24). This is followed by white + * space (space or tabulator) and the shared secret. Lines starting + * with '#' are skipped and can be used as comments. + */ char *client_file; + + /** + * conf_ctx - Context pointer for callbacks + * + * This is used as the ctx argument in get_eap_user() calls. + */ void *conf_ctx; + + /** + * eap_sim_db_priv - EAP-SIM/AKA database context + * + * This is passed to the EAP-SIM/AKA server implementation as a + * callback context. + */ void *eap_sim_db_priv; + + /** + * ssl_ctx - TLS context + * + * This is passed to the EAP server implementation as a callback + * context for TLS operations. + */ void *ssl_ctx; + + /** + * pac_opaque_encr_key - PAC-Opaque encryption key for EAP-FAST + * + * This parameter is used to set a key for EAP-FAST to encrypt the + * PAC-Opaque data. It can be set to %NULL if EAP-FAST is not used. If + * set, must point to a 16-octet key. + */ u8 *pac_opaque_encr_key; + + /** + * eap_fast_a_id - EAP-FAST authority identity (A-ID) + * + * If EAP-FAST is not used, this can be set to %NULL. In theory, this + * is a variable length field, but due to some existing implementations + * requiring A-ID to be 16 octets in length, it is recommended to use + * that length for the field to provide interoperability with deployed + * peer implementations. + */ u8 *eap_fast_a_id; + + /** + * eap_fast_a_id_len - Length of eap_fast_a_id buffer in octets + */ size_t eap_fast_a_id_len; + + /** + * eap_fast_a_id_info - EAP-FAST authority identifier information + * + * This A-ID-Info contains a user-friendly name for the A-ID. For + * example, this could be the enterprise and server names in + * human-readable format. This field is encoded as UTF-8. If EAP-FAST + * is not used, this can be set to %NULL. + */ char *eap_fast_a_id_info; + + /** + * eap_fast_prov - EAP-FAST provisioning modes + * + * 0 = provisioning disabled, 1 = only anonymous provisioning allowed, + * 2 = only authenticated provisioning allowed, 3 = both provisioning + * modes allowed. + */ int eap_fast_prov; + + /** + * pac_key_lifetime - EAP-FAST PAC-Key lifetime in seconds + * + * This is the hard limit on how long a provisioned PAC-Key can be + * used. + */ int pac_key_lifetime; + + /** + * pac_key_refresh_time - EAP-FAST PAC-Key refresh time in seconds + * + * This is a soft limit on the PAC-Key. The server will automatically + * generate a new PAC-Key when this number of seconds (or fewer) of the + * lifetime remains. + */ int pac_key_refresh_time; + + /** + * eap_sim_aka_result_ind - EAP-SIM/AKA protected success indication + * + * This controls whether the protected success/failure indication + * (AT_RESULT_IND) is used with EAP-SIM and EAP-AKA. + */ int eap_sim_aka_result_ind; + + /** + * tnc - Trusted Network Connect (TNC) + * + * This controls whether TNC is enabled and will be required before the + * peer is allowed to connect. Note: This is only used with EAP-TTLS + * and EAP-FAST. If any other EAP method is enabled, the peer will be + * allowed to connect without TNC. + */ int tnc; + + /** + * wps - Wi-Fi Protected Setup context + * + * If WPS is used with an external RADIUS server (which is quite + * unlikely configuration), this is used to provide a pointer to WPS + * context data. Normally, this can be set to %NULL. + */ struct wps_context *wps; + + /** + * ipv6 - Whether to enable IPv6 support in the RADIUS server + */ int ipv6; + + /** + * get_eap_user - Callback for fetching EAP user information + * @ctx: Context data from conf_ctx + * @identity: User identity + * @identity_len: identity buffer length in octets + * @phase2: Whether this is for Phase 2 identity + * @user: Data structure for filling in the user information + * Returns: 0 on success, -1 on failure + * + * This is used to fetch information from user database. The callback + * will fill in information about allowed EAP methods and the user + * password. The password field will be an allocated copy of the + * password data and RADIUS server will free it after use. + */ int (*get_eap_user)(void *ctx, const u8 *identity, size_t identity_len, int phase2, struct eap_user *user); + + /** + * eap_req_id_text - Optional data for EAP-Request/Identity + * + * This can be used to configure an optional, displayable message that + * will be sent in EAP-Request/Identity. This string can contain an + * ASCII-0 character (nul) to separate network infromation per RFC + * 4284. The actual string length is explicit provided in + * eap_req_id_text_len since nul character will not be used as a string + * terminator. + */ const char *eap_req_id_text; + + /** + * eap_req_id_text_len - Length of eap_req_id_text buffer in octets + */ size_t eap_req_id_text_len; };