企业官网建设流程全解析

• 后端
• 认证鉴权
• 云原生

本指南聚焦 Open Policy Agent (OPA) 策略语言 Rego 中的一个实用场景——通过内置函数crypto.md5对 JSON 载荷计算摘要（Digest）并与期望值比对，从而验证载荷在传输过程中是否被篡改或丢失。读完本文，你将掌握crypto.md5的调用方式、与json.marshal配合实现完整性校验的完整写法，以及从 OPA 源码层面理解该内置函数的实现原理。

场景与示例概览

在授权与审计类策略中，除了判断"谁能做什么"，常常还需要回答"这份数据是否完整、未被改动"。内容校验（Content Verification）正是为此设计：对载荷的 JSON 表示计算摘要，摘要相当于载荷的"指纹"——载荷中任何一处变化都会产生不同的摘要，从而被检测出来。

本示例位于仓库docs/docs/policy-reference/_examples/crypto/digest_verification/目录，围绕以下目标展开：

• 使用crypto.md5计算载荷摘要；
• 将计算得到的摘要与预期的摘要比对；
• 输出digest_valid布尔结果，供上层决策使用。

策略实现：三步完成摘要校验

示例的策略文件为 policy.rego，全文如下：

package crypto_digest_verification # Verify payload integrity using MD5 digest # (commonly used for content verification) payload_json := json.marshal(input.payload) computed_digest := crypto.md5(payload_json) digest_valid := computed_digest == input.expected_digest

整个校验逻辑可以拆解为三个明确步骤：

1. 序列化载荷：json.marshal(input.payload)将input.payload对象转换为规范化后的 JSON 字符串。这一步很关键——crypto.md5接收的是字符串输入，必须先完成序列化才能参与摘要计算。
2. 计算摘要：crypto.md5(payload_json)对序列化结果计算 MD5 摘要，返回十六进制编码的字符串。
3. 比对验证：digest_valid := computed_digest == input.expected_digest将计算出的摘要与input.expected_digest比对，相等则载荷完整，返回true；否则返回false，提示载荷已被篡改或传输不完整。

输入与输出：完整可运行的样例

配套的输入文件 input.json 定义了一个包含用户、动作与资源的典型授权载荷，以及期望的摘要值：

{ "payload": { "user": "alice", "action": "read", "resource": "/api/users" }, "expected_digest": "ea99819f665c10c744cbbf8da651c37a" }

在 OPA 中对该输入执行查询（查询目标为data.crypto_digest_verification，见 config.json），得到的输出如 output.json 所示：

{ "computed_digest": "ea99819f665c10c744cbbf8da651c37a", "digest_valid": true, "payload_json": "{\"action\":\"read\",\"resource\":\"/api/users\",\"user\":\"alice\"}" }

可以看到，输出中的computed_digest与input.json中的expected_digest完全一致，digest_valid为true，说明载荷未经篡改。

动手验证篡改检测：任意修改input.json中payload对象的值（例如将"user": "alice"改为其他名字，或修改"resource"路径），重新执行查询后会发现computed_digest发生变化、与expected_digest不再相等，digest_valid变为false。这正是摘要校验的核心价值：任何细微改动都会改变指纹，从而被立即发现。

crypto.md5 内置函数：声明与底层实现

内置函数声明

crypto.md5是 OPA 的官方内置函数（Builtin），其声明定义在 v1/ast/builtins.go：

• 名称：crypto.md5
• 功能描述：返回输入字符串经 MD5 函数哈希后的字符串（"Returns a string representing the input string hashed with the MD5 function"）
• 签名：输入参数x为字符串（types.S），返回y为x的 MD5 哈希值（也是字符串）
• 特性：声明了CanSkipBctx: true，表示该函数不依赖内置上下文（Builtin Context），可在不携带上下文的情况下跳过相关处理，纯函数式地完成计算

底层实现原理

从源码 v1/topdown/crypto.go 可以看清其真实调用链：

func builtinCryptoMd5(_ BuiltinContext, operands []*ast.Term, iter func(*ast.Term) error) error { bs, err := builtins.StringOperandByteSlice(operands[0].Value, 1) if err != nil { return err } md5sum := md5.Sum(bs) return iter(ast.StringTerm(toHexEncodedString(md5sum[:]))) }

实现要点如下：

1. 通过builtins.StringOperandByteSlice将第一个操作数（字符串参数）转换为字节切片；若参数类型不符，会返回类型错误。
2. 调用 Go 标准库crypto/md5的md5.Sum(bs)直接计算 16 字节的 MD5 摘要。
3. 通过toHexEncodedString（内部使用encoding/hex）将摘要字节编码为十六进制字符串后返回。因此策略中拿到的computed_digest是形如ea99819f665c10c744cbbf8da651c37a的 32 位十六进制小写字符串，必须与期望值保持相同的编码形式才能正确比对。

此外，crypto.md5的注册位于 v1/topdown/crypto.go，同文件中还实现了crypto.sha1、crypto.sha256等同类摘要内置函数以及基于 HMAC 的crypto.hmac_md5（内部复用md5.New），说明 OPA 在加密摘要方面提供了成体系的函数族，可按需选用。

扩展思考：摘要校验的应用要点

• 适用场景：当策略引擎需要校验上游传来的数据（如 Webhook 载荷、配置快照、签名前的内容）是否在传输过程中被篡改或遗漏时，摘要比对是一种轻量而有效的方案。OPA 本身也广泛使用摘要（如 bundle 的哈希校验，见 v1/bundle/hash.go）来保证内容一致性。
• 先序列化再摘要：由于crypto.md5只接受字符串，任何结构化数据都必须先用json.marshal（或按需选择其他序列化方式）转成字符串。需要注意，序列化的字段顺序会影响摘要结果，OPA 的json.marshal输出是确定性的，示例输出中可以看到字段按字典序排列（action、resource、user），这意味着同一份 JSON 对象在 OPA 中序列化结果稳定，摘要可复现；但若与外部系统约定比对，必须与对方保持一致的序列化规则。
• 安全提示：MD5 属于已被证明存在碰撞缺陷的算法，不适用于需要抗碰撞能力的加密签名场景；在本示例语境下它主要用于内容完整性/一致性校验。若策略对安全性要求更高，可改用同族的 SHA-256（crypto.sha256）等更强算法，调用方式与crypto.md5完全一致。
• 策略落点：digest_valid这样的布尔变量可以直接被授权规则引用（如allow { digest_valid }），让"数据完整"成为放行条件之一，实现数据完整性与访问控制的一体化决策。

• 后端
• 认证鉴权
• 云原生