首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >「哈希摘要与校验」接口功能详解|数据鱼API

「哈希摘要与校验」接口功能详解|数据鱼API

原创
作者头像
用户12862874
发布于 2026-11-21 21:31:39
发布于 2026-11-21 21:31:39
130
举报

接口简介

「哈希摘要与校验」是数据鱼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 的顺序与去重后的算法入参顺序一致,重复算法只计算一次。

代码语言:javascript
复制
GET /api/hash/text?text=abc&algo=md5,sha256&format=hex_upper

HMAC 计算 /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。

代码语言:javascript
复制
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 为服务端算出的标准小写十六进制值,便于调用方自行对照。比较采用恒定时间实现,不会因前缀匹配长度不同而提前返回,可用于校验签名场景下的摘要值。

代码语言:javascript
复制
GET /api/hash/verify?text=abc&expected=900150983cd24fb0d6963f7d28e17f72&algo=md5

数据与限制

  • 文本上限 65536 字节,按字节而非字符计算。
  • 单次请求最多 32 个摘要算法,超过返回 4002。
  • 输出格式三种:hex 小写、hex_upper 大写、base64;校验端点只接受十六进制口径。
  • 算法清单取当前 PHP 运行时的 hash 能力:摘要 60 种、HMAC 44 种,服务端升级扩展后数量可能变化。
  • 默认摘要算法为 md5、sha1、sha256、sha512,默认 HMAC 算法为 sha256。

典型使用场景

构建流水线在产物发布前计算 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 删除。

目录
  • 接口简介
  • 端点总览
  • 通用约定
  • 核心端点详解
    • 多算法摘要 /api/hash/text
    • HMAC 计算 /api/hash/hmac
    • 摘要校验 /api/hash/verify
  • 数据与限制
  • 典型使用场景
  • 注意事项
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档