curl `--digest` 详解:HTTP Digest 摘要认证的用法、原理与源码实现

原创2026-09-08 20:54:212,157 阅读
文章标签:网络通信CLI跨平台

curl --digest 详解:HTTP Digest 摘要认证的用法、原理与源码实现

--digest 是 curl 命令行工具启用 HTTP Digest(摘要)认证 的开关。与把用户名密码以 Base64 明文形式放在请求头中的 --basic 不同,Digest 采用“挑战—应答(challenge-response)”机制,避免密码以明文在网络上传输。本文以 curl 仓库中 digest.md 为主干,结合源码与测试用例,讲透 --digest 的完整用法、认证流程与底层实现,读完你既能写出正确的命令行,也能看懂从选项解析到 Authorization 头生成的全部代码链路。

--digest 是什么

根据 curl 官方选项手册 digest.md:

Enable HTTP Digest authentication. This authentication scheme avoids sending the password over the wire in clear text. Use this in combination with the normal --user option to set username and password.

即:--digest 启用 HTTP Digest 认证。该认证机制不会以明文在网络上发送密码;需要与设置用户名和密码的 --user 选项配合使用。

从该文件的元数据(front-matter)可以获取它的完整技术画像:

元数据字段 值 含义
Long digest 长选项名为 --digest
Help HTTP Digest Authentication 选项帮助文本
Protocols HTTP 仅对 HTTP/HTTPS 生效
Category proxy auth http 归类于代理、认证、HTTP 类
Added 7.10.6 自 curl 7.10.6 起加入
Multi boolean 布尔开关,可用 --no-digest 关闭
See-also user / proxy-digest / anyauth 相关选项

基本命令示例

选项文档给出的标准用法是:

curl -u name:password --digest $URL

将 -u(即 --user,见 user.md)与 --digest 组合,即可对目标服务器启用 Digest 认证:

# 访问需要 Digest 认证的受保护页面
curl --digest -u alice:s3cret https://example.com/private/

# 显式长选项写法,等价于上面
curl --digest --user alice:s3cret https://example.com/private/

几点与 --user 配合的注意点(源自 user.md):

  • --user 指定首个冒号前的部分为用户名,因此用户名中无法包含冒号(密码中可以);
  • 若只给用户名不给密码,curl 会交互式提示输入密码;
  • --user 会覆盖 --netrc 与 --netrc-optional 的设置;
  • 在支持的平台上 curl 会尽量从进程列表中隐藏命令行参数,但凭据仍可能在瞬间对同机其他用户可见,敏感场景建议从配置文件或 netrc 中读取,而不是把密码明文写进命令行。

为什么需要 Digest:与 Basic 的对比

HTTP 认证方案中,curl 命令行默认(不带任何认证选项)使用 Basic(见 basic.md)。Basic 的流程是直接把 用户名:密码 做 Base64 编码后放进 Authorization: Basic ... 头——而 Base64 是可逆编码而非加密,任何能截获请求的人都能轻易还原出明文密码。只有在 HTTPS(TLS)保护下,Basic 才不泄露密码。

Digest 则不同:即使传输链路本身没有加密(明文 HTTP),服务器也不会要求客户端直接发送密码。取而代之的是挑战—应答流程:

  1. 客户端首先发起不带认证信息的请求;
  2. 服务器返回 401 Unauthorized,并在 WWW-Authenticate: Digest ... 头中给出 challenge,通常包含一个一次性 nonce(随机数)、realm(保护域)、支持的 qop 与 algorithm;
  3. 客户端用密码与 challenge 中的 nonce、请求方法、URI 等做单向散列计算,把计算结果放进 Authorization: Digest ... 头重试请求;
  4. 服务器用自己持有的密码副本做同样的计算并比对,从而完成身份校验。

由于密码只参与不可逆的摘要计算,而 challenge 又由服务器每次动态下发,Digest 相比 Basic 能有效抵抗“抓包直接读密码”的攻击,也具备一定的防重放能力(配合 nonce 计数与 cnonce)。

工作原理:一次典型的 Digest 认证往返

以仓库测试用例 tests/data/test1001 为例(该用例标题即 HTTP Digest auth),服务器先返回:

HTTP/1.1 401 Authentication Required
WWW-Authenticate: Digest realm="testrealm", nonce="1053604144"

curl 解析 challenge 后,重发请求并带上计算好的凭据头:

Authorization: Digest username="auser", realm="testrealm", nonce="1053604144", uri="/1001", response="6af4d89c952f4dd4cc215a6878dc499d"

请求中出现的字段是 Digest 应答的核心组成:

字段 含义
username 用户名
realm 服务器 challenge 声明的保护域,客户端原样带回
nonce 服务器 challenge 下发的随机数,客户端原样带回
uri 被保护资源的请求 URI(request-target)
response 客户端计算出的摘要响应值,即身份凭证
cnonce 客户端自己生成的随机数(当使用 qop=auth 时需要)
nc nonce 计数(十六进制,表示该 nonce 被使用的次数,防重放)
algorithm 散列算法,如 MD5、MD5-sess、SHA-256、SHA-256-sess
qop 保护质量,如 auth

response 的计算本质上是一串 HA1、HA2 的摘要套嵌,其中:

  • HA1 = H(username:realm:password),可视为口令的“加盐散列凭证”;
  • HA2 = H(method:uri),绑定请求方法与资源地址;
  • 最终 response = H(HA1:nonce:nc:cnonce:qop:HA2)(使用 qop 时)。

因此,即使攻击者抓到了完整的 Authorization 头,也无法逆向出密码,更不能把它直接重放到另一个 nonce 场景中。

在 curl 认证体系中的定位

Digest 只是 curl 支持的多种 HTTP 认证之一。若想使用某一种而非其他方案,可以在 --basic、--digest、--ntlm、--negotiate 之间显式选择。

  • --anyauth(见 anyauth.md):不指定具体方案,让 curl 先发一次请求探测服务器 WWW-Authenticate 声称支持的能力,然后自动选择“最安全”的一种。代价是可能多一次网络往返;并且如果从标准输入(stdin)上传数据,探测可能导致数据需要发送两次、要求客户端能 rewind,做不到时上传会失败。
  • --proxy-digest(见 proxy-digest.md):与 --digest 相对,它针对的是代理服务器。使用 --proxy-digest 并配合 --proxy-user 与 -x/--proxy:
curl --proxy-digest --proxy-user user:passwd -x http://proxy.example.com:8080 https://example.com/

这三者的分工可以总结为:

选项 认证对象 配套用户名选项
--digest 远端主机(目标服务器) --user / -u
--proxy-digest 代理服务器 --proxy-user
--anyauth 远端主机(自动选择方案) --user / -u

注意 --digest 与 --basic 同属“明确指定一种方案”,而 --anyauth 会取代这种显式选择,故二者互斥使用(See-also 字段将三者互为索引)。

源码级深入:从选项到 Authorization 头的完整链路

了解命令行行为之后,可以沿仓库源码把 --digest 的调用链走一遍。

第一步:CLI 选项解析(src/tool_getparam.c)

命令行工具在 src/tool_getparam.c 中把 --digest 解析到认证类型位掩码:

case C_DIGEST: /* --digest */
  togglebit(toggle, &config->authtype, CURLAUTH_DIGEST);

随后该配置会通过 curl_easy_setopt() 以 CURLOPT_HTTPAUTH 落到 libcurl。在 lib/setopt.c 的 CURLOPT_HTTPAUTH / CURLOPT_PROXYAUTH 分支中,libcurl 会归一化认证位(例如把遗留的 CURLAUTH_DIGEST_IE 位展开为标准的 CURLAUTH_DIGEST)。对 libcurl API 使用者而言,等价于:

curl_easy_setopt(curl, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST);
curl_easy_setopt(curl, CURLOPT_USERPWD, "alice:s3cret");

第二步:challenge 的解析与存储(lib/http.c 与 lib/http_digest.c)

当服务器返回 401 及 WWW-Authenticate: Digest ... 后,lib/http.c 中的 auth_digest() 函数会记录服务器声称支持的 CURLAUTH_DIGEST 能力,并调用 Curl_input_digest() 把 challenge 解码保存:

We call this function on input Digest headers even if Digest authentication is not activated yet, as we need to store the incoming data from this header in case we are going to use Digest.

这一步的关键设计在于:即使客户端还没选定 Digest,也会先解析并缓存 challenge,以便后续需要时立即使用。

真正的输入/输出实现在 lib/http_digest.c:

  • Curl_input_digest()(lib/http_digest.c):根据认证对象区分两种存储——data->state.digest(服务器认证)与 data->state.proxydigest(代理认证,配合 --proxy-digest 使用),然后调用 Curl_auth_decode_digest_http_message() 解析 WWW-Authenticate 头;
  • Curl_output_digest()(lib/http_digest.c):负责生成最终要发送的 Authorization / Proxy-Authorization 头;
  • digest_flush_stale()(lib/http_digest.c):当对端主机或凭据发生变化时,自动清理缓存的 nonce 等会话状态,避免把上一个服务器的 challenge 误用到下一个连接上——这解释了为何 curl 对多个并发主机/多套凭据使用 Digest 时仍能保持正确性。

第三步:最终请求头的输出(lib/http.c 的认证输出函数)

在真正发送请求前,lib/http.c 根据“已被选中”的认证方法分发到对应实现:

if(authstatus->picked == CURLAUTH_DIGEST) {
  auth = "Digest";
  result = Curl_output_digest(data, proxy, request, path);
  ...
}

只有服务器 challenge 被成功解析后,这一分支才会带着合法 nonce 输出形如 Authorization: Digest ... 的头。

第四步:摘要计算内核(lib/vauth/digest.c)

所有挑战参数的解码与摘要计算最终落在 lib/vauth/digest.c。从该文件头部注释可以看到它实现的算法族:

RFC2831 DIGEST-MD5 authentication
RFC7616 DIGEST-SHA256, DIGEST-SHA512-256 authentication

从源码结构看,它内部为每种算法维护一个编号常量(ALGO_MD5、ALGO_MD5SESS、ALGO_SHA256、ALGO_SHA256SESS 等),即除经典的 RFC 2617 MD5 / MD5-sess 外,也支持更新的 SHA-256、SHA-256-sess 变体。应答生成时会执行关键步骤:

  1. 解析 challenge 中的 nonce、realm、algorithm、qop(lib/vauth/digest.c),其中 realm 缺失时按 RFC 约定置空处理;
  2. 调用 Curl_rand_hex() 生成客户端随机数 cnonce;
  3. 初始化 MD5_context/SHA 上下文,依次计算 HA1、HA2 与最终 response 的十六进制摘要。

相关的容量约束在 lib/vauth/digest.h 中定义:DIGEST_MAX_VALUE_LENGTH 256(单个挑战参数值最大长度)、DIGEST_MAX_CONTENT_LENGTH 1024(challenge 整体最大长度),超出即拒绝,避免恶意服务器用超长 challenge 撑爆内存。

整个 Digest 实现还被编译开关 CURL_DISABLE_DIGEST_AUTH 控制(见 lib/vauth/digest.h 与 lib/http.c),可在构建时整体裁剪。

用测试用例验证行为

仓库测试套件提供了可直接观察 Digest 行为的端到端用例,例如:

  • tests/data/test1001(HTTP Digest auth):服务器下发 WWW-Authenticate: Digest realm="testrealm", nonce="1053604144",客户端重试并携带计算好的 Authorization: Digest ... response="...";
  • tests/data/test1002:两次上传场景下的 Digest 认证,验证同一个 nonce 会话中请求目标(uri)变化时摘要的差异;
  • tests/data/test1030:同样基于 WWW-Authenticate: Digest realm=... 挑战,校验客户端回带头的正确性。

这些用例对理解一个要点很有帮助:Digest 是“先吃 401,再带 Authorization 重试”的两段式流程,而响应摘要 response 与 uri、方法强绑定,所以每个请求的应答值都是不同的。

实战中的注意事项与安全建议

综合文档与实现,使用 --digest 时请留意以下几点:

  1. 必须配合 --user:Digest 计算需要密码参与,不给凭据则无从认证;仅需交互输入密码时可用 --user alice(省略密码部分)。
  2. 只覆盖服务器认证:若你经过的是需要认证的代理,请改用/追加 --proxy-digest --proxy-user user:passwd -x proxy。
  3. 适合未启用 TLS 的场景:Digest 避免了明文密码传输,但它不等同于 HTTPS;它能抵抗“直接读出密码”的抓包,却仍可能受中间人降级攻击影响。对安全性要求高的场景,首选仍是 HTTPS + Basic,或 HTTPS 上的 Digest。Digest 与 IE 变体(Digest IE,对应 CURLAUTH_DIGEST_IE)等历史差异也不应被忽略。
  4. 与 --anyauth 二选一:显式 --digest 与自动探测的 --anyauth 是两种互斥策略;若从 stdin 上传数据又依赖重试探测,上传可能失败。
  5. 凭据保护:不要把密码硬编码进可被他人读取的脚本或历史记录;尽量经由 netrc/配置文件注入。

小结

掌握这条从命令行到认证内核的完整链路后,无论排查服务端 401 循环、比较各种认证方案,还是理解 libcurl 中 CURLOPT_HTTPAUTH 与 CURLAUTH_DIGEST 的语义,都能做到有的放矢。

登录后查看全文
curl