> ## Documentation Index
> Fetch the complete documentation index at: https://learn.orbexa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# UCP安全模型与多层认证机制

> 系统讲解UCP安全模型的多层认证架构设计，覆盖API Keys基础认证、OAuth 2.0用户授权、mTLS双向TLS高安全通信及HTTP消息签名RFC 9421请求完整性验证机制，结合JWK格式签名密钥管理与Content-Digest校验为AI代理商务交易构建从传输层到应用层的完整安全保障体系

# 安全与认证

## 6.1 认证机制总览

UCP支持四种认证机制，适用于不同的安全需求层级：

| 认证方式                        | 标准            | 适用场景              | 安全级别 |
| --------------------------- | ------------- | ----------------- | ---- |
| **API Keys**                | 自定义           | 公开目录浏览、低敏感度操作     | 基础   |
| **OAuth 2.0**               | RFC 6749/6750 | 用户身份关联、代表用户操作     | 标准   |
| **mTLS**                    | RFC 8705      | 服务端到服务端高安全通信      | 高    |
| **HTTP Message Signatures** | RFC 9421      | Webhook签名验证、请求完整性 | 高    |

### API Keys

适用于无需用户身份的场景（如浏览公开商品目录）：

```http theme={null}
GET /ucp/catalog/products?query=鞋
Authorization: Bearer ucp_pk_live_xxxxxxxxxxxx
```

API Key通常区分测试环境（`ucp_pk_test_`）和生产环境（`ucp_pk_live_`）。

### OAuth 2.0

详见第3章。用于需要代表消费者操作的场景（结账、订单查询等）。UCP强制使用Authorization Code + PKCE流程。

### mTLS (Mutual TLS)

双向TLS认证，客户端和服务器都需要提供证书。适用于平台与平台之间的高安全通信：

```text theme={null}
AI代理 ←──mTLS──→ 商家API
  │                   │
  └─ 客户端证书        └─ 服务器证书
     (证明代理身份)       (证明商家身份)
```

mTLS遵循 **RFC 8705 OAuth 2.0 Mutual-TLS Client Authentication**，可以与OAuth 2.0结合使用。

### HTTP Message Signatures (RFC 9421)

UCP的Webhook通知和关键API调用使用HTTP消息签名确保完整性和真实性。这是UCP安全模型中最重要的机制之一。

## 6.2 JWK签名密钥

商家在 `/.well-known/ucp` Profile中发布签名公钥，使用JSON Web Key (JWK)格式：

```json theme={null}
{
  "signing_keys": [
    {
      "kid": "key-2026-04",
      "kty": "EC",
      "crv": "P-256",
      "x": "f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
      "y": "x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0",
      "use": "sig",
      "alg": "ES256"
    }
  ]
}
```

**JWK字段说明**:

| 字段    | 值         | 说明                    |
| ----- | --------- | --------------------- |
| `kid` | 字符串       | 密钥标识符，用于在多个密钥中定位      |
| `kty` | `EC`      | 密钥类型：椭圆曲线             |
| `crv` | `P-256`   | 曲线：NIST P-256         |
| `x`   | Base64URL | 椭圆曲线公钥X坐标             |
| `y`   | Base64URL | 椭圆曲线公钥Y坐标             |
| `use` | `sig`     | 用途：签名                 |
| `alg` | `ES256`   | 算法：ECDSA with SHA-256 |

**密钥轮换**: 商家可以在 `signing_keys` 数组中同时发布多个密钥（通过不同的 `kid` 区分），支持平滑的密钥轮换。旧密钥在过渡期内保留，新签名使用新密钥。

## 6.3 HTTP消息签名 (RFC 9421)

### 签名创建（商家侧）

商家发送Webhook时，按RFC 9421标准创建签名：

**步骤1**: 计算请求体的Content-Digest（RFC 9530）

```http theme={null}
Content-Digest: sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:
```

**步骤2**: 定义签名输入（Signature-Input）

```http theme={null}
Signature-Input: sig1=("@method" "@target-uri" "content-digest" "content-type");created=1712836800;keyid="key-2026-04";alg="ecdsa-p256-sha256"
```

签名组件说明：

* `@method`: HTTP方法（如POST）
* `@target-uri`: 完整请求URI
* `content-digest`: 请求体摘要
* `content-type`: 内容类型
* `created`: 签名创建时间戳（Unix时间）
* `keyid`: 对应Profile中的JWK `kid`
* `alg`: 签名算法

**步骤3**: 构造签名基础字符串

```text theme={null}
"@method": POST
"@target-uri": https://agent.example.com/webhooks/ucp
"content-digest": sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:
"content-type": application/json
"@signature-params": ("@method" "@target-uri" "content-digest" "content-type");created=1712836800;keyid="key-2026-04";alg="ecdsa-p256-sha256"
```

**步骤4**: 使用私钥（ES256）对基础字符串签名

```http theme={null}
Signature: sig1=:MEUCIQDXsM...base64签名值...=:
```

### 签名验证（AI代理侧）

```text theme={null}
验证清单:

1. 解析 Signature-Input 获取 keyid 和签名组件列表
2. 从商家 /.well-known/ucp 获取对应 kid 的 JWK 公钥
3. 验证 Content-Digest:
   - 计算请求体的 SHA-256 哈希
   - 与 Content-Digest 头中的值比较
4. 按 Signature-Input 中的组件顺序重建签名基础字符串
5. 使用 JWK 公钥验证 ES256 签名
6. 检查 created 时间戳（拒绝超过5分钟的签名）
7. 验证通过 → 处理Webhook
   验证失败 → 返回 401，记录安全日志
```

## 6.4 Content-Digest (RFC 9530)

Content-Digest头提供请求体的完整性校验，防止传输过程中的篡改：

```http theme={null}
Content-Digest: sha-256=:base64编码的SHA-256哈希:
```

计算方式：

```text theme={null}
1. 取完整的HTTP请求体（raw bytes）
2. 计算 SHA-256 哈希
3. Base64编码
4. 格式: sha-256=:base64值:
```

Content-Digest与HTTP消息签名配合使用——签名覆盖Content-Digest头，Content-Digest覆盖请求体，形成完整的安全链条。

## 6.5 传输安全

| 要求                           | 说明                                 |
| ---------------------------- | ---------------------------------- |
| **HTTPS必须**                  | 所有UCP通信必须使用HTTPS，Profile端点不允许重定向   |
| **TLS 1.2+**                 | 最低TLS 1.2，推荐TLS 1.3                |
| **证书验证**                     | AI代理必须严格验证商家的TLS证书                 |
| **HSTS**                     | 建议启用HTTP Strict Transport Security |
| **Certificate Transparency** | 建议使用CT日志中的证书                       |

## 6.6 数据安全与隐私

UCP对数据处理有明确的安全边界：

| 数据类型     | AI代理的权限             | 禁止行为      |
| -------- | ------------------- | --------- |
| 商品目录     | 缓存、展示给用户            | 用于模型训练    |
| 买家个人信息   | 传递给商家完成交易           | 存储或共享给第三方 |
| 支付凭证     | 通过Payment Handler传递 | 存储、记录或转发  |
| 订单数据     | 展示给对应消费者            | 聚合分析或数据挖掘 |
| 签名密钥（私钥） | 不应接触私钥              | 任何形式的获取   |

## 6.7 安全最佳实践

1. **密钥轮换**: 定期轮换JWK签名密钥，在Profile中同时发布新旧密钥确保平滑过渡
2. **速率限制**: 对所有UCP端点实施合理的速率限制
3. **审计日志**: 记录所有结账和订单操作的完整审计日志
4. **签名时间窗口**: Webhook签名的 `created` 时间戳应在5分钟以内
5. **令牌安全**: access\_token不应出现在URL参数或日志中
6. **CORS**: UCP API端点应配置严格的CORS策略
7. **输入验证**: 所有输入参数必须严格验证类型和范围

***

**下一章**: [商家集成指南](/zh/book-3/ch7-merchant-integration) — `/.well-known/ucp` Profile部署和能力声明