[svn-commits] mmichelson: branch mmichelson/authenticate r380814 - /team/mmichelson/authent...

[SVN commits to the Digium repositories]

Author: mmichelson
Date: Mon Feb  4 13:31:54 2013
New Revision: 380814

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=380814
Log:
Add some doxygen to the authenticator code.


Modified:
    team/mmichelson/authenticate/res/res_sip_authenticator_digest.c

Modified: team/mmichelson/authenticate/res/res_sip_authenticator_digest.c
URL: http://svnview.digium.com/svn/asterisk/team/mmichelson/authenticate/res/res_sip_authenticator_digest.c?view=diff&rev=380814&r1=380813&r2=380814
==============================================================================
--- team/mmichelson/authenticate/res/res_sip_authenticator_digest.c (original)
+++ team/mmichelson/authenticate/res/res_sip_authenticator_digest.c Mon Feb  4 13:31:54 2013
@@ -30,6 +30,12 @@
 	<support_level>core</support_level>
  ***/
 
+/*!
+ * \brief Determine if authentication is required
+ *
+ * Authentication is required if the endpoint has at least one auth
+ * section specified
+ */
 static int digest_requires_authentication(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata)
 {
 	return ao2_container_count(endpoint->sip_auths);
@@ -43,8 +49,37 @@
 	ast_free(data);
 }
 
+/*!
+ * \brief Thread-local storage for \ref ast_sip_auth
+ *
+ * The PJSIP authentication API is a bit annoying. When you set
+ * up an authentication server, you specify a lookup callback to
+ * call into when verifying incoming credentials. The problem
+ * with this callback is that it only gives you the realm and
+ * authentication username. In 2.0.5, there is a new version of
+ * the callback you can use that gives the pjsip_rx_data in
+ * addition.
+ *
+ * Unfortunately, the data we actually \b need is the
+ * \ref ast_sip_auth we are currently observing. So we have two
+ * choices:
+ * 1) Use the current PJSIP API and use thread-local storage
+ * to temporarily store our SIP authentication information. Then
+ * in the callback, we can retrieve the authentication info and
+ * use as needed. Given our threading model, this is safe.
+ * 2) Use the 2.0.5 API and temporarily store the authentication
+ * information in the rdata's endpoint_info. Then in the callback,
+ * we can retrieve the authentication info from the rdata.
+ *
+ * I've chosen option 1 since it does not require backporting
+ * any APIs from future versions of PJSIP, plus I feel the
+ * thread-local option is a bit cleaner.
+ */
 AST_THREADSTORAGE_CUSTOM(auth_store, NULL, auth_store_cleanup);
 
+/*!
+ * \brief Store authentication information in thread-local storage
+ */
 static int store_auth(struct ast_sip_auth *auth)
 {
 	struct ast_sip_auth **pointing;
@@ -58,6 +93,9 @@
 	return 0;
 }
 
+/*!
+ * \brief Remove authentication information from thread-local storage
+ */
 static int remove_auth(void)
 {
 	struct ast_sip_auth **pointing;
@@ -71,6 +109,9 @@
 	return 0;
 }
 
+/*!
+ * \brief Retrieve authentication information from thread-local storage
+ */
 static struct ast_sip_auth *get_auth(void)
 {
 	struct ast_sip_auth **auth;
@@ -82,6 +123,21 @@
 	return NULL;
 }
 
+/*!
+ * \brief Lookup callback for authentication verification
+ *
+ * This function is called when we call pjsip_auth_srv_verify(). It
+ * expects us to verify that the realm and account name from the
+ * Authorization header is correct. We are then supposed to supply
+ * a password or MD5 sum of credentials.
+ *
+ * \param pool A memory pool we can use for allocations
+ * \param realm The realm from the Authorization header
+ * \param acc_name the user from the Authorization header
+ * \param[out] info The credentials we need to fill in
+ * \retval PJ_SUCCESS Successful authentication
+ * \retval other Unsuccessful
+ */
 static pj_status_t digest_lookup(pj_pool_t *pool, const pj_str_t *realm,
 		const pj_str_t *acc_name, pjsip_cred_info *info)
 {
@@ -115,6 +171,9 @@
 	return PJ_SUCCESS;
 }
 
+/*!
+ * \brief Common code for initializing a pjsip_auth_srv
+ */
 static void setup_auth_srv(pj_pool_t *pool, pjsip_auth_srv *auth_server, struct ast_sip_auth *auth)
 {
 	pj_str_t realm;
@@ -123,6 +182,15 @@
 	pjsip_auth_srv_init(pool, auth_server, &realm, digest_lookup, 0);
 }
 
+/*!
+ * \brief astobj2 callback for verifying incoming credentials
+ *
+ * \param obj The ast_sip_auth to check against
+ * \param arg The pre-made response. Used only for its pool
+ * \param data The incoming request
+ * \return CMP_MATCH on successful authentication
+ * \return 0 on failed authentication
+ */
 static int verify(void *obj, void *arg, void *data, int flags)
 {
 	struct ast_sip_auth *auth = obj;
@@ -143,6 +211,13 @@
 	return authed == PJ_SUCCESS ? CMP_MATCH : 0;
 }
 
+/*!
+ * \brief astobj2 callback for adding digest challenges to responses
+ *
+ * \param obj The ast_aip_auth to build a challenge from
+ * \param arg The response to add the challenge to
+ * \return 0
+ */
 static int challenge(void *obj, void *arg, int flags)
 {
 	struct ast_sip_auth *auth = obj;
@@ -157,6 +232,15 @@
 	return 0;
 }
 
+/*!
+ * \brief Check authentication using Digest scheme
+ *
+ * This function will check an incoming message against configured authentication
+ * options. If \b any of the incoming Authorization headers result in successful
+ * authentication, then authentication is considered successful.
+ * 
+ * \see ast_sip_check_authentication
+ */
 static enum ast_sip_check_auth_result digest_check_auth(struct ast_sip_endpoint *endpoint,
 		pjsip_rx_data *rdata, pjsip_tx_data *tdata)
 {