c2patool - C2PA命令行工具

c2patool 是一个用于处理C2PA 清单 和媒体资产（音频、图像或视频文件）的命令行工具。

在支持格式的文件上使用此工具，以

• 读取C2PA清单的摘要JSON报告。
• 读取C2PA清单数据的低级报告。
• 将C2PA清单添加到文件中。

有关从Node.js服务器应用程序调用c2patool的简单示例，请参阅c2pa-service-example 仓库。

安装

安装C2PA工具有两种方法

• 使用预构建的二进制可执行文件：这是安装工具的最快方法。如果您只是想快速尝试C2PA工具，请使用此方法。
• 使用Cargo Binstall，这是一种安装Rust二进制文件的低复杂性方法。此方法更适合长期使用。如果您知道您想要将C2PA工具用于开发，请使用此方法。

安装预构建的二进制文件

安装此工具最快的方式是使用二进制可执行文件。如果您只想快速尝试C2PA Tool

1. 请访问 c2patool 仓库发布页面。
2. 在最新发布版本下，点击 资源。
3. 下载适用于您操作系统的存档（Linux、macOS 或 Windows）。
4. 将可执行文件复制到您的 PATH 路径上的位置。

通过输入如下命令来确认您可以运行该工具：

c2patool -h

注意：您可能还想获取仓库中 sample 目录提供的示例文件。要这样做，请使用以下命令克隆仓库：git clone https://github.com/contentauth/c2patool.git。

使用 Cargo Binstall

推荐使用 Cargo Binstall 安装 C2PA Tool，因为它使操作更简单：

• 自动选择适用于您的平台/架构的正确安装包。
• 在新版本发布时更新工具。
• 维护，因为您无需手动跟踪系统上的随机二进制文件。
• 集成到 CI 或其他脚本环境中。

此外，使用 Binstall 使您能够自动化代码签名以确保包完整性。

过程

前提条件：安装 Rust。

要使用 Binstall 安装

1. 按照您操作系统的快速安装方法安装 cargo-binstall，或通过运行以下命令从源代码构建：cargo install cargo-binstall
2. 运行 cargo binstall c2patool。

升级

为确保您拥有最新版本，请输入以下命令

c2patool -V

工具将显示已安装的版本。将显示的版本号与 仓库发布页面 上显示的最新发布版本进行比较。

如果您需要升级，只需再次运行 cargo binstall c2patool 或使用 cargo-update 即可。

从源代码构建

注意：除非您正在积极开发 C2PA Tool，或者系统上没有预构建的二进制文件，否则请使用上述描述的任何一种安装方法。

cargo install c2patool

要在 Windows 机器上构建工具，您需要安装 7zip 工具。

注意：如果在安装时遇到错误，您可能需要通过输入以下命令来更新 Rust 安装：

rustup update

支持文件格式

^* MP4 文件碎片目前尚不支持。

^** 只读

用法

工具的命令行语法是

c2patool [trust] [PATH] [OPTIONS]

其中

• trust 是一个可选子命令，用于启用对“已知证书列表”中证书的信任支持。使用此子命令，将提供一些附加选项。
• PATH 是读取或嵌入清单的资产的（相对或绝对）文件路径。
• OPTIONS 是以下表中描述的命令行选项之一或多个。

显示清单数据

要显示与资产文件关联的清单，请提供文件的路径作为参数；例如

c2patool sample/C.jpg

工具将清单 JSON 显示到标准输出（stdout）。

使用 --output 参数将清单内容（包括清单的断言和配料缩略图）写入指定的目录。

c2patool sample/C.jpg --output ./report

详细清单报告

使用 -d 选项显示一个详细报告，描述资产中包含的清单的内部 C2PA 格式；例如，使用 sample 目录中的示例图像之一

c2patool sample/C.jpg -d

默认情况下，该工具将详细报告显示到标准输出（stdout）。如果您指定了一个输出文件夹，则该工具会将它保存到该文件夹中名为 detailed.json 的文件中。

显示信息报告

使用 --info 选项打印关于资产文件和相关C2PA数据的高级报告。对于云清单，工具显示清单的URL。显示清单存储的大小和清单数量。它将报告清单是否已验证或显示验证过程中遇到的任何错误。

c2patool sample/C.jpg --info

工具将报告显示到标准输出（stdout）。

从文件创建成分

--ingredient 选项创建成分报告。当与 --output 文件夹一起使用时，它提取或创建一个缩略图图像和包含C2PA数据的二进制 .c2pa 清单存储。该工具生成的JSON成分可以添加到清单定义中，以将资产的完整历史和验证记录带入新创建的清单中。

提供文件的路径作为参数；例如

c2patool sample/C.jpg --ingredient --output ./ingredient

将清单添加到资产文件中

使用 --manifest / -m 选项将参数中指定的C2PA清单定义文件添加到待签名的资产文件中。将输出文件指定为 --output / -o 选项的参数。输出扩展类型必须与源匹配。工具不会在文件类型之间进行转换。例如

c2patool sample/image.jpg -m sample/test.json -o signed_image.jpg

工具使用文件中给出的值生成新的清单，并将清单存储显示到标准输出（stdout）。

注意：如果输出文件与源文件相同，则工具将覆盖源文件。

如果清单定义文件有 private_key 和 sign_cert 字段，则工具使用它们指定的私钥和证书分别签署清单。否则，工具使用内置的测试证书和密钥，这适用于开发和测试。您还可以使用环境变量指定私钥和证书；有关更多信息，请参阅 创建和使用X.509证书。

指定父文件

父文件 代表当前编辑之前图像的状态。

将父文件作为 --parent / -p 选项的参数指定；例如

c2patool sample/image.jpg -m sample/test.json -p sample/c.jpg -o signed_image.jpg

您可以通过提供文件夹或成分JSON文件来传递使用 --ingredient 选项生成的成分。

c2patool sample/C.jpg --ingredient --output ./ingredient

c2patool sample/image.jpg -m sample/test.json -p ./ingredient -o signed_image.jpg

强制覆盖

如果输出文件已存在，则工具将返回错误。使用 --force / -f 选项强制覆盖输出文件。例如

c2patool sample/image.jpg -m sample/test.json -f -o signed_image.jpg

生成外部清单

使用 --sidecar / -s 选项将清单放置在与输出文件相同位置的独立侧车文件中。清单将具有相同的输出文件名，但带有 .c2pa 扩展名。工具将复制输出文件，但原始文件将保持不变。

c2patool sample/image.jpg -s -m sample/test.json -o signed_image.jpg

生成远程清单

使用--remote / -r选项，在输出文件中放置对清单的HTTP引用。清单作为外部副文件返回，位于与输出文件相同的路径，具有相同的文件名，但扩展名为.c2pa。将清单放置在-r选项指定的位置。当使用远程清单时，远程URL应公开可访问，以便对用户最有用。验证资产时，将自动获取远程清单。

c2patool sample/image.jpg -r http://my_server/myasset.c2pa -m sample/test.json -o signed_image.jpg

在上面的示例中，工具将URL http://my_server/myasset.c2pa嵌入到signed_image.jpg中，然后从该URL获取清单并保存到signed_image.c2pa。

如果你同时使用-s和-r选项，工具将在输出文件中嵌入清单并添加远程引用。

使用自己的签名者签名声明字节

在生成清单时，如果系统上没有可访问的私钥，请使用--signer-path参数指定执行签名的可执行文件的路径。此可执行文件从标准输入（stdin）接收声明字节（要签名的字节），并将签名字节输出到标准输出（stdout）。

例如，以下命令使用名为custom-signer的可执行文件签名资产声明字节。

c2patool sample/image.jpg            \
    --manifest sample/test.json      \
    --output sample/signed-image.jpg \
    --signer-path ./custom-signer    \
    --reserve-size 20248             \
    -f

有关计算--reserve-size参数值的更多信息，请参阅c2patool --help。

在命令行上提供清单定义

要使用命令行参数而不是文件提供清单定义，请使用--config / -c选项。

例如，以下命令添加一个名为"org.contentauth.test"的自定义声明。

c2patool sample/image.jpg \
  -c '{"assertions": \
    [{"label": "org.contentauth.test", \
      "data": {"my_key": "whatever I want"}}]}'

加快签名速度

默认情况下，c2patool在签署清单后立即验证签名。要禁用此操作并加快验证过程，请使用--no_signing_verify选项。

配置信任支持

通过使用trust子命令启用信任支持，如下所示

c2patool [path] trust [OPTIONS]

与trust子命令一起，有几个附加的CLI选项可用于指定包含信任锚点列表或已知证书列表的文件的路径，如下表所述。您还可以使用环境变量来指定这些值。

例如

c2patool sample/C.jpg trust \
  --allowed_list sample/allowed_list.pem \
  --trust_config sample/store.cfg

带有URL参数值的另一个示例

c2patool sample/C.jpg trust \
  --trust_anchors https://server.com/anchors.pem \
  --trust_config https://server.com/store.cfg

使用验证已知证书列表

重要：C2PA计划发布一个官方信任列表。在此之前，C2PA Verify工具使用临时已知证书列表。这些列表可能随时更改，并在C2PA发布其信任列表时被弃用。

要配置C2PA工具以使用验证临时已知证书列表，请在您的系统上设置以下环境变量

export C2PATOOL_TRUST_ANCHORS='https://contentcredentials.org/trust/anchors.pem'
export C2PATOOL_ALLOWED_LIST='https://contentcredentials.org/trust/allowed.sha256.txt'
export C2PATOOL_TRUST_CONFIG='https://contentcredentials.org/trust/store.cfg'

注意：设置这些环境变量时，C2PA工具在每次运行时都会发出多个HTTP请求。由于这些列表可能随时更改（并且允许的列表可能会频繁更改），请经常检查这些列表，以保持与Verify网站的同步。但是，在执行大量操作时，您可能希望将这些文件本地缓存，以避免大量网络调用可能影响性能。

然后您可以运行

c2patool sample/C.jpg trust

您也可以将这些值作为CLI参数指定

c2patool sample/C.jpg trust \
  --trust_anchors='https://contentcredentials.org/trust/anchors.pem' \
  --allowed_list='https://contentcredentials.org/trust/allowed.sha256.txt' \
  --trust_config='https://contentcredentials.org/trust/store.cfg'

注意：此示例图像应显示signingCredential.untrusted验证状态，因为用于签名的测试签名证书不包含在上面的信任列表中。

夜间构建

每天大约在05:30 UTC（对我们美国团队的夜间）生成临时二进制文件，此后大约可用两周。这些对于测试目的可能很有帮助。有关更多信息，请参阅关于夜间构建的文档。