scan4all 项目中的 Go HTTP Digest 认证客户端:基于 RFC 7616 的 Digest 摘要认证实现与使用指南
scan4all 项目中的 Go HTTP Digest 认证客户端:基于 RFC 7616 的 Digest 摘要认证实现与使用指南
导读:本文以 scan4all 仓库内 vendored 的
github.com/Mzack9999/go-http-digest-auth-client(即github.com/xinsnake/go-http-digest-auth-client)库为核心,讲解基于 RFC 7616 HTTP Digest Access Authentication 的 Go 摘要认证客户端实现与两种调用方式。读完本文,你将掌握如何用dac.NewRequest一次性完成 Digest 认证请求、如何用dac.NewTransport无侵入地接入标准net/http请求链路,以及库内部对WWW-Authenticate解析、Authorization响应摘要计算(MD5/SHA-256、qop、nc、cnonce、userhash)的完整实现原理——这套能力在 scan4all 的各类 HTTP 探测、指纹识别与弱口令爆破等安全扫描场景中,用于正确处理需要摘要认证的保护性资源。
一、这个库在 scan4all 中扮演什么角色
scan4all 是一个聚合了端口扫描、Web 指纹识别、PoC 检测与多类应用口令爆破等能力的综合安全扫描工具(项目描述见 README.md)。在它的依赖清单 go.mod 中,明确引入了 github.com/Mzack9999/go-http-digest-auth-client v0.6.1-0.20220414142836-eb8883508809,并以 vendored 方式固定在 vendor/github.com/Mzack9999/go-http-digest-auth-client 目录下(该库以 package digest_auth_client 提供,import 路径写为 github.com/xinsnake/go-http-digest-auth-client)。
之所以需要这样一个专门的客户端,是因为摘要认证(Digest Access Authentication)与 Basic 认证不同,它不是一次性把明文凭据塞进请求头,而是:
- 服务端先以
401+WWW-Authenticate头下发挑战(challenge)参数; - 客户端根据挑战中的
realm、nonce、qop、algorithm等参数,结合用户名、密码、请求方法、请求 URI 和请求体,计算出一个不可逆的摘要(digest); - 客户端用
Authorization: Digest ...头重新发起请求,服务端独立复算并比对,通过后才返回真实资源。
这意味着,凡是受摘要认证保护的管理后台、网络设备、Web 中间件控制面,在安全扫描中若不实现这套握手流程,只能收到 401 而无法触达保护之下的真实内容。本库的作用正是让这类请求对调用方保持透明:开发者只需提供用户名、密码、方法与 URI,库自动完成 401 挑战→计算摘要→携带 Authorization 重放 的完整过程。配合该库的还有同目录 vendor 体系中其他认证类依赖(如 vendor/modules.txt 中列出的 github.com/Azure/go-ntlmssp 等),共同构成扫描器对不同认证协议的适配层。
二、仓库中的实现文件概览
vendored 库目录下共 3 个 Go 源文件,职责划分清晰:
| 文件 | 职责 |
|---|---|
| digest_auth_client.go | 对外公开的类型 DigestRequest、DigestTransport 及 NewRequest、NewTransport、UpdateRequest、Execute、RoundTrip 等核心方法;负责发起请求、捕获 401、调度摘要计算与重放 |
| www_authenticate.go | 解析服务端下发的 WWW-Authenticate 响应头,抽取 realm、nonce、opaque、qop、algorithm、stale、charset、userhash、domain 等挑战参数 |
| authorization.go | 根据挑战参数与请求信息计算并格式化 Authorization: Digest ... 头,实现 A1/A2 与 response 的摘要算法 |
三个文件协同完成一次完整的 Digest 握手,下文将沿“两种用法 → 请求执行流程 → 挑战解析 → 摘要计算 → 请求头拼装”的主线展开。
三、两种标准用法(继承自 README 并补充细节)
原 README.md 给出了两种推荐用法,二者都要求先 import 该库:
import dac "github.com/xinsnake/go-http-digest-auth-client"
3.1 用法一:Request 风格(面向单次请求)
// 创建一次新的 digest 认证请求
dr := dac.NewRequest(username, password, method, uri, payload)
response1, err := dr.Execute()
// 检查 error,处理 response1
// 复用同一个请求对象发起新请求,避免额外的握手过程
dr.UpdateRequest(username, password, method, uri, payload)
response2, err := dr.Execute()
// 检查 error,处理 response2
要点说明:
NewRequest(username, password, method, uri, payload)的五个参数依次为:用户名、密码、HTTP 方法(如"GET"、"POST")、完整请求 URI、请求体字符串(无请求体时传空字符串)。- 返回值是
DigestRequest值类型,携带认证上下文(Auth、Wa字段),因此首次Execute()完成握手后,该对象内已缓存服务端挑战与服务端接受的摘要参数。 - 第 26 行的
UpdateRequest用于“换参数、不换凭据上下文”的复用场景:调用后再次Execute(),会走 existing digest 分支(见下文executeExistingDigest),无需再次经历 401 挑战往返,直接基于刷新后的nc(nonce count,计数器递增)、cnonce与时间戳重算摘要并重放。这在连续访问同一受保护资源目录下的多个 URI 时非常高效。 Execute()返回的*http.Response需要由调用方负责resp.Body.Close()(源码在 digest_auth_client.go 的注释中明确说明)。
3.2 用法二:Transport 风格(无缝接入标准 net/http)
t := dac.NewTransport(username, password)
req, err := http.NewRequest(method, uri, payload)
if err != nil {
log.Fatalln(err)
}
resp, err := t.RoundTrip(req)
if err != nil {
log.Fatalln(err)
}
defer resp.Body.Close()
fmt.Println(resp)
要点说明:
NewTransport(username, password)返回DigestTransport,它实现了标准库的http.RoundTripper接口(源码见 digest_auth_client.go),因此可以像http.DefaultTransport一样直接传给http.Client{Transport: t},对上层业务代码几乎零侵入。RoundTrip内部从*http.Request中提取方法、URI,并读取请求体内容(buf.ReadFrom(req.Body)),然后构造NewRequest完成整个握手,再返回最终的*http.Response。- 该风格适合改造已有
net/http调用链:只要把http.Client的Transport换成DigestTransport,原有请求代码几乎不用改动即可获得摘要认证能力。
四、执行流程:一次请求背后的三步握手
Execute() 是 Request 风格的调度入口,其逻辑在 digest_auth_client.go 中清晰可见,整体可分为三种路径:
4.1 首次请求(无认证上下文)
- 构造
http.NewRequest(dr.Method, dr.URI, bytes.NewReader([]byte(dr.Body))),把调用方传入的Header赋给请求头,用getHTTPClient()得到 HTTP 客户端后执行client.Do(req)。 - 若响应
resp.StatusCode == 401,进入executeNewDigest(resp):- 先
resp.Body.Close()(认证阶段不需要响应体); - 从
resp.Header.Get("WWW-Authenticate")取出挑战字符串,若为空则直接报错failed to get WWW-Authenticate header, please check your server configuration; - 调用
newWwwAuthenticate(waString)解析挑战参数并保存到dr.Wa; - 调用
newAuthorization(dr)计算Authorization头内容; - 用
executeRequest(auth.toString())携带认证头重放原请求; - 把生成的
authorization存到dr.Auth,供后续复用。
- 先
- 若响应状态码不是 401(如 200/302/403 等),则直接原样返回响应,不做任何摘要处理——这符合 Digest 协议的“先挑战后认证”语义。
4.2 复用请求(已有认证上下文)
第二次及以后的 Execute() 走 executeExistingDigest():
- 调用
dr.Auth.refreshAuthorization(dr)刷新摘要:nc自增、基于当前纳秒时间戳重新生成cnonce、按新请求的 method/URI 重算 response; - 用刷新后的
Authorization头直接executeRequest重放,不再与服务器进行 401 往返。
从源码结构看,这是 README 中“reuse the existing digest authentication request so no extra request is needed”一句的实现依据。
4.3 HTTP 客户端与 TLS 行为
getHTTPClient()(digest_auth_client.go)的细节值得注意:
- 若调用方已在
dr.HTTPClient/dt.HTTPClient注入自定义*http.Client,则直接复用,否则库内部创建一个默认客户端; - 默认客户端的
Timeout为 30 秒; - 默认构造
tls.Config{},仅当DigestRequest.CertVal为false时才设置InsecureSkipVerify = true。而NewRequest中CertVal初始值为true(digest_auth_client.go),即默认校验 TLS 证书;在安全扫描中若目标使用自签名证书,需要把dr.CertVal置为false才能放行。 - 该字段在
RoundTrip路径中同样有效——RoundTrip会把dt.HTTPClient透传给内部dr,但CertVal需要在构造DigestTransport后手动设置(DigestTransport结构体本身不暴露该字段,见 digest_auth_client.go)。
五、挑战解析:WWW-Authenticate 是如何被吃透的
服务端下发的 WWW-Authenticate 头典型形如:
WWW-Authenticate: Digest realm="testrealm@host.com", qop="auth,auth-int", nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093", opaque="5ccc069c403ebaf9f0171e9517f40e41"
www_authenticate.go 用一组正则表达式逐一抽取字段,解析结果存入 wwwAuthenticate 结构体:
| 字段 | 正则 | 说明 |
|---|---|---|
Algorithm |
algorithm="([^ ,]+)" |
摘要算法(MD5 / MD5-SESS / SHA-256 / SHA-256-SESS),可为空 |
Domain |
domain="(.+?)" |
挑战适用的 URI 空间,可空 |
Nonce |
nonce="(.+?)" |
服务器一次性随机数,必填 |
Opaque |
opaque="(.+?)" |
服务器返回的会话标识,客户端应原样回传 |
Qop |
qop="(.+?)" |
保护质量,auth / auth-int 或组合 |
Realm |
realm="(.+?)" |
认证领域(realm),参与摘要计算 |
Stale |
stale=([^ ,])" |
指示 nonce 是否过期,true/false,转为 bool |
Charset |
charset="(.+?)" |
字符集声明(RFC 7616 扩展) |
Userhash |
userhash=([^ ,])" |
是否要求对用户名做哈希(RFC 7616 新增),转为 bool |
实现上有两点可以留意:
- 全部采用非贪婪正则逐项匹配,字段缺失时对应结构体字段保持零值,容忍不同服务器的头格式差异;
stale与userhash通过strings.ToLower(...) == "true"转成布尔值,大小写不敏感。
六、摘要计算:authorization 的算法内幕
authorization.go 是算法的核心,按 RFC 7616 的流程实现。整体分为“刷新上下文 → 计算 A1/A2 → 计算 response → 拼装头”四步。
6.1 上下文刷新(refreshAuthorization)
- 把当前请求的用户名写入
ah.Username; - 若服务端要求
userhash,则将用户名替换为H(username:realm)(ah.hash(fmt.Sprintf("%s:%s", ah.Username, ah.Realm))); ah.Nc++递增 nonce 计数器;- 生成客户端随机数
cnonce:ah.hash(fmt.Sprintf("%d:%s:my_value", time.Now().UnixNano(), dr.Username)),即以“纳秒时间戳 + 用户名”为输入做摘要,保证每次请求的 cnonce 不同; - 用
url.Parse(dr.URI).RequestURI()取出请求路径与查询串作为摘要所用的uri(注意:是RequestURI()而非完整 URL); - 调用
computeResponse计算 response 摘要。
6.2 A1 的计算
computeA1 根据 algorithm 分三种情况(authorization.go):
| 算法 | A1 公式 |
|---|---|
空 / MD5 / SHA-256 |
username:realm:password |
MD5-SESS / SHA-256-SESS |
H(username:realm:password):nonce:cnonce |
其中 H 即算法摘要函数:MD5* 系用 MD5,SHA-256* 系用 SHA-256,未知算法返回空字符串(hash 函数的实现见 authorization.go)。
6.3 A2 与 qop 的选择
computeA2(authorization.go)按服务端下发的 qop 分派:
- 若
qop包含auth-int:A2 = method:uri:H(body),并把本次请求的ah.Qop置为auth-int(完整性保护,把请求体摘要纳入计算); - 若
qop为auth或空:A2 = method:uri,ah.Qop置为auth; - 其它情况返回空串。
6.4 response 的计算
computeResponse(authorization.go)实现标准公式:
response = H( H(A1) : nonce : nc : cnonce : qop : H(A2) )
其中 nc 以 8 位十六进制格式化(%08x),参与计算的中间串为:
nonce : nc : cnonce : qop : H(A2)
最终响应头的完整拼装由 toString() 完成(authorization.go):依次输出 Digest username=..., realm=..., nonce=..., uri=..., response=..., algorithm=..., cnonce=..., opaque=..., qop=..., nc=..., userhash=true(可选字段自动跳过,末尾用 strings.TrimSuffix 去掉最后的 , )。这也是 executeRequest 中 req.Header.Add("Authorization", authString) 最终写入的完整值。
6.5 已知限制(基于源码结构推断)
authorization结构体中Username_字段标注// TODO,未见赋值逻辑——对应 RFC 7616 中可选字段的扩展支持尚不完整;- 若服务端指定未知算法(非上述四种),
hash返回空串,response 计算会因此异常,属于边界场景; DigestTransport.RoundTrip会读取并消费请求体(buf.ReadFrom(req.Body)),复用同一req对象时请求体不会被还原,多次重放同一请求时需注意。
七、在扫描场景中的工程化建议
结合 scan4all 这类安全扫描工具的典型需求,使用本库时有几点实践建议:
- 凭据来自爆破字典:
NewRequest/NewTransport每次接收一组用户名密码,可直接把 brute 目录下httpuser.txt、httppass.txt、tomcatuserpass.txt等字典行循环喂入,逐组尝试摘要认证; - 关闭 TLS 校验的姿势:对自签名证书目标,Request 风格请设置
dr.CertVal = false;Transport 风格则需在构造后自行扩展(DigestTransport未暴露该字段,可将自定义HTTPClient传入dt.HTTPClient以覆盖默认 TLS 配置); - 复用优先:连续探测同一受保护目录下的多个路径时,用
UpdateRequest复用DigestRequest,避免每次请求都先吃一个 401,可显著降低握手开销; - Body 处理:使用 Transport 风格时注意请求体会被读取消费;使用 Request 风格时 body 以字符串传入,POST 等带请求体的请求需要显式传入 payload。
八、小结
go-http-digest-auth-client 在 scan4all 的 vendored 依赖中提供了对 RFC 7616 Digest 摘要认证的完整 Go 实现:对外提供 Request 与 Transport 两种风格,对内完成“401 挑战捕获 → WWW-Authenticate 解析 → A1/A2/response 摘要计算 → Authorization 头重放 → 上下文复用”的闭环。其支持 MD5、MD5-SESS、SHA-256、SHA-256-SESS 四种算法,兼容 auth / auth-int 两种 qop,并实现了 RFC 7616 新增的 userhash 特性。对于需要在 HTTP 扫描链路中穿透摘要认证保护资源的场景,这份实现是一个开箱即用的参考范本。
附注:原库作者在 README 中声明因时间限制不再继续维护,并建议评估替代方案;scan4all 当前固定使用
v0.6.1-0.20220414142836-eb8883508809(见 go.mod),使用时若遇到极端兼容性问题可参考该提示。