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

# SessionId 加密与公钥配置

> 汇总 DeCard 托管模式支持的加密与签名能力，包括接口请求签名、Webhook 验签、字段加密和引导页令牌。接口签名规则见鉴权指南，事件验签见Webhook 与 WebSocket 实时通知。

<Warning>
  **DeCard 托管不发布 RSA 公钥、也没有 `SessionId` 请求头**：DeCard 托管模式**没有** `SessionId` 头、**没有** RSA 非对称公钥发布、**没有** JWT 式会话令牌。本页**不**列任何公钥，因为 DeCard 托管并不公布公钥。卡密文 / PIN 等敏感数据不通过"接入机构用公钥加密会话令牌再换密文"的方式获取，而是锁定在 DCS 托管的 H5 页面上呈现（见下文）。
</Warning>

***

### 1. DeCard 托管的敏感数据安全策略

DeCard 托管模式对卡密文、PIN 等敏感操作采用的安全策略如下：

| 维度            | DeCard 托管                                                                                                                  |
| :------------ | :------------------------------------------------------------------------------------------------------------------------- |
| **密钥体系**      | 对称：HMAC-SHA256（API Key + Secret Key）                                                                                       |
| **会话令牌**      | 无 `SessionId`。H5 引导页使用一次性 secret 令牌（由 DCS 生成，见下文）                                                                          |
| **卡敏感信息展示**   | **明文不经过接入机构后端**。卡号/CVV/有效期由 DCS 托管 H5 页直接呈现给终端用户（见 [查看卡敏感信息](../how-to-use/managing-cards/viewing-encrypted-card-details)） |
| **PIN 设置/重置** | DCS 托管 H5 页完成（见 [管理卡片 PIN](../how-to-use/managing-cards/managing-a-cards-pin)）                                             |
| **公钥发布**      | **不公布**。DeCard 托管无公钥基础设施                                                                                                   |

**结论**：DeCard 托管把敏感数据**锁定在 DCS 托管的 H5 页面上，从架构上避免了"接入机构处理加密卡数据"的路径**——接入机构无需持有解密密钥或生成会话令牌，即可为无 PCI 资质的终端安全展示卡号、CVV 与 PIN。

### 2. DeCard 托管具备的加密与签名能力

DeCard 托管提供以下加密/签名能力，各自在对应子页详述；本页汇总索引，方便您快速定位。

#### 2.1 接口请求签名：HMAC-SHA256

每次调用 DCS 接口都需要在请求头携带 `X-DAPI-SIGN` 签名。签名由 HMAC-SHA256 算法、以 DCS 交付的 `SecretKey` 为密钥、对拼接串（`apiKey + timestamp + nonce + payload`）计算得出。

> 详见 [鉴权指南 · 接口签名](./overview#2-接口签名（hmac-sha256）)。

#### 2.2 Webhook 推送验签：HMAC-SHA256（X-Signature）

DCS 向您推送 Webhook 时，在 HTTP 头携带 `X-Signature`。该签名同样是 HMAC-SHA256（密钥为您的 `SecretKey`，待签名内容 `payload` 为原始消息体）。您收到后复算签名进行比对，即可验证来源真实性与消息完整性。

> 详见 [Webhook 与 WebSocket 实时通知 · X-Signature 验签](./webhook-websocket#1-4-安全：x-signature-验签)。

#### 2.3 字段级 AES 加密：手机号

用户注册接口 `POST /account/v1/register` 的 `mobile` 字段**支持 AES 加密传输**（也可传明文）。接口定义注释为：

```json theme={null}
{
  "mobile": ""  // 手机号(支持AES加密/明文)，示例：18232339999（不加区号）
}
```

这意味着接入机构可以选择在传输手机号前用 AES 加密，降低传输环节泄露的风险。DCS 官方示例使用 `SecureUtil.aes(Base64.decode(SECRET)).encryptBase64(mobile)`：以 Base64 解码后的 Secret Key 构造 AES，并把密文输出为 Base64；邮箱使用同一规则。该示例没有单独传 IV 参数，请按官方实现保持一致，不要自行改成另一套 AES-GCM/CBC 报文格式。`/account/v1/register` 的具体请求/响应格式见 [用户注册](../how-to-use/signing-up-a-customer/overview)。

#### 2.4 H5 引导页的一次性 secret 令牌

DCS 托管 H5 页（KYC、卡信息查看、实体卡激活、PIN 设置等）使用**一次性 secret 令牌**进行鉴权：您调用签发接口拿到引导链接（含一次性 secret），终端用户打开该链接，DCS 页面用 `GET /redirect/public/v1/secret-validate?secret=…` 校验其有效性。secret 由 DCS 生成、有效期一次性（用完或过期即失效）。

这是一种**服务端签发、一次性消费**的令牌模型：令牌由 DCS 服务端生成并下发，终端用户打开后由 DCS 校验消费，接入机构无需在客户端生成或加密任何会话令牌。

> 详见 [H5 KYC 与开卡引导页](./h5-kyc-guidance)。

#### 2.5 Apple Pay 与 Google Pay 绑卡加密

在推送绑卡（Push Provisioning）流程中，DeCard 托管涉及 Apple Pay 的 `encryptedPassData`（加密 PAN、有效期、日期时间，Base64）、`activationData`（加密 nonce + nonceSignature + authCode，Base64）、`ephemeralPublicKey`（ECC P-256 曲线、uncompressed 格式、Base64）等加密字段。这些字段的加密由 Apple/Google 的支付令牌化（Tokenization）基础设施完成，**密钥由 Apple/Google 与卡网络管理，不属于 DCS 发布给接入机构的公钥体系**。

> 详见 [Apple Pay 与 Google Pay 绑卡](../how-to-use/managing-cards/push-provisioning)。

### 3. 能力自查清单

| 需求                                   | DeCard 托管是否有 | 对应机制 / 去向                                                                                    |
| :----------------------------------- | :----------- | :------------------------------------------------------------------------------------------- |
| 验证接口请求来源                             | ✅ 有          | HMAC-SHA256 请求签名（[鉴权指南](./overview)）                                                         |
| 验证 Webhook 推送真实性                     | ✅ 有          | `X-Signature` HMAC-SHA256 验签（[Webhook 与 WebSocket](./webhook-websocket)）                     |
| 加密传输用户手机号                            | ✅ 有          | `mobile` 字段 AES 加密，按官方 `SecureUtil.aes(Base64.decode(SECRET)).encryptBase64(...)` 示例（见 §2.3） |
| 安全展示完整卡号/CVV                         | ✅ 有（H5 托管）   | DCS H5 引导页（[查看卡敏感信息](../how-to-use/managing-cards/viewing-encrypted-card-details)）           |
| 设置/重置 PIN                            | ✅ 有（H5 托管）   | DCS H5 引导页（[管理卡片 PIN](../how-to-use/managing-cards/managing-a-cards-pin)）                    |
| 服务端发布 RSA/ECC 公钥供接入机构加密会话令牌          | ❌ 无          | DeCard 托管不采用该安全模型（见 §1）                                                                      |
| 客户端生成 `SessionId` → 请求头携带 → 服务端加解密响应 | ❌ 无          | DeCard 托管不采用该安全模型（见 §1）                                                                      |
| 用于校验会话数据的公钥                          | ❌ 无          | DeCard 托管架构不涉及会话数据公钥（见 §1）                                                                   |

***

## 下一步 / 相关

* 接口鉴权与签名：[鉴权指南](./overview)
* Webhook 推送验签：[Webhook 与 WebSocket 实时通知](./webhook-websocket)
* 安全展示卡信息：[查看卡敏感信息](../how-to-use/managing-cards/viewing-encrypted-card-details)
* PIN 安全设置/重置：[管理卡片 PIN](../how-to-use/managing-cards/managing-a-cards-pin)
* H5 托管页面与一次性 secret：[H5 KYC 与开卡引导页](./h5-kyc-guidance)
* Apple/Google Pay 绑卡加密字段：[Apple Pay 与 Google Pay 绑卡](../how-to-use/managing-cards/push-provisioning)
* 用户注册（含 AES 加密 mobile 字段）：[用户注册](../how-to-use/signing-up-a-customer/overview)