From d71d746d3f9c84f2aa4e822404a1c3fe5c7da122 Mon Sep 17 00:00:00 2001 From: Daniel-Constantin Mierla Date: Fri, 28 Aug 2015 11:18:10 +0200 Subject: [PATCH] auth: regenerated the readme --- modules/auth/README | 209 +++++++++++++++++++++++++++++--------------- 1 file changed, 138 insertions(+), 71 deletions(-) diff --git a/modules/auth/README b/modules/auth/README index ef541259eb4..71b990a5658 100644 --- a/modules/auth/README +++ b/modules/auth/README @@ -15,46 +15,46 @@ Daniel-Constantin Mierla asipto.com - Copyright © 2002, 2003 FhG FOKUS + Copyright © 2002, 2003 FhG FOKUS __________________________________________________________________ Table of Contents 1. Admin Guide - 1.1. Overview - 1.2. Dependencies - 1.3. Parameters - - 1.3.1. auth_checks_register (flags) - 1.3.2. auth_checks_no_dlg (flags) - 1.3.3. auth_checks_in_dlg (flags) - 1.3.4. qop (string) - 1.3.5. nonce_count (boolean) - 1.3.6. one_time_nonce (boolean) - 1.3.7. nid_pool_no (integer) - 1.3.8. nc_array_size (integer) - 1.3.9. nc_array_order (integer) - 1.3.10. otn_in_flight_no (integer) - 1.3.11. otn_in_flight_order (integer) - 1.3.12. secret (string) - 1.3.13. nonce_expire (integer) - 1.3.14. nonce_auth_max_drift (integer) - 1.3.15. force_stateless_reply (boolean) - 1.3.16. realm_prefix (string) - 1.3.17. 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. Overview + 2. Dependencies + 3. Parameters + + 3.1. auth_checks_register (flags) + 3.2. auth_checks_no_dlg (flags) + 3.3. auth_checks_in_dlg (flags) + 3.4. qop (string) + 3.5. nonce_count (boolean) + 3.6. one_time_nonce (boolean) + 3.7. nid_pool_no (integer) + 3.8. nc_array_size (integer) + 3.9. nc_array_order (integer) + 3.10. otn_in_flight_no (integer) + 3.11. otn_in_flight_order (integer) + 3.12. secret (string) + 3.13. nonce_expire (integer) + 3.14. nonce_auth_max_drift (integer) + 3.15. force_stateless_reply (boolean) + 3.16. realm_prefix (string) + 3.17. use_domain (boolean) + + 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) List of Examples @@ -85,7 +85,43 @@ Daniel-Constantin Mierla Chapter 1. Admin Guide -1.1. Overview + Table of Contents + + 1. Overview + 2. Dependencies + 3. Parameters + + 3.1. auth_checks_register (flags) + 3.2. auth_checks_no_dlg (flags) + 3.3. auth_checks_in_dlg (flags) + 3.4. qop (string) + 3.5. nonce_count (boolean) + 3.6. one_time_nonce (boolean) + 3.7. nid_pool_no (integer) + 3.8. nc_array_size (integer) + 3.9. nc_array_order (integer) + 3.10. otn_in_flight_no (integer) + 3.11. otn_in_flight_order (integer) + 3.12. secret (string) + 3.13. nonce_expire (integer) + 3.14. nonce_auth_max_drift (integer) + 3.15. force_stateless_reply (boolean) + 3.16. realm_prefix (string) + 3.17. use_domain (boolean) + + 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. Overview This is a generic module that itself doesn't provide all functions necessary for authentication but provides functions that are needed by @@ -99,21 +135,39 @@ Chapter 1. Admin Guide 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 (flags) +3. Parameters + + 3.1. auth_checks_register (flags) + 3.2. auth_checks_no_dlg (flags) + 3.3. auth_checks_in_dlg (flags) + 3.4. qop (string) + 3.5. nonce_count (boolean) + 3.6. one_time_nonce (boolean) + 3.7. nid_pool_no (integer) + 3.8. nc_array_size (integer) + 3.9. nc_array_order (integer) + 3.10. otn_in_flight_no (integer) + 3.11. otn_in_flight_order (integer) + 3.12. secret (string) + 3.13. nonce_expire (integer) + 3.14. nonce_auth_max_drift (integer) + 3.15. force_stateless_reply (boolean) + 3.16. realm_prefix (string) + 3.17. use_domain (boolean) + +3.1. auth_checks_register (flags) See description of parameter auth_checks_in_dlg. -1.3.2. auth_checks_no_dlg (flags) +3.2. auth_checks_no_dlg (flags) See description of parameter auth_checks_in_dlg. -1.3.3. auth_checks_in_dlg (flags) +3.3. auth_checks_in_dlg (flags) These three module parameters control which optional integrity checks will be performed on the SIP message carrying digest response during @@ -198,7 +252,7 @@ modparam("auth", "auth_checks_in_dlg", 15) ... -1.3.4. qop (string) +3.4. 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 @@ -220,7 +274,7 @@ modparam("auth", "auth_checks_in_dlg", 15) modparam("auth", "qop", "auth") # set qop=auth ... -1.3.5. nonce_count (boolean) +3.5. 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 @@ -316,7 +370,7 @@ route{ } ... -1.3.6. one_time_nonce (boolean) +3.6. 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 @@ -360,7 +414,7 @@ modparam("auth", "one_time_nonce", 1) # Note: stateful mode should be used, see the nonce_count example ... -1.3.7. nid_pool_no (integer) +3.7. 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 @@ -396,7 +450,7 @@ modparam("auth", "one_time_nonce", 1) modparam("auth", "nid_pool_no", 4) ... -1.3.8. nc_array_size (integer) +3.8. 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 @@ -420,7 +474,7 @@ modparam("auth", "nid_pool_no", 4) modparam("auth", "nc_array_size", 4194304) # 4Mb ... -1.3.9. nc_array_order (integer) +3.9. 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 @@ -437,7 +491,7 @@ modparam("auth", "nc_array_size", 4194304) # 4Mb modparam("auth", "nc_array_order", 22) # 4Mb ... -1.3.10. otn_in_flight_no (integer) +3.10. 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. @@ -463,7 +517,7 @@ modparam("auth", "nc_array_order", 22) # 4Mb modparam("auth", "otn_in_flight_no", 8388608) # 8 Mb (1Mb memory) ... -1.3.11. otn_in_flight_order (integer) +3.11. 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 @@ -481,7 +535,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.12. secret (string) +3.12. secret (string) Secret phrase used to calculate the nonce value used to challenge the client for authentication. @@ -501,7 +555,7 @@ modparam("auth", "otn_in_flight_order", 23) # 8 Mb (1Mb memory) modparam("auth", "secret", "johndoessecretphrase") ... -1.3.13. nonce_expire (integer) +3.13. 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 @@ -518,7 +572,7 @@ modparam("auth", "secret", "johndoessecretphrase") modparam("auth", "nonce_expire", 600) # Set nonce_expire to 600s ... -1.3.14. nonce_auth_max_drift (integer) +3.14. 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. @@ -540,7 +594,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.15. force_stateless_reply (boolean) +3.15. 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 @@ -552,13 +606,13 @@ modparam("auth", "nonce_auth_max_drift", 1) # set max drift to 1 s modparam("auth", "force_stateless_reply", 1) ... -1.3.16. realm_prefix (string) +3.16. 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 master domain can be defined for SIP purposes (like sip.mydomain.net pointing to same IP address as the SRV record for mydomain.net). By - ignoring the realm_prefix “sip.â€, at authentication, sip.mydomain.net + ignoring the realm_prefix "sip.", at authentication, sip.mydomain.net will be equivalent to mydomain.net . Default value is empty string. @@ -566,7 +620,7 @@ modparam("auth", "force_stateless_reply", 1) Example 1.14. realm_prefix parameter example modparam("auth", "realm_prefix", "sip.") -1.3.17. use_domain (boolean) +3.17. use_domain (boolean) If set to 1, pv_auth_check() uses domain parts of the URIs to check user identity. @@ -576,9 +630,19 @@ modparam("auth", "realm_prefix", "sip.") modparam("auth", "use_domain", 1) ... -1.4. Functions +4. Functions -1.4.1. consume_credentials() + 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) + +4.1. consume_credentials() This function removes previously authorized credential headers from the message being processed by the server. That means that the downstream @@ -595,7 +659,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 @@ -608,7 +672,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 @@ -622,7 +686,7 @@ if (has_credentials("myrealm")) { * 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, the + It must not be empty string "". In case of REGISTER requests, the To header field domain (e.g., variable $td) can be used (because this header field represents the user being registered), for all other messages From header field domain can be used (e.g., variable @@ -645,7 +709,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 @@ -667,7 +731,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 @@ -686,7 +750,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,20 +763,17 @@ if (!auth_check("$fd", "subscriber", "1")) { * -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 * -4 (nonce expired) - the nonce has expired * -5 (no credentials) - request does not contain an Authorization header with the correct realm * -6 (nonce reused) - the nonce has already been used to authenticate a previous request - * -8 (auth user mismatch) - the auth user is different then the - From/To user 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 + 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). @@ -741,7 +802,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 @@ -764,7 +825,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 @@ -779,6 +840,12 @@ if (!pv_proxy_authenticate("$fd", "$avp(password)", "0")) { it is for a REGISTER request or not. The parameter may be a pseudo variable. + The set of possible return codes is the same than + pv_{www,proxy}_authenticate, with one more possible value: + + -8 (auth user mismatch) - the auth user is different than the From/To + user + This function can be used from REQUEST_ROUTE. Example 1.23. pv_auth_check usage @@ -789,7 +856,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.