「哈希摘要与校验」是数据鱼API平台提供的多算法摘要接口,Base 路径 /api/hash,共 6 个端点。服务端直接调用 PHP 的 hash 扩展,可用的摘要算法 60 种、HMAC 算法 44 种,覆盖 MD、SHA-1、SHA-2、SHA-3、RIPEMD、Whirlpool、Tiger、GOST、CRC、FNV、Murmur、xxHash、Haval 等族系,具体清单以 /api/hash/algorithms 的返回为准。
接口分三组能力:一次请求跑多种摘要、单算法 HMAC 计算、原文与期望摘要的一致性校验。摘要结果支持小写十六进制、大写十六进制与 Base64 三种编码,批量算法用逗号分隔,省去为每种算法各发一次请求的往返。
方法 | 路径 | 说明 | 鉴权 |
|---|---|---|---|
GET | /api/hash/ping | 健康检查,返回版本与服务器时间,免鉴权 | 免鉴权 |
GET | /api/hash/stats | 返回算法数量、默认算法、格式、上限等运行参数 | 需要 |
GET | /api/hash/algorithms | 返回完整摘要与 HMAC 算法清单、常用算法与格式 | 需要 |
GET | /api/hash/text | 对文本按一个或多个算法计算摘要 | 需要 |
GET | /api/hash/hmac | 以密钥计算 HMAC 摘要 | 需要 |
GET | /api/hash/verify | 比较原文摘要与期望值是否一致 | 需要 |
鉴权用 X-API-Key 请求头或 ?api_key= 查询参数,缺失返回 4011,无效返回 4013。本接口全部端点为 GET,参数走查询串;文本内容较长时注意 URL 长度,正文上限为 65536 字节,接近上限建议改用 POST 表单或 JSON body 提交,参数名与查询串一致。
响应统一为 {code, msg, data} 三段结构。参数类错误集中在 4001 与 4002:缺少 text、key、expected、algo 返回 4001,算法名不在支持清单、文本超长、编码格式非法返回 4002,错误信息会带上具体算法名与服务端支持清单的指引。4003 用于取值不在支持列表的场景,本接口的算法与格式错误统一走 4002。这是数据鱼API平台开发工具类接口的通用约定。
/api/hash/text参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
text | string | 是 | — | 待摘要文本,按 UTF-8 字节计算,二进制安全 |
algo | string | 否 | md5,sha1,sha256,sha512 | 算法名,多个用英文逗号、中文逗号或空格分隔,最多 32 个 |
format | string | 否 | hex | 输出编码,取 hex、hex_upper、base64 |
返回 text_bytes、text_chars、format、algo_count 与 digests 数组,数组每项含 algo、bits、digest。bits 是该算法的输出位宽,可用于校验长度;digests 的顺序与去重后的算法入参顺序一致,重复算法只计算一次。
GET /api/hash/text?text=abc&algo=md5,sha256&format=hex_upper/api/hash/hmac参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
text | string | 是 | — | 待摘要文本 |
key | string | 是 | — | HMAC 密钥,按原文字节参与计算 |
algo | string | 否 | sha256 | 必须是 hmac 清单内的算法 |
format | string | 否 | hex | 输出编码,取 hex、hex_upper、base64 |
返回 algo、format、text_bytes、key_bytes、bits、hmac。算法名大小写不敏感,服务端会统一归一化;部分摘要算法没有对应的 HMAC 实现,传入 /api/hash/algorithms 的 hmac 清单之外的算法会返回 4002。
GET /api/hash/hmac?text=order-2024&key=secret&algo=sha256/api/hash/verify参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
text | string | 是 | — | 原文 |
expected | string | 是 | — | 期望摘要,十六进制,大小写不敏感,允许空白 |
algo | string | 是 | — | 单算法名 |
返回 algo、match、digest、expected、note。expected 会先去掉所有空白并转小写再比较,digest 为服务端算出的标准小写十六进制值,便于调用方自行对照。比较采用恒定时间实现,不会因前缀匹配长度不同而提前返回,可用于校验签名场景下的摘要值。
GET /api/hash/verify?text=abc&expected=900150983cd24fb0d6963f7d28e17f72&algo=md5hex 小写、hex_upper 大写、base64;校验端点只接受十六进制口径。构建流水线在产物发布前计算 sha256,把结果写入清单文件,供下载方核对完整性。
Webhook 接收端用 HMAC 校验请求签名,把原始报文与签名头分别作为 text 和 expected 传入,避免自行实现比较逻辑。
数据同步任务用 md5 与 crc32 双算法生成指纹,比对源端与目标端文件是否一致,减少全量传输。
verify 只做十六进制比较,若摘要以 Base64 输出,需先转成十六进制再校验,否则 match 恒为 false;同样地,expected 传 Base64 字符串不会报错,只会得到不匹配结果。
摘要算法不可逆,本接口不提供反查或撞库能力。密码存储不应使用本接口,应使用 bcrypt、argon2 等带盐且可调工作因子的专用方案,服务端的 stats 响应里也写明了这一口径。
MD5、SHA-1 已被证明存在实用碰撞构造,用于完整性校验时优先选 SHA-256 及以上;CRC32、FNV 等非密码学哈希只适合分桶与快速比对,不具备抗碰撞性。算法选择由调用方自行负责,数据鱼API平台不对据此得出的安全结论负责。
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。