From 534b6c8a981b509fd508be1656926d474de0bf77 Mon Sep 17 00:00:00 2001 From: Arran Cudbard-Bell Date: Mon, 2 Mar 2015 00:37:29 -0500 Subject: [PATCH] Basic doxygen comments. Addresses #31 Documentation source was from https://github.com/FreeRADIUS/freeradius-client/pull/31 by @nmav --- include/freeradius-client.h | 264 ++++++++++++++++++------------------ include/pathnames.h | 6 +- lib/avpair.c | 187 ++++++++++++------------- lib/buildreq.c | 125 +++++++++-------- lib/clientid.c | 39 ++---- lib/config.c | 168 +++++++++++------------ lib/dict.c | 100 ++++++-------- lib/env.c | 35 ++--- lib/ip_util.c | 128 +++++++---------- lib/log.c | 27 +--- lib/md5.h | 6 +- lib/options.h | 18 +-- lib/rc-md5.c | 9 +- lib/sendserver.c | 63 ++++----- lib/util.c | 90 +++++------- 15 files changed, 567 insertions(+), 698 deletions(-) diff --git a/include/freeradius-client.h b/include/freeradius-client.h index bb774604..797cdfaa 100644 --- a/include/freeradius-client.h +++ b/include/freeradius-client.h @@ -52,7 +52,7 @@ #define BUFFER_LEN 8192 #define NAME_LENGTH 32 -#define GETSTR_LENGTH 128 /* must be bigger than AUTH_PASS_LEN */ +#define GETSTR_LENGTH 128 //!< must be bigger than AUTH_PASS_LEN. #define MAX_SECRET_LENGTH (3 * 16) /* MUST be multiple of 16 */ @@ -139,131 +139,131 @@ typedef struct rc_conf rc_handle; /* standard RADIUS attribute-value pairs */ -#define PW_USER_NAME 1 /* string */ -#define PW_USER_PASSWORD 2 /* string */ -#define PW_CHAP_PASSWORD 3 /* string */ -#define PW_NAS_IP_ADDRESS 4 /* ipaddr */ -#define PW_NAS_PORT 5 /* integer */ -#define PW_SERVICE_TYPE 6 /* integer */ -#define PW_FRAMED_PROTOCOL 7 /* integer */ -#define PW_FRAMED_IP_ADDRESS 8 /* ipaddr */ -#define PW_FRAMED_IP_NETMASK 9 /* ipaddr */ -#define PW_FRAMED_ROUTING 10 /* integer */ -#define PW_FILTER_ID 11 /* string */ -#define PW_FRAMED_MTU 12 /* integer */ -#define PW_FRAMED_COMPRESSION 13 /* integer */ -#define PW_LOGIN_IP_HOST 14 /* ipaddr */ -#define PW_LOGIN_SERVICE 15 /* integer */ -#define PW_LOGIN_PORT 16 /* integer */ -#define PW_OLD_PASSWORD 17 /* string */ /* deprecated */ -#define PW_REPLY_MESSAGE 18 /* string */ -#define PW_LOGIN_CALLBACK_NUMBER 19 /* string */ -#define PW_FRAMED_CALLBACK_ID 20 /* string */ -#define PW_EXPIRATION 21 /* date */ /* deprecated */ -#define PW_FRAMED_ROUTE 22 /* string */ -#define PW_FRAMED_IPX_NETWORK 23 /* integer */ -#define PW_STATE 24 /* string */ -#define PW_CLASS 25 /* string */ -#define PW_VENDOR_SPECIFIC 26 /* string */ -#define PW_SESSION_TIMEOUT 27 /* integer */ -#define PW_IDLE_TIMEOUT 28 /* integer */ -#define PW_TERMINATION_ACTION 29 /* integer */ -#define PW_CALLED_STATION_ID 30 /* string */ -#define PW_CALLING_STATION_ID 31 /* string */ -#define PW_NAS_IDENTIFIER 32 /* string */ -#define PW_PROXY_STATE 33 /* string */ -#define PW_LOGIN_LAT_SERVICE 34 /* string */ -#define PW_LOGIN_LAT_NODE 35 /* string */ -#define PW_LOGIN_LAT_GROUP 36 /* string */ -#define PW_FRAMED_APPLETALK_LINK 37 /* integer */ -#define PW_FRAMED_APPLETALK_NETWORK 38 /* integer */ -#define PW_FRAMED_APPLETALK_ZONE 39 /* string */ -#define PW_ACCT_STATUS_TYPE 40 /* integer */ -#define PW_ACCT_DELAY_TIME 41 /* integer */ -#define PW_ACCT_INPUT_OCTETS 42 /* integer */ -#define PW_ACCT_OUTPUT_OCTETS 43 /* integer */ -#define PW_ACCT_SESSION_ID 44 /* string */ -#define PW_ACCT_AUTHENTIC 45 /* integer */ -#define PW_ACCT_SESSION_TIME 46 /* integer */ -#define PW_ACCT_INPUT_PACKETS 47 /* integer */ -#define PW_ACCT_OUTPUT_PACKETS 48 /* integer */ -#define PW_ACCT_TERMINATE_CAUSE 49 /* integer */ -#define PW_ACCT_MULTI_SESSION_ID 50 /* string */ -#define PW_ACCT_LINK_COUNT 51 /* integer */ -#define PW_ACCT_INPUT_GIGAWORDS 52 /* integer */ -#define PW_ACCT_OUTPUT_GIGAWORDS 53 /* integer */ -#define PW_EVENT_TIMESTAMP 55 /* integer */ -#define PW_EGRESS_VLANID 56 /* string */ -#define PW_INGRESS_FILTERS 57 /* integer */ -#define PW_EGRESS_VLAN_NAME 58 /* string */ -#define PW_USER_PRIORITY_TABLE 59 /* string */ -#define PW_CHAP_CHALLENGE 60 /* string */ -#define PW_NAS_PORT_TYPE 61 /* integer */ -#define PW_PORT_LIMIT 62 /* integer */ -#define PW_LOGIN_LAT_PORT 63 /* string */ -#define PW_TUNNEL_TYPE 64 /* string */ -#define PW_TUNNEL_MEDIUM_TYPE 65 /* integer */ -#define PW_TUNNEL_CLIENT_ENDPOINT 66 /* string */ -#define PW_TUNNEL_SERVER_ENDPOINT 67 /* string */ -#define PW_ACCT_TUNNEL_CONNECTION 68 /* string */ -#define PW_TUNNEL_PASSWORD 69 /* string */ -#define PW_ARAP_PASSWORD 70 /* string */ -#define PW_ARAP_FEATURES 71 /* string */ -#define PW_ARAP_ZONE_ACCESS 72 /* integer */ -#define PW_ARAP_SECURITY 73 /* integer */ -#define PW_ARAP_SECURITY_DATA 74 /* string */ -#define PW_PASSWORD_RETRY 75 /* integer */ -#define PW_PROMPT 76 /* integer */ -#define PW_CONNECT_INFO 77 /* string */ -#define PW_CONFIGURATION_TOKEN 78 /* string */ -#define PW_EAP_MESSAGE 79 /* string */ -#define PW_MESSAGE_AUTHENTICATOR 80 /* string */ -#define PW_TUNNEL_PRIVATE_GROUP_ID 81 /* string */ -#define PW_TUNNEL_ASSIGNMENT_ID 82 /* string */ -#define PW_TUNNEL_PREFERENCE 83 /* string */ -#define PW_ARAP_CHALLENGE_RESPONSE 84 /* string */ -#define PW_ACCT_INTERIM_INTERVAL 85 /* integer */ -#define PW_ACCT_TUNNEL_PACKETS_LOST 86 /* integer */ -#define PW_NAS_PORT_ID_STRING 87 /* string */ -#define PW_FRAMED_POOL 88 /* string */ -#define PW_CHARGEABLE_USER_IDENTITY 89 /* string */ -#define PW_CUI 89 /* string */ -#define PW_TUNNEL_CLIENT_AUTH_ID 90 /* string */ -#define PW_TUNNEL_SERVER_AUTH_ID 91 /* string */ -#define PW_NAS_FILTER_RULE 92 /* string */ -#define PW_ORIGINATING_LINE_INFO 94 /* string */ -#define PW_NAS_IPV6_ADDRESS 95 /* string */ -#define PW_FRAMED_INTERFACE_ID 96 /* string */ -#define PW_FRAMED_IPV6_PREFIX 97 /* string */ -#define PW_LOGIN_IPV6_HOST 98 /* string */ -#define PW_FRAMED_IPV6_ROUTE 99 /* string */ -#define PW_FRAMED_IPV6_POOL 100 /* string */ -#define PW_ERROR_CAUSE 101 /* integer */ -#define PW_EAP_KEY_NAME 102 /* string */ - -#define PW_FRAMED_IPV6_ADDRESS 168 /* ipaddr6 */ -#define PW_DNS_SERVER_IPV6_ADDRESS 169 /* ipaddr6 */ -#define PW_ROUTE_IPV6_INFORMATION 170 /* ipv6prefix */ +#define PW_USER_NAME 1 //!< string. +#define PW_USER_PASSWORD 2 //!< string. +#define PW_CHAP_PASSWORD 3 //!< string. +#define PW_NAS_IP_ADDRESS 4 //!< ipaddr. +#define PW_NAS_PORT 5 //!< integer. +#define PW_SERVICE_TYPE 6 //!< integer. +#define PW_FRAMED_PROTOCOL 7 //!< integer. +#define PW_FRAMED_IP_ADDRESS 8 //!< ipaddr. +#define PW_FRAMED_IP_NETMASK 9 //!< ipaddr. +#define PW_FRAMED_ROUTING 10 //!< integer. +#define PW_FILTER_ID 11 //!< string. +#define PW_FRAMED_MTU 12 //!< integer. +#define PW_FRAMED_COMPRESSION 13 //!< integer. +#define PW_LOGIN_IP_HOST 14 //!< ipaddr. +#define PW_LOGIN_SERVICE 15 //!< integer. +#define PW_LOGIN_PORT 16 //!< integer. +#define PW_OLD_PASSWORD 17 //!< string */ /* deprecated. +#define PW_REPLY_MESSAGE 18 //!< string. +#define PW_LOGIN_CALLBACK_NUMBER 19 //!< string. +#define PW_FRAMED_CALLBACK_ID 20 //!< string. +#define PW_EXPIRATION 21 //!< date */ /* deprecated. +#define PW_FRAMED_ROUTE 22 //!< string. +#define PW_FRAMED_IPX_NETWORK 23 //!< integer. +#define PW_STATE 24 //!< string. +#define PW_CLASS 25 //!< string. +#define PW_VENDOR_SPECIFIC 26 //!< string. +#define PW_SESSION_TIMEOUT 27 //!< integer. +#define PW_IDLE_TIMEOUT 28 //!< integer. +#define PW_TERMINATION_ACTION 29 //!< integer. +#define PW_CALLED_STATION_ID 30 //!< string. +#define PW_CALLING_STATION_ID 31 //!< string. +#define PW_NAS_IDENTIFIER 32 //!< string. +#define PW_PROXY_STATE 33 //!< string. +#define PW_LOGIN_LAT_SERVICE 34 //!< string. +#define PW_LOGIN_LAT_NODE 35 //!< string. +#define PW_LOGIN_LAT_GROUP 36 //!< string. +#define PW_FRAMED_APPLETALK_LINK 37 //!< integer. +#define PW_FRAMED_APPLETALK_NETWORK 38 //!< integer. +#define PW_FRAMED_APPLETALK_ZONE 39 //!< string. +#define PW_ACCT_STATUS_TYPE 40 //!< integer. +#define PW_ACCT_DELAY_TIME 41 //!< integer. +#define PW_ACCT_INPUT_OCTETS 42 //!< integer. +#define PW_ACCT_OUTPUT_OCTETS 43 //!< integer. +#define PW_ACCT_SESSION_ID 44 //!< string. +#define PW_ACCT_AUTHENTIC 45 //!< integer. +#define PW_ACCT_SESSION_TIME 46 //!< integer. +#define PW_ACCT_INPUT_PACKETS 47 //!< integer. +#define PW_ACCT_OUTPUT_PACKETS 48 //!< integer. +#define PW_ACCT_TERMINATE_CAUSE 49 //!< integer. +#define PW_ACCT_MULTI_SESSION_ID 50 //!< string. +#define PW_ACCT_LINK_COUNT 51 //!< integer. +#define PW_ACCT_INPUT_GIGAWORDS 52 //!< integer. +#define PW_ACCT_OUTPUT_GIGAWORDS 53 //!< integer. +#define PW_EVENT_TIMESTAMP 55 //!< integer. +#define PW_EGRESS_VLANID 56 //!< string. +#define PW_INGRESS_FILTERS 57 //!< integer. +#define PW_EGRESS_VLAN_NAME 58 //!< string. +#define PW_USER_PRIORITY_TABLE 59 //!< string. +#define PW_CHAP_CHALLENGE 60 //!< string. +#define PW_NAS_PORT_TYPE 61 //!< integer. +#define PW_PORT_LIMIT 62 //!< integer. +#define PW_LOGIN_LAT_PORT 63 //!< string. +#define PW_TUNNEL_TYPE 64 //!< string. +#define PW_TUNNEL_MEDIUM_TYPE 65 //!< integer. +#define PW_TUNNEL_CLIENT_ENDPOINT 66 //!< string. +#define PW_TUNNEL_SERVER_ENDPOINT 67 //!< string. +#define PW_ACCT_TUNNEL_CONNECTION 68 //!< string. +#define PW_TUNNEL_PASSWORD 69 //!< string. +#define PW_ARAP_PASSWORD 70 //!< string. +#define PW_ARAP_FEATURES 71 //!< string. +#define PW_ARAP_ZONE_ACCESS 72 //!< integer. +#define PW_ARAP_SECURITY 73 //!< integer. +#define PW_ARAP_SECURITY_DATA 74 //!< string. +#define PW_PASSWORD_RETRY 75 //!< integer. +#define PW_PROMPT 76 //!< integer. +#define PW_CONNECT_INFO 77 //!< string. +#define PW_CONFIGURATION_TOKEN 78 //!< string. +#define PW_EAP_MESSAGE 79 //!< string. +#define PW_MESSAGE_AUTHENTICATOR 80 //!< string. +#define PW_TUNNEL_PRIVATE_GROUP_ID 81 //!< string. +#define PW_TUNNEL_ASSIGNMENT_ID 82 //!< string. +#define PW_TUNNEL_PREFERENCE 83 //!< string. +#define PW_ARAP_CHALLENGE_RESPONSE 84 //!< string. +#define PW_ACCT_INTERIM_INTERVAL 85 //!< integer. +#define PW_ACCT_TUNNEL_PACKETS_LOST 86 //!< integer. +#define PW_NAS_PORT_ID_STRING 87 //!< string. +#define PW_FRAMED_POOL 88 //!< string. +#define PW_CHARGEABLE_USER_IDENTITY 89 //!< string. +#define PW_CUI 89 //!< string. +#define PW_TUNNEL_CLIENT_AUTH_ID 90 //!< string. +#define PW_TUNNEL_SERVER_AUTH_ID 91 //!< string. +#define PW_NAS_FILTER_RULE 92 //!< string. +#define PW_ORIGINATING_LINE_INFO 94 //!< string. +#define PW_NAS_IPV6_ADDRESS 95 //!< string. +#define PW_FRAMED_INTERFACE_ID 96 //!< string. +#define PW_FRAMED_IPV6_PREFIX 97 //!< string. +#define PW_LOGIN_IPV6_HOST 98 //!< string. +#define PW_FRAMED_IPV6_ROUTE 99 //!< string. +#define PW_FRAMED_IPV6_POOL 100 //!< string. +#define PW_ERROR_CAUSE 101 //!< integer. +#define PW_EAP_KEY_NAME 102 //!< string. + +#define PW_FRAMED_IPV6_ADDRESS 168 //!< ipaddr6. +#define PW_DNS_SERVER_IPV6_ADDRESS 169 //!< ipaddr6. +#define PW_ROUTE_IPV6_INFORMATION 170 //!< ipv6prefix. /* Experimental SIP-specific attributes (draft-sterman-aaa-sip-00.txt etc) */ -#define PW_DIGEST_RESPONSE 206 /* string */ -#define PW_DIGEST_ATTRIBUTES 207 /* string */ -#define PW_DIGEST_REALM 1063 /* string */ -#define PW_DIGEST_NONCE 1064 /* string */ -#define PW_DIGEST_METHOD 1065 /* string */ -#define PW_DIGEST_URI 1066 /* string */ -#define PW_DIGEST_QOP 1067 /* string */ -#define PW_DIGEST_ALGORITHM 1068 /* string */ -#define PW_DIGEST_BODY_DIGEST 1069 /* string */ -#define PW_DIGEST_CNONCE 1070 /* string */ -#define PW_DIGEST_NONCE_COUNT 1071 /* string */ -#define PW_DIGEST_USER_NAME 1072 /* string */ +#define PW_DIGEST_RESPONSE 206 //!< string. +#define PW_DIGEST_ATTRIBUTES 207 //!< string. +#define PW_DIGEST_REALM 1063 //!< string. +#define PW_DIGEST_NONCE 1064 //!< string. +#define PW_DIGEST_METHOD 1065 //!< string. +#define PW_DIGEST_URI 1066 //!< string. +#define PW_DIGEST_QOP 1067 //!< string. +#define PW_DIGEST_ALGORITHM 1068 //!< string. +#define PW_DIGEST_BODY_DIGEST 1069 //!< string. +#define PW_DIGEST_CNONCE 1070 //!< string. +#define PW_DIGEST_NONCE_COUNT 1071 //!< string. +#define PW_DIGEST_USER_NAME 1072 //!< string. /* Merit Experimental Extensions */ -#define PW_USER_ID 222 /* string */ -#define PW_USER_REALM 223 /* string */ +#define PW_USER_ID 222 //!< string. +#define PW_USER_REALM 223 //!< string. /* Integer Translations */ @@ -316,7 +316,7 @@ typedef struct rc_conf rc_handle; /* PROHIBIT PROTOCOL */ -#define PW_DUMB 0 /* 1 and 2 are defined in FRAMED PROTOCOLS */ +#define PW_DUMB 0 //!< 1 and 2 are defined in FRAMED PROTOCOLS. #define PW_AUTH_ONLY 3 #define PW_ALL 255 @@ -371,9 +371,9 @@ typedef struct rc_conf rc_handle; typedef struct dict_attr { - char name[NAME_LENGTH + 1]; /* attribute name */ - int value; /* attribute index */ - int type; /* string, int, etc. */ + char name[NAME_LENGTH + 1]; //!< attribute name. + int value; //!< attribute index. + int type; //!< string, int, etc.. struct dict_attr *next; } DICT_ATTR; @@ -415,15 +415,15 @@ typedef struct value_pair typedef struct send_data /* Used to pass information to sendserver() function */ { - uint8_t code; /* RADIUS packet code */ - uint8_t seq_nbr; /* Packet sequence number */ - char *server; /* Name/addrress of RADIUS server */ - int svc_port; /* RADIUS protocol destination port */ - char *secret; /* Shared secret of RADIUS server */ - int timeout; /* Session timeout in seconds */ + uint8_t code; //!< RADIUS packet code. + uint8_t seq_nbr; //!< Packet sequence number. + char *server; //!< Name/addrress of RADIUS server. + int svc_port; //!< RADIUS protocol destination port. + char *secret; //!< Shared secret of RADIUS server. + int timeout; //!< Session timeout in seconds. int retries; - VALUE_PAIR *send_pairs; /* More a/v pairs to send */ - VALUE_PAIR *receive_pairs; /* Where to place received a/v pairs */ + VALUE_PAIR *send_pairs; //!< More a/v pairs to send. + VALUE_PAIR *receive_pairs; //!< Where to place received a/v pairs. } SEND_DATA; #ifndef MIN diff --git a/include/pathnames.h b/include/pathnames.h index 0256d473..3df4da72 100644 --- a/include/pathnames.h +++ b/include/pathnames.h @@ -17,12 +17,12 @@ #ifndef PATHNAMES_H #define PATHNAMES_H -#define _PATH_DEV_URANDOM "/dev/urandom" /* Linux only */ -#define _PATH_ETC_ISSUE "/etc/issue" +#define _PATH_DEV_URANDOM "/dev/urandom" /* Linux only */ +#define _PATH_ETC_ISSUE "/etc/issue" /* normally defined in the Makefile */ #ifndef _PATH_ETC_RADIUSCLIENT_CONF -#define _PATH_ETC_RADIUSCLIENT_CONF "/etc/radiusclient.conf" +# define _PATH_ETC_RADIUSCLIENT_CONF "/etc/radiusclient.conf" #endif #endif /* PATHNAMES_H */ diff --git a/lib/avpair.c b/lib/avpair.c index 34d6e504..624dad5a 100644 --- a/lib/avpair.c +++ b/lib/avpair.c @@ -13,23 +13,23 @@ * and I'll send you a copy. * */ - #include #include #include #include "util.h" -/* - * Function: rc_avpair_add - * - * Purpose: add an attribute-value pair to the given list. +/** Adds an attribute-value pair to the given list * - * Returns: pointer to added a/v pair upon success, NULL pointer upon failure. - * - * Remarks: Always appends the new pair to the end of the list. + * @note Always appends the new pair to the end of the list. * + * @param rh a handle to parsed configuration. + * @param list a #VALUE_PAIR array of values; initially must be %NULL. + * @param attrid The attribute of the pair to add (e.g., %PW_USER_NAME). + * @param pval the value (e.g., the actual username). + * @param len the length of @pval, or -1 if to calculate (in case of strings). + * @param vendorpec The vendor ID in case of a vendor specific value - 0 otherwise. + * @return pointer to added a/v pair upon success, NULL pointer upon failure. */ - VALUE_PAIR *rc_avpair_add (rc_handle const *rh, VALUE_PAIR **list, int attrid, void const *pval, int len, int vendorpec) { VALUE_PAIR *vp; @@ -45,22 +45,19 @@ VALUE_PAIR *rc_avpair_add (rc_handle const *rh, VALUE_PAIR **list, int attrid, v } -/* - * Function: rc_avpair_assign - * - * Purpose: assign the given value to an attribute-value pair. - * - * Returns: 0 on success, - * -1 on failure. +/** Assigns the given value to an attribute-value pair * + * @param vp a pointer to a #VALUE_PAIR structure. + * @param pval the value (e.g., the actual username). + * @param len the length of @pval, or -1 if to calculate (in case of strings). + * @return 0 on success or -1 on failure. */ - int rc_avpair_assign (VALUE_PAIR *vp, void const *pval, int len) { switch (vp->type) { - case PW_TYPE_STRING: + case PW_TYPE_STRING if (len == -1) len = (uint32_t)strlen((char const *)pval); if (len > AUTH_STRING_LEN) { @@ -102,15 +99,15 @@ int rc_avpair_assign (VALUE_PAIR *vp, void const *pval, int len) return 0; } -/* - * Function: rc_avpair_new - * - * Purpose: make a new attribute-value pair with given parameters. - * - * Returns: pointer to generated a/v pair when successful, NULL when failure. +/** Make a new attribute-value pair with given parameters * + * @param rh a handle to parsed configuration. + * @param attrid The attribute of the pair to add (e.g., %PW_USER_NAME). + * @param pval the value (e.g., the actual username). + * @param len the length of pval, or -1 if to calculate (in case of strings). + * @param vendorpec The vendor ID in case of a vendor specific value - 0 otherwise. + * @return pointer to generated a/v pair when successful, NULL when failure. */ - VALUE_PAIR *rc_avpair_new (rc_handle const *rh, int attrid, void const *pval, int len, int vendorpec) { VALUE_PAIR *vp = NULL; @@ -119,7 +116,7 @@ VALUE_PAIR *rc_avpair_new (rc_handle const *rh, int attrid, void const *pval, in attrid = attrid | (vendorpec << 16); if ((pda = rc_dict_getattr (rh, attrid)) == NULL) { - rc_log(LOG_ERR,"rc_avpair_new: unknown attribute %d", attrid); + rc_log(LOG_ERR,"rc_avpair_new unknown attribute %d", attrid); return NULL; } if (vendorpec != 0 && rc_dict_getvend(rh, vendorpec) == NULL) @@ -172,19 +169,19 @@ VALUE_PAIR *rc_avpair_new (rc_handle const *rh, int attrid, void const *pval, in return vp; } -/* - * - * Function: rc_avpair_gen +/** Takes attribute/value pairs from buffer and builds a value_pair list using allocated memory * - * Purpose: takes attribute/value pairs from buffer and builds a - * value_pair list using allocated memory. Uses recursion. + * @note Uses recursion. * - * Returns: value_pair list or NULL on failure + * @param rh a handle to parsed configuration. + * @param pair a pointer to a #VALUE_PAIR structure. + * @param ptr the value (e.g., the actual username). + * @param length the length of ptr, or -1 if to calculate (in case of strings). + * @param vendorpec The vendor ID in case of a vendor specific value - 0 otherwise. + * @return value_pair list or %NULL on failure. */ - -VALUE_PAIR * -rc_avpair_gen(rc_handle const *rh, VALUE_PAIR *pair, unsigned char const *ptr, - int length, int vendorpec) +VALUE_PAIR *rc_avpair_gen(rc_handle const *rh, VALUE_PAIR *pair, unsigned char const *ptr, + int length, int vendorpec) { int attribute, attrlen, x_len; unsigned char const *x_ptr; @@ -196,7 +193,7 @@ rc_avpair_gen(rc_handle const *rh, VALUE_PAIR *pair, unsigned char const *ptr, char hex[3]; if (length < 2) { - rc_log(LOG_ERR, "rc_avpair_gen: received attribute with " + rc_log(LOG_ERR, "rc_avpair_gen received attribute with " "invalid length"); goto shithappens; } @@ -341,16 +338,13 @@ rc_avpair_gen(rc_handle const *rh, VALUE_PAIR *pair, unsigned char const *ptr, return NULL; } -/* - * Function: rc_avpair_get - * - * Purpose: Find the first attribute value-pair (which matches the given - * attribute) from the specified value-pair list. - * - * Returns: found value_pair +/** Find the first attribute value-pair (which matches the given attribute) from the specified value-pair list * + * @param vp a pointer to a #VALUE_PAIR structure. + * @param attrid The attribute of the pair to find (e.g., %PW_USER_NAME). + * @param vendorpec The vendor ID in case of a vendor specific value - 0 otherwise. + * @return the value pair found. */ - VALUE_PAIR *rc_avpair_get (VALUE_PAIR *vp, int attrid, int vendorpec) { for (; vp != NULL && !(ATTRID(vp->attribute) == ATTRID(attrid) && @@ -361,17 +355,16 @@ VALUE_PAIR *rc_avpair_get (VALUE_PAIR *vp, int attrid, int vendorpec) return vp; } -/* - * Function: rc_avpair_insert +/** Insert a VALUE_PAIR into a list * - * Purpose: Given the address of an existing list "a" and a pointer - * to an entry "p" in that list, add the value pair "b" to - * the "a" list after the "p" entry. If "p" is NULL, add - * the value pair "b" to the end of "a". + * Given the address of an existing list "a" and a pointer to an entry "p" in that list, add the value pair "b" to + * the "a" list after the "p" entry. If "p" is NULL, add the value pair "b" to the end of "a". * + * @param a a #VALUE_PAIR array of values. + * @param p a pointer to a #VALUE_PAIR in a. + * @param b The #VALUE_PAIR pointer to add in a. */ - -void rc_avpair_insert (VALUE_PAIR **a, VALUE_PAIR *p, VALUE_PAIR *b) +void rc_avpair_insert(VALUE_PAIR **a, VALUE_PAIR *p, VALUE_PAIR *b) { VALUE_PAIR *this_node = NULL; VALUE_PAIR *vp; @@ -417,13 +410,10 @@ void rc_avpair_insert (VALUE_PAIR **a, VALUE_PAIR *p, VALUE_PAIR *b) return; } -/* - * Function: rc_avpair_free - * - * Purpose: frees all value_pairs in the list +/** Frees all value_pairs in the list * + * @param pair a pointer to a VALUE_PAIR structure. */ - void rc_avpair_free (VALUE_PAIR *pair) { VALUE_PAIR *next; @@ -436,18 +426,17 @@ void rc_avpair_free (VALUE_PAIR *pair) } } -/* - * Function: rc_fieldcpy +/** Copy a data field from the buffer * - * Purpose: Copy a data field from the buffer. Advance the buffer - * past the data field. Ensure that no more than len - 1 - * bytes are copied and that resulting string is terminated - * with '\0'. + * Advance the buffer past the data field. Ensure that no more than len - 1 bytes are copied and that resulting + * string is terminated with '\0'. * + * @param string the provided string to copy. + * @param uptr the current position of the buffer. + * @param stopat characters to which parsing should stop. + * @param len the maximum length of string. */ - -static void -rc_fieldcpy(char *string, char const **uptr, char const *stopat, size_t len) +static void rc_fieldcpy(char *string, char const **uptr, char const *stopat, size_t len) { char const *ptr, *estring; @@ -482,22 +471,18 @@ rc_fieldcpy(char *string, char const **uptr, char const *stopat, size_t len) return; } - -/* - * Function: rc_avpair_parse - * - * Purpose: parses the buffer to extract the attribute-value pairs. - * - * Returns: 0 = successful parse of attribute-value pair, - * -1 = syntax (or other) error detected. - * - */ - #define PARSE_MODE_NAME 0 #define PARSE_MODE_EQUAL 1 #define PARSE_MODE_VALUE 2 #define PARSE_MODE_INVALID 3 +/** Parses the buffer to extract the attribute-value pairs + * + * @param rh a handle to parsed configuration. + * @param buffer the buffer to be parsed. + * @param first_pair an allocated array of values. + * @return 0 on successful parse of attribute-value pair, or -1 on syntax (or other) error detected. + */ int rc_avpair_parse (rc_handle const *rh, char const *buffer, VALUE_PAIR **first_pair) { int mode; @@ -521,7 +506,7 @@ int rc_avpair_parse (rc_handle const *rh, char const *buffer, VALUE_PAIR **first switch (mode) { - case PARSE_MODE_NAME: /* Attribute Name */ + case PARSE_MODE_NAME /* Attribute Name */ rc_fieldcpy (attrstr, &buffer, " \t\n=,", sizeof(attrstr)); if ((attr = rc_dict_findattr (rh, attrstr)) == NULL) @@ -709,15 +694,16 @@ int rc_avpair_parse (rc_handle const *rh, char const *buffer, VALUE_PAIR **first return 0; } -/* - * Function: rc_avpair_tostr - * - * Purpose: Translate an av_pair into two strings - * - * Returns: 0 on success, -1 on failure +/** Translate an av_pair into two strings * + * @param rh a handle to parsed configuration. + * @param pair a pointer to a VALUE_PAIR structure. + * @param name the name of the pair. + * @param ln the size of name. + * @param value the value of the pair. + * @param lv the size of value. + * @return 0 on success, -1 on failure. */ - int rc_avpair_tostr (rc_handle const *rh, VALUE_PAIR *pair, char *name, int ln, char *value, int lv) { DICT_VALUE *dval; @@ -729,7 +715,7 @@ int rc_avpair_tostr (rc_handle const *rh, VALUE_PAIR *pair, char *name, int ln, *name = *value = '\0'; if (!pair || pair->name[0] == '\0') { - rc_log(LOG_ERR, "rc_avpair_tostr: pair is NULL or empty"); + rc_log(LOG_ERR, "rc_avpair_tostr pair is NULL or empty"); return -1; } @@ -821,16 +807,17 @@ int rc_avpair_tostr (rc_handle const *rh, VALUE_PAIR *pair, char *name, int ln, return 0; } -/* - * Function: rc_avpair_log +/** Format a sequence of attribute value pairs into a printable string * - * Purpose: format sequence of attribute value pairs into printable - * string. The caller should provide a storage buffer and the buffer length. - * Returns pointer to provided storage buffer. + * The caller should provide a storage buffer and the buffer length. * + * @param rh a handle to parsed configuration. + * @param pair a pointer to a #VALUE_PAIR structure. + * @param buf will hold the string output of the pair. + * @param len the size of buf. + * @return a pointer to provided storage buffer. */ -char * -rc_avpair_log(rc_handle const *rh, VALUE_PAIR *pair, char *buf, size_t buf_len) +char *rc_avpair_log(rc_handle const *rh, VALUE_PAIR *pair, char *buf, size_t buf_len) { size_t len, nlen; VALUE_PAIR *vp; @@ -850,14 +837,12 @@ rc_avpair_log(rc_handle const *rh, VALUE_PAIR *pair, char *buf, size_t buf_len) return buf; } -/* - * Function: rc_avpair_readin - * - * Purpose: get a sequence of attribute value pairs from the file input - * and make them into a list of value_pairs +/** Get a sequence of attribute value pairs from the file input and make them into a list of value_pairs * + * @param rh a handle to parsed configuration. + * @param input a %FILE handle. + * @return the array of value pairs. */ - VALUE_PAIR *rc_avpair_readin(rc_handle const *rh, FILE *input) { VALUE_PAIR *vp = NULL; @@ -873,7 +858,7 @@ VALUE_PAIR *rc_avpair_readin(rc_handle const *rh, FILE *input) continue; if (rc_avpair_parse(rh, q, &vp) < 0) { - rc_log(LOG_ERR, "rc_avpair_readin: malformed attribute: %s", buffer); + rc_log(LOG_ERR, "rc_avpair_readin malformed attribute: %s", buffer); rc_avpair_free(vp); return NULL; } diff --git a/lib/buildreq.c b/lib/buildreq.c index a71b1f99..0a04cb84 100644 --- a/lib/buildreq.c +++ b/lib/buildreq.c @@ -8,21 +8,23 @@ * and I'll send you a copy. * */ - #include #include #include unsigned char rc_get_id(); -/* - * Function: rc_buildreq - * - * Purpose: builds a skeleton RADIUS request using information from the - * config file. +/** Build a skeleton RADIUS request using information from the config file * + * @param rh a handle to parsed configuration. + * @param data a pointer to a #SEND_DATA structure. + * @param code one of standard RADIUS codes (e.g., %PW_ACCESS_REQUEST). + * @param server the name of the server. + * @param port the server's port number. + * @param secret the secret used by the server. + * @param timeout the timeout in seconds of a message. + * @param retries the number of retries. */ - void rc_buildreq(rc_handle const *rh, SEND_DATA *data, int code, char *server, unsigned short port, char *secret, int timeout, int retries) { @@ -35,31 +37,30 @@ void rc_buildreq(rc_handle const *rh, SEND_DATA *data, int code, char *server, u data->code = code; } -/* - * Function: rc_get_id - * - * Purpose: generate random id +/** Generates a random ID * + * @return the random ID. */ - unsigned char rc_get_id() { return (unsigned char)(random() & UCHAR_MAX); } -/* - * Function: rc_aaa - * - * Purpose: Builds an authentication/accounting request for port id client_port - * with the value_pairs send and submits it to a server - * - * Returns: received value_pairs in received, messages from the server in msg - * and 0 on success, negative on failure as return value +/** Builds an authentication/accounting request for port id client_port with the value_pairs send and submits it to a server * + * @param rh a handle to parsed configuration. + * @param client_port the client port number to use (may be zero to use any available). + * @param send a #VALUE_PAIR array of values (e.g., %PW_USER_NAME). + * @param received an allocated array of received values. + * @param msg must be an array of %PW_MAX_MSG_SIZE or %NULL; will contain the concatenation of any + * %PW_REPLY_MESSAGE received. + * @param add_nas_port if non-zero it will include %PW_NAS_PORT in sent pairs. + * @param request_type one of standard RADIUS codes (e.g., %PW_ACCESS_REQUEST). + * @return received value_pairs in received, messages from the server in msg and %OK_RC (0) on success, negative + * on failure as return value. */ - int rc_aaa(rc_handle *rh, uint32_t client_port, VALUE_PAIR *send, VALUE_PAIR **received, - char *msg, int add_nas_port, int request_type) + char *msg, int add_nas_port, int request_type) { SEND_DATA data; VALUE_PAIR *adt_vp = NULL; @@ -165,7 +166,7 @@ int rc_aaa(rc_handle *rh, uint32_t client_port, VALUE_PAIR *send, VALUE_PAIR **r aaaserver->deadtime_ends[i] = -1; } -exit: +exit if (request_type != PW_ACCOUNTING_REQUEST) { *received = data.receive_pairs; } else { @@ -175,17 +176,17 @@ int rc_aaa(rc_handle *rh, uint32_t client_port, VALUE_PAIR *send, VALUE_PAIR **r return result; } -/* - * Function: rc_auth - * - * Purpose: Builds an authentication request for port id client_port - * with the value_pairs send and submits it to a server - * - * Returns: received value_pairs in received, messages from the server in msg (if non-NULL), - * and 0 on success, negative on failure as return value +/** Builds an authentication request for port id client_port with the value_pairs send and submits it to a server * + * @param rh a handle to parsed configuration. + * @param client_port the client port number to use (may be zero to use any available). + * @param send a #VALUE_PAIR array of values (e.g., %PW_USER_NAME). + * @param received an allocated array of received values. + * @param msg must be an array of %PW_MAX_MSG_SIZE or %NULL; will contain the concatenation of any + * %PW_REPLY_MESSAGE received. + * @return received value_pairs in @received, messages from the server in msg (if non-NULL), + * and %OK_RC (0) on success, negative on failure as return value. */ - int rc_auth(rc_handle *rh, uint32_t client_port, VALUE_PAIR *send, VALUE_PAIR **received, char *msg) { @@ -193,63 +194,61 @@ int rc_auth(rc_handle *rh, uint32_t client_port, VALUE_PAIR *send, VALUE_PAIR ** return rc_aaa(rh, client_port, send, received, msg, 1, PW_ACCESS_REQUEST); } -/* - * Function: rc_auth_proxy - * - * Purpose: Builds an authentication request - * with the value_pairs send and submits it to a server. - * Works for a proxy; does not add IP address, and does - * does not rely on config file. +/** Builds an authentication request for proxying * - * Returns: received value_pairs in received, messages from the server in msg (if non-NULL) - * and 0 on success, negative on failure as return value + * Builds an authentication request with the value_pairs send and submits it to a server. + * Works for a proxy; does not add IP address, and does does not rely on config file. * + * @param rh a handle to parsed configuration. + * @param client_port the client port number to use (may be zero to use any available). + * @param send a #VALUE_PAIR array of values (e.g., %PW_USER_NAME). + * @param received an allocated array of received values. + * @param msg must be an array of %PW_MAX_MSG_SIZE or %NULL; will contain the concatenation of + * any %PW_REPLY_MESSAGE received. + * @return received value_pairs in @received, messages from the server in msg (if non-NULL) + * and %OK_RC (0) on success, negative on failure as return value. */ - int rc_auth_proxy(rc_handle *rh, VALUE_PAIR *send, VALUE_PAIR **received, char *msg) { - return rc_aaa(rh, 0, send, received, msg, 0, PW_ACCESS_REQUEST); } - -/* - * Function: rc_acct +/** Builds an accounting request for port id client_port with the value_pairs at send * - * Purpose: Builds an accounting request for port id client_port - * with the value_pairs send + * @note NAS-IP-Address, NAS-Port and Acct-Delay-Time get filled in by this function, the rest has to be supplied. * - * Remarks: NAS-IP-Address, NAS-Port and Acct-Delay-Time get filled - * in by this function, the rest has to be supplied. + * @param rh a handle to parsed configuration. + * @param client_port the client port number to use (may be zero to use any available). + * @param send a #VALUE_PAIR array of values (e.g., %PW_USER_NAME). + * @return received value_pairs in @received, and %OK_RC (0) on success, negative on failure as return value. */ - int rc_acct(rc_handle *rh, uint32_t client_port, VALUE_PAIR *send) { - return rc_aaa(rh, client_port, send, NULL, NULL, 1, PW_ACCOUNTING_REQUEST); } -/* - * Function: rc_acct_proxy - * - * Purpose: Builds an accounting request with the value_pairs send +/** Builds an accounting request with the value_pairs at send * + * @param rh a handle to parsed configuration. + * @param send a #VALUE_PAIR array of values (e.g., %PW_USER_NAME). + * @return %OK_RC (0) on success, negative on failure as return value. */ - int rc_acct_proxy(rc_handle *rh, VALUE_PAIR *send) { return rc_aaa(rh, 0, send, NULL, NULL, 0, PW_ACCOUNTING_REQUEST); } -/* - * Function: rc_check - * - * Purpose: ask the server hostname on the specified port for a - * status message +/** Asks the server hostname on the specified port for a status message * + * @param rh a handle to parsed configuration. + * @param host the name of the server. + * @param secret the secret used by the server. + * @param port the server's port number. + * @param msg must be an array of %PW_MAX_MSG_SIZE or %NULL; will contain the concatenation of any + * %PW_REPLY_MESSAGE received. + * @return %OK_RC (0) on success, negative on failure as return value. */ - int rc_check(rc_handle *rh, char *host, char *secret, unsigned short port, char *msg) { SEND_DATA data; diff --git a/lib/clientid.c b/lib/clientid.c index 852a6fb1..2448925d 100644 --- a/lib/clientid.c +++ b/lib/clientid.c @@ -21,16 +21,12 @@ struct map2id_s { struct map2id_s *next; }; -/* - * Function: rc_read_mapfile - * - * Purpose: Read in the ttyname to port id map file - * - * Arguments: the file name of the map file +/** Read in the ttyname to port id map file * - * Returns: zero on success, negative integer on failure + * @param rh a handle to parsed configuration. + * @param filename the file name of the map file. + * @return zero on success, negative integer on failure. */ - int rc_read_mapfile(rc_handle *rh, char const *filename) { char buffer[1024]; @@ -41,7 +37,7 @@ int rc_read_mapfile(rc_handle *rh, char const *filename) if ((mapfd = fopen(filename,"r")) == NULL) { - rc_log(LOG_ERR,"rc_read_mapfile: can't read %s: %s", filename, strerror(errno)); + rc_log(LOG_ERR,"rc_read_mapfile can't read %s: %s", filename, strerror(errno)); return -1; } @@ -93,16 +89,12 @@ int rc_read_mapfile(rc_handle *rh, char const *filename) return 0; } -/* - * Function: rc_map2id - * - * Purpose: Map ttyname to port id +/** Maps ttyname to port id * - * Arguments: full pathname of the tty - * - * Returns: port id, zero if no entry found + * @param rh a handle to parsed configuration. + * @param name full pathname of the tty. + * @return port id, or zero if no entry found. */ - uint32_t rc_map2id(rc_handle const *rh, char const *name) { struct map2id_s *p; @@ -120,21 +112,16 @@ uint32_t rc_map2id(rc_handle const *rh, char const *name) for(p = rh->map2id_list; p; p = p->next) if (!strcmp(ttyname, p->name)) return p->id; - rc_log(LOG_WARNING,"rc_map2id: can't find tty %s in map database", ttyname); + rc_log(LOG_WARNING,"rc_map2id can't find tty %s in map database", ttyname); return 0; } -/* - * Function: rc_map2id_free +/** Free allocated map2id list * - * Purpose: Free allocated map2id list - * - * Arguments: Radius Client handle + * @param rh a handle to parsed configuration. */ - -void -rc_map2id_free(rc_handle *rh) +void rc_map2id_free(rc_handle *rh) { struct map2id_s *p, *np; diff --git a/lib/config.c b/lib/config.c index 50fc869b..44e2b21d 100644 --- a/lib/config.c +++ b/lib/config.c @@ -20,14 +20,13 @@ #include #include "util.h" -/* - * Function: find_option - * - * Purpose: find an option in the option list +/** Find an option in the option list * - * Returns: pointer to option on success, NULL otherwise + * @param rh a handle to parsed configuration. + * @param optname the name of the option. + * @param type the option type. + * @return pointer to option on success, NULL otherwise. */ - static OPTION *find_option(rc_handle const *rh, char const *optname, unsigned int type) { int i; @@ -44,20 +43,19 @@ static OPTION *find_option(rc_handle const *rh, char const *optname, unsigned in return NULL; } -/* - * Function: set_option_... - * - * Purpose: set a specific option doing type conversions +/** Set a specific option doing type conversions * - * Returns: 0 on success, -1 on failure + * @param filename the name of the config file (for logging purposes). + * @param line the line number in the file. + * @param p Value. + * @return 0 on success, -1 on failure. */ - static int set_option_str(char const *filename, int line, OPTION *option, char const *p) { if (p) { option->val = (void *) strdup(p); if (option->val == NULL) { - rc_log(LOG_CRIT, "read_config: out of memory"); + rc_log(LOG_CRIT, "read_config out of memory"); return -1; } } else { @@ -239,21 +237,22 @@ static int set_option_auo(char const *filename, int line, OPTION *option, char c return 0; } - -/* Function: rc_add_config - * - * Purpose: allow a config option to be added to rc_handle from inside a program +/** Allow a config option to be added to rc_handle from inside a program * - * Returns: 0 on success, -1 on failure + * @param rh a handle to parsed configuration. + * @param option_name the name of the option. + * @param option_val the value to be added. + * @param source typically should be %__FILE__ or %__func__ for logging purposes. + * @param line %__LINE__ for logging purposes. + * @return 0 on success, -1 on failure. */ - int rc_add_config(rc_handle *rh, char const *option_name, char const *option_val, char const *source, int line) { OPTION *option; if ((option = find_option(rh, option_name, OT_ANY)) == NULL) { - rc_log(LOG_ERR, "ERROR: unrecognized option: %s", option_name); + rc_log(LOG_ERR, "ERROR unrecognized option: %s", option_name); return -1; } @@ -291,17 +290,15 @@ int rc_add_config(rc_handle *rh, char const *option_name, char const *option_val return 0; } -/* - * Function: rc_config_init +/** Initialise a configuration structure * - * Purpose: initialize the configuration structure from an external program. For use when not + * Initialize the configuration structure from an external program. For use when not * running a standalone client that reads from a config file. * - * Returns: rc_handle on success, NULL on failure + * @param rh a handle to parsed configuration. + * @return rc_handle on success, NULL on failure. */ - -rc_handle * -rc_config_init(rc_handle *rh) +rc_handle *rc_config_init(rc_handle *rh) { int i; SERVER *authservers; @@ -312,7 +309,7 @@ rc_config_init(rc_handle *rh) rh->config_options = malloc(sizeof(config_options_default)); if (rh->config_options == NULL) { - rc_log(LOG_CRIT, "rc_config_init: out of memory"); + rc_log(LOG_CRIT, "rc_config_init out of memory"); rc_destroy(rh); return NULL; } @@ -348,17 +345,12 @@ rc_config_init(rc_handle *rh) return rh; } - -/* - * Function: rc_read_config +/** Read the global config file * - * Purpose: read the global config file - * - * Returns: new rc_handle on success, NULL when failure + * @param filename a name of a file. + * @return new rc_handle on success, NULL when failure. */ - -rc_handle * -rc_read_config(char const *filename) +rc_handle *rc_read_config(char const *filename) { FILE *configfd; char buffer[512], *p; @@ -375,7 +367,7 @@ rc_read_config(char const *filename) rh->config_options = malloc(sizeof(config_options_default)); if (rh->config_options == NULL) { - rc_log(LOG_CRIT, "rc_read_config: out of memory"); + rc_log(LOG_CRIT, "rc_read_config out of memory"); rc_destroy(rh); return NULL; } @@ -474,14 +466,12 @@ rc_read_config(char const *filename) return rh; } -/* - * Function: rc_conf_str, rc_conf_int, rc_conf_src +/** Get the value of a config option * - * Purpose: get the value of a config option - * - * Returns: config option value + * @param rh a handle to parsed configuration. + * @param optname the name of an option. + * @return config option value. */ - char *rc_conf_str(rc_handle const *rh, char const *optname) { OPTION *option; @@ -491,11 +481,17 @@ char *rc_conf_str(rc_handle const *rh, char const *optname) if (option != NULL) { return (char *)option->val; } else { - rc_log(LOG_CRIT, "rc_conf_str: unkown config option requested: %s", optname); + rc_log(LOG_CRIT, "rc_conf_str unkown config option requested: %s", optname); return NULL; } } +/** Get the value of a config option + * + * @param rh a handle to parsed configuration. + * @param optname the name of an option. + * @return config option value. + */ int rc_conf_int(rc_handle const *rh, char const *optname) { OPTION *option; @@ -506,7 +502,7 @@ int rc_conf_int(rc_handle const *rh, char const *optname) if (option->val) { return *((int *)option->val); } else { - rc_log(LOG_ERR, "rc_conf_int: config option %s was not set", optname); + rc_log(LOG_ERR, "rc_conf_int config option %s was not set", optname); return 0; } } else { @@ -515,6 +511,12 @@ int rc_conf_int(rc_handle const *rh, char const *optname) } } +/** Get the value of a config option + * + * @param rh a handle to parsed configuration. + * @param optname the name of an option. + * @return config option value. + */ SERVER *rc_conf_srv(rc_handle const *rh, char const *optname) { OPTION *option; @@ -524,19 +526,17 @@ SERVER *rc_conf_srv(rc_handle const *rh, char const *optname) if (option != NULL) { return (SERVER *)option->val; } else { - rc_log(LOG_CRIT, "rc_conf_srv: unkown config option requested: %s", optname); + rc_log(LOG_CRIT, "rc_conf_srv unkown config option requested: %s", optname); return NULL; } } -/* - * Function: test_config - * - * Purpose: test the configuration the user supplied +/** Tests the configuration the user supplied * - * Returns: 0 on success, -1 when failure + * @param rh a handle to parsed configuration. + * @param filename a name of a configuration file. + * @return 0 on success, -1 when failure. */ - int test_config(rc_handle const *rh, char const *filename) { #if 0 @@ -546,7 +546,7 @@ int test_config(rc_handle const *rh, char const *filename) if (!(rc_conf_srv(rh, "authserver")->max)) { - rc_log(LOG_ERR,"%s: no authserver specified", filename); + rc_log(LOG_ERR,"%s no authserver specified", filename); return -1; } if (!(rc_conf_srv(rh, "acctserver")->max)) @@ -629,15 +629,12 @@ int test_config(rc_handle const *rh, char const *filename) return 0; } -/* - * Function: rc_find_match - * - * Purpose: see if ip_addr is one of the ip addresses of hostname - * - * Returns: 0 on success, -1 when failure +/** See if ip_addr is one of the ip addresses of hostname * + * @param ip_addr an IPv4 address. + * @param hostname the name of the host. + * @return 0 on success, -1 when failure. */ - static int find_match (uint32_t *ip_addr, char const *hostname) { @@ -670,17 +667,12 @@ static int find_match (uint32_t *ip_addr, char const *hostname) return -1; } -/* - * Function: rc_ipaddr_local - * - * Purpose: checks if provided address is local address - * - * Returns: 0 if local, 1 if not local, -1 on failure +/** Checks if provided address is local address * + * @param ip_addr an IPv4 address. + * @return 0 if local, 1 if not local, -1 on failure. */ - -static int -rc_ipaddr_local(uint32_t ip_addr) +static int rc_ipaddr_local(uint32_t ip_addr) { int temp_sock, res, serrno; struct sockaddr_in sin; @@ -702,17 +694,12 @@ rc_ipaddr_local(uint32_t ip_addr) return -1; } -/* - * Function: rc_is_myname - * - * Purpose: check if provided name refers to ourselves - * - * Returns: 0 if yes, 1 if no and -1 on failure +/** Checks if provided name refers to ourselves * + * @param hostname the name of the host. + * @return 0 if yes, 1 if no and -1 on failure. */ - -static int -rc_is_myname(char const *hostname) +static int rc_is_myname(char const *hostname) { uint32_t addr; char **paddr; @@ -733,15 +720,14 @@ rc_is_myname(char const *hostname) return 1; } -/* - * Function: rc_find_server - * - * Purpose: locate a server in the rh config or if not found, check for a servers file - * - * Returns: 0 on success, -1 on failure +/** Locate a server in the rh config or if not found, check for a servers file * + * @param rh a handle to parsed configuration. + * @param server_name the name of the server. + * @param ip_addr will hold an IPv4 address. + * @param secret will hold the server's secret (of %MAX_SECRET_LENGTH). + * @return 0 on success, -1 on failure. */ - int rc_find_server (rc_handle const *rh, char const *server_name, uint32_t *ip_addr, char *secret) { int i; @@ -796,7 +782,7 @@ int rc_find_server (rc_handle const *rh, char const *server_name, uint32_t *ip_a if ((clientfd = fopen (rc_conf_str(rh, "servers"), "r")) == NULL) { - rc_log(LOG_ERR, "rc_find_server: couldn't open file: %s: %s", strerror(errno), rc_conf_str(rh, "servers")); + rc_log(LOG_ERR, "rc_find_server couldn't open file: %s: %s", strerror(errno), rc_conf_str(rh, "servers")); return -1; } @@ -856,12 +842,12 @@ int rc_find_server (rc_handle const *rh, char const *server_name, uint32_t *ip_a return 0; } -/* - * Function: rc_config_free +/** + * rc_config_free: + * @param rh a handle to parsed configuration * - * Purpose: Free allocated config values + * Free allocated config values * - * Arguments: Radius Client handle */ void diff --git a/lib/dict.c b/lib/dict.c index 84dbba0e..f1eae95e 100644 --- a/lib/dict.c +++ b/lib/dict.c @@ -18,15 +18,15 @@ #include #include -/* - * Function: rc_read_dictionary +/** Initialize the dictionary * - * Purpose: Initialize the dictionary. Read all ATTRIBUTES into - * the dictionary_attributes list. Read all VALUES into - * the dictionary_values list. + * Read all ATTRIBUTES into the dictionary_attributes list. + * Read all VALUES into the dictionary_values list. * + * @param rh a handle to parsed configuration. + * @param filename the name of the dictionary file. + * @return 0 on success, -1 on failure. */ - int rc_read_dictionary (rc_handle *rh, char const *filename) { FILE *dictfd; @@ -48,7 +48,7 @@ int rc_read_dictionary (rc_handle *rh, char const *filename) if ((dictfd = fopen (filename, "r")) == NULL) { - rc_log(LOG_ERR, "rc_read_dictionary: couldn't open dictionary %s: %s", + rc_log(LOG_ERR, "rc_read_dictionary couldn't open dictionary %s: %s", filename, strerror(errno)); return -1; } @@ -349,15 +349,13 @@ int rc_read_dictionary (rc_handle *rh, char const *filename) return 0; } -/* - * Function: rc_dict_getattr - * - * Purpose: Return the full attribute structure based on the - * attribute id number. +/** Lookup a DICT_ATTR by attribute number * + * @param rh a handle to parsed configuration. + * @param attribute the attribute ID. + * @return the full attribute structure based on the attribute id number. */ - -DICT_ATTR *rc_dict_getattr (rc_handle const *rh, int attribute) +DICT_ATTR *rc_dict_getattr(rc_handle const *rh, int attribute) { DICT_ATTR *attr; @@ -373,15 +371,14 @@ DICT_ATTR *rc_dict_getattr (rc_handle const *rh, int attribute) return NULL; } -/* - * Function: rc_dict_findattr +/** Lookup a DICT_ATTR by its name * - * Purpose: Return the full attribute structure based on the - * attribute name. + * @param rh a handle to parsed configuration. + * @param attrname the attribute name. * + * @return the full attribute structure based on the attribute name. */ - -DICT_ATTR *rc_dict_findattr (rc_handle const *rh, char const *attrname) +DICT_ATTR *rc_dict_findattr(rc_handle const *rh, char const *attrname) { DICT_ATTR *attr; @@ -398,15 +395,13 @@ DICT_ATTR *rc_dict_findattr (rc_handle const *rh, char const *attrname) } -/* - * Function: rc_dict_findval - * - * Purpose: Return the full value structure based on the - * value name. +/** Lookup a DICT_VALUE by its name * + * @param rh a handle to parsed configuration. + * @param valname the value name. + * @return the full value structure based on the value name. */ - -DICT_VALUE *rc_dict_findval (rc_handle const *rh, char const *valname) +DICT_VALUE *rc_dict_findval(rc_handle const *rh, char const *valname) { DICT_VALUE *val; @@ -422,16 +417,13 @@ DICT_VALUE *rc_dict_findval (rc_handle const *rh, char const *valname) return NULL; } -/* - * Function: rc_dict_findvend - * - * Purpose: Return the full vendor structure based on the - * vendor name. +/** Lookup a DICT_VENDOR by its name * + * @param rh a handle to parsed configuration. + * @param valname the vendor name. + * @return the full vendor structure based on the vendor name. */ - -DICT_VENDOR * -rc_dict_findvend(rc_handle const *rh, char const *vendorname) +DICT_VENDOR *rc_dict_findvend(rc_handle const *rh, char const *vendorname) { DICT_VENDOR *vend; @@ -441,16 +433,13 @@ rc_dict_findvend(rc_handle const *rh, char const *vendorname) return NULL; } -/* - * Function: rc_dict_getvend - * - * Purpose: Return the full vendor structure based on the - * vendor id number. +/** Lookup a DICT_VENDOR by its IANA number * + * @param rh a handle to parsed configuration. + * @param vendorpec the vendor ID. + * @return the full vendor structure based on the vendor id number. */ - -DICT_VENDOR * -rc_dict_getvend (rc_handle const *rh, int vendorpec) +DICT_VENDOR *rc_dict_getvend (rc_handle const *rh, int vendorpec) { DICT_VENDOR *vend; @@ -460,16 +449,14 @@ rc_dict_getvend (rc_handle const *rh, int vendorpec) return NULL; } -/* - * Function: dict_getval - * - * Purpose: Return the full value structure based on the - * actual value and the associated attribute name. +/** Get DICT_VALUE based on attribute name and integer value number * + * @param rh a handle to parsed configuration. + * @param value the attribute value. + * @param attrname the attribute name. + * @return the full value structure based on the actual value and the associated attribute name. */ - -DICT_VALUE * -rc_dict_getval (rc_handle const *rh, uint32_t value, char const *attrname) +DICT_VALUE *rc_dict_getval(rc_handle const *rh, uint32_t value, char const *attrname) { DICT_VALUE *val; @@ -486,16 +473,11 @@ rc_dict_getval (rc_handle const *rh, uint32_t value, char const *attrname) return NULL; } -/* - * Function: rc_dict_free +/** Frees the allocated av lists * - * Purpose: Free allocated av lists - * - * Arguments: Radius Client handle + * @param rh a handle to parsed configuration. */ - -void -rc_dict_free(rc_handle *rh) +void rc_dict_free(rc_handle *rh) { DICT_ATTR *attr, *nattr; DICT_VALUE *val, *nval; diff --git a/lib/env.c b/lib/env.c index 03dccf91..e70dd212 100644 --- a/lib/env.c +++ b/lib/env.c @@ -13,13 +13,11 @@ #include #include -/* - * Function: rc_new_env - * - * Purpose: allocate space for a new environment +/** Allocate space for a new environment * + * @param size the maximum size of the environment. + * @return the initialized environment. */ - ENV *rc_new_env(int size) { ENV *p; @@ -32,7 +30,7 @@ ENV *rc_new_env(int size) if ((p->env = malloc(size * sizeof(char *))) == NULL) { - rc_log(LOG_CRIT, "rc_new_env: out of memory"); + rc_log(LOG_CRIT, "rc_new_env out of memory"); free(p); return NULL; } @@ -45,26 +43,21 @@ ENV *rc_new_env(int size) return p; } -/* - * Function: rc_free_env - * - * Purpose: free the space used by an env structure +/** Free the space used by an env structure * + * @param env an initialized environment value. */ - void rc_free_env(ENV *env) { free(env->env); free(env); } -/* - * Function: rc_add_env - * - * Purpose: add an environment entry +/** Add an environment entry * + * @param env an initialized environment value. + * @return 0 on success or -1 on error. */ - int rc_add_env(ENV *env, char const *name, char const *value) { int i; @@ -88,7 +81,7 @@ int rc_add_env(ENV *env, char const *name, char const *value) snprintf(env->env[i], len, "%s=%s", name, value); } else { if (env->size == (env->maxsize-1)) { - rc_log(LOG_CRIT, "rc_add_env: not enough space for environment (increase ENV_SIZE)"); + rc_log(LOG_CRIT, "rc_add_env not enough space for environment (increase ENV_SIZE)"); return -1; } @@ -108,13 +101,11 @@ int rc_add_env(ENV *env, char const *name, char const *value) return 0; } -/* - * Function: rc_import_env - * - * Purpose: imports an array of null-terminated strings +/** Imports an array of null-terminated strings * + * @param env an initialized environment value. + * @return 0 on success or -1 on error. */ - int rc_import_env(ENV *env, char const **import) { char *es; diff --git a/lib/ip_util.c b/lib/ip_util.c index 8e48189e..39be880e 100644 --- a/lib/ip_util.c +++ b/lib/ip_util.c @@ -31,14 +31,11 @@ static __thread size_t hostbuflen=HOSTBUF_SIZE; static __thread char *tmphostbuf=NULL; -/* - * Function: rc_gethostbyname - * - * Purpose: threadsafe replacement for gethostbyname. +/** Threadsafe replacement for gethostbyname * - * Returns: NULL on failure, hostent pointer on success + * @param hostname the name of the host. + * @return NULL on failure, hostent pointer on success. */ - struct hostent *rc_gethostbyname(char const *hostname) { struct hostent *hp; @@ -47,7 +44,7 @@ struct hostent *rc_gethostbyname(char const *hostname) struct hostent hostbuf; int res; int herr; - + if(!tmphostbuf) tmphostbuf = malloc(hostbuflen); #endif #endif @@ -74,16 +71,15 @@ struct hostent *rc_gethostbyname(char const *hostname) return NULL; } return hp; -} +} -/* - * Function: rc_gethostbyname - * - * Purpose: threadsafe replacement for gethostbyname. +/** Threadsafe replacement for gethostbyname * - * Returns: NULL on failure, hostent pointer on success + * @param addr an address + * @param length the length of @addr + * @param format %AF_INET or %AF_INET6 + * @return NULL on failure, hostent pointer on success */ - struct hostent *rc_gethostbyaddr(char const *addr, size_t length, int format) { struct hostent *hp; @@ -92,14 +88,14 @@ struct hostent *rc_gethostbyaddr(char const *addr, size_t length, int format) struct hostent hostbuf; int res; int herr; - + if(!tmphostbuf) tmphostbuf = malloc(hostbuflen); #endif #endif #ifdef GETHOSTBYADDR_R #if defined (GETHOSTBYADDRRSTYLE_GNU) - while ((res = gethostbyaddr_r(addr, length, format, &hostbuf, tmphostbuf, hostbuflen, + while ((res = gethostbyaddr_r(addr, length, format, &hostbuf, tmphostbuf, hostbuflen, &hp, &herr)) == ERANGE) { /* Enlarge the buffer */ @@ -120,17 +116,13 @@ struct hostent *rc_gethostbyaddr(char const *addr, size_t length, int format) return NULL; } return hp; -} +} -/* - * Function: rc_get_ipaddr - * - * Purpose: return an IP address in host long notation from a host - * name or address in dot notation. +/** Return an IP address in host long notation from a host name or address in dot notation * - * Returns: 0 on failure + * @param host the name of the host. + * @return 0 on failure. */ - uint32_t rc_get_ipaddr (char const *host) { struct hostent *hp; @@ -141,21 +133,17 @@ uint32_t rc_get_ipaddr (char const *host) } else if ((hp = rc_gethostbyname(host)) == NULL) { - rc_log(LOG_ERR,"rc_get_ipaddr: couldn't resolve hostname: %s", host); + rc_log(LOG_ERR,"rc_get_ipaddr couldn't resolve hostname: %s", host); return (uint32_t)0; } return ntohl((*(uint32_t *) hp->h_addr)); } -/* - * Function: rc_good_ipaddr - * - * Purpose: check for valid IP address in standard dot notation. - * - * Returns: 0 on success, -1 when failure +/** Check for valid IP address in standard dot notation * + * @param addr an IPv4 address in dot notation. + * @return 0 on success, -1 when failure. */ - int rc_good_ipaddr (char const *addr) { int dot_count; @@ -197,14 +185,11 @@ int rc_good_ipaddr (char const *addr) } } -/* - * Function: rc_ip_hostname - * - * Purpose: Return a printable host name (or IP address in dot notation) - * for the supplied IP address. +/** Return a printable host name (or IP address in dot notation) for the supplied IP address * + * @param h_ipaddr an IPv4 address. + * @return the printable hostname. */ - char const *rc_ip_hostname (uint32_t h_ipaddr) { struct hostent *hp; @@ -218,18 +203,16 @@ char const *rc_ip_hostname (uint32_t h_ipaddr) return (hp == NULL) ? "unknown" : hp->h_name; } -/* - * Function: rc_getport - * - * Purpose: get the port number for the supplied request type +/** Get the port number for the supplied request type * + * @param type %AUTH or %ACCT. + * @return the port number. */ - unsigned short rc_getport(int type) { struct servent *svp; - if ((svp = getservbyname ((type==AUTH)?"radius":"radacct", "udp")) == NULL) + if ((svp = getservbyname ((type==AUTH)?"radius""radacct", "udp")) == NULL) { return (type==AUTH) ? PW_AUTH_UDP_PORT : PW_ACCT_UDP_PORT; } else { @@ -237,15 +220,12 @@ unsigned short rc_getport(int type) } } -/* - * Function: rc_own_hostname - * - * Purpose: get the hostname of this machine - * - * Returns -1 on failure, 0 on success +/** Get the hostname of this machine * + * @param hostname will hold the name of the host. + * @param len the size of hostname. + * @return -1 on failure, 0 on success. */ - int rc_own_hostname(char *hostname, int len) { @@ -256,7 +236,7 @@ rc_own_hostname(char *hostname, int len) #if defined(HAVE_UNAME) if (uname(&uts) < 0) { - rc_log(LOG_ERR,"rc_own_hostname: couldn't get own hostname"); + rc_log(LOG_ERR,"rc_own_hostname couldn't get own hostname"); return -1; } strlcpy(hostname, uts.nodename, len); @@ -279,15 +259,11 @@ rc_own_hostname(char *hostname, int len) return 0; } -/* - * Function: rc_own_ipaddress - * - * Purpose: get the IP address of this host in host order - * - * Returns: IP address on success, 0 on failure +/** Get the IPv4 address of this host in host order * + * @param rh a handle to parsed configuration. + * @return IP address on success, 0 on failure. */ - uint32_t rc_own_ipaddress(rc_handle *rh) { char hostname[256]; @@ -301,7 +277,7 @@ uint32_t rc_own_ipaddress(rc_handle *rh) strlcpy(hostname, rc_conf_str(rh, "bindaddr"), sizeof(hostname)); } if ((rh->this_host_ipaddr = rc_get_ipaddr (hostname)) == 0) { - rc_log(LOG_ERR, "rc_own_ipaddress: couldn't get own IP address"); + rc_log(LOG_ERR, "rc_own_ipaddress couldn't get own IP address"); return 0; } } @@ -309,16 +285,11 @@ uint32_t rc_own_ipaddress(rc_handle *rh) return rh->this_host_ipaddr; } -/* - * Function: rc_own_bind_ipaddress - * - * Purpose: get the IP address to be used as a source address - * for sending requests in host order - * - * Returns: IP address +/** Get the IP address to be used as a source address for sending requests in host order * + * @param rh to configure bind address for. + * @return an IPv4 address. */ - uint32_t rc_own_bind_ipaddress(rc_handle *rh) { char hostname[256]; @@ -329,7 +300,7 @@ uint32_t rc_own_bind_ipaddress(rc_handle *rh) rh->this_host_bind_ipaddr = malloc(sizeof(*rh->this_host_bind_ipaddr)); if (rh->this_host_bind_ipaddr == NULL) - rc_log(LOG_CRIT, "rc_own_bind_ipaddress: out of memory"); + rc_log(LOG_CRIT, "rc_own_bind_ipaddress out of memory"); if (rc_conf_str(rh, "bindaddr") == NULL || strcmp(rc_conf_str(rh, "bindaddr"), "*") == 0) { rval = INADDR_ANY; @@ -346,26 +317,23 @@ uint32_t rc_own_bind_ipaddress(rc_handle *rh) return rval; } -/* - * Function: rc_get_srcaddr +/** Find outbound interface address for a given destination * - * Purpose: given remote address find local address which the - * system will use as a source address for sending - * datagrams to that remote address - * - * Returns: 0 in success, -1 on failure, address is filled into - * the first argument. + * Given remote address find local address which the system will use as a source address for sending + * datagrams to that remote address. * + * @param lia local address. + * @param ria the remove address. + * @return 0 in success, -1 on failure, address is filled into the first argument. */ -int -rc_get_srcaddr(struct sockaddr *lia, struct sockaddr *ria) +int rc_get_srcaddr(struct sockaddr *lia, struct sockaddr *ria) { int temp_sock; socklen_t namelen; temp_sock = socket(ria->sa_family, SOCK_DGRAM, 0); if (temp_sock == -1) { - rc_log(LOG_ERR, "rc_get_srcaddr: socket: %s", strerror(errno)); + rc_log(LOG_ERR, "rc_get_srcaddr socket: %s", strerror(errno)); return -1; } diff --git a/lib/log.c b/lib/log.c index 09b01a2e..ae2b9802 100644 --- a/lib/log.c +++ b/lib/log.c @@ -13,17 +13,10 @@ #include #include -/* - * Function: rc_openlog - * - * Purpose: open log - * - * Arguments: identification string - * - * Returns: nothing +/** Opens system log * + * @param ident the name of the program. */ - void rc_openlog(char const *ident) { #ifndef _MSC_VER /* TODO: Fix me */ @@ -31,25 +24,19 @@ void rc_openlog(char const *ident) #endif } -/* - * Function: rc_log - * - * Purpose: log information - * - * Arguments: priority (just like syslog), rest like printf - * - * Returns: nothing +/** Logs information on system log * + * @param prio the syslog priority. + * @param format the format of the data to print. */ - void rc_log(int prio, char const *format, ...) { char buff[1024]; va_list ap; va_start(ap,format); - vsnprintf(buff, sizeof(buff), format, ap); - va_end(ap); + vsnprintf(buff, sizeof(buff), format, ap); + va_end(ap); #ifndef _MSC_VER /* TODO: Fix me */ syslog(prio, "%s", buff); diff --git a/lib/md5.h b/lib/md5.h index fcbaf91f..4302a3f8 100644 --- a/lib/md5.h +++ b/lib/md5.h @@ -63,9 +63,9 @@ #define MD5_DIGEST_LENGTH 16 typedef struct MD5Context { - uint32_t state[4]; /* state */ - uint32_t count[2]; /* number of bits, mod 2^64 */ - uint8_t buffer[MD5_BLOCK_LENGTH]; /* input buffer */ + uint32_t state[4]; //!< State. + uint32_t count[2]; //!< Number of bits, mod 2^64. + uint8_t buffer[MD5_BLOCK_LENGTH]; //!< Input buffer. } MD5_CTX; /* include */ diff --git a/lib/options.h b/lib/options.h index 05b66dfd..6587bdbc 100644 --- a/lib/options.h +++ b/lib/options.h @@ -12,20 +12,20 @@ #define OPTION_LEN 64 /* ids for different option types */ -#define OT_STR (1<<0) /* string */ -#define OT_INT (1<<1) /* integer */ -#define OT_SRV (1<<2) /* server list */ -#define OT_AUO (1<<3) /* authentication order */ +#define OT_STR (1<<0) //!< string. +#define OT_INT (1<<1) //!< integer. +#define OT_SRV (1<<2) //!< server list. +#define OT_AUO (1<<3) //!< authentication order. -#define OT_ANY ((unsigned int)~0) /* used internally */ +#define OT_ANY ((unsigned int)~0) //!< Used internally. /* status types */ -#define ST_UNDEF (1<<0) /* option is undefined */ +#define ST_UNDEF (1<<0) //!< option is undefined. typedef struct _option { - char name[OPTION_LEN]; /* name of the option */ - int type, status; /* type and status */ - void *val; /* pointer to option value */ + char name[OPTION_LEN]; //!< name of the option. + int type, status; //!< type and status. + void *val; //!< pointer to option value. } OPTION; static OPTION config_options_default[] = { diff --git a/lib/rc-md5.c b/lib/rc-md5.c index be9fbcbd..640aad23 100644 --- a/lib/rc-md5.c +++ b/lib/rc-md5.c @@ -8,12 +8,17 @@ * FORCE MD5 TO USE OUR MD5 HEADER FILE! * * If we don't do this, it might pick up the systems broken MD5. - * - Alan DeKok */ #include "rc-md5.h" +/** Hash the provided data using MD5 + * + * @param[out] output will hold a 16-byte checksum. + * @param[in] input pointer to data to hash. + * @param[in] inlen the length of input. + */ void rc_md5_calc(unsigned char *output, unsigned char const *input, - size_t inlen) + size_t inlen) { MD5_CTX context; diff --git a/lib/sendserver.c b/lib/sendserver.c index fd100acc..8cbbcfe5 100644 --- a/lib/sendserver.c +++ b/lib/sendserver.c @@ -27,15 +27,13 @@ static void rc_random_vector (unsigned char *); static int rc_check_reply (AUTH_HDR *, int, char const *, unsigned char const *, unsigned char); -/* - * Function: rc_pack_list - * - * Purpose: Packs an attribute value pair list into a buffer. - * - * Returns: Number of octets packed. +/** Packs an attribute value pair list into a buffer * + * @param vp a pointer to a #VALUE_PAIR. + * @param secret the secret used by the server. + * @param auth a pointer to #AUTH_HDR. + * @return The number of octets packed. */ - static int rc_pack_list (VALUE_PAIR *vp, char *secret, AUTH_HDR *auth) { int length, i, pc, padded_length; @@ -64,7 +62,7 @@ static int rc_pack_list (VALUE_PAIR *vp, char *secret, AUTH_HDR *auth) switch (vp->attribute) { - case PW_USER_PASSWORD: + case PW_USER_PASSWORD /* Encrypt the password */ @@ -187,9 +185,12 @@ static int rc_pack_list (VALUE_PAIR *vp, char *secret, AUTH_HDR *auth) return total_length; } -/* Function strappend +/** Appends a string to the provided buffer * - * Purpose: appends a string to the provided buffer + * @param dest the destination buffer. + * @param max_size the maximum size available in the destination buffer. + * @param pos the current position in the dest buffer; initially must be zero. + * @param src the source buffer to append. */ static void strappend(char *dest, unsigned max_size, int *pos, const char *src) { @@ -208,13 +209,15 @@ static void strappend(char *dest, unsigned max_size, int *pos, const char *src) return; } -/* - * Function: rc_send_server - * - * Purpose: send a request to a RADIUS server and wait for the reply +/** Sends a request to a RADIUS server and waits for the reply * + * @param rh a handle to parsed configuration + * @param data a pointer to a #SEND_DATA structure + * @param msg must be an array of %PW_MAX_MSG_SIZE or %NULL; will contain the concatenation of + * any %PW_REPLY_MESSAGE received. + * @return %OK_RC (0) on success, %TIMEOUT_RC on timeout %REJECT_RC on acess reject, or negative + * on failure as return value. */ - int rc_send_server (rc_handle *rh, SEND_DATA *data, char *msg) { int sockfd; @@ -262,7 +265,7 @@ int rc_send_server (rc_handle *rh, SEND_DATA *data, char *msg) */ if (rc_find_server (rh, server_name, &auth_ipaddr, secret) != 0) { - rc_log(LOG_ERR, "rc_send_server: unable to find server: %s", server_name); + rc_log(LOG_ERR, "rc_send_server unable to find server: %s", server_name); return ERROR_RC; } /*}*/ @@ -341,7 +344,7 @@ int rc_send_server (rc_handle *rh, SEND_DATA *data, char *msg) auth->length = htons ((unsigned short) total_length); } - DEBUG(LOG_ERR, "DEBUG: local %s : 0, remote %s : %u\n", + DEBUG(LOG_ERR, "DEBUG: local %s : 0, remote %s : %u\n", inet_ntoa(sinlocal.sin_addr), inet_ntoa(sinremote.sin_addr), data->svc_port); @@ -494,16 +497,15 @@ int rc_send_server (rc_handle *rh, SEND_DATA *data, char *msg) return result; } -/* - * Function: rc_check_reply - * - * Purpose: verify items in returned packet. - * - * Returns: OK_RC -- upon success, - * BADRESP_RC -- if anything looks funny. +/** Verify items in returned packet * + * @param auth a pointer to #AUTH_HDR. + * @param bufferlen the available buffer length. + * @param secret the secret used by the server. + * @param vector a random vector of %AUTH_VECTOR_LEN. + * @param seq_nbr a unique sequence number. + * @return %OK_RC upon success, %BADRESP_RC if anything looks funny. */ - static int rc_check_reply (AUTH_HDR *auth, int bufferlen, char const *secret, unsigned char const *vector, uint8_t seq_nbr) { int secretlen; @@ -520,7 +522,7 @@ static int rc_check_reply (AUTH_HDR *auth, int bufferlen, char const *secret, un /* Do sanity checks on packet length */ if ((totallen < 20) || (totallen > 4096)) { - rc_log(LOG_ERR, "rc_check_reply: received RADIUS server response with invalid length"); + rc_log(LOG_ERR, "rc_check_reply received RADIUS server response with invalid length"); return BADRESP_RC; } @@ -610,15 +612,10 @@ static int rc_check_reply (AUTH_HDR *auth, int bufferlen, char const *secret, un } -/* - * Function: rc_random_vector - * - * Purpose: generates a random vector of AUTH_VECTOR_LEN octets. - * - * Returns: the vector (call by reference) +/** Generates a random vector of AUTH_VECTOR_LEN octets * + * @param vector a buffer with at least %AUTH_VECTOR_LEN bytes. */ - static void rc_random_vector (unsigned char *vector) { int randno; diff --git a/lib/util.c b/lib/util.c index 0cd4bff6..a6beb17f 100644 --- a/lib/util.c +++ b/lib/util.c @@ -25,12 +25,6 @@ #define RC_BUFSIZ 1024 -/* - * Function: rc_str2tm - * - * Purpose: Turns printable string into correct tm struct entries. - * - */ static char const * months[] = { @@ -38,6 +32,11 @@ static char const * months[] = "Jul", "Aug", "Sep", "Oct", "Nov", "Dec" }; +/** Turns printable string into correct tm struct entries + * + * @param valstr the printable date in 'day month year' format. + * @param tm the output struct. + */ void rc_str2tm (char const *valstr, struct tm *tm) { int i; @@ -59,20 +58,19 @@ void rc_str2tm (char const *valstr, struct tm *tm) tm->tm_year = atoi (&valstr[7]) - 1900; } -/* - * Function: rc_getifname - * - * Purpose: get the network interface name associated with this tty +/** Get the network interface name associated with this tty * + * @param rh a handle to parsed configuration. + * @param tty the name of the tty. + * @return the network iface name. */ - char *rc_getifname(rc_handle *rh, char const *tty) { #if defined(BSD4_4) || defined(linux) int fd; if ((fd = open(tty, O_RDWR|O_NDELAY)) < 0) { - rc_log(LOG_ERR, "rc_getifname: can't open %s: %s", tty, strerror(errno)); + rc_log(LOG_ERR, "rc_getifname can't open %s: %s", tty, strerror(errno)); return NULL; } #endif @@ -100,11 +98,12 @@ char *rc_getifname(rc_handle *rh, char const *tty) #endif } -/* - * Function: rc_getstr - * - * Purpose: Reads in a string from the user (with or witout echo) +/** Reads in a string from the user (with or witout echo) * + * @param rh a handle to parsed configuration. + * @param prompt the prompt to print. + * @param do_echo whether to echo characters. + * @return the data user typed or NULL. */ #ifndef _MSC_VER char *rc_getstr (rc_handle *rh, char const *prompt, int do_echo) @@ -163,7 +162,7 @@ char *rc_getstr (rc_handle *rh, char const *prompt, int do_echo) (void)write(out, prompt, strlen(prompt)); /* well, this looks ugly, but it handles the following end of line - markers: \r \r\0 \r\n \n \n\r, at least at a second pass */ + markers \r \r\0 \r\n \n \n\r, at least at a second pass */ p = rh->buf; for (;;) @@ -224,31 +223,25 @@ void rc_mdelay(int msecs) select(0, NULL, NULL, NULL, &tv); } -/* - * Function: rc_mksid - * - * Purpose: generate a quite unique string +/** Generate a quite unique string * - * Remarks: not that unique at all... + * @note not that unique at all... * + * @param rh a handle to parsed configuration. + * @return unique string. Memory does not need to be freed. */ -char * -rc_mksid (rc_handle *rh) +char *rc_mksid (rc_handle *rh) { snprintf (rh->buf1, sizeof(rh->buf1), "%08lX%04X", (unsigned long int) time (NULL), (unsigned int) getpid ()); return rh->buf1; } -/* - * Function: rc_new - * - * Purpose: Initialises new Radius Client handle +/** Initialises new Radius Client handle * + * @return a new rc_handle (free with rc_destroy). */ - -rc_handle * -rc_new(void) +rc_handle *rc_new(void) { rc_handle *rh; @@ -261,17 +254,12 @@ rc_new(void) return rh; } -/* - * Function: rc_destroy - * - * Purpose: Destroys Radius Client handle reclaiming all memory +/** Destroys Radius Client handle reclaiming all memory * + * @param rh The Radius client handle to free. */ - -void -rc_destroy(rc_handle *rh) +void rc_destroy(rc_handle *rh) { - rc_map2id_free(rh); rc_dict_free(rh); rc_config_free(rh); @@ -280,15 +268,13 @@ rc_destroy(rc_handle *rh) free(rh); } -/* - * Function: rc_fgetln - * - * Purpose: Get next line from the stream. +/** Get next line from the stream. * + * @param fp a %FILE pointer. + * @param len output length. + * @return the next line in an allocated buffer. */ - -char * -rc_fgetln(FILE *fp, size_t *len) +char *rc_fgetln(FILE *fp, size_t *len) { static char *buf = NULL; static size_t bufsiz = 0; @@ -328,16 +314,12 @@ rc_fgetln(FILE *fp, size_t *len) return buf; } -/* - * Function: rc_getctime - * - * Purpose: Get current time (seconds since epoch) expressed as - * double-precision floating point number. +/** Returns the current time as a double. * + * @return current time (seconds since epoch) expressed as + * double-precision floating point number. */ - -double -rc_getctime(void) +double rc_getctime(void) { struct timeval timev;