auth(s): documentation updated

modules_s/auth/README

@@ -10,9 +10,12 @@ Juha Heinanen
    TutPro Inc
    <[email protected]>
 
+Daniel-Constantin Mierla
+
+   asipto.com
+   <[email protected]>
+
    Copyright © 2002, 2003 FhG FOKUS
-   Revision History
-   Revision $Revision$ $Date$
      __________________________________________________________________
 
    1.1. Overview
@@ -37,6 +40,10 @@ Juha Heinanen
    1.4. Functions
 
         1.4.1. consume_credentials()
+        1.4.2. www_challenge(realm, flags)
+        1.4.3. proxy_challenge(realm, flags)
+        1.4.4. pv_www_authenticate(realm, passwd, flags)
+        1.4.5. pv_proxy_authenticate(realm, passwd, flags)
 
 1.1. Overview
 
@@ -58,9 +65,6 @@ Juha Heinanen
 
 1.3. Parameters
 
-   Revision History
-   Revision $Revision$ $Date$
-
 1.3.1.  auth_checks_register, auth_checks_no_dlg, and auth_checks_in_dlg
 (flags)
 
@@ -111,7 +115,9 @@ Juha Heinanen
    secret (32 chars or longer are recommended).
 
    Example 1. Setting the auth_checks_register module parameter
+...
 modparam("auth", "auth_checks_register", 2) # callid
+...
 
 1.3.2. qop (string)
 
@@ -131,7 +137,9 @@ modparam("auth", "auth_checks_register", 2) # callid
    See also: nonce_count.
 
    Example 2. qop example
+...
 modparam("auth", "qop", "auth")   # set qop=auth
+...
 
 1.3.3. nonce_count (boolean)
 
@@ -178,6 +186,7 @@ modparam("auth", "qop", "auth")   # set qop=auth
    nonce_expire. one_time_nonce.
 
    Example 3. nonce_count example
+...
 modparam("auth", "nonce_count", 1) # enable nonce_count support
 modparam("auth", "qop", "auth")    # enable qop=auth
 
@@ -265,8 +274,10 @@ route{
    nonce_count.
 
    Example 4. one_time_nonce example
+...
 modparam("auth", "one_time_nonce", 1)
 # Note: stateful mode should be used, see the nonce_count example
+...
 
 1.3.5. nid_pool_no (integer)
 
@@ -300,7 +311,9 @@ modparam("auth", "one_time_nonce", 1)
    otn_in_flight_no.
 
    Example 5. nid_pool_no example
+...
 modparam("auth", "nid_pool_no", 4)
+...
 
 1.3.6. nc_array_size (integer)
 
@@ -322,7 +335,9 @@ modparam("auth", "nid_pool_no", 4)
    See also: nonce_count and nid_pool_no.
 
    Example 6. nc_array_size example
+...
 modparam("auth", "nc_array_size", 4194304)   # 4Mb
+...
 
 1.3.7. nc_array_order (integer)
 
@@ -337,7 +352,9 @@ modparam("auth", "nc_array_size", 4194304)   # 4Mb
    See also: nonce_count, nc_array_size and nid_pool_no.
 
    Example 7. nc_array_order example
+...
 modparam("auth", "nc_array_order", 22)   # 4Mb
+...
 
 1.3.8. otn_in_flight_no (integer)
 
@@ -361,7 +378,9 @@ modparam("auth", "nc_array_order", 22)   # 4Mb
    See also: one_time_nonce and nid_pool_no.
 
    Example 8. otn_in_flight_no example
+...
 modparam("auth", "otn_in_flight_no", 8388608)   # 8 Mb (1Mb memory)
+...
 
 1.3.9. otn_in_flight_order (integer)
 
@@ -377,14 +396,18 @@ modparam("auth", "otn_in_flight_no", 8388608)   # 8 Mb (1Mb memory)
    See also: one_time_nonce, otn_in_flight_no and nid_pool_no.
 
    Example 9. otn_in_flight_order example
+...
 modparam("auth", "otn_in_flight_order", 23)   # 8 Mb (1Mb memory)
+...
 
 1.3.10. secret (string)
 
    Default value is randomly generated string.
 
    Example 10. Setting secret module parameter
+...
 modparam("auth", "secret", "johndoessecretphrase")
+...
 
 1.3.11. nonce_expire (integer)
 
@@ -399,7 +422,9 @@ modparam("auth", "secret", "johndoessecretphrase")
    The value is in seconds and default value is 300 seconds.
 
    Example 11. nonce_expire example
+...
 modparam("auth", "nonce_expire", 600)   # Set nonce_expire to 600s
+...
 
 1.3.12. nonce_auth_max_drift (integer)
 
@@ -419,13 +444,12 @@ modparam("auth", "nonce_expire", 600)   # Set nonce_expire to 600s
    See also: nonce_expire.
 
    Example 12. nonce_auth_max_drift example
+...
 modparam("auth", "nonce_auth_max_drift", 1)   # set max drift to 1 s
+...
 
 1.4. Functions
 
-   Revision History
-   Revision $Revision$ $Date$
-
 1.4.1. consume_credentials()
 
    This function removes previously authorized credentials from the
@@ -433,12 +457,135 @@ modparam("auth", "nonce_auth_max_drift", 1)   # set max drift to 1 s
    message will not contain credentials there were used by this server.
    This ensures that the proxy will not reveal information about
    credentials used to downstream elements and also the message will be a
-   little bit shorter. The function must be called after www_authorize or
-   proxy_authorize.
+   little bit shorter. The function must be called after www_authorize,
+   proxy_authorize, www_authenticate or proxy_authenticate.
 
    Example 13. consume_credentials example
 ...
-if (www_authorize("", "subscriber)) {
+if (www_authenticate("realm", "subscriber)) {
     consume_credentials();
 };
 ...
+
+1.4.2.  www_challenge(realm, flags)
+
+   The function challenges a user agent. It will generate a WWW-Authorize
+   header field containing a digest challenge, it will put the header
+   field into a response generated from the request the server is
+   processing and send the reply. Upon reception of such a reply the user
+   agent should compute credentials and retry the request. For more
+   information regarding digest authentication see RFC2617.
+
+   Meaning of the parameters is as follows:
+     * realm - Realm is a opaque string that the user agent should present
+       to the user so he can decide what username and password to use.
+       Usually this is domain of the host the server is running on.
+       It must not be empty string “”. In case of REGISTER requests To
+       header field domain (e.g., varibale $td) can be used (because this
+       header field represents a user being registered), for all other
+       messages From header field domain can be used (e.g., varibale $fd).
+       The string may contain pseudo variables.
+     * flags - Value of this parameter can be a bitmask of following:
+          + 1 - build challenge header with qop=auth
+          + 2 - build challenge header with qop=auth-int
+          + 4 - do not send '500 Internal Server Error' reply
+            automatically in failure cases (error code is returned to
+            config)
+
+   This function can be used from REQUEST_ROUTE.
+
+   Example 14. www_challenge usage
+...
+if (!www_authenticate("$td", "subscriber")) {
+        www_challenge("$td", "1");
+}
+...
+
+1.4.3.  proxy_challenge(realm, flags)
+
+   The function challenges a user agent. It will generate a
+   Proxy-Authorize header field containing a digest challenge, it will put
+   the header field into a response generated from the request the server
+   is processing and send the reply. Upon reception of such a reply the
+   user agent should compute credentials and retry the request. For more
+   information regarding digest authentication see RFC2617.
+
+   Meaning of the parameters the same as for function www_challenge(realm,
+   flags)
+
+   This function can be used from REQUEST_ROUTE.
+
+   Example 15. proxy_challenge usage
+...
+if (!proxy_authenticate("$fd", "subscriber)) {
+        proxy_challenge("$fd", "1");
+};
+...
+
+1.4.4.  pv_www_authenticate(realm, passwd, flags)
+
+   The function verifies credentials according to RFC2617. If the
+   credentials are verified successfully then the function will succeed
+   and mark the credentials as authorized (marked credentials can be later
+   used by some other functions). If the function was unable to verify the
+   credentials for some reason then it will fail and the script should
+   call www_challenge which will challenge the user again.
+
+   Negative codes may be interpreted as follows:
+     * -1 (generic error) - some generic error occurred and no reply was
+       sent out;
+     * -2 (invalid password) - wrong password;
+     * -3 (invalid user) - authentication user does not exist.
+
+   Meaning of the parameters is as follows:
+     * realm - Realm is a opaque string that the user agent should present
+       to the user so he can decide what username and password to use.
+       Usually this is domain of the host the server is running on.
+       It must not be empty string “”. In case of REGISTER requests To
+       header field domain (e.g., varibale $td) can be used (because this
+       header field represents a user being registered), for all other
+       messages From header field domain can be used (e.g., varibale $fd).
+       The string may contain pseudo variables.
+     * passwd - the password to be used for authentication. Can contain
+       config variables. Username is taken from Auth header.
+     * flags - the value of this parameter can be a bitmask of following:
+          + 1 - the value of password parameter is HA1 format
+          + 2 - build challenge header with no qop and add it to avp
+          + 4 - build challenge header with qop=auth and add it to avp
+          + 8 - build challenge header with qop=auth-int and add it to avp
+
+   When challenge header is built and stored in avp, append_to_reply() and
+   sl reply functions can be used to send appropriate SIP reply to
+   challenge for authentication.
+
+   This function can be used from REQUEST_ROUTE.
+
+   Example 16. pv_www_authenticate usage
+...
+if (!pv_www_authenticate("$td", "123abc", "0")) {
+        www_challenge("$td", "1");
+};
+...
+
+1.4.5.  pv_proxy_authenticate(realm, passwd, flags)
+
+   The function verifies credentials according to RFC2617. If the
+   credentials are verified successfully then the function will succeed
+   and mark the credentials as authorized (marked credentials can be later
+   used by some other functions). If the function was unable to verify the
+   credentials for some reason then it will fail and the script should
+   call proxy_challenge which will challenge the user again. For more
+   about the negative return codes, see the above function.
+
+   Meaning of the parameters is the same as for pv_www_authenticate(realm,
+   passwd, flags)
+
+   This function can be used from REQUEST_ROUTE.
+
+   Example 17. pv_proxy_authenticate usage
+...
+$avp(password)="xyz";
+if (!pv_proxy_authenticate("$fd", "$avp(password)", "0")) {
+        proxy_challenge("$fd", "1");
+};
+...

modules_s/auth/doc/auth.xml

@@ -17,6 +17,12 @@
 		<affiliation><orgname>TutPro Inc</orgname></affiliation>
 		<email>[email protected]</email>
 	    </author>
+	    <author>
+		<firstname>Daniel-Constantin</firstname>
+		<surname>Mierla</surname>
+		<affiliation><orgname>asipto.com</orgname></affiliation>
+		<email>[email protected]</email>
+	    </author>
 	</authorgroup>
 
 	<copyright>
@@ -25,12 +31,6 @@
 	    <holder>FhG FOKUS</holder>
 	</copyright>
 
-	<revhistory>
-	    <revision>
-		<revnumber>$Revision$</revnumber>
-		<date>$Date$</date>
-	    </revision>
-	</revhistory>
     </sectioninfo>
 
     <title>Auth Module</title>

modules_s/auth/doc/functions.xml

@@ -3,14 +3,6 @@
    "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 
 <section id="auth.functions" xmlns:xi="http://www.w3.org/2001/XInclude">
-    <sectioninfo>
-	<revhistory>
-	    <revision>
-		<revnumber>$Revision$</revnumber>
-		<date>$Date$</date>
-	    </revision>
-	</revhistory>
-    </sectioninfo>
 
     <title>Functions</title>
     
@@ -23,18 +15,248 @@
 	    this server. This ensures that the proxy will not reveal
 	    information about credentials used to downstream elements and also
 	    the message will be a little bit shorter. The function must be
-	    called after <function>www_authorize</function> or
-	    <function>proxy_authorize</function>.
+	    called after <function>www_authorize</function>,
+		<function>proxy_authorize</function>,
+		<function>www_authenticate</function> or
+	    <function>proxy_authenticate</function>.
 	</para>
 	<example>
 	    <title>consume_credentials example</title>
 	    <programlisting>
 ...
-if (www_authorize("", "subscriber)) {
+if (www_authenticate("realm", "subscriber)) {
     consume_credentials();
 };
 ...
 	    </programlisting>
 	</example>
     </section>
+	<section id="www_challenge">
+		<title>
+			<function moreinfo="none">www_challenge(realm, flags)</function>
+		</title>
+		<para>
+		The function challenges a user agent. It will generate a
+		WWW-Authorize header field containing a digest challenge, it will
+		put the header field into a response generated from the request the
+		server is processing and send the reply. Upon reception of such a
+		reply the user agent should compute credentials and retry the
+		request. For more information regarding digest authentication
+		see RFC2617.
+		</para>
+		<para>Meaning of the parameters is as follows:</para>
+		<itemizedlist>
+		<listitem>
+			<para><emphasis>realm</emphasis> - Realm is a opaque string that
+			the user agent should present to the user so he can decide what
+			username and password to use. Usually this is domain of the host
+			the server is running on.
+			</para>
+			<para>
+			It must not be empty string <quote></quote>. In case of REGISTER
+			requests To header field domain (e.g., varibale $td) can be used
+			(because this header field represents a user being registered),
+			for all other messages From header field domain can be used
+			(e.g., varibale $fd).
+			</para>
+			<para>
+			The string may contain pseudo variables.
+			</para>
+		</listitem>
+		<listitem>
+			<para><emphasis>flags</emphasis> - Value of this parameter can be
+			a bitmask of following:</para>
+			<itemizedlist>
+			<listitem>
+				<para><emphasis>1</emphasis> - build challenge header with
+					qop=auth</para>
+			</listitem>
+			<listitem>
+				<para><emphasis>2</emphasis> - build challenge header with
+					qop=auth-int</para>
+			</listitem>
+			<listitem>
+				<para><emphasis>4</emphasis> - do not send '500 Internal
+					Server Error' reply automatically in failure cases
+					(error code is returned to config)</para>
+			</listitem>
+			</itemizedlist>
+		</listitem>
+		</itemizedlist>
+		<para>
+		This function can be used from REQUEST_ROUTE.
+		</para>
+
+		<example>
+		<title>www_challenge usage</title>
+		<programlisting format="linespecific">
+...
+if (!www_authenticate("$td", "subscriber")) {
+	www_challenge("$td", "1");
+}
+...
+</programlisting>
+		</example>
+	</section>
+
+	<section id="proxy_challenge">
+		<title>
+			<function moreinfo="none">proxy_challenge(realm, flags)</function>
+		</title>
+		<para>
+		The function challenges a user agent. It will generate a
+		Proxy-Authorize header field containing a digest challenge, it will
+		put the header field into a response generated from the request the
+		server is processing and send the reply. Upon reception of such a
+		reply the user agent should compute credentials and retry the request.
+		For more information regarding digest authentication see RFC2617.
+		</para>
+		<para>Meaning of the parameters the same as for function
+		www_challenge(realm, flags)</para>
+		<para>
+		This function can be used from REQUEST_ROUTE.
+		</para>
+		<example>
+		<title>proxy_challenge usage</title>
+		<programlisting format="linespecific">
+...
+if (!proxy_authenticate("$fd", "subscriber)) {
+	proxy_challenge("$fd", "1");
+};
+...
+</programlisting>
+		</example>
+	</section>
+
+	<section id="pv_www_authenticate">
+		<title>
+		<function moreinfo="none">pv_www_authenticate(realm, passwd, flags)</function>
+		</title>
+		<para>
+		The function verifies credentials according to
+		<ulink url="http://www.ietf.org/rfc/rfc2617.txt">RFC2617</ulink>.
+		If the credentials are verified successfully then the function
+		will succeed and mark the credentials as authorized (marked
+		credentials can be later used by some other functions). If the
+		function was unable to verify the credentials for some reason
+		then it will fail and the script should
+		call <function moreinfo="none">www_challenge</function> which will
+		challenge the user again.
+		</para>
+		<para>Negative codes may be interpreted as follows:</para>
+		<itemizedlist>
+			<listitem><para>
+			<emphasis>-1 (generic error)</emphasis> - some generic error
+			occurred and no reply was sent out;
+			</para></listitem>
+			<listitem><para>
+			<emphasis>-2 (invalid password)</emphasis> - wrong password;
+			</para></listitem>
+			<listitem><para>
+			<emphasis>-3 (invalid user)</emphasis> - authentication user does
+			not exist.
+			</para></listitem>
+		</itemizedlist>
+		<para>Meaning of the parameters is as follows:</para>
+		<itemizedlist>
+		<listitem>
+			<para><emphasis>realm</emphasis> - Realm is a opaque string that
+			the user agent should present to the user so he can decide what
+			username and password to use. Usually this is domain of the host
+			the server is running on.
+			</para>
+			<para>
+			It must not be empty string <quote></quote>. In case of REGISTER
+			requests To header field domain (e.g., varibale $td) can be used
+			(because this header field represents a user being registered),
+			for all other messages From header field domain can be used
+			(e.g., varibale $fd).
+			</para>
+			<para>
+			The string may contain pseudo variables.
+			</para>
+		</listitem>
+		<listitem>
+			<para><emphasis>passwd</emphasis> - the password to be used
+			for authentication. Can contain config variables. Username is
+			taken from Auth header.</para>
+		</listitem>
+		<listitem>
+			<para><emphasis>flags</emphasis> - the value of this parameter
+				can be a bitmask of following:</para>
+			<itemizedlist>
+			<listitem>
+				<para><emphasis>1</emphasis> - the value of password
+					parameter is HA1 format</para>
+			</listitem>
+			<listitem>
+				<para><emphasis>2</emphasis> - build challenge header with
+					no qop and add it to avp</para>
+			</listitem>
+			<listitem>
+				<para><emphasis>4</emphasis> - build challenge header with
+					qop=auth and add it to avp</para>
+			</listitem>
+			<listitem>
+				<para><emphasis>8</emphasis> - build challenge header with
+					qop=auth-int and add it to avp</para>
+			</listitem>
+			</itemizedlist>
+		</listitem>
+		</itemizedlist>
+		<para>
+		<para>
+			When challenge header is built and stored in avp,
+			append_to_reply() and sl reply functions can be used to send
+			appropriate SIP reply to challenge for authentication.
+		</para>
+		This function can be used from REQUEST_ROUTE.
+		</para>
+		<example>
+		<title><function moreinfo="none">pv_www_authenticate</function>
+		usage</title>
+		<programlisting format="linespecific">
+...
+if (!pv_www_authenticate("$td", "123abc", "0")) {
+	www_challenge("$td", "1");
+};
+...
+</programlisting>
+		</example>
+	</section>
+
+	<section id="pv_proxy_authenticate">
+		<title>
+			<function moreinfo="none">pv_proxy_authenticate(realm, passwd, flags)</function>
+		</title>
+		<para>
+		The function verifies credentials according to
+		<ulink url="http://www.ietf.org/rfc/rfc2617.txt">RFC2617</ulink>. If
+		the credentials are verified successfully then the function will
+		succeed and mark the credentials as authorized (marked credentials can
+		be later used by some other functions). If the function was unable to
+		verify the credentials for some reason then it will fail and
+		the script should call
+		<function moreinfo="none">proxy_challenge</function> which will
+		challenge the user again. For more about the negative return codes,
+		see the above function.
+		</para>
+		<para>Meaning of the parameters is the same as for
+		pv_www_authenticate(realm, passwd, flags)</para>
+		<para>
+		This function can be used from REQUEST_ROUTE.
+		</para>
+		<example>
+		<title>pv_proxy_authenticate usage</title>
+		<programlisting format="linespecific">
+...
+$avp(password)="xyz";
+if (!pv_proxy_authenticate("$fd", "$avp(password)", "0")) {
+	proxy_challenge("$fd", "1");
+};
+...
+</programlisting>
+		</example>
+	</section>
+
 </section>

modules_s/auth/doc/params.xml

@@ -3,14 +3,6 @@
    "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 
 <section id="auth.parameters" xmlns:xi="http://www.w3.org/2001/XInclude">
-    <sectioninfo>
-	<revhistory>
-	    <revision>
-		<revnumber>$Revision$</revnumber>
-		<date>$Date$</date>
-	    </revision>
-	</revhistory>
-    </sectioninfo>
 
     <title>Parameters</title>
     
@@ -81,7 +73,9 @@
 	    <title>Setting the <varname>auth_checks_register</varname> module 
 				parameter</title>
 	    <programlisting>
+...
 modparam("auth", "auth_checks_register", 2) # callid
+...
 	    </programlisting>
 	</example>
     </section>
@@ -115,7 +109,9 @@ modparam("auth", "auth_checks_register", 2) # callid
 	<example>
 	    <title>qop example</title>
 	    <programlisting>
+...
 modparam("auth", "qop", "auth")   # set qop=auth
+...
 	    </programlisting>
 	</example>
     </section>
@@ -190,6 +186,7 @@ modparam("auth", "qop", "auth")   # set qop=auth
 	<example>
 	    <title>nonce_count example</title>
 	    <programlisting>
+...
 modparam("auth", "nonce_count", 1) # enable nonce_count support
 modparam("auth", "qop", "auth")    # enable qop=auth
 
@@ -300,8 +297,10 @@ route{
 	<example>
 	    <title>one_time_nonce example</title>
 	    <programlisting>
+...
 modparam("auth", "one_time_nonce", 1)
 # Note: stateful mode should be used, see the nonce_count example
+...
 	    </programlisting>
 	</example>
 	</section>
@@ -351,7 +350,9 @@ modparam("auth", "one_time_nonce", 1)
 	<example>
 	    <title>nid_pool_no example</title>
 	    <programlisting>
+...
 modparam("auth", "nid_pool_no", 4)
+...
 	    </programlisting>
 	</example>
     </section>
@@ -388,7 +389,9 @@ modparam("auth", "nid_pool_no", 4)
 	<example>
 	    <title>nc_array_size example</title>
 	    <programlisting>
+...
 modparam("auth", "nc_array_size", 4194304)   # 4Mb
+...
 	    </programlisting>
 	</example>
     </section>
@@ -401,7 +404,8 @@ modparam("auth", "nc_array_size", 4194304)   # 4Mb
 		be raised (log2(<varname>nc_array_size</varname>)).
 	</para>
 	<para>
-		<varname>nc_array_size</varname> = 2^<varname>nc_array_order</varname>.			For more details see <varname>nc_array_size</varname>.
+		<varname>nc_array_size</varname> = 2^<varname>nc_array_order</varname>.
+		For more details see <varname>nc_array_size</varname>.
 	</para>
 	<para>
 	    The default value is 20 (1M in-flight nonces, using 1Mb memory).
@@ -415,7 +419,9 @@ modparam("auth", "nc_array_size", 4194304)   # 4Mb
 	<example>
 	    <title>nc_array_order example</title>
 	    <programlisting>
+...
 modparam("auth", "nc_array_order", 22)   # 4Mb
+...
 	    </programlisting>
 	</example>
     </section>
@@ -455,7 +461,9 @@ modparam("auth", "nc_array_order", 22)   # 4Mb
 	<example>
 	    <title>otn_in_flight_no example</title>
 	    <programlisting>
+...
 modparam("auth", "otn_in_flight_no", 8388608)   # 8 Mb (1Mb memory)
+...
 	    </programlisting>
 	</example>
     </section>
@@ -484,7 +492,9 @@ modparam("auth", "otn_in_flight_no", 8388608)   # 8 Mb (1Mb memory)
 	<example>
 	    <title>otn_in_flight_order example</title>
 	    <programlisting>
+...
 modparam("auth", "otn_in_flight_order", 23)   # 8 Mb (1Mb memory)
+...
 	    </programlisting>
 	</example>
     </section>
@@ -497,7 +507,9 @@ modparam("auth", "otn_in_flight_order", 23)   # 8 Mb (1Mb memory)
 	<example>
 	    <title>Setting secret module parameter</title>
 	    <programlisting>
+...
 modparam("auth", "secret", "johndoessecretphrase")
+...
 	    </programlisting>
 	</example>
     </section>
@@ -520,7 +532,9 @@ modparam("auth", "secret", "johndoessecretphrase")
 	<example>
 	    <title>nonce_expire example</title>
 	    <programlisting>
+...
 modparam("auth", "nonce_expire", 600)   # Set nonce_expire to 600s
+...
 	    </programlisting>
 	</example>
     </section>
@@ -550,7 +564,9 @@ modparam("auth", "nonce_expire", 600)   # Set nonce_expire to 600s
 	<example>
 	    <title>nonce_auth_max_drift example</title>
 	    <programlisting>
+...
 modparam("auth", "nonce_auth_max_drift", 1)   # set max drift to 1 s
+...
 	    </programlisting>
 	</example>
     </section>