curl `--proxy-digest`:使用 HTTP Digest 认证访问代理服务器的完整指南
curl --proxy-digest:使用 HTTP Digest 认证访问代理服务器的完整指南
导读
--proxy-digest 是 curl 命令行工具用于向 HTTP 代理服务器启用 HTTP Digest 认证的开关选项(自 7.12.0 版本加入)。在需要通过需要身份验证的代理访问外网,且不希望密码以明文形式在网络上传输的场景中,Digest 认证比默认的 Basic 认证更安全。本文将完整讲解该选项的用法、与相关选项(--proxy-user、--digest、--proxy-basic、--proxy-anyauth)的配合方式,并结合 curl 源码与测试用例揭示其底层实现原理,帮助你正确、安全地配置代理认证。
一、选项速览
--proxy-digest 的官方手册定义位于 docs/cmdline-opts/proxy-digest.md,核心信息如下:
| 属性 | 值 |
|---|---|
| 长选项 | --proxy-digest |
| 帮助文本 | Digest auth with the proxy(对代理使用 Digest 认证) |
| 分类 | proxy、tls |
| 加入版本 | 7.12.0 |
| 取值类型 | boolean(开关型,可多次指定,多次指定不会改变行为) |
官方描述:
Use HTTP Digest authentication when communicating with the given proxy. Use
--digestfor enabling HTTP Digest with a remote host.
即:该选项只作用于代理,不作用于目标主机;若需要让目标主机也使用 Digest 认证,须另外使用 --digest。
二、基本用法:让 curl 通过 Digest 认证代理
Digest 认证需要提供用户名和密码,curl 中通过 --proxy-user(长格式 --proxy-user user:passwd)指定代理凭据。典型命令如下(取自官方示例):
curl --proxy-digest --proxy-user user:passwd -x proxy $URL
各参数含义:
--proxy-digest:声明与代理通信时采用 HTTP Digest 认证;--proxy-user user:passwd:指定代理认证使用的用户名与密码,中间用英文冒号分隔(密码含特殊字符时可用--proxy-user "user:pa:ss"形式或借助--config配置文件);-x proxy/--proxy proxy:指定代理服务器地址,例如-x http://proxy.example.com:8080。
需要注意的是:curl 与代理之间的认证凭据必须单独指定。--user(即 -u)设置的是目标主机(origin server)的凭据,--proxy-user 设置的才是代理的凭据,二者互不替代。若只给了代理认证参数而目标主机无需认证,则只发送代理的认证头。
三、代理认证的默认行为与 Basic 对比
根据 docs/cmdline-opts/proxy-basic.md 的说明:
Basic is the default authentication method curl uses with proxies.
也就是说,只要通过 --proxy-user 提供了代理凭据而未显式指定认证方式,curl 默认采用 HTTP Basic 认证。Basic 认证会把 用户名:密码 经 Base64 编码后直接放入 Proxy-Authorization 请求头,Base64 只是编码而非加密,任何人都可以解码还原明文密码,因此在非加密的 HTTP 代理链路上存在泄露风险。
--proxy-digest 的价值正在于此:Digest 认证不会直接发送密码明文,而是以密码为原料参与摘要运算,服务器通过挑战-应答(challenge-response)机制验证身份,密码不会在链路上以明文传输。两者对比如下:
| 维度 | --proxy-basic |
--proxy-digest |
|---|---|---|
| 密码传输 | Base64 编码(可逆,等同明文) | 不直接传输密码,仅传输摘要值 |
| 防重放 | 无 | 依赖 nonce 等机制增强 |
| 默认状态 | 代理认证的默认方式 | 需显式开启 |
| 适用场景 | 内网可信链路、快速联调 | 需要更高安全性的代理链路 |
因此在需要穿越不可信网络访问代理时,优先选择 --proxy-digest(或配合 HTTPS 代理)。
四、与目标主机认证的配合:--digest
--proxy-digest 与 --digest 是两个互相独立的开关:前者控制与代理的认证,后者控制与目标主机的认证。官方手册 docs/cmdline-opts/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
--useroption to set username and password.
因此,「代理要求 Digest、目标站点也要求 Digest」的完整场景应同时使用两个选项并分别给出凭据:
curl --proxy-digest --proxy-user foo:bar \
--digest --user digest:a-lot \
-x http://proxy.example.com:8080 \
https://api.example.com/data
这一用法在 curl 官方测试用例中有完整验证。测试 tests/data/test168 的名称为 HTTP with proxy-requiring-Digest to site-requiring-Digest,其命令为:
--proxy http://%HOSTIP:%HTTPPORT --proxy-user foo:bar --proxy-digest --digest --user digest:a-lot
对应的期望协议数据(<verify><protocol>)同时包含了两个独立的认证头:
Proxy-Authorization: Digest username="foo", realm="weirdorealm", nonce="12345", ...
Authorization: Digest username="digest", realm="realmweirdo", nonce="123456", ...
可见 curl 会把代理认证与主机认证分别处理,Proxy-Authorization 头使用 --proxy-user 的凭据,Authorization 头使用 --user 的凭据,互不干扰。
五、与其他代理认证选项的关系
5.1 与 --proxy-anyauth:固定方式 vs 自动协商
proxy-anyauth.md 描述:
Automatically pick a suitable authentication method when communicating with the given HTTP proxy. This might cause an extra request/response round-trip.
--proxy-anyauth 让 curl 自动挑选代理支持的认证方式(可能包含 Basic、Digest、NTLM 等),好处是无需预知代理支持什么,代价是额外的一次请求/响应往返(先发无认证请求,收到 407 及 Proxy-Authenticate 头后再重试)。而 --proxy-digest 是固定使用 Digest,省去协商往返,前提是你要确认代理确实支持 Digest。
5.2 与 --proxy-basic、--proxy-ntlm 等:同组互斥
同组的代理认证选项还有 --proxy-basic、--proxy-ntlm、--proxy-negotiate 等。从命令行解析源码 src/tool_getparam.c 可以看出,每个选项都只是把对应的布尔标志写入 config 结构体(如 config->proxydigest = toggle)。而真正决定使用哪种认证的优先级逻辑位于 src/config2setopts.c:
if(config->proxyanyauth)
my_setopt_bitmask(curl, CURLOPT_PROXYAUTH, CURLAUTH_ANY);
else if(config->proxynegotiate)
my_setopt_bitmask(curl, CURLOPT_PROXYAUTH, CURLAUTH_GSSNEGOTIATE);
else if(config->proxyntlm)
my_setopt_bitmask(curl, CURLOPT_PROXYAUTH, CURLAUTH_NTLM);
else if(config->proxydigest)
my_setopt_bitmask(curl, CURLOPT_PROXYAUTH, CURLAUTH_DIGEST);
else if(config->proxybasic)
my_setopt_bitmask(curl, CURLOPT_PROXYAUTH, CURLAUTH_BASIC);
可见这些开关存在优先级顺序(--proxy-anyauth 最高,其次 negotiate、ntlm、digest、basic 依次递减),同时指定多个时只有一个生效,因此实践中应只选择一个。
六、底层实现原理(源码级)
6.1 命令行解析
--proxy-digest 在命令行解析表中注册为布尔开关 src/tool_getparam.c:
{"proxy-digest", ARG_BOOL, ' ', C_PROXY_DIGEST},
解析分支 src/tool_getparam.c 将标志写入配置:
case C_PROXY_DIGEST: /* --proxy-digest */
config->proxydigest = toggle;
break;
6.2 映射为 libcurl 选项 CURLOPT_PROXYAUTH
如上节所示,--proxy-digest 最终映射到 libcurl 的 CURLOPT_PROXYAUTH 选项,并传入认证位掩码 CURLAUTH_DIGEST。这些常量定义于 include/curl/curl.h:
#define CURLAUTH_DIGEST (((unsigned long)1) << 1)
#define CURLAUTH_DIGEST_IE (((unsigned long)1) << 4)
CURLOPT_PROXYAUTH 的处理入口在 lib/setopt.c,它调用内部函数 httpauth():
case CURLOPT_PROXYAUTH:
return httpauth(data, TRUE, (unsigned long)arg);
httpauth()(定义于 lib/setopt.c)会把 CURLAUTH_DIGEST_IE 归一化为标准 Digest 位,并根据编译配置裁剪不支持的认证位(如未启用 NTLM/SPNEGO 时清除相应位),最终将位掩码存入 data->set.proxyauth。若所选认证类型在当前构建中全部不可用,则返回 CURLE_NOT_BUILT_IN。这一点对使用者有实际意义:--proxy-digest 依赖构建时启用了 Digest 支持(通常默认启用,可用 curl -V 查看特性列表确认)。
6.3 认证头的生成
代理认证头的输出由 lib/http.c 中的 Curl_http_output_auth() 负责(在 lib/http_proxy.c 构造代理请求时调用)。关键逻辑 lib/http.c:
- 若应用选定了认证方法但尚未确定最终方法(
want已设置而picked未设置),则直接把picked设为want——由于--proxy-digest只设置了一个位,curl 会在首次请求时就使用 Digest 构造Proxy-Authorization头; - 对代理请求(
is_connect或 origin 即代理)输出Proxy-Authorization头,对目标主机请求输出Authorization头,两者互不干扰,这与测试 tests/data/test168 中观察到的双头行为一致。
Digest 认证通常需要两次交互:首次发送无认证请求(或携带不完整挑战的请求),代理返回 407 Proxy Authentication Required 及 Proxy-Authenticate: Digest ... 挑战,curl 据此计算摘要值后重试。测试 tests/data/test168 的期望协议中连续出现了两条请求,正是这一「挑战-应答」过程的体现。在 Curl_http_output_auth() 中,当认证需要多次往返且请求不是 GET/HEAD 时,curl 会以零长度请求体作为探测(data->req.authneg = TRUE),避免把真实请求体重复发送。
6.4 CONNECT 隧道场景
当使用 --proxytunnel 且代理要求认证时,Digest 认证发生在 CONNECT 请求上。测试 tests/data/test1060(HTTP proxy CONNECT auth Digest, large headers and data)验证了该场景:
--proxy http://%HOSTIP:%HTTPPORT --proxy-user silly:person --proxy-digest --proxytunnel
其期望协议为:
CONNECT test.remote.haxx.se.%TESTNUMBER:8990 HTTP/1.1
Host: test.remote.haxx.se.%TESTNUMBER:8990
即通过 --proxytunnel 建立 CONNECT 隧道时,Proxy-Authorization: Digest ... 头加在 CONNECT 请求上,隧道建立后再进行目标主机的正常通信。
七、常见使用场景汇总
| 场景 | 推荐命令 |
|---|---|
| 普通 HTTP 代理要求 Digest 认证 | curl --proxy-digest --proxy-user user:passwd -x http://proxy:8080 http://example.com/ |
| 代理与目标站点都要求 Digest | curl --proxy-digest --proxy-user foo:bar --digest --user name:pass -x http://proxy:8080 https://api.example.com/ |
| 代理要求 Digest 且目标走 HTTPS 隧道 | curl --proxy-digest --proxy-user user:passwd --proxytunnel -x http://proxy:8080 https://example.com/ |
| 不确定代理支持的认证方式 | curl --proxy-anyauth --proxy-user user:passwd -x http://proxy:8080 http://example.com/(多一次往返协商) |
八、注意事项与限制
- 凭据分离:
--proxy-user只影响代理认证,目标主机的用户名密码要用--user提供,两者可同时存在(参见测试 tests/data/test168)。 - 不适用于 SOCKS 代理:
--proxy-digest面向 HTTP/HTTPS 代理(-x http://...或-x https://...)。SOCKS 代理的认证走不同的机制(如--socks5系列),不受本选项影响。 - 明文凭据提醒:
--proxy-user中的密码会出现在命令行与进程列表中(ps可见),敏感环境可改用--config配置文件或环境变量方式注入,减少泄露面。 - 构建依赖:Digest 认证依赖构建时的
digest特性,可用curl -V输出的 Features 列表确认;在关闭认证支持的精简构建中,--proxy-digest会返回CURLE_NOT_BUILT_IN(见 lib/setopt.c)。 - 选项优先级:
--proxy-digest与--proxy-basic、--proxy-ntlm、--proxy-negotiate、--proxy-anyauth属于同一组,按 src/config2setopts.c 的固定优先级生效,避免同时指定多个。 - 与 HTTPS 代理配合更佳:Digest 虽避免了密码明文传输,但挑战参数与摘要值本身仍可能被离线攻击;如需最高安全等级,可考虑 HTTPS 代理(
-x https://...)与 Digest 组合使用。
九、延伸阅读
- docs/cmdline-opts/proxy-digest.md:本选项的官方手册页;
- docs/cmdline-opts/digest.md:目标主机的 Digest 认证选项;
- docs/cmdline-opts/proxy-basic.md:代理 Basic 认证(默认方式);
- docs/cmdline-opts/proxy-anyauth.md:自动协商代理认证方式;
- docs/cmdline-opts/proxy.md:
-x/--proxy代理地址规范; - src/tool_getparam.c 与 src/config2setopts.c:命令行解析与选项映射实现;
- lib/setopt.c 与 lib/http.c:
CURLOPT_PROXYAUTH处理与认证头输出实现; - tests/data/test168、tests/data/test1060:代理 Digest 认证的官方测试用例。