文档中心

证书中心

用户指南

使用 c2patool 完成 C2PA 签名与验证

本文介绍如何使用证书中心提供的 c2patool（火山引擎 C2PA SDK 定制版）组装 C2PA Manifest，并调用云签服务完成签名与写入。

该工具基于官方 contentauth/c2pa-rs 定制，内置了证书中心 C2PA 云签远程 Signer。您只需配置访问密钥（AK/SK）和证书实例 ID，即可通过命令行完成端到端签名，无需自行安装官方 c2pa-rs 或实现远程 Signer。

说明

云签流程对您透明。执行签名命令时，工具依次完成：

通过 GetC2PAInstance 拉取本次签名使用的 C2PA 证书链；

在本地计算内容绑定（Hard Binding）并组装 Claim / Manifest；

把待签数据提交到 C2PASign，由云端 HSM 完成签名（私钥全程保存在云端，不可导出）；

将签名结果与 Manifest 写入目标文件。

因此，CLI 签名路径下您不需要手动调用 GetC2PAInstance / C2PASign，也不需要在本地保存任何私钥。工具仓库为 volcengine/c2patool。

工具概览

工具	说明	适用场景	仓库地址
云签版 c2patool（火山引擎 C2PA SDK）	基于官方 c2patool / c2pa-rs 定制，内置证书中心云签远程 Signer，同时保留 Manifest 组装、写入、查看与验证能力。	脚本化 / 批量签名、服务端通过命令行集成、内容凭证的查看、验证与调试。	volcengine/c2patool
c2pa-rs（官方 Rust SDK）	C2PA 官方 Rust SDK，云签版 c2patool 即基于它构建。	需要在自有服务代码中深度集成、自定义 Manifest 组装流程；可参考火山定制版源码中的云签 Signer 实现。	contentauth/c2pa-rs

注意

请勿直接使用官方 c2patool 对接证书中心云签。官方版本默认使用本地 PEM 私钥 / 证书签名，不识别火山引擎 AK/SK、区域与证书实例等云签参数，无法调用证书中心云签服务。云签场景请使用 volcengine/c2patool。

安装与构建

云签版 c2patool 支持 macOS、Linux、Windows。当前以源码构建为主，需要本地已安装 Rust 工具链（安装方式参见 rustup）。

构建产物位于 target/release/c2patool，将其加入 PATH 后，用以下命令验证：

准备工作

开始签名前，请确认：

已购买并签发 C2PA 证书，并确认实例状态为已签发。具体操作，请参见购买 C2PA 证书。

已准备访问密钥（AK/SK），且对应账号 / 角色已被授予 C2PA 签名相关权限。权限与授权流程参见证书中心 C2PA 功能完整使用流程。

已准备待签文件，以及描述断言的 Manifest JSON（见准备 Manifest）。

获取云签接入信息。接入证书中心云签时，以下取值固定：网关地址 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），完整对照见下文参数表。网关地址与请求结构的通用说明参见调用方法。

配置云签凭证（AK/SK）

推荐通过环境变量配置 Access Key、Secret Key 和证书实例 ID，避免把密钥写进命令行历史或提交到代码仓库。

说明

云签网关地址必须在命令行中通过 --signer-url 显式指定；只要传入该参数，工具即启用云签模式，其余凭证自动从环境变量读取。

云签相关参数也可以通过命令行传入。命令行参数与环境变量的对应关系如下：

命令行参数	环境变量	默认值	说明
--signer-url <url>	—	无（必填）	云签网关地址，提供该参数即启用云签模式。不支持环境变量，必须显式传入。接入证书中心时固定为 https://pca.volcengineapi.com。
--volc-ak <ak>（等价 --access-key）	SIGNER_ACCESS_KEY	无（必填）	Access Key ID。
--volc-sk <sk>（等价 --secret-key）	SIGNER_SECRET_KEY	无（必填）	Secret Access Key。说明若 --secret-key 与 SIGNER_SECRET_KEY 均未设置，工具会回退读取 VOLC_SECRET_KEY（该变量仅在云签模式下生效）。
--volc-instance-id <id>（等价 --instance-id）	SIGNER_INSTANCE_ID	无（必填）	C2PA 证书实例 ID，用于 GetC2PAInstance 与 C2PASign。
--volc-region <region>（等价 --region）	—	cn-north-1	服务区域。
--volc-service <service>（等价 --service）	—	c2pa_tob	OpenAPI 服务名。CLI 内置默认值为 c2pa_tob；接入证书中心必须显式指定为 pca。
--volc-version <version>（等价 --api-version）	—	1.0	API 版本。CLI 内置默认值为 1.0；接入证书中心必须显式指定为 2025-10-01。
--signing-algorithm <alg>（等价 --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）由工具在签名时自动计算，无需手动填写：

说明

建议通过 claim_generator_info（name + version + specVersion）声明签名方 / 工具身份。若省略该字段或传空数组，SDK 会自动填入 c2pa 库自身的名称与版本作为默认身份。specVersion 需与实际 c2patool 版本能力匹配，对照见 C2PA Manifest 写入规范指导文档。

常见可选字段：

assertions：主动声明的断言，例如 c2pa.actions.v2（对素材执行的操作）、c2pa.metadata（创建工具 / 拍摄信息）。

ingredients：引入的上游素材及其 C2PA Manifest，用于多素材合成场景。

更复杂的写入要求（AI 生成标注、多素材合成、转码重封装等）参见C2PA Manifest 写入规范指导文档及各最佳实践文档。

签名并写入

按上一节完成环境变量配置后，按下例显式传入云签网关地址（--signer-url）、服务名（--service）与 API 版本（--api-version）即可进入云签模式；区域默认 cn-north-1 已与证书中心一致，无需额外指定：

以下为完整的 c2patool 调用示例，云签参数使用 --volc-* 形式（与去掉前缀的长参数等价）：

示例中 # 后为参数说明，实际执行时请删除注释；需要可直接复制的命令可使用上文基于环境变量的写法。

-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 拉取证书链、调用 C2PASign 完成远程签名，并写入 Manifest。您无需关心证书链解析、签名预留空间（reserve size）等底层细节。

说明

工具按文件类型选择元数据写入方式，且输出文件扩展名必须与输入一致（工具不做格式转换，例如输入 .jpg 则输出也必须是 .jpg）。请保证文件扩展名、真实内容与格式一致（例如 JPEG 用 .jpg、MP4 用 .mp4）；三者不一致会导致写入位置错误或后续校验失败。签名完成后不要再改动文件字节（如再次压缩、写入其他元数据），否则内容绑定会失效。

查看与验证内容凭证

签名完成后，用同一个二进制查看与校验产物：

工具在读取 Manifest 时会自动校验签名完整性（Claim 签名是否匹配、文件是否被篡改），校验结果体现在输出 JSON 的 validation_status 字段中；出现校验问题时，该字段会返回错误对象数组。因此在脚本中判断是否通过，最稳妥的做法是解析 validation_status——为空或不存在即视为通过：

默认只校验签名完整性，不判断证书是否受信任。要在本地校验证书链能否追溯到受信任根 CA，有两种方式：

方式一：一次性校验（当次命令生效）

使用 trust 子命令，配合 --trust_anchors 指定信任锚 PEM 文件（本地路径或 URL）：

trust 子命令另外支持：

--allowed_list <path|url>：端实体证书"允许名单"，优先级高于 --trust_anchors。

--trust_config <path|url>：允许的 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 子命令：

说明

方式二下载的是 C2PA 官方 Conformance 信任列表，用于判断签名证书是否在 C2PA 官方信任体系内。若要按证书中心自有根 / 中间证书校验，请使用方式一，传入从控制台下载的证书链 PEM。

需要跨方校验证书信任状态或 Conformance 合规性时，也可使用公开验证工具：

Content Credentials Verify：查看内容凭证和证书信任状态。

C2PA Verify：检查 Manifest 是否符合 C2PA Conformance 要求。

说明

证书信任状态和内容完整性校验结果需要分别判断。证书中心的 C2PAVerify 接口仅验证 C2PA 证书实例签名本身，不等同于对完整媒体文件的 Manifest 结构、内容绑定和信任状态校验；后者请通过本工具或公开验证工具完成。

分发前检查建议：签名后第一步先用 c2patool signed.jpg --detailed 检查 Manifest 结构和 validation_status，确认无误后再进入分发流程。

常用参数速览

参数	说明
<asset>	输入文件路径；仅给出路径时打印该文件的凭证摘要 JSON。
-m / --manifest <path>	要嵌入的 Manifest Definition JSON 文件路径（签名时必填，需配合 -o）。
-o / --output <path>	签名后文件的输出路径；查看时若指向目录，则把 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 <path>	指定父素材（产物衍生自已有文件时使用）。
-s / --sidecar	生成边车 .c2pa Manifest，而不写入原文件。
-r / --remote <url>	嵌入远程 Manifest 引用 URL（Manifest 以边车文件形式保存在输出文件旁）。
--external-manifest <path>	用一个独立的二进制 .c2pa Manifest 对输入文件做校验 / 读取，覆盖内嵌或远程 Manifest。
-i / --ingredient	为输入文件生成 ingredient 报告（多素材合成时引用上游素材使用）。
-c / --config <json>	以内联 JSON 字符串提供 Manifest 定义，替代 --manifest（二者互斥）。
--settings <path>	指定 C2PA SDK 设置文件（JSON / TOML）。默认取 C2PATOOL_SETTINGS 环境变量，未设置时回退到 ~/.config/c2pa/c2pa.toml。
--use-time-authority	云签阶段启用可信时间戳（TSA）；TSA 地址取 Manifest 签名配置中的 ta_url 或环境变量 C2PA_TA_URL。
<asset> trust --trust_anchors <path/url>	当次读取启用证书信任校验；信任锚为 PEM 格式文件路径或 URL，另支持 --allowed_list、--trust_config，详见查看与验证内容凭证。
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）。接入证书中心时，--signer-url 固定为 https://pca.volcengineapi.com，--volc-service 固定为 pca，--volc-version 固定为 2025-10-01。完整参数以 c2patool --help 输出为准。

支持的文件格式

支持的完整格式清单以官方 supported-formats 为准。常见格式的 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 为准；其中 PDF 当前为只读，不支持写入。