Varwof.org
Index Demo GitHub

01 Asn1中文

Source: https://github.com/varwof/dev-docs/blob/main/aic/zh/01-asn1.md

AIC ASN.1 类型定义

对应规范版本 v1.7.1。已知限制（参数级子集校验）见 02-code-map.md。 关键文件：gateway-core/aic.go、gateway-core/decision.go、gateway-core/constraints.go

AIC 整体结构

AIC ::= SEQUENCE {
    version                     INTEGER DEFAULT 1,
    agentId                     UTF8String (SIZE(1..256)),
    principalUid                PrincipalUid,
    capabilities                SEQUENCE SIZE(0..256) OF Capability,
    delegationMode              DelegationMode DEFAULT authorized,
    authorizationConstraints    [0] EXPLICIT SEQUENCE SIZE(0..32) OF Capability OPTIONAL,
    delegationAuthorization     DelegationAuthorization,
    extensions                  [1] EXPLICIT Extensions OPTIONAL
}

DelegationMode ::= INTEGER {
    authorized (0),
    representative (1)
} (0..1)
字段 类型 约束 说明
version INTEGER DEFAULT 1 仅定义 v1 AIC 版本号
agentId UTF8String SIZE(1..256) Agent 唯一标识，续期不变
principalUid SEQUENCE 见下 责任主体标识
capabilities SEQUENCE OF Capability 0~256 条 CA 认证后的 Capability 声明
delegationMode INTEGER (0..1) authorized / representative 委托模式
authorizationConstraints SEQUENCE OF Capability OPTIONAL 0~32 条 授权边界约束（v1.6 新增）
delegationAuthorization SEQUENCE 见下 主体签名证据
extensions Extensions OPTIONAL ≤32 条 通用扩展槽

delegationAuthorization 为必填字段。双证书部署时，握手证书与授权证书均为完整 AIC，均 MUST 携带（见 08-dual-cert.md）。

authorizationConstraints

复用 Capability 容器，schemeId MUST 为 "varwof/constraint-v1"（规范推荐值）；为向后兼容，代码亦接受 "constraint" 和 "constraint-v1"；其他 schemeId 被跳过，capabilityId 标识具体约束类型：

capabilityId parameters 格式 说明
network:cidr ["10.0.0.0/8", "192.168.0.0/16"] 允许的 IP 网段
session:max-concurrent {"max": 5} 最大并发 Agent 实例数
time:window {"start": "22:00", "end": "06:00"} 允许执行的时间窗口

约束数量上限 ≤ 32 条（wire 格式 + CA 签发阶段统一），单条 parameters ≤ 512 字节。

设计原则（"有限的限制"）：

  • 只放授权边界，不放运行时策略（超时/重试/限流/路由）
  • 由授权方决定、因人而异、变更频率低
  • 网关在 TLS 握手阶段离线验证，不依赖外部系统

编码标签约定（Context Tags）

为跨平台、跨语言稳定实现，编码标签遵循以下规则（v1.7.1）：

  1. 必填字段使用 universal tag（INTEGER / UTF8String / OCTET STRING / SEQUENCE 等），不打 context tag；同 tag 的必填字段按结构内位置顺序解码，无歧义。
  2. 所有 OPTIONAL 字段一律使用 context-specific 显式标签 [n] EXPLICIT，编号按字段在结构内出现的顺序从 0 开始；同一结构内编号唯一，跨结构可重复。
  3. 标准外部类型（AlgorithmIdentifier、Extensions 等）遵循 RFC 5280 编码约定，不套用本规则（如 AlgorithmIdentifier.parameters 保持无标签 OPTIONAL）。
  4. DEFAULT 字段编码：DER 允许省略等于默认值的字段，实现 MUST 容忍两种形式；Go encoding/asn1 当前总是编码 DEFAULT 字段（非最小 DER，但可解析）。
结构 字段 tag 说明
AIC authorizationConstraints [0] 与 capabilities / delegationAuthorization 同 SEQUENCE tag，必须区分
AIC extensions [1] 结构末尾，显式标签防未来歧义
DelegationAuthTBS authorizationConstraints [0] 与 capabilities 同 SEQUENCE tag，必须区分
PrincipalAuthorization authorizationConstraints [0] 与 grants 同 SEQUENCE tag，必须区分
PrincipalAuthorization delegationPolicy [1] 与 grants / constraints 同 SEQUENCE tag，必须区分
PrincipalAuthorization extensions [2] 结构内 SEQUENCE 字段 tag 全唯一
DelegationPolicy maxSessionHours [0] 与三个必填 INTEGER 字段区分
PrincipalUid hashAlgo [0] 末尾 OPTIONAL
Capability parameters [0] 既有约定，保持不变

说明：DelegationMode / DelegationModeEnum 定义为 INTEGER + 命名常量 + 范围约束（(0..1)），Go encoding/asn1 原生支持，跨语言实现一致。

PrincipalUid

PrincipalUid ::= SEQUENCE {
    version     INTEGER (0..255) DEFAULT 1,
    realm       UTF8String (SIZE(1..128)),
    identifier  UTF8String (SIZE(1..256)),
    keyHash     OCTET STRING (SIZE(1..64)),
    hashAlgo    [0] EXPLICIT AlgorithmIdentifier OPTIONAL
}
-- hashAlgo 省略时默认 SHA-256（OID 2.16.840.1.101.3.4.2.1）；keyHash = hashAlgo(SPKI)；
-- 规范仅支持输出长度不超过64字节的哈希算法（SHA-2/SHA-3 系列、BLAKE2/BLAKE3、国密 SM3 等均满足）
字段 说明
realm 全局命名空间（如组织域名 corp.com），SIZE(1..128)
identifier 空间内唯一标识（如 zhangsan），SIZE(1..256)
keyHash SPKI 按 hashAlgo 求值的哈希（SHA-256/SM3 = 32 字节），长度由算法决定
hashAlgo keyHash 的计算算法标识，省略时默认 SHA-256

keyHash 绑定的是 SPKI 而非证书指纹或纯身份字符串。选择依据：证书指纹随换证变化、破坏身份连续；纯身份字符串无密码学绑定、无法离线验证归属；SPKI 哈希可离线验证归属、同密钥换证身份连续、密钥更换即全部关联授权失效。同一密钥对换发新证书时 SPKI 不变，Agent 证书自动延续。

keyHash 计算 MUST 使用 hashAlgo 声明的哈希算法对主体 SPKI 求值（keyHash = hashAlgo(SPKI)）；省略时默认 SHA-256（OID 2.16.840.1.101.3.4.2.1）。规范仅支持输出长度不超过 64 字节的哈希算法（受 keyHash OCTET STRING (SIZE(1..64)) 约束）：当前实现（pki-types P1-A-12）已支持 SHA-2/SHA-3 全族计算——SHA-256（32 字节）/ SHA-384（48）/ SHA-512（64）/ SHA3-256（32）/ SHA3-384（48）/ SHA3-512（64），keyHash 长度随算法输出长度变化，无需修改结构；BLAKE2/BLAKE3、国密 SM3 等输出长度 ≤64 字节的算法因 pki-types 零外部依赖策略仅登记 OID 与长度映射、暂不提供计算实现（显式报 unsupported，不静默降级），接入方可在依赖侧自行实现；若未来需要支持输出长度超过 64 字节的算法（如 SHAKE 长输出），需升级 AIC version 并放宽 SIZE 约束。

安全策略：主体密钥轮换将导致 PrincipalUid.String() 变更（因 KeyHash 变化）。此时已签发的存量 Agent 证书 MUST 通过吊销流程（CRL/OCSP）失效。此设计强制主体密钥与 Agent 授权强绑定，防止身份冒用，符合短命证书安全模型。

通信格式 realm:identifier:keyFingerprint 仅供人类阅读和日志输出，机器判等 MUST 基于 ASN.1 结构体反序列化。需要按主体检索/关联（级联吊销、审计、证书查询）时，可通过数据库索引或 PrincipalUid.realm / identifier 字段完成；该查找仅用于管理关联，授权绑定与吊销仍以 keyHash 为准。

Capability

Capability 是协议中唯一的通用容器，语义由 schemeId 定义。

Capability ::= SEQUENCE {
    schemeId        UTF8String (SIZE(1..128)),
    capabilityId    UTF8String (SIZE(1..256)),
    parameters      [0] EXPLICIT OCTET STRING (SIZE(0..4096)) OPTIONAL
}

Glob 匹配规则：

模式 含义 示例
http:GET:/api/v1/users 精确匹配 仅该路径
http:GET:/api/v1/* 单段通配（* 不含 /） /api/v1/users
http:*:/api/v1/* 通配 HTTP 方法 任意方法的 /api/v1/
varwof-gateway-v1:* 方案下所有能力 该 schemeId 任意 capabilityId
/api/v1/** 跨路径任意深度 /api/v1/users、/api/v1/users/roles

Reason

委托授权原因说明，供审计与展示，不参与权限决策。语义由授权方决定。reason 仅用于 DelegationAuthorization / DelegationAuthTBS（描述本次委托的原因），不进入 PrincipalAuthorization。

Reason ::= SEQUENCE {
    reasonCode  UTF8String (SIZE(1..64)),     -- 机器识别的标准原因码（受控词表，如 "SCHEDULED_MAINTENANCE"），应尽可能短
    description UTF8String (SIZE(1..512))     -- 人类可读的详细描述（如 "因版本v2.3.1上线，需临时关闭旧缓存"）
}
字段 类型 约束 说明
reasonCode UTF8String SIZE(1..64)，MUST 非空 机器识别的标准原因码（受控词表，如 SCHEDULED_MAINTENANCE），应尽可能短
description UTF8String SIZE(1..512)，MUST 非空 人类可读的详细描述（如 因版本v2.3.1上线，需临时关闭旧缓存）

v1.7.1 新增。reasonCode 和 description 均 MUST 存在；Reason 在 DelegationAuthorization / DelegationAuthTBS 中为必填字段（授权必有缘由）。 reasonCode 为受控词表：取值使用 SCREAMING_SNAKE 风格（如 SCHEDULED_MAINTENANCE、AUTO_RENEWAL），应尽可能短（数字或简短文字，≤64）；新增取值需注册（当前为实现方维护的受控白名单，注册机制待定）。

DelegationAuthorization

DelegationAuthorization ::= SEQUENCE {
    reason             Reason,                          -- v1.7.1 新增：委托授权原因（必填）
    requestedLifetime  INTEGER (1..86400),              -- SHOULD 3600–86400；API 输入层 0 → 3600 归一化，wire 值恒为 1..86400
    timestamp          GeneralizedTime,
    nonce              OCTET STRING (SIZE(32)),
    signatureAlgorithm AlgorithmIdentifier,
    signatureValue     OCTET STRING
}

设计决策：signatureAlgorithm / signatureValue 平铺，不合并为嵌套 Signature 类型（v1.7.1 定案，2026-08-06 复核确认）

DelegationAuthorization 中签名算法与签名值平铺为 signatureAlgorithm AlgorithmIdentifier + signatureValue OCTET STRING 两个并列字段，与 RFC 5280 §4.1 的 Certificate ::= SEQUENCE { tbsCertificate, signatureAlgorithm, signatureValue } 顶层三段惯例一致（CMS/PKCS#7 亦同）。理由：

  1. 统一解析路径：验证方用同一解析顺序（先取算法 OID、再取签名值）处理 CA 签名与主体签名，双层签名无需两套解析逻辑；
  2. 惯例一致性：X.509/CMS 均平铺，合并为嵌套 Signature ::= SEQUENCE { algorithm, value } 属非惯例做法，无安全或功能收益；
  3. 无复用需求：签名结构目前仅出现于 DA，将来若需复用可在新版本定义独立类型，不影响现有 wire format。

不得将 signatureAlgorithm / signatureValue 合并为嵌套 SEQUENCE。

  • nonce：必填 32 字节，防重放
  • requestedLifetime：1–86400 秒（SHOULD 3600–86400），默认 3600（1 小时）。wire 值恒为 1..86400；"0 → 3600"仅存在于 API 输入层归一化（调用方传 0 时按默认 3600 处理），编码进 TBS/DA 的值必须已在 1..86400 范围内。
  • timestamp：MUST 为 UTC（GeneralizedTime Z 形式）
  • reason：v1.7.1 新增，必填，位于结构首位；与 DelegationAuthTBS.reason 为同一委托原因（TBS 内被签名覆盖）

DelegationAuthTBS（签名覆盖结构）

主体私钥签名的是以下结构的 DER 编码：

DelegationAuthTBS ::= SEQUENCE {
    version                  INTEGER DEFAULT 1,
    agentId                  UTF8String (SIZE(1..256)),
    principalUid             PrincipalUid,
    reason                   Reason,                          -- v1.7.1 新增：委托授权原因（必填，被签名覆盖）
    capabilities             SEQUENCE SIZE(0..256) OF Capability,
    delegationMode           DelegationMode,
    authorizationConstraints [0] EXPLICIT SEQUENCE SIZE(0..32) OF Capability OPTIONAL,
    requestedLifetime        INTEGER (1..86400),              -- SHOULD 3600–86400
    timestamp                GeneralizedTime,                 -- MUST 使用 UTC（Z 形式）
    nonce                    OCTET STRING (SIZE(32))
}

v1.6 新增 authorizationConstraints 字段。为保持向后兼容，该字段为 OPTIONAL。旧证书无此字段不影响验证。

设计决策：DelegationAuthTBS 不含 Agent 公钥哈希（agentKeyHash）（v1.7.1 定案，2026-08-06 复核确认）

1. 责任模型：当前 AI/Agent 属机器范畴、不具备法律主体资格，授权责任主体为自然人（principalUid.keyHash 锚定）。用户/责任主体的签名覆盖"授权范围"（agentId + capabilities + 授权边界 + 授权缘由 + 期限 + nonce）即可；Agent 的"身份 ↔ 公钥"绑定由 CA 在证书签发时完成（CSR 持钥证明 + 证书级 SPKI 绑定），无需重复进入授权证据链。

2. 简洁性：AIC 证书的 TBSCertificate 已含 Agent SPKI，TBS 再增加 agentKeyHash 属重复信息，且增加 wire format 复杂度与用户审批负担（要求自然人核对密钥指纹不现实）。

3. 信任边界：剩余风险（签发通道中的 key-swap：在用户确认与 CA 签发之间替换 CSR 公钥）属于"签发通道不受控"场景，与 CA 私钥泄露同属信任根/通道失守边界；本规范假定签发通道受控。

4. 演进预留：当 AI/Agent 取得法律主体资格（成为独立权利/义务主体），或部署要求完全不可信的签发通道时，可通过 TBS version 升级向后兼容地增加 agentKeyHash（hashAlgo(Agent SPKI)）字段，使责任主体签名覆盖"授权给该 agentId 的这把公钥"，将 Agent 自身纳入授权证据链。旧证书与旧验证逻辑不受影响（version 字段区分，参照 v1.6 → v1.7 的演进方式）。

v1.7.1：reason 位于 DelegationAuthTBS（principalUid 之后）与 DelegationAuthorization（结构首位），均为必填——授权必有缘由；TBS 内的 reason 被主体签名覆盖，主体签名时即已知晓委托原因。

PrincipalAuthorization

PrincipalAuthorization ::= SEQUENCE {
    version                     INTEGER DEFAULT 1,
    grants                      SEQUENCE SIZE(0..256) OF Capability,
    authorizationConstraints    [0] EXPLICIT SEQUENCE SIZE(0..32) OF Capability OPTIONAL,
    delegationPolicy            [1] EXPLICIT DelegationPolicy OPTIONAL,
    extensions                  [2] EXPLICIT Extensions OPTIONAL
}

DelegationPolicy ::= SEQUENCE {
    version             INTEGER DEFAULT 1,
    maxAgents           INTEGER DEFAULT 1,
    allowedMode         DelegationModeEnum DEFAULT authorizedOnly,
    maxSessionHours     [0] EXPLICIT INTEGER OPTIONAL
}

DelegationModeEnum ::= INTEGER {
    authorizedOnly (0),
    representativeAllowed (1)
} (0..1)
字段 类型 约束 说明
version INTEGER DEFAULT 1 仅定义 v1 版本号
grants SEQUENCE OF Capability ≤ 256 条 主体允许授予的能力集合。直接使用时 = 权限上界；委托时 = Agent 能力的上界
authorizationConstraints SEQUENCE OF Capability OPTIONAL SIZE(0..32) v1.6.1。主体级授权边界约束，定义 Principal 在何种条件下行使授权。复用 Capability 容器，schemeId MUST 为 "varwof/constraint-v1"（规范推荐值，向后兼容接受 "constraint" / "constraint-v1"）。CA 签发阶段与 wire 格式统一上限 32 条
delegationPolicy SEQUENCE OPTIONAL 委托策略
extensions Extensions OPTIONAL ≤ 32 条 通用扩展槽

委托约束（v1.6）：

  • 当前仅支持 Principal → Agent 单层委托（chainDepth = 0）
  • 多级委托链（FUTURE）：已授权 Agent 可使用自身私钥对下级 Agent 签发新的 DelegationAuthorization，形成可递归验证的密码学证据链
  • Agent 证书 MUST 为终端实体证书（cA = FALSE）
  • 当前 Agent MUST NOT 派生下级 Agent

DelegationDepthControl（FUTURE — 规范预留，暂不实现）

放置于 AIC extensions 槽位，OID 1.3.6.1.4.1.66257.1.1.4：

DelegationDepthControl ::= SEQUENCE {
    chainDepth  INTEGER (0..255),  -- OID .1.1.4.1
    maxDepth    INTEGER (0..255)   -- OID .1.1.4.2
}
字段 类型 说明
chainDepth INTEGER (0..255) 当前委托层级。直接授权 = 0，一级委托 = 1，以此类推
maxDepth INTEGER (0..255) 最大允许委托深度。网关验证 chainDepth ≤ maxDepth，超出则拒绝连接

设计原则：

  • 该扩展仅在启用多级委托链时使用，单层部署可不携带
  • 每一级委托的 DelegationAuthorization 独立签名，任何一跳被篡改均导致整链失败
  • 验证方离线完成：解析证书扩展 → 逐级验签 → 检查 chainDepth ≤ maxDepth，不依赖外部服务
  • 多级委托模式下，chainDepth = N 的 Agent 对下级授权时，构造的 DelegationDepthControl 中 chainDepth = N+1、maxDepth 不变
  • 暂不实现：当前网关仅支持单层委托（直接授权 = 0），多级委托链的 CA 签发逻辑、网关验证管线、审计追踪均为 FUTURE

权限交集公式

CapabilityId 级别的交集：

EffectiveCapability = P_grants ∩ C_agent ∩ T_policy
集合 来源 说明
P_grants PrincipalAuthorization.grants 主体允许授予的能力
C_agent AIC.capabilities CA 认证后的 Agent 能力声明
T_policy 网关本地策略 部署侧配置的策略约束

Capability Parameters 交集语义（v1.6 明确）：

对于每条匹配的 Capability：
  if C_agent.parameters 超出 P_grants.parameters 的边界范围：
    该条 Capability 视为无效（被过滤或拒绝）
  else:
    完全采用 C_agent.parameters（以 Agent 为准，但不越界）

示例：

主体授权 Agent 声明 结果
mysql:SELECT:*（max_rows=1000） mysql:SELECT:*（max_rows=100） ✅ 通过，取 max_rows=100
mysql:SELECT:*（max_rows=1000） mysql:SELECT:*（max_rows=5000） ❌ 拒绝（超出主体边界）
http:GET:/api/v1/* http:GET:/api/v1/users ✅ 通过，取 Agent 声明的具体路径

主体定义最大权限边界，Agent 声明具体操作参数。Agent 的参数 MUST 在主体授权范围内，超出即拒绝。

执行层（v1.7.1 明确）：该参数级子集校验在 CA 签发阶段由 CA 机械执行（与能力级子集同一层：capabilities ⊆ grants 且各参数不越界）；网关运行时执行能力级 P∩C∩T 交集、不再逐参数比对（参数边界已由签发阶段固化）。本规则仅适用于能力层（capabilities/grants）；授权约束层（authorizationConstraints）不适用子集关系——PA 与 AIC 约束各自独立检查（v1.6.1 保持）。

证书体积约束

证书类型 建议上限 硬上限 说明
全协议安全上限 12KB 16KB DER 编码保证 TCP/HTTP/DTLS/QUIC 四网关全部兼容。16KB 对应 QUIC CRYPTO_BUFFER_EXCEEDED（quic-go 硬限制），超过即握手失败
握手证书（AIC 轻量版） 8KB 16KB 用于 mTLS/DTLS/QUIC 握手。双证书部署时含 agentId + principalUid + delegationMode + DelegationAuthorization，capabilities 至少一条（具体占位能力由部署按注册表定义）
完整授权证书（含全部 constraints + extensions） 64KB 128KB 握手完成后通过应用层传输。超出 128KB MUST 被网关拒绝
capabilities 条目 ≤ 256 条 — 约 250 条能力声明=~12KB DER。256 为 ASN.1 SEQUENCE SIZE 上限

v1.6：双证书部署方案见 08-dual-cert.md。握手证书只包含 agentId + principalUid + delegationMode + DelegationAuthorization（capabilities 至少一条，具体占位能力由部署按注册表定义），始终小于 8KB，确保在所有传输层协议下稳定通过。