本文介绍如何使用证书中心提供的 [c2patool](https://github.com/volcengine/c2patool)（火山引擎 C2PA SDK 定制版）组装 C2PA Manifest，并调用云签服务完成签名与写入。该工具基于官方 [contentauth/c2pa-rs](https://github.com/contentauth/c2pa-rs/tree/main/cli) 定制，内置了证书中心 C2PA 云签远程 Signer。您只需配置访问密钥（AK/SK）和证书实例 ID，即可通过命令行完成端到端签名，无需自行安装官方 c2pa\-rs 或实现远程 Signer。 > **说明** > 云签流程对您透明。执行签名命令时，工具依次完成： 1. > 通过 [GetC2PAInstance](https://docs.volcengine.com/docs/6638/2665212) 拉取本次签名使用的 C2PA 证书链； 2. > 在本地计算内容绑定（Hard Binding）并组装 Claim / Manifest； 3. > 把待签数据提交到 [C2PASign](https://docs.volcengine.com/docs/6638/2665213)，由云端 HSM 完成签名（私钥全程保存在云端，不可导出）； 4. > 将签名结果与 Manifest 写入目标文件。 > 因此，CLI 签名路径下您不需要手动调用 GetC2PAInstance / C2PASign，也不需要在本地保存任何私钥。工具仓库为 [volcengine/c2patool](https://github.com/volcengine/c2patool)。 ## 工具概览 |**工具** |**说明** |**适用场景** |**仓库地址** | |---|---|---|---| |云签版 c2patool（火山引擎 C2PA SDK） |基于官方 c2patool / c2pa\-rs 定制，内置证书中心云签远程 Signer，同时保留 Manifest 组装、写入、查看与验证能力。 |脚本化 / 批量签名、服务端通过命令行集成、内容凭证的查看、验证与调试。 |[volcengine/c2patool](https://github.com/volcengine/c2patool) | |c2pa\-rs（官方 Rust SDK） |C2PA 官方 Rust SDK，云签版 c2patool 即基于它构建。 |需要在自有服务代码中深度集成、自定义 Manifest 组装流程；可参考火山定制版源码中的云签 Signer 实现。 |[contentauth/c2pa-rs](https://github.com/contentauth/c2pa-rs) | > **注意** > 请勿直接使用官方 c2patool 对接证书中心云签。官方版本默认使用本地 PEM 私钥 / 证书签名，不识别火山引擎 AK/SK、区域与证书实例等云签参数，无法调用证书中心云签服务。云签场景请使用 [volcengine/c2patool](https://github.com/volcengine/c2patool)。 ## 安装与构建云签版 c2patool 支持 macOS、Linux、Windows。当前以源码构建为主，需要本地已安装 Rust 工具链（安装方式参见 [rustup](https://rustup.rs/)）。 ```Bash # 获取源码 git clone https://github.com/volcengine/c2patool.git cd c2patool # 构建发布版本 cargo build --release ``` 构建产物位于 `target/release/c2patool`，将其加入 PATH 后，用以下命令验证： ```Bash c2patool --help ``` ## 准备工作开始签名前，请确认： 1. **已购买并签发 C2PA 证书，** 并确认实例状态为 **已签发**。具体操作，请参见[购买 C2PA 证书](https://docs.volcengine.com/docs/6638/2586558)。 2. **已准备访问密钥（AK/SK）** ，且对应账号 / 角色已被授予 C2PA 签名相关权限。权限与授权流程参见[证书中心 C2PA 功能完整使用流程](https://docs.volcengine.com/docs/6638/2663741)。 3. **已准备待签文件**，以及描述断言的 Manifest JSON（见 [准备 Manifest](https://docs.volcengine.com/docs/6638/2663807?#idQzUStD)）。 4. **获取云签接入信息**。接入证书中心云签时，以下取值固定：网关地址 `https://pca.volcengineapi.com`（`--signer-url`）、区域 `cn-north-1`（`--volc-region`）、服务名 `pca`（`--volc-service`）、API 版本 `2025-10-01`（`--volc-version`）。各 `--volc-*` 参数也支持去掉前缀的等价写法（如 `--volc-ak` 等价 `--access-key`），完整对照见下文参数表。网关地址与请求结构的通用说明参见 [调用方法](https://docs.volcengine.com/docs/6638/2587614)。 ## 配置云签凭证（AK/SK）推荐通过环境变量配置 Access Key、Secret Key 和证书实例 ID，避免把密钥写进命令行历史或提交到代码仓库。 ```Bash export SIGNER_ACCESS_KEY="您的 Access Key ID" export SIGNER_SECRET_KEY="您的 Secret Access Key" # 未设置时工具会回退读取 VOLC_SECRET_KEY export SIGNER_INSTANCE_ID="您的 C2PA 证书实例 ID" # 证书中心云签网关地址不支持环境变量，用 shell 变量保存后在签名命令中展开传入（请勿 export，工具不读取该变量） SIGNER_URL="https://pca.volcengineapi.com" ``` > **说明** > 云签网关地址必须在命令行中通过 `--signer-url` 显式指定；只要传入该参数，工具即启用云签模式，其余凭证自动从环境变量读取。云签相关参数也可以通过命令行传入。命令行参数与环境变量的对应关系如下： |**命令行参数** |**环境变量** |**默认值** |**说明** | |---|---|---|---| |`--signer-url ` |— |无（必填） |云签网关地址，提供该参数即启用云签模式。不支持环境变量，必须显式传入。接入证书中心时固定为 `https://pca.volcengineapi.com`。 | |`--volc-ak `（等价 `--access-key`） |`SIGNER_ACCESS_KEY` |无（必填） |Access Key ID。 | |`--volc-sk `（等价 `--secret-key`） |`SIGNER_SECRET_KEY` |无（必填） |Secret Access Key。

> **说明**

> 若 `--secret-key` 与 `SIGNER_SECRET_KEY`均未设置，工具会回退读取 `VOLC_SECRET_KEY`（该变量仅在云签模式下生效）。
| |`--volc-instance-id `（等价 `--instance-id`） |`SIGNER_INSTANCE_ID` |无（必填） |C2PA 证书实例 ID，用于 [GetC2PAInstance](https://docs.volcengine.com/docs/6638/2665212) 与 [C2PASign](https://docs.volcengine.com/docs/6638/2665213)。 | |`--volc-region `（等价 `--region`） |— |`cn-north-1` |服务区域。 | |`--volc-service `（等价 `--service`） |— |`c2pa_tob` |OpenAPI 服务名。CLI 内置默认值为 `c2pa_tob`；接入证书中心必须显式指定为 `pca`。 | |`--volc-version `（等价 `--api-version`） |— |`1.0` |API 版本。CLI 内置默认值为 `1.0`；接入证书中心必须显式指定为 `2025-10-01`。 | |`--signing-algorithm `（等价 `--volc-signing-algorithm`） |— |`RSASSA_PSS_SHA_256` |云签签名算法。支持的云签算法：

* `RSASSA_PSS_SHA_256`（默认，对应 PS256）

* `RSASSA_PSS_SHA_384`

* `RSASSA_PSS_SHA_512`

* `ECDSA_SHA_256`

* `ECDSA_SHA_384`

* `ECDSA_SHA_512`

* `ED25519_SHA_512` | |`--use-time-authority` |— |关闭 |启用可信时间戳（TSA）；TSA 地址取 Manifest 中的 `ta_url` 或环境变量 `C2PA_TA_URL`。 | > **说明** * > 请勿把 AK/SK 硬编码到脚本或提交到 Git。生产环境建议通过环境变量或密钥管理服务注入，并按最小权限原则授予签名权限。 * > 若未提供 `--signer-url`，工具会回退到本地签名模式（需要本地 PEM 私钥 / 证书）。证书中心私钥由云端 HSM 托管、不可导出，因此本地模式**不适用于**证书中心云签场景。 ## 准备 Manifest Manifest JSON 描述本次要写入的 Claim、断言（assertion）和素材来源（ingredient）。一个最小可用的 Manifest 只需声明签名方身份和标题；内容绑定（文件 Hash）由工具在签名时自动计算，无需手动填写： ```JSON { "claim_generator_info": [ { "name": "my-c2pa-signer", "version": "1.0.0", "specVersion": "2.4.0" } ], "title": "示例图片", "assertions": [ { "label": "c2pa.actions.v2", "data": { "actions": [ { "action": "c2pa.created" } ], "allActionsIncluded": true } } ] } ``` > **说明** > 建议通过 claim_generator_info（name + version + specVersion）声明签名方 / 工具身份。若省略该字段或传空数组，SDK 会自动填入 c2pa 库自身的名称与版本作为默认身份。specVersion 需与实际 c2patool 版本能力匹配，对照见 [C2PA Manifest 写入规范指导文档](https://docs.volcengine.com/docs/6638/2587619)。常见可选字段： * `assertions`：主动声明的断言，例如 `c2pa.actions.v2`（对素材执行的操作）、`c2pa.metadata`（创建工具 / 拍摄信息）。 * `ingredients`：引入的上游素材及其 C2PA Manifest，用于多素材合成场景。更复杂的写入要求（AI 生成标注、多素材合成、转码重封装等）参见[C2PA Manifest 写入规范指导文档](https://docs.volcengine.com/docs/6638/2587619)及各[最佳实践](https://docs.volcengine.com/docs/6638/2663742)文档。 ## 签名并写入按上一节完成环境变量配置后，按下例显式传入云签网关地址（`--signer-url`）、服务名（`--service`）与 API 版本（`--api-version`）即可进入云签模式；区域默认 `cn-north-1` 已与证书中心一致，无需额外指定： ```Bash c2patool input.jpg \ --manifest manifest.json \ --output signed.jpg \ --signer-url "$SIGNER_URL" \ --service pca \ --api-version 2025-10-01 ``` 以下为完整的 c2patool 调用示例，云签参数使用 `--volc-*` 形式（与去掉前缀的长参数等价）： ```Bash c2patool \ input.jpg \ # 要写入的原始文件 -p parent.jpg \ # 父文件，视情况而定，可传可不传 --volc-region cn-north-1 \ # 火山引擎服务的 Region --volc-service pca \ # 服务名，固定为 pca --volc-version 2025-10-01 \ # API 版本，固定为 2025-10-01 --volc-instance-id c2pa-cert-3d4efbb4df1e4dfc8fe37a3050f3dc5f \ # 签名使用的证书实例 ID --volc-ak "$VOLC_AK" \ # 账号的 AK --volc-sk "$VOLC_SK" \ # 账号的 SK --signer-url https://pca.volcengineapi.com \ # C2PA 云签服务的 API 地址 -m manifest.json \ # 要写入的 Manifest 文件 -o output2.jpg \ # 输出文件路径 --force # 输出文件已存在时是否覆盖 ``` * 示例中 `#` 后为参数说明，实际执行时请删除注释；需要可直接复制的命令可使用上文基于环境变量的写法。 * `-p`（`--parent`）为可选参数：产物衍生自已有文件时用于指定父素材（如多素材合成、转码 / 重封装场景），纯新建内容可省略。 * 云签参数同时支持 `--volc-*` 与去掉前缀两种等价写法（如 `--volc-ak` 等价 `--access-key`）；AK/SK 与证书实例 ID 也可通过 `SIGNER_ACCESS_KEY` / `SIGNER_SECRET_KEY` / `SIGNER_INSTANCE_ID` 环境变量传入。 * 接入证书中心时，网关地址、服务名与 API 版本取值固定（`https://pca.volcengineapi.com` / `pca` / `2025-10-01`），不要使用工具内置的默认服务名与版本。输出文件已存在时，可加 `--force` 覆盖。签名过程中，工具会自动调用 [GetC2PAInstance](https://docs.volcengine.com/docs/6638/2665212) 拉取证书链、调用 [C2PASign](https://docs.volcengine.com/docs/6638/2665213) 完成远程签名，并写入 Manifest。您无需关心证书链解析、签名预留空间（reserve size）等底层细节。 > **说明** > 工具按文件类型选择元数据写入方式，且输出文件扩展名必须与输入一致（工具不做格式转换，例如输入 `.jpg` 则输出也必须是 `.jpg`）。请保证文件扩展名、真实内容与格式一致（例如 JPEG 用 `.jpg`、MP4 用 `.mp4`）；三者不一致会导致写入位置错误或后续校验失败。签名完成后不要再改动文件字节（如再次压缩、写入其他元数据），否则内容绑定会失效。 ## 查看与验证内容凭证签名完成后，用同一个二进制查看与校验产物： ```Bash # 仅给出文件路径：打印该文件的 C2PA 凭证摘要（读取时会自动校验签名完整性） c2patool signed.jpg # 打印高层信息：Manifest 数量、Manifest Store 大小（及占文件比例）、云清单 URL、校验问题列表 c2patool signed.jpg --info # 输出 Manifest 的详细内容（含所有 assertion / claim / signature 字段） c2patool signed.jpg --detailed # 将 Manifest、断言和素材缩略图导出到目录（内含 manifest_store.json；加 --detailed 额外生成 detailed.json） c2patool signed.jpg --output out_dir ``` 工具在读取 Manifest 时会自动校验签名完整性（Claim 签名是否匹配、文件是否被篡改），校验结果体现在输出 JSON 的 `validation_status` 字段中；出现校验问题时，该字段会返回错误对象数组。因此在脚本中判断是否通过，最稳妥的做法是解析 `validation_status`——为空或不存在即视为通过： ```Bash # 用 jq 判断：validation_status 为空数组或不存在即视为通过 if c2patool signed.jpg 2>/dev/null | jq -e '(.validation_status // []) | length == 0' >/dev/null; then echo "签名完整、文件未被篡改" else echo "校验失败" fi ``` 默认只校验签名完整性，不判断证书是否受信任。要在本地校验证书链能否追溯到受信任根 CA，有两种方式： ### **方式一：一次性校验（当次命令生效）** 使用 `trust` 子命令，配合 `--trust_anchors` 指定信任锚 PEM 文件（本地路径或 URL）： ```Bash # 信任锚 PEM 可从控制台 C2PA > 证书管理下载证书链，或直接传官方信任列表的 URL c2patool signed.jpg trust --trust_anchors ./trust_anchors.pem ``` `trust` 子命令另外支持： * `--allowed_list `：端实体证书"允许名单"，优先级高于 `--trust_anchors`。 * `--trust_config `：允许的 EKU OID 列表配置。以上参数也可以通过环境变量 `C2PATOOL_TRUST_ANCHORS` / `C2PATOOL_ALLOWED_LIST` / `C2PATOOL_TRUST_CONFIG` 提供。启用信任校验后，`validation_status` 中会体现证书受信状态（例如未受信时返回 `signingCredential.untrusted`）。 ### **方式二：下载官方信任列表并长期生效** 执行一次 `init trust`，工具会把官方 C2PA Conformance 信任列表下载到 settings 文件同目录（文件名为 `c2pa-trust-list.pem`）；之后每次读取都会自动加载该列表并开启证书信任校验，无需再带 trust 子命令： ```Bash c2patool init trust # 下载官方信任列表，后续读取自动启用信任校验 c2patool init trust --legacy # 额外下载旧版过渡信任锚、store 配置与允许名单 ``` > **说明** > 方式二下载的是 C2PA 官方 Conformance 信任列表，用于判断签名证书是否在 C2PA 官方信任体系内。若要按证书中心自有根 / 中间证书校验，请使用方式一，传入从控制台下载的证书链 PEM。需要跨方校验证书信任状态或 Conformance 合规性时，也可使用公开验证工具： * [Content Credentials Verify](https://contentcredentials.org/verify)：查看内容凭证和证书信任状态。 * [C2PA Verify](https://verify.contentauthenticity.org/)：检查 Manifest 是否符合 C2PA Conformance 要求。 > **说明** > 证书信任状态和内容完整性校验结果需要分别判断。证书中心的 [C2PAVerify](https://docs.volcengine.com/docs/6638/2665214) 接口仅验证 C2PA 证书实例签名本身，不等同于对完整媒体文件的 Manifest 结构、内容绑定和信任状态校验；后者请通过本工具或公开验证工具完成。 > 分发前检查建议：签名后第一步先用 `c2patool signed.jpg --detailed` 检查 Manifest 结构和 `validation_status`，确认无误后再进入分发流程。 ## 常用参数速览 |**参数** |**说明** | |---|---| |`` |输入文件路径；仅给出路径时打印该文件的凭证摘要 JSON。 | |`-m / --manifest ` |要嵌入的 Manifest Definition JSON 文件路径（签名时必填，需配合 `-o`）。 | |`-o / --output ` |签名后文件的输出路径；查看时若指向目录，则把 Manifest 报告（`manifest_store.json` 及断言 / 素材缩略图）导出到该目录。 | |`-f / --force` |输出文件 / 目录已存在时允许覆盖。 | |`--info` |打印高层信息：Manifest 数量、Manifest Store 大小及占比、云清单 URL、校验问题列表。 | |`-d / --detailed` |打印详细 Manifest 与 assertion 内容。 | |`--crjson` |以 crJSON 格式输出 Manifest（与 `--detailed `互斥）。 | |`--certs` |提取当前 Manifest 的证书链（PEM）。 | |`--tree` |打印 Manifest Store 树状图。 | |`-p / --parent ` |指定父素材（产物衍生自已有文件时使用）。 | |`-s / --sidecar` |生成边车 `.c2pa` Manifest，而不写入原文件。 | |`-r / --remote ` |嵌入远程 Manifest 引用 URL（Manifest 以边车文件形式保存在输出文件旁）。 | |`--external-manifest ` |用一个独立的二进制 `.c2pa `Manifest 对输入文件做校验 / 读取，覆盖内嵌或远程 Manifest。 | |`-i / --ingredient` |为输入文件生成 ingredient 报告（多素材合成时引用上游素材使用）。 | |`-c / --config ` |以内联 JSON 字符串提供 Manifest 定义，替代 `--manifest`（二者互斥）。 | |`--settings ` |指定 C2PA SDK 设置文件（JSON / TOML）。默认取 `C2PATOOL_SETTINGS` 环境变量，未设置时回退到 `~/.config/c2pa/c2pa.toml`。 | |`--use-time-authority` |云签阶段启用可信时间戳（TSA）；TSA 地址取 Manifest 签名配置中的 `ta_url` 或环境变量 `C2PA_TA_URL`。 | |` trust --trust_anchors ` |当次读取启用证书信任校验；信任锚为 PEM 格式文件路径或 URL，另支持 `--allowed_list`、`--trust_config`，详见 [查看与验证内容凭证](https://docs.volcengine.com/docs/6638/2663807#zA1wEorb)。 | |`init trust（init trust --legacy）` |下载官方 C2PA Conformance 信任列表到 settings 同目录，后续读取自动启用信任校验；`--legacy` 额外下载旧版过渡信任材料。 | 云签相关参数（`--signer-url`、`--volc-ak`、`--volc-sk`、`--volc-instance-id`、`--volc-region`、`--volc-service`、`--volc-version`、`--volc-signing-algorithm`）与去掉 volc\- 前缀的长参数等价，环境变量对应关系见 [配置云签凭证（AK/SK）](https://docs.volcengine.com/docs/6638/2663807#n3zTmYw4)。接入证书中心时，`--signer-url` 固定为 `https://pca.volcengineapi.com`，`--volc-service` 固定为 `pca`，`--volc-version` 固定为 `2025-10-01`。完整参数以 `c2patool --help` 输出为准。 ## 支持的文件格式支持的完整格式清单以官方 [supported-formats](https://github.com/contentauth/c2pa-rs/blob/main/docs/supported-formats.md) 为准。常见格式的 Manifest 存储位置如下： |**文件格式** |**扩展名** |**元数据存储位置** | |---|---|---| |JPEG |`.jpg` / `.jpeg` |`APP11` marker（JUMBF superbox） | |PNG |`.png` |`caBX` ancillary chunk（JUMBF superbox） | |WebP |.`webp` |RIFF `C2PA` chunk（JUMBF superbox） | |GIF |`.gif` |Application Extension block（JUMBF superbox） | |HEIF / HEIC / AVIF |`.heif` / `.heic` / `.avif` |ISO BMFF `uuid` box，extended type `d8fec3d6-1b0e-483c-9297-5828877ec481` | |MP4 / MOV / M4A |`.mp4` / `.mov` / `.m4a` |ISO BMFF `uuid` box，extended type 同上 | |WAV |`.wav` |RIFF `C2PA` chunk（JUMBF superbox） | |PDF |`.pdf` |**仅支持读取 / 验证**，不支持写入；读取时解析增量更新（incremental update）中的 EmbeddedFiles | > **说明** * > 工具判断文件类型时**优先看扩展名**，扩展名缺失时再使用 MIME，最后才 sniff 文件头。批量处理时务必保证文件扩展名正确。 * > 上表为云签版 c2patool（基于 c2pa\-rs 0.90.0）常见的可写入 / 读取格式。TIFF、JPEG XL、MP3、FLAC、SVG、AVI、DNG 等格式也在支持范围内，完整清单与各格式的读写能力以官方 [supported\-formats](https://github.com/contentauth/c2pa-rs/blob/main/docs/supported-formats.md) 为准；其中 PDF 当前为只读，不支持写入。 ## 相关文档 * [证书中心 C2PA 功能完整使用流程](https://docs.volcengine.com/docs/6638/2663741) * [购买 C2PA 证书](https://docs.volcengine.com/docs/6638/2586558) * [管理 C2PA 证书](https://docs.volcengine.com/docs/6638/2586813) * [C2PA Manifest 写入规范指导文档](https://docs.volcengine.com/docs/6638/2587619) * [纯 AI 生成内容写入最佳实践](https://docs.volcengine.com/docs/6638/2663743) * [多素材 AI 合成写入最佳实践](https://docs.volcengine.com/docs/6638/2663744) * [含 C2PA 内容转码与重封装写入最佳实践](https://docs.volcengine.com/docs/6638/2663745) * [API 列表](https://docs.volcengine.com/docs/6638/2587615) * [调用方法](https://docs.volcengine.com/docs/6638/2587614)