kamailio-auth模块详解【以下内容来源于官网，本文只做翻译】

以下是《Auth 模块》文档的中文翻译：

---

Auth 模块

作者：Jan Janak
FhG Fokus
jan@iptel.org
Juha Heinanen
TutPro Inc
jh@song.fi
Daniel-Constantin Mierla
asipto.com
miconda@gmail.com
版权所有 © 2002, 2003 FhG FOKUS
官网链接:
https://kamailio.org/docs/modules/6.0.x/modules/tm.html

目录

1. 管理员指南
   1. 概述
   2. 依赖
   3. 参数
      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.18. algorithm (string)
      3.19. add_authinfo_hdr (boolean)
   4. 函数
      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.10. auth_algorithm(algorithm)
      示例列表
      1.1. 设置 auth_checks_register 模块参数
      1.2. qop 示例
      1.3. nonce_count 示例
      1.4. one_time_nonce 示例
      1.5. nid_pool_no 示例
      1.6. nc_array_size 示例
      1.7. nc_array_order 示例
      1.8. otn_in_flight_no 示例
      1.9. otn_in_flight_order 示例
      1.10. 设置 secret 模块参数
      1.11. nonce_expire 示例
      1.12. nonce_auth_max_drift 示例
      1.13. force_stateless_reply 示例
      1.14. realm_prefix 参数示例
      1.15. force_stateless_reply 示例
      1.16. 使用 SHA-256 示例
      1.17. 添加 Authentication-Info 头示例
      1.18. consume_credentials 示例
      1.19. consume_credentials 示例
      1.20. www_challenge 使用示例
      1.21. proxy_challenge 使用示例
      1.22. auth_challenge 使用示例
      1.23. pv_www_authenticate 使用示例
      1.24. pv_proxy_authenticate 使用示例
      1.25. pv_auth_check 使用示例
      1.26. auth_get_www_authenticate
      1.27. auth_algorithm 示例

---

第 1 章 管理员指南

1. 概述

这是一个通用模块，本身并不提供所有认证所需的功能，但提供了其他认证相关模块（称为认证后端）所需的功能。

我们将认证代码分为多个模块，因为现在有多个后端（目前支持数据库认证和 RADIUS）。这使我们能够创建单独的包，用户只需安装和加载所需的功能。这也避免了二进制包中不必要的依赖。

2. 依赖

在使用此模块之前，必须加载以下模块：

• sl - 无状态回复。

3. 参数

3.1. auth_checks_register (flags)

参见 auth_checks_in_dlg 参数的描述。

3.2. auth_checks_no_dlg (flags)

参见 auth_checks_in_dlg 参数的描述。

3.3. auth_checks_in_dlg (flags)

这三个模块参数控制在 SIP MD5 摘要认证期间对携带摘要响应的 SIP 消息执行哪些可选的完整性检查。auth_checks_register 控制对 REGISTER 消息的完整性检查，auth_checks_no_dlg 控制对没有 To 头字段或没有 To 标签的 SIP 请求（即建立对话或对话外的请求）的可选完整性检查，auth_checks_in_dlg 控制对对话内的 SIP 请求（如 BYE 或 re-INVITE）的完整性检查。所有三个参数的默认值为 0（旧行为，无额外检查）。

启用额外检查后，nonce 将包括对消息的选定部分（见下文）和其他密钥的额外 MD5 哈希。这将用于检查当 UA 尝试重用 nonce 时，消息的选定部分是否相同，从而保护或严重限制重放攻击。

所有三个参数的可能标志值为：

• 1：检查消息 URI 是否更改（使用整个 URI）
• 2：检查 Call-ID
• 4：检查 From 标签
• 8：检查源 IP 地址（参见 nonce.h）

例如，将 auth_checks_register 设置为 3 将检查 REGISTER 消息的 Call-ID 或请求 URI 是否从生成原始 nonce 的 REGISTER 消息中更改（这将允许在同一 UA 内且在有效期内重用 nonce）。启用额外检查将限制 UA 的 nonce 缓存，需要额外的挑战和往返，但会提供更好的保护。

警告：除非您确定所有用户代理在被挑战时不会更改 From 标签，否则不要为 REGISTER 消息（auth_checks_register）和对话外消息（auth_checks_no_dlg）启用 From 标签检查（4）。某些用户代理在挑战请求不在对话中时也会更改 Call-ID，因此避免为非对话消息启用 Call-ID 检查（2）。在某些罕见情况下，这也需要为 REGISTER 消息完成。

当设置了 secret 参数并启用了额外检查时，secret 的前半部分将用于过期时间的 MD5，另一半用于额外检查的 MD5，因此请确保您有一个长密钥（建议 32 个字符或更长）。

示例 1.1. 设置 auth_checks_register 模块参数

...
# 对于 REGISTER 请求，我们将请求 URI、Call-ID 和请求的源 IP 哈希到 nonce 字符串中。
# 这确保生成的凭据不能与其他注册器、具有其他源 IP 地址或 Call-ID 的用户代理一起使用。
# 请注意，如果启用此功能，每次 REGISTER 消息更改 Call-ID 的用户代理将无法注册。
modparam("auth", "auth_checks_register", 11)# 对于建立对话的请求（如原始 INVITE、OPTIONS 等），我们哈希请求 URI 和源 IP。
# 哈希 Call-ID 和 From 标签需要额外的预防措施，因为这些检查可能会使某些 UA 无法使用。
modparam("auth", "auth_checks_no_dlg", 9)# 对于对话中的请求，如 re-INVITE，我们可以像前一种情况一样哈希源 IP 和请求 URI。
# 此外，我们可以哈希 Call-ID 和 From 标签，因为这些在对话中是固定的，保证不会更改。
# 此设置有效地将生成的凭据的使用限制为单个对话中的单个用户代理。
modparam("auth", "auth_checks_in_dlg", 15)
...

3.4. qop (string)

如果设置，则为挑战启用 qop：每个挑战将包含一个 qop 参数。这是推荐的方式，但一些较旧的非 RFC3261 兼容的 UA 可能会感到困惑，并且在启用 qop 时可能无法正确认证。

启用 qop 和 nonce_count 将提供额外的安全性（防止重放攻击），同时仍允许 UA 侧的凭据缓存，从而不影响性能。

可能的值为：“auth”、“auth-int” 和 “”（未设置）。

默认值为未设置（""）。

另请参见：nonce_count。

示例 1.2. qop 示例

...
modparam("auth", "qop", "auth")   # 设置 qop=auth
...

3.5. nonce_count (boolean)

如果启用，则记住接收到的 nc 值并检查其是否大于先前的值（对于成功的认证，接收到的 nc 必须大于先前接收到的值，详见 RFC2617）。这将提供防止重放攻击的保护，同时仍允许 UA 侧的凭据缓存。

它依赖于 qop 的启用（如果未启用 qop，挑战将不包括 qop，因此 UA 可能不会在其响应中包含 qop 或 nc 参数）。

如果响应不包括 qop 或 nc（例如不支持它们的旧 UA），则响应将根据其他启用的 nonce 检查进行检查，顺序为：one_time_nonce 和 auth_checks_*。如果响应仅包括 nc，则仅执行正常检查和 nonce_count 检查，所有其他检查将被忽略。

检查通过跟踪有限数量的 nonce 来工作。最大跟踪 nonce 数使用 nc_array_size 或 nc_array_order 参数设置。如果超过此数量，较旧的条目将被覆盖。只要可挑战消息的平均响应时间的最大速率低于 nc_array_size，检查应该可以正常工作。为了获得最佳性能（最大重用缓存凭据），nc_array_size 除以 nid_pool_no 应低于消息速率乘以所需的 nonce_expire。

最大接受的 nc 值为 255。如果 nc 大于此值，nonce 将被视为过时，UA 将被重新挑战。

注意：nonce_count 应仅在状态模式下启用（应在认证检查之前创建事务以吸收可能的重新传输，并且所有回复应使用 t_reply() 以状态方式发送）。如果在无状态模式下使用 nonce_count 和认证检查，则所有重新传输都将被挑战。

默认值为 0（关闭）。

另请参见：qop、nc_array_size、nc_array_order、nid_pool_no、nonce_expire、one_time_nonce。

示例 1.3. nonce_count 示例

...
modparam("auth", "nonce_count", 1) # 启用 nonce_count 支持
modparam("auth", "qop", "auth")    # 启用 qop=auth....
route{
...# 进入状态模式并捕获重新传输if (!t_newtran()) {xlog("L_NOTICE", "Failed to create new transaction\n");drop;};if (method=="REGISTER"){if (!www_authenticate("test", "credentials")){# 必须使用 t_reply 发送回复，因为此时事务已经创建#（我们处于“状态”模式）if ($? == -2){t_reply("500", "Internal Server Error");}else if ($? == -3){t_reply("400", "Bad Request");}else{if ($digest_challenge)append_to_reply("%$digest_challenge");t_reply("401", "Unauthorized");}drop;}if (!save_noreply("location")) {t_reply("400", "Invalid REGISTER Request");drop;}append_to_reply("%$contact");t_reply("$code", "$reason"); # 不使用 %，直接使用 avpsdrop;}else{if (!proxy_authenticate("my_realm", "credentials")){if ($? == -2){t_reply("500", "Internal Server Error");}else if ($? == -3){t_reply("400", "Bad Request");}else{if ($digest_challenge)append_to_reply("%$digest_challenge");t_reply("401", "Unauthorized");}drop;}}
...

3.6. one_time_nonce (boolean)

如果设置为 1，则禁用 nonce 重用：每个 nonce 仅允许使用一次，即在第一次响应挑战时。所有消息都将被挑战，即使是重新传输。应使用状态模式，以在认证检查之前捕获重新传输（使用 t_newtran() 并在认证检查之前使用 t_reply() 发送所有回复）。

one_time_nonce 提供了增强的重放保护，但代价是使 UA 侧的凭据缓存无效，挑战每条消息（从而生成额外的消息和额外的往返）并要求状态模式。通常应优先使用 qop 和 nonce_count（如果可能），并回退到 auth_checks_*。由于上述缺点，仅当 auth_checks_register、auth_checks_no_dlg 和 auth_checks_in_dlg 提供的额外检查被认为不足以满足特定设置时，才应使用 one_time_nonce。

与 nonce_count 相比，one_time_nonce 提供了相同的保护，但消息成本更高。唯一的优点是它适用于不支持 qop 和 nc 的用户代理，并且对于相同的最大在途 nonce 数，它使用的内存更少（减少 8 倍）。当 UA 不支持 nc 时，one_time_nonce 可以作为 nonce_count 的备用（当两者都启用时，它会自动发生）。

与 nonce_count 类似，one_time_nonce 通过跟踪有限数量的 nonce 来工作。最大跟踪 nonce 数使用 otn_in_flight_no 或 otn_in_flight_order 参数设置。如果超过此数量，较旧的条目将被覆盖。只要可挑战消息的平均响应时间的最大速率低于 otn_in_flight_no，检查应该可以正常工作。

默认值为 0（关闭）。

另请参见：otn_in_flight_no、otn_in_flight_order、nid_pool_no、nonce_count。

示例 1.4. one_time_nonce 示例

...
modparam("auth", "one_time_nonce", 1)
# 注意：应使用状态模式，参见 nonce_count 示例
...

3.7. nid_pool_no (integer)

控制 nonce_count 和 one_time_nonce 数组的分区数（为减少 nonce 大小，两者共用）。

可以将这些数组分为多个分区，而不是使用单个数组来保持 nonce 状态。每个 Kamailio 进程被分配到一个分区，从而在多 CPU 机器上实现更高的并发性。除了提高性能外，增加 nid_pool_no 也有负面影响：在某些情况下，它可能会减少支持的最大在途 nonce 数。在最坏的情况下，当只有一个 Kamailio 进程接收大部分流量时（例如，两个代理之间的非常繁忙的 TCP 连接），在途 nonce 可能限制为数组大小（nc_array_size 用于 nonce_count 或 otn_in_flight_no 用于 one_time_nonce）除以分区数（nid_pool_no）。然而，对于正常流量，当接收消息的进程是随机选择或以轮询方式选择时，最大在途 nonce 数将很少受到 nid_pool_no 的影响（消息将接近均匀地分布到使用不同分区的进程）。

nid_pool_no 值应为以下之一：1、2、4、8、16、32 或 64（最大值为 64，所有值应为 2^k 形式，否则将向下舍入为 2^k）。

默认值为 1。

另请参见：nonce_count、one_time_nonce、nc_array_size、otn_in_flight_no。

示例 1.5. nid_pool_no 示例

...
modparam("auth", "nid_pool_no", 4)
...

3.8. nc_array_size (integer)

nonce_count 的最大在途 nonce 数。它表示将保持状态的最大 nonce 数。当超过此数量时，较旧的 nonce 的状态将被丢弃以为新的 nonce 腾出空间（详见 nonce_count）。

值应为 2^k 形式。如果不是，则向下舍入为 2^k（例如，值 1000000 将向下舍入为 2^19=524288）。可以使用 nc_array_order 直接指定 2 的幂（例如，设置为 20 等同于设置为 1048576）。

用于保持 nonce 状态的内存将为 nc_array_size 字节。

默认值为 1048576（1M 在途 nonce，使用 1Mb 内存）。

另请参见：nonce_count、nid_pool_no。

示例 1.6. nc_array_size 示例

...
modparam("auth", "nc_array_size", 4194304)   # 4Mb
...

3.9. nc_array_order (integer)

等同于 nc_array_size，但不是直接指定大小，而是指定 2 的幂（log2()）。

nc_array_size = 2^nc_array_order。有关更多详细信息，请参见 nc_array_size。

默认值为 20（1M 在途 nonce，使用 1Mb 内存）。

另请参见：nonce_count、nc_array_size、nid_pool_no。

示例 1.7. nc_array_order 示例

...
modparam("auth", "nc_array_order", 22)   #...

3.10. otn_in_flight_no (integer)

one_time_nonce 的最大在途 nonce 数。它表示为一次性 nonce 检查记住的最大 nonce 数。当超过此数量时，较旧的 nonce 的信息将被丢弃并覆盖为新生成的 nonce 的信息（详见 one_time_nonce）。

值应为 2^k 形式。如果不是，则向下舍入为 2^k（例如，值 1000000 将向下舍入为 2^19=524288）。可以使用 otn_in_flight_order 直接指定 2 的幂（例如，设置为 19 等同于设置为 524288）。

用于保持 nonce 信息的内存将为 otn_in_flight_no 除以 8（每个 nonce 仅保留 1 位状态）。

默认值为 1048576（1M 在途 nonce，使用 128Kb 内存）。

另请参见：one_time_nonce、nid_pool_no。

示例 1.8. otn_in_flight_no 示例

...
modparam("auth", "otn_in_flight_no", 8388608)   # 8 Mb (1Mb 内存)
...

3.11. otn_in_flight_order (integer)

等同于 otn_in_flight_no，但不是直接指定大小，而是指定 2 的幂（log2()）。

otn_in_flight_no = 2^otn_in_flight_order。有关更多详细信息，请参见 otn_in_flight_order。

默认值为 20（1M 在途 nonce，使用 128Kb 内存）。

另请参见：one_time_nonce、otn_in_flight_no、nid_pool_no。

示例 1.9. otn_in_flight_order 示例

...
modparam("auth", "otn_in_flight_order", 23)   # 8 Mb (1Mb 内存)
...

3.12. secret (string)

用于计算 nonce 值的密钥短语，用于挑战客户端进行认证。

如果在您的安装中使用多个服务器，并希望在第二个服务器上针对第一个服务器生成的 nonce 进行认证，则必须在所有服务器上显式设置相同的 secret。然而，由于使用共享（且固定）的密钥作为 nonce 是不安全的，最好保持默认值。任何客户端应将认证请求发送到发出挑战的服务器。

默认值为随机生成的字符串。

示例 1.10. 设置 secret 模块参数

...
modparam("auth", "secret", "johndoessecretphrase")
...

3.13. nonce_expire (integer)

Nonce 具有有限的生命周期。在给定时间段后，nonce 将被视为无效。这是为了防止重放攻击。包含过时 nonce 的凭据将不被授权，但用户代理将再次被挑战。这次挑战将包含 stale 参数，这将向客户端指示它不必打扰用户询问用户名和密码，它可以使用现有的用户名和密码重新计算凭据。

值为秒，默认值为 300 秒。

示例 1.11. nonce_expire 示例

...
modparam("auth", "nonce_expire", 600)   # 设置 nonce_expire 为 600 秒
...

3.14. nonce_auth_max_drift (integer)

nonce 创建时间与当前时间之间的最大差异（以秒为单位），如果 nonce 创建时间似乎在未来。

在某些情况下，例如系统时间向后调整后不久，或当当前代理是未时间同步的集群的一部分时，可能会收到一个创建时间在未来的 nonce。在这种情况下，如果差异大于 nonce_auth_max_drift 秒，则认为 nonce 过时并重新挑战（否则在时间大幅向后调整后，某些先前生成的 nonce 可能会在太长时间内有效）。

默认值为 3 秒。

另请参见：nonce_expire。

示例 1.12. nonce_auth_max_drift 示例

...
modparam("auth", "nonce_auth_max_drift", 1)   # 设置最大差异为 1 秒
...

3.15. force_stateless_reply (boolean)

如果设置为 1，www_challenge() 和 proxy_challenge() 函数将无状态地发送回复，无论是否存在事务。如果设置为 0（默认），则如果存在事务，则以状态方式发送回复，否则以无状态方式发送。

示例 1.13. force_stateless_reply 示例

...
modparam("auth", "force_stateless_reply", 1)
...

3.16. realm_prefix (string)

自动从 realm 中剥离的前缀。作为 SRV 记录的替代方案（并非所有 SIP 客户端都支持 SRV 查找），可以为 SIP 目的定义主域的子域（如 sip.mydomain.net 指向与 mydomain.net 的 SRV 记录相同的 IP 地址）。通过忽略 realm_prefix “sip.”，在认证时，sip.example.com 将等同于 example.com。

默认值为空字符串。

示例 1.14. realm_prefix 参数示例

modparam("auth", "realm_prefix", "sip.")

3.17. use_domain (boolean)

如果设置为 1，pv_auth_check() 使用 URI 的域部分来检查用户身份。

示例 1.15. force_stateless_reply 示例

...
modparam("auth", "use_domain", 1)
...

3.18. algorithm (string)

配置用于摘要认证的哈希算法。可能的值为 “MD5” 或 “SHA-256”。如果留空，则使用 MD5。如果指定，则使用指定的算法，并将其放入挑战头的 ‘algorithm’ 字段中。

警告：SHA-256 哈希值占用 MD5 哈希值的两倍空间。因此，如果此选项与另一个未分配至少 65 字节来存储哈希值的 auth_* 模块一起使用，可能会发生缓冲区溢出。SHA-256 可以安全地与 auth_db 模块一起使用，因为它分配了 256 字节来存储 HA1 值。

示例 1.16. 使用 SHA-256 示例

...
modparam("auth", "algorithm", "SHA-256")
...

3.19. add_authinfo_hdr (boolean)

是否在 200 OK 响应中添加 Authentication-Info 头？Authentication-Info 头提供相互认证。服务器向客户端证明它知道用户的密钥。

该头还包括下一个 nonce，客户端可以在未来的请求中使用。如果启用了 one_time_nonce，则为下一个 nonce 计算新的 nonce。否则，当前 nonce 用于下一个 nonce。

默认值为 0（否）。

示例 1.17. 添加 Authentication-Info 头示例

...
modparam("auth", "add_authinfo_hdr", yes)
...

4. 函数

4.1. consume_credentials()

此函数从服务器正在处理的消息中删除先前授权的凭据头。这意味着下游消息将不包含此服务器使用的凭据。这确保代理不会向下游元素透露有关使用的凭据的信息，并且消息也会稍微短一些。必须在 www_authorize、proxy_authorize、www_authenticate 或 proxy_authenticate 之后调用此函数。

示例 1.18. consume_credentials 示例

...
if (www_authenticate("realm", "subscriber")) {consume_credentials();
}
...

4.2. has_credentials(realm)

如果请求具有带有提供的 realm 的 Authorization 或 Proxy-Authorization 头，则此函数返回 true。参数可以是带有伪变量的字符串。

示例 1.19. consume_credentials 示例

...
if (has_credentials("myrealm")) {...
}
...

4.3. www_challenge(realm, flags)

此函数挑战用户代理。它将生成一个包含摘要挑战的 WWW-Authorize 头字段，将其放入服务器正在处理的请求生成的响应中，并发送 401 回复。收到此类回复后，用户代理应计算凭据并重试请求。有关摘要认证的更多信息，请参见 RFC2617。有关发送回复的模块参数，请参见 force_stateless_reply。

参数的含义如下：

• realm - Realm 是一个不透明的字符串，用户代理应将其呈现给用户，以便用户决定使用什么用户名和密码。通常这是服务器运行的主机的域。

  它不能是空字符串 “”。对于 REGISTER 请求，可以使用 To 头字段域（例如，变量 $td）（因为此头字段表示正在注册的用户），对于所有其他消息，可以使用 From 头字段域（例如，变量 $fd）。

  字符串可以包含伪变量。

• flags - 此参数的值可以是以下位的组合：

  • 1 - 构建带有 qop=auth 的挑战头
  • 2 - 构建带有 qop=auth-int 的挑战头
  • 4 - 在失败情况下不自动发送 ‘500 Internal Server Error’ 回复（错误代码返回到配置）
  • 16 - 构建带有 stale=true 的挑战头

此函数可用于 REQUEST_ROUTE。

示例 1.20. www_challenge 使用示例

...
if (!www_authenticate("$td", "subscriber")) {www_challenge("$td", "1");exit;
}
...

4.4. proxy_challenge(realm, flags)

此函数挑战用户代理。它将生成一个包含摘要挑战的 Proxy-Authorize 头字段，将其放入服务器正在处理的请求生成的响应中，并发送 407 回复。收到此类回复后，用户代理应计算凭据并重试请求。有关摘要认证的更多信息，请参见 RFC2617。有关发送回复的模块参数，请参见 force_stateless_reply。

参数的含义与 www_challenge(realm, flags) 函数相同。

此函数可用于 REQUEST_ROUTE。

示例 1.21. proxy_challenge 使用示例

...
if (!proxy_authenticate("$fd", "subscriber")) {proxy_challenge("$fd", "1");exit;
}
...

4.5. auth_challenge(realm, flags)

此函数挑战用户代理进行认证。它结合了 www_challenge() 和 proxy_challenge() 函数，通过内部调用第一个函数用于 REGISTER 请求，第二个函数用于其他请求类型。换句话说，它通过发送 401 回复来挑战 REGISTER 请求的认证，并通过发送 407 回复来挑战其他类型的 SIP 请求。

参数的含义与 www_challenge(realm, flags) 函数相同。

此函数可用于 REQUEST_ROUTE。

示例 1.22. auth_challenge 使用示例

...
if (!auth_check("$fd", "subscriber", "1")) {auth_challenge("$fd", "1");exit;
}
...

4.6. pv_www_authenticate(realm, passwd, flags [, method])

此函数根据 RFC2617 验证凭据。如果凭据验证成功，则函数将成功并将凭据标记为已授权（标记的凭据稍后可由其他函数使用）。如果函数由于某种原因无法验证凭据，则它将失败，脚本应调用 www_challenge，这将再次挑战用户。

负代码可以解释如下：

• -1（通用错误）- 发生了一些通用错误，未发送回复
• -2（无效密码）- 密码错误
• -4（nonce 过期）- nonce 已过期
• -5（无凭据）- 请求不包含具有正确 realm 的 Authorization 头
• -6（nonce 重用）- nonce 已用于认证先前的请求

参数的含义如下：

• realm - Realm 是一个不透明的字符串，用户代理应将其呈现给用户，以便用户决定使用什么用户名和密码。通常这是服务器运行的主机的域。

  它不能是空字符串 “”。对于 REGISTER 请求，可以使用 To 头字段域（例如，变量 $td）（因为此头字段表示正在注册的用户），对于所有其他消息，可以使用 From 头字段域（例如，变量 $fd）。

  字符串可以包含伪变量。

• passwd - 用于认证的密码。可以包含配置变量。用户名取自 Auth 头。

• flags - 此参数的值可以是以下位的组合：

  • 1 - 密码参数的值是 HA1 格式
  • 2 - 构建不带 qop 的挑战头并将其添加到 avp
  • 4 - 构建带有 qop=auth 的挑战头并将其添加到 avp
  • 8 - 构建带有 qop=auth-int 的挑战头并将其添加到 avp
  • 16 - 构建带有 stale=true 的挑战头
  • 32 - 在认证失败时不使 nc 无效

• method - 用于认证的方法。此参数是可选的，如果未设置，则为请求行上的第一个 “word”。

当构建挑战头并存储在 avp 中时，可以使用 append_to_reply() 和 sl 回复函数发送适当的 SIP 回复以挑战认证。

此函数可用于 REQUEST_ROUTE。

示例 1.23. pv_www_authenticate 使用示例

...
if (!pv_www_authenticate("$td", "123abc", "0")) {www_challenge("$td", "1");exit;
}
...

4.7. pv_proxy_authenticate(realm, passwd, flags)

此函数根据 RFC2617 验证凭据。如果凭据验证成功，则函数将成功并将凭据标记为已授权（标记的凭据稍后可由其他函数使用）。如果函数由于某种原因无法验证凭据，则它将失败，脚本应调用 proxy_challenge，这将再次挑战用户。有关负返回代码的更多信息，请参见上述函数。

参数的含义与 pv_www_authenticate(realm, passwd, flags) 相同。

此函数可用于 REQUEST_ROUTE。

示例 1.24. pv_proxy_authenticate 使用示例

...
$avp(password)="xyz";
if (!pv_proxy_authenticate("$fd", "$avp(password)", "0")) {proxy_challenge("$fd", "1");exit;
}
...

4.8. pv_auth_check(realm, passwd, flags, checks)

此函数结合了 pv_www_authenticate 和 pv_proxy_authenticate 的功能，如果 SIP 请求是 REGISTER，则首先执行，否则执行第二个。

前三个参数的含义与 pv_www_authenticate(realm, passwd, flags) 相同。

参数 checks 可用于控制函数的行为。如果为 1，则函数将检查认证用户名是否与 To 或 From 头用户名匹配，无论是否为 REGISTER 请求。参数可以是伪变量。

可能的返回代码集与 pv_{www,proxy}_authenticate 相同，但还有一个可能的值：

• -8（认证用户不匹配）- 认证用户与 From/To 用户不同

此函数可用于 REQUEST_ROUTE。

示例 1.25. pv_auth_check 使用示例

...
$avp(password)="xyz";
if (!pv_auth_check("$fd", "$avp(password)", "0", "1")) {auth_challenge("$fd", "1");exit;
}
...

4.9. auth_get_www_authenticate(realm, flags, pvdest)

构建 WWW-Authentication 头并将结果值设置在 ‘pvdest’ 伪变量参数中。

realm 和 flags 参数的含义与 pv_www_authenticate(realm, passwd, flags) 相同。

此函数可用于 ANY_ROUTE。

示例 1.26. auth_get_www_authenticate

...
if (auth_get_www_authenticate("$fd", "0", "$var(wauth)")) {xlog("www authenticate header is [$var(wauth)]\n");
}
...

4.10. auth_algorithm(algorithm)

设置用于摘要认证的哈希算法，从而覆盖 algorithm 参数。可能的值与 algorithm 参数相同。参数可以是伪变量。

示例 1.27. auth_algorithm 示例

...
auth_algorithm("$alg");
...

---