auth: Converting to book docbook format

modules/auth/README

@@ -1,4 +1,4 @@
-1. Auth Module
+The Auth Module
 
 Jan Janak
 
@@ -18,41 +18,34 @@ Daniel-Constantin Mierla
    Copyright © 2002, 2003 FhG FOKUS
      __________________________________________________________________
 
-   1.1. Overview
-   1.2. Dependencies
-   1.3. Parameters
-
-        1.3.1. auth_checks_register, auth_checks_no_dlg, and
-                auth_checks_in_dlg (flags)
-
-        1.3.2. qop (string)
-        1.3.3. nonce_count (boolean)
-        1.3.4. one_time_nonce (boolean)
-        1.3.5. nid_pool_no (integer)
-        1.3.6. nc_array_size (integer)
-        1.3.7. nc_array_order (integer)
-        1.3.8. otn_in_flight_no (integer)
-        1.3.9. otn_in_flight_order (integer)
-        1.3.10. secret (string)
-        1.3.11. nonce_expire (integer)
-        1.3.12. nonce_auth_max_drift (integer)
-        1.3.13. force_stateless_reply (boolean)
-        1.3.14. realm_prefix (string)
-        1.3.15. use_domain (boolean)
-
-   1.4. Functions
-
-        1.4.1. consume_credentials()
-        1.4.2. has_credentials(realm)
-        1.4.3. www_challenge(realm, flags)
-        1.4.4. proxy_challenge(realm, flags)
-        1.4.5. auth_challenge(realm, flags)
-        1.4.6. pv_www_authenticate(realm, passwd, flags [, method])
-        1.4.7. pv_proxy_authenticate(realm, passwd, flags)
-        1.4.8. pv_auth_check(realm, passwd, flags, checks)
-        1.4.9. auth_get_www_authenticate(realm, flags, pvdest)
-
-1.1. Overview
+   List of Examples
+
+   1. Setting the auth_checks_register module parameter
+   2. qop example
+   3. nonce_count example
+   4. one_time_nonce example
+   5. nid_pool_no example
+   6. nc_array_size example
+   7. nc_array_order example
+   8. otn_in_flight_no example
+   9. otn_in_flight_order example
+   10. Setting secret module parameter
+   11. nonce_expire example
+   12. nonce_auth_max_drift example
+   13. force_stateless_reply example
+   14. realm_prefix parameter example
+   15. force_stateless_reply example
+   16. consume_credentials example
+   17. consume_credentials example
+   18. www_challenge usage
+   19. proxy_challenge usage
+   20. auth_challenge usage
+   21. pv_www_authenticate usage
+   22. pv_proxy_authenticate usage
+   23. pv_auth_check usage
+   24. auth_get_www_authenticate
+
+1. Overview
 
    This is a generic module that itself doesn't provide all functions
    necessary for authentication but provides functions that are needed by
@@ -66,13 +59,31 @@ Daniel-Constantin Mierla
    functionality. This also allows us to avoid unnecessary dependencies in
    the binary packages.
 
-1.2. Dependencies
+2. Dependencies
 
    The module does not depend on any other module.
 
-1.3. Parameters
-
-1.3.1.  auth_checks_register, auth_checks_no_dlg, and auth_checks_in_dlg
+3. Parameters
+
+   3.1. auth_checks_register, auth_checks_no_dlg, and auth_checks_in_dlg
+          (flags)
+
+   3.2. qop (string)
+   3.3. nonce_count (boolean)
+   3.4. one_time_nonce (boolean)
+   3.5. nid_pool_no (integer)
+   3.6. nc_array_size (integer)
+   3.7. nc_array_order (integer)
+   3.8. otn_in_flight_no (integer)
+   3.9. otn_in_flight_order (integer)
+   3.10. secret (string)
+   3.11. nonce_expire (integer)
+   3.12. nonce_auth_max_drift (integer)
+   3.13. force_stateless_reply (boolean)
+   3.14. realm_prefix (string)
+   3.15. use_domain (boolean)
+
+3.1.  auth_checks_register, auth_checks_no_dlg, and auth_checks_in_dlg
 (flags)
 
    These three module parameters control which optional integrity checks
@@ -158,7 +169,7 @@ modparam("auth", "auth_checks_in_dlg", 15)
 
 ...
 
-1.3.2. qop (string)
+3.2. qop (string)
 
    If set, enable qop for challenges: each challenge will include a qop
    parameter. This is the recommended way, but some older non rfc3261
@@ -180,7 +191,7 @@ modparam("auth", "auth_checks_in_dlg", 15)
 modparam("auth", "qop", "auth")   # set qop=auth
 ...
 
-1.3.3. nonce_count (boolean)
+3.3. nonce_count (boolean)
 
    If enabled the received nc value is remembered and checked against the
    older value (for a successful authentication the received nc must be
@@ -276,7 +287,7 @@ route{
         }
 ...
 
-1.3.4. one_time_nonce (boolean)
+3.4. one_time_nonce (boolean)
 
    If set to 1 nonce reuse is disabled: each nonce is allowed only once,
    in the first reponse to a challenge. All the messages will be
@@ -320,7 +331,7 @@ modparam("auth", "one_time_nonce", 1)
 # Note: stateful mode should be used, see the nonce_count example
 ...
 
-1.3.5. nid_pool_no (integer)
+3.5. nid_pool_no (integer)
 
    Controls the number of partitions for the nonce_count and
    one_time_nonce arrays (it's common to both of them to reduce the nonce
@@ -356,7 +367,7 @@ modparam("auth", "one_time_nonce", 1)
 modparam("auth", "nid_pool_no", 4)
 ...
 
-1.3.6. nc_array_size (integer)
+3.6. nc_array_size (integer)
 
    Maximum number of in-flight nonces for nonce_count. It represents the
    maximum nonces for which state will be kept. When this number is
@@ -380,7 +391,7 @@ modparam("auth", "nid_pool_no", 4)
 modparam("auth", "nc_array_size", 4194304)   # 4Mb
 ...
 
-1.3.7. nc_array_order (integer)
+3.7. nc_array_order (integer)
 
    Equivalent to nc_array_size, but instead of directly specifying the
    size, its value is the power at which 2 should be raised
@@ -397,7 +408,7 @@ modparam("auth", "nc_array_size", 4194304)   # 4Mb
 modparam("auth", "nc_array_order", 22)   # 4Mb
 ...
 
-1.3.8. otn_in_flight_no (integer)
+3.8. otn_in_flight_no (integer)
 
    Maximum number of in-flight nonces for one_time_nonce. It represents
    the maximum number of nonces remembered for the one-time-nonce check.
@@ -423,7 +434,7 @@ modparam("auth", "nc_array_order", 22)   # 4Mb
 modparam("auth", "otn_in_flight_no", 8388608)   # 8 Mb (1Mb memory)
 ...
 
-1.3.9. otn_in_flight_order (integer)
+3.9. otn_in_flight_order (integer)
 
    Equivalent to otn_in_flight_no, but instead of directly specifying the
    size, its value is the power at which 2 should be raised
@@ -441,7 +452,7 @@ modparam("auth", "otn_in_flight_no", 8388608)   # 8 Mb (1Mb memory)
 modparam("auth", "otn_in_flight_order", 23)   # 8 Mb (1Mb memory)
 ...
 
-1.3.10. secret (string)
+3.10. secret (string)
 
    Secret phrase used to calculate the nonce value used to challenge the
    client for authentication.
@@ -461,7 +472,7 @@ modparam("auth", "otn_in_flight_order", 23)   # 8 Mb (1Mb memory)
 modparam("auth", "secret", "johndoessecretphrase")
 ...
 
-1.3.11. nonce_expire (integer)
+3.11. nonce_expire (integer)
 
    Nonces have limited lifetime. After a given period of time nonces will
    be considered invalid. This is to protect replay attacks. Credentials
@@ -478,7 +489,7 @@ modparam("auth", "secret", "johndoessecretphrase")
 modparam("auth", "nonce_expire", 600)   # Set nonce_expire to 600s
 ...
 
-1.3.12. nonce_auth_max_drift (integer)
+3.12. nonce_auth_max_drift (integer)
 
    Maximum difference in seconds between a nonce creation time and the
    current time, if the nonce creation time appears to be in the future.
@@ -500,7 +511,7 @@ modparam("auth", "nonce_expire", 600)   # Set nonce_expire to 600s
 modparam("auth", "nonce_auth_max_drift", 1)   # set max drift to 1 s
 ...
 
-1.3.13. force_stateless_reply (boolean)
+3.13. force_stateless_reply (boolean)
 
    If set to 1, www_challenge() and proxy_challenge() functions send reply
    statelessly no matter if transaction exists or not. If set to 0
@@ -512,7 +523,7 @@ modparam("auth", "nonce_auth_max_drift", 1)   # set max drift to 1 s
 modparam("auth", "force_stateless_reply", 1)
 ...
 
-1.3.14. realm_prefix (string)
+3.14. realm_prefix (string)
 
    Prefix to be automatically strip from realm. As an alternative to SRV
    records (not all SIP clients support SRV lookup), a subdomain of the
@@ -526,7 +537,7 @@ modparam("auth", "force_stateless_reply", 1)
    Example 14. realm_prefix parameter example
 modparam("auth", "realm_prefix", "sip.")
 
-1.3.15. use_domain (boolean)
+3.15. use_domain (boolean)
 
    If set to 1, pv_auth_check() uses domain parts of the URIs to check
    user identity.
@@ -536,9 +547,19 @@ modparam("auth", "realm_prefix", "sip.")
 modparam("auth", "use_domain", 1)
 ...
 
-1.4. Functions
+4. Functions
+
+   4.1. consume_credentials()
+   4.2. has_credentials(realm)
+   4.3. www_challenge(realm, flags)
+   4.4. proxy_challenge(realm, flags)
+   4.5. auth_challenge(realm, flags)
+   4.6. pv_www_authenticate(realm, passwd, flags [, method])
+   4.7. pv_proxy_authenticate(realm, passwd, flags)
+   4.8. pv_auth_check(realm, passwd, flags, checks)
+   4.9. auth_get_www_authenticate(realm, flags, pvdest)
 
-1.4.1. consume_credentials()
+4.1. consume_credentials()
 
    This function removes previously authorized credential headers from the
    message being processed by the server. That means that the downstream
@@ -555,7 +576,7 @@ if (www_authenticate("realm", "subscriber")) {
 };
 ...
 
-1.4.2. has_credentials(realm)
+4.2. has_credentials(realm)
 
    This function returns true of the request has Autorization or
    Proxy-Authorization header with provided realm. The parameter can be
@@ -568,7 +589,7 @@ if (has_credentials("myrealm")) {
 }
 ...
 
-1.4.3.  www_challenge(realm, flags)
+4.3.  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
@@ -605,7 +626,7 @@ if (!www_authenticate("$td", "subscriber")) {
 }
 ...
 
-1.4.4.  proxy_challenge(realm, flags)
+4.4.  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
@@ -627,7 +648,7 @@ if (!proxy_authenticate("$fd", "subscriber")) {
 };
 ...
 
-1.4.5.  auth_challenge(realm, flags)
+4.5.  auth_challenge(realm, flags)
 
    The function challenges a user agent for authentication. It combines
    the functions www_challenge() and proxy_challenge(), by calling
@@ -646,7 +667,7 @@ if (!auth_check("$fd", "subscriber", "1")) {
 };
 ...
 
-1.4.6.  pv_www_authenticate(realm, passwd, flags [, method])
+4.6.  pv_www_authenticate(realm, passwd, flags [, method])
 
    The function verifies credentials according to RFC2617. If the
    credentials are verified successfully then the function will succeed
@@ -699,7 +720,7 @@ if (!pv_www_authenticate("$td", "123abc", "0")) {
 };
 ...
 
-1.4.7.  pv_proxy_authenticate(realm, passwd, flags)
+4.7.  pv_proxy_authenticate(realm, passwd, flags)
 
    The function verifies credentials according to RFC2617. If the
    credentials are verified successfully then the function will succeed
@@ -722,7 +743,7 @@ if (!pv_proxy_authenticate("$fd", "$avp(password)", "0")) {
 };
 ...
 
-1.4.8.  pv_auth_check(realm, passwd, flags, checks)
+4.8.  pv_auth_check(realm, passwd, flags, checks)
 
    The function combines the functionalities of pv_www_authenticate and
    pv_proxy_authenticate, first being exectuted if the SIP request is a
@@ -747,7 +768,7 @@ if (!pv_auth_check("$fd", "$avp(password)", "0", "1")) {
 };
 ...
 
-1.4.9.  auth_get_www_authenticate(realm, flags, pvdest)
+4.9.  auth_get_www_authenticate(realm, flags, pvdest)
 
    Build WWW-Authentication header and set the resulting value in 'pvdest'
    pseudo-variable parameter.

modules/auth/doc/auth.xml

@@ -9,8 +9,9 @@
 	]
 >
 
-<section id="auth" xmlns:xi="http://www.w3.org/2001/XInclude">
-    <sectioninfo>
+<book id="auth" xmlns:xi="http://www.w3.org/2001/XInclude">
+    <bookinfo>
+	<title>The Auth Module</title>
 	<authorgroup>
 	    <author>
 		<firstname>Jan</firstname>
@@ -38,9 +39,9 @@
 	    <holder>FhG FOKUS</holder>
 	</copyright>
 
-    </sectioninfo>
+	<toc></toc>
+    </bookinfo>
 
-    <title>Auth Module</title>
     
     <section id="auth.overview">
 	<title>Overview</title>
@@ -70,4 +71,4 @@
     <xi:include href="params.xml"/>
     <xi:include href="functions.xml"/>
 
-</section>
+</book>