|
|
@@ -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.
|
Olle E. Johansson