CVE-2017-3167: add documentation to ap_get_basic_auth_pw()

Now that we've released, add clarifying comments to the now-deprecated
API.

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1799374 13f79535-47bb-0310-9956-ffa450edef68

diff --git a/include/http_protocol.h b/include/http_protocol.h
index c5a6a60e3ea7add61d48d4447dc362dbc46fcb7e..9b8e754100aa2b6c457d9b2d1e6f6437e9c6e570 100644 (file)
--- a/include/http_protocol.h
+++ b/include/http_protocol.h
@@ -577,8 +577,15 @@ AP_DECLARE_HOOK(int, note_auth_failure, (request_rec *r, const char *auth_type))
 
 /**
  * Get the password from the request headers. This function has multiple side
- * effects due to its prior use in the old authentication framework.
- * ap_get_basic_auth_components() should be preferred.
+ * effects due to its prior use in the old authentication framework, including
+ * setting r->user (which is supposed to indicate that the user in question has
+ * been authenticated for the current request).
+ *
+ * Modules which call ap_get_basic_auth_pw() during the authentication phase
+ * MUST either immediately authenticate the user after the call, or else stop
+ * the request immediately with an error response, to avoid incorrectly
+ * authenticating the current request. (See CVE-2017-3167.) The replacement
+ * ap_get_basic_auth_components() API should be preferred.
  *
  * @deprecated @see ap_get_basic_auth_components
  * @param r The current request