hCaptcha 是什么?Token、Siteverify 与 Enterprise 详解

hCaptcha 是放在表单前面的一种机器人检查。访问者在小组件里通过一个挑战,小组件随后会向表单添加一个名为 h-captcha-response 的 token。你的服务器把这个 token 发给 hCaptcha,确认它是真的。那么,对开发者来说 hCaptcha 是什么?它就是一个小组件、一个 token 和一次校验调用,如果脚本必须通过它,你要处理的也是这些。本指南讲解如何识别它、服务器检查什么、每个错误是什么意思,以及脚本要发送什么。
关于验证码的总体概念,请参阅 验证码是什么,网站为什么使用它。本页只讲 hCaptcha。
如何在页面上识别 hCaptcha
hCaptcha 开发者指南 把小组件展示为一个类名为 h-captcha、带有 data-sitekey 属性的元素。CapSkip 的 hCaptcha 页面把 sitekey 称为公开的 UUID。当脚本改为自行构建小组件时,sitekey 是 hcaptcha.render() 的一个参数,配置指南对此有记载。挑战成功之后,该指南说 hCaptcha 会向表单提交添加 h-captcha-response token。
所以有三样东西可以识别它:一个类名为 h-captcha 的元素、一个 sitekey,以及挑战通过之后出现的名为 h-captcha-response 的表单字段。CapSkip API 文档补充说,表单可能还带有第二个名为 g-recaptcha-response 的字段,需要填入同一个 token。
Checkbox、invisible 和 Enterprise 账户
Checkbox 和 invisible 是两种小组件模式。Enterprise 是一种账户等级,两种模式都可以使用,它会改变服务器校验回复所包含的内容。CapSkip 对它们全部使用同一个方法。
- Checkbox。 访问者勾选一个框,并且按照 CapSkip 文档的说法,有时还要回答一个图片挑战。
- Invisible。 invisible 指南说,你要在元素上把 data-size 设为 invisible,这样小组件会在后台渲染,只在需要挑战时才显示出来。你的页面用 hcaptcha.execute() 触发它,token 会交给你的回调函数。
- Enterprise。 校验回复会多出两个字段,score 和 score_reason,hCaptcha 指南把它们标注为仅限 Enterprise。CapSkip 的任务上没有 score 选项。唯一相关的开关是针对 hCaptcha 的 High score mode,见下面的常见问题。
一些 Enterprise 站点还会在小组件运行之前,通过 hcaptcha.setData() 向它传入一个名为 rqdata 的值。hCaptcha 的公开文档没有描述它,所以这里关于它的一切都依据 CapSkip 文档:站点为每次挑战签发一个值,它很快就会过期,所以脚本每个任务都需要一个新的。
服务器如何处理 token
服务器把 token 以 URL 编码的表单正文发送(POST)到 https://api.hcaptcha.com/siteverify,指南警告不要发送 JSON。有两个字段是必需的:账户的 secret 和 token,分别以 secret 和 response 发送。指南推荐 remoteip(用户的地址),并把 sitekey 列为可选,用来说明你期望的是哪个 sitekey。JSON 答复包含 success、challenge_ts、hostname 和 error-codes。
token 只能使用一次。指南给出的唯一有效期是默认 120 秒,写在某个错误代码的说明里。CapSkip 文档则说约为两分钟。请在提交之前才请求 token。
Siteverify 错误,以及要检查什么
这些代码来自 hCaptcha 指南中的错误表。脚本通常只会看到表单被拒绝。最后一列是对该检查什么的解读,不是 hCaptcha 的文字。
| 错误代码 | 指南的说法 | 要检查什么 |
|---|---|---|
missing-input-response | 缺少 token 参数。 | 表单提交中没有 h-captcha-response 字段,或者站点读取的是另一个名字。 |
invalid-input-response | token 无效或格式错误。 | 这个值在进入表单的途中被截断、被修改,或者被编码了两次。 |
expired-input-response | token 已过期(默认 120 秒)。 | 从识别到提交之间过了太久。识别之后请立即提交。 |
already-seen-response | 该 token 已被校验过一次。 | token 被重复使用,或者表单提交重试时用了旧 token。请每次都请求一个新的。 |
sitekey-secret-mismatch | 该 sitekey 没有与所提供的 secret 一起注册。 | 这是服务器端的站点配置问题,不是脚本发送的东西。 |
invalid-input-secret | 密钥无效或格式错误。 | 同样在服务器端,在站点所有者的代码里。 |
它与 reCAPTCHA 和 Turnstile 的比较
三者都是把一个 token 放进表单,并在服务器端校验,所以区别只在名称和数字。reCAPTCHA 使用 g-recaptcha-response,Google 的校验指南说 token 的有效期是两分钟,并且只能校验一次。Turnstile 使用 cf-turnstile-response,Cloudflare 的 服务端校验指南 给出的是 300 秒和单次使用。在 CapSkip Python SDK 中,对应的调用是 hcaptcha()、recaptcha() 和 turnstile(),取自 1.7.0 源码。
发给 CapSkip 的请求是什么样的
CapSkip 运行在你的 Windows PC 上,使用 2captcha 请求格式,所以一个 hCaptcha 任务就是两次 HTTP 调用。下面两条 curl.exe 命令在 PowerShell 和 cmd 中都能照原样运行。第一条提交任务,并返回一个任务 id。第二条用该 id 轮询,CAPCHA_NOT_READY 表示等几秒再问一次。只有当页面设置了 rqdata 时才加上 data 字段。只有在 CapSkip 中开启了 API Key Validation 时,key 才有意义。
curl.exe -X POST -d "key=YOUR_API_KEY&method=hcaptcha&sitekey=YOUR_SITEKEY&pageurl=https://example.com/login&json=1" http://127.0.0.1:8080/in.php curl.exe "http://127.0.0.1:8080/res.php?key=YOUR_API_KEY&action=get&id=12345&json=1"
通过 Python SDK 完成同样的任务只需一次调用,它会提交、轮询并返回结果。可用的选项有 invisible、data(Enterprise 的 rqdata)、userAgent 和 proxy。只有当你发送的 userAgent 与 CapSkip 用来识别的浏览器一致时,CapSkip 才会采用它。结果里以 code 和 token 携带 token,另外还有 respKey,以及获得该 token 的 User-Agent。
# pip install capskip
from capskip import CapSkip
# The key matters only when API Key Validation is on in CapSkip.
solver = CapSkip(apiKey="YOUR_API_KEY", host="127.0.0.1", port=8080)
# For an Enterprise rqdata add data=RQDATA; for an invisible widget
# add invisible=1. Neither is needed for a plain checkbox.
result = solver.hcaptcha(
sitekey="YOUR_SITEKEY",
url="https://example.com/login",
)
# The token goes in h-captcha-response, sent with this User-Agent.
print(result["code"][:12], result["userAgent"])两个代码块都是针对 CapSkip 的模拟服务器运行的,不是真实的应用,每个都发送了 method=hcaptcha,并带有给定的 sitekey 和页面地址。没有发生真实的识别,所以这里不对识别耗时或成功率做任何声明。完整脚本和所有参数见 CapSkip hCaptcha 识别工具页面,该方法列在 CapSkip API 文档.
- 用 capskip SDK 在 Python 中识别 hCaptcha
- 在 Node.js 中用新的 rqdata 识别 hCaptcha Enterprise
- 用 HCaptchaAsync 在 C# 中识别 hCaptcha
在服务器上运行 CapSkip
如果你的脚本运行在另一台机器上,请把 CapSkip 切换到 Server mode,并把主机设置指向那台机器。 设置指南中的连接设置 对这两种模式都有说明,Server mode 需要 CapSkip 以管理员身份运行,并且这台机器仍然是你控制的 Windows PC。请检查哪些地址可以访问该端口,并为不应访问的地址添加 Windows Firewall 阻止规则。由于识别发生在那台机器上,hCaptcha 看到的是它的网络,所以如果这对站点很重要,请给任务附加一个代理。
常见问题
hCaptcha 和 reCAPTCHA 是一回事吗?
不是。它们是各自独立的服务,有各自的小组件、字段名和校验主机。脚本必须发送正确的字段,并向 CapSkip 请求正确的方法。
我怎么判断一个站点是否使用 hCaptcha Enterprise?
并不总能从前端看出来。CapSkip 文档说,一些 Enterprise 站点会在小组件运行之前,把一个 rqdata 值传给 hcaptcha.setData()。如果你看到了这个调用,就把该值作为 data 选项发送,并且每个任务都用新的。如果没有看到,就正常识别,如果站点拒绝 token,再试试 High score mode。
为什么表单会拒绝 CapSkip 返回的 token?
CapSkip 文档列出了常见原因:token 太旧或已经用过,sitekey 与页面不匹配,或者 User-Agent 与回复中的不一致。对于严格的站点,文档还补充了针对 hCaptcha 的 High score mode 设置,位置在 Settings, Captcha types,它需要在运行 CapSkip 的 PC 上安装 Google Chrome。
我能在服务器上运行 CapSkip 来处理 hCaptcha 任务吗?
可以。在你控制的 Windows 机器上使用 Server mode,并让你的脚本指向它的地址。
简短版结论
hCaptcha 是一个以单次使用的 token 收尾的小组件,只在 hCaptcha 的 siteverify 地址校验一次。在你自己的 Windows PC 上运行的 本地验证码识别工具 用一个方法就能覆盖 checkbox、invisible 和 Enterprise 几种情况,没有按次费用。
