Skip to content

usage.md

Latest commit

 

History

History
448 lines (300 loc) · 24.2 KB

usage.md

File metadata and controls

448 lines (300 loc) · 24.2 KB
Raw

Using C2PA Tool

C2PA Tool's command-line syntax is:

c2patool <ASSET_PATH> [OPTIONS] [SUBCOMMAND]

Where:

  • <ASSET_PATH> is the (relative or absolute) file path to the asset to read or embed a manifest into.
  • [OPTIONS] is one or more of the command-line options described in following table.
  • [SUBCOMMAND] is one of the optional subcommands: init, trust, fragment, or help.

By default, C2PA Tool writes the JSON manifest data found in the asset to the standard output. You can override the default by using the --output, -o option.

Subcommands

The tool supports the following subcommands:

Options

The following options are available with any (or no) subcommand. Additional options are available with each subcommand.

CLI option          Short version Argument Description
--certs N/A Extract a certificate chain to standard output (stdout). See Extracting a certificate chain.
--config -c <config> Specify a manifest definition as a JSON string. See Providing a manifest definition on the command line.
--create <source_type> Create a new manifest with the specified C2PA digital source type (e.g. digitalCapture, trainedAlgorithmicMedia). Mutually exclusive with --update and --parent. See Specifying manifest intent.
--detailed -d N/A Display detailed C2PA-formatted manifest data. See Displaying a detailed manifest report.
--external-manifest N/A <c2pa_file> Path to the binary .c2pa (sidecar) manifest to use for validation against the input asset. See Using an external manifest.
--force -f N/A Force overwriting output file. See Forced overwrite.
--help -h N/A Display CLI help information.
--info N/A Display brief information about the file. See Displaying an information report.
--ingredient -i N/A Create an ingredient definition in the --output folder. See Creating an ingredient from a file.
--manifest -m <manifest_file> Specify a manifest definition file to add to an asset file. See Adding a manifest to an asset file.
--no_signing_verify None N/A Do not validate the signature after signing an asset, which speeds up signing. See Speeding up signing
--output -o <output_file> Path to output folder or file. This option can be used in two ways:
•With the -m option to add a manifest to the specified asset file. The argument then specifies the name of the resulting asset file with Content Credentials added.
•Without the -m option to write the manifest data to a directory (including assertion and ingredient thumbnails). The argument then specifies the output directory to use.
--parent -p <parent_file> Path to parent file. See Specifying a parent file.
--remote -r <manifest_url> URL for remote manifest available over HTTP. See Generating a remote manifest.
--identity-signer-path N/A <command> Command for signing the CAWG identity assertion. Same protocol as --signer-path. See Signing assets.
--reserve-size N/A <size> Space to reserve for signatures when using --signer-path or --identity-signer-path. Default: 20000. See Signing assets.
--settings N/A <settings_file> Path to the settings file. Default is the value of the C2PATOOL_SETTINGS environment variable. If not set, defaults to ~/.config/c2pa/c2pa.toml. See Configuring SDK settings.
--sidecar -s N/A Put manifest in external "sidecar" file with .c2pa extension. See Generating an external manifest.
--signer-path N/A <command> Command for signing the C2PA claim. See Signing assets.
--tree N/A Create a tree diagram of the manifest store. See Displaying a tree diagram.
--update N/A Create an update manifest (non-editorial changes to an already-signed parent asset). Mutually exclusive with --create. See Specifying manifest intent.
--version -V N/A Display version information.

Displaying manifest data

To display the manifest associated with an asset file, provide the path to the file as the argument; for example:

c2patool sample/C.jpg

The tool displays the manifest JSON to standard output (stdout).

Saving manifest data to a directory

Use the --output argument to write the contents of the manifest (including the manifest's assertion and ingredient thumbnails) to the specified directory.

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

Detailed manifest report

Use the -d option to display a detailed report describing the internal C2PA format of manifests contained in the asset; for example, using one of the example images in the sample directory:

c2patool sample/C.jpg -d

By default, the tool displays the detailed report to standard output (stdout). If you specify an output folder, the tool saves it to a file named detailed.json in that folder.

Displaying an information report

Use the --info option to print a high-level report about the asset file and related C2PA data. For a cloud manifest the tool displays the URL to the manifest. Displays the size of the manifest store and number of manifests. It will report if the manifest validated or show any errors encountered in validation.

c2patool sample/C.jpg --info

The tool displays the report to standard output (stdout).

Extracting a certificate chain

Use the --certs option to extract the PEM certificate chain from the active manifest's signature and print it to standard output (stdout). For example:

c2patool sample/C.jpg --certs

This is useful for inspecting the signing certificate used to sign the manifest.

Using an external manifest

Use the --external-manifest option to validate an asset against a separate binary .c2pa sidecar manifest file instead of the manifest embedded in the asset. This overrides any embedded or remote manifest. For example:

c2patool sample/image.jpg --external-manifest sample/image.c2pa

Displaying a tree diagram

Use the --tree option to display a text tree diagram of the manifest store, showing the structure of assertions and nested ingredients. For example:

c2patool sample/C.jpg --tree

Forced overwrite

The tool will return an error if the output file already exists. Use the --force / -f option to force overwriting the output file. For example:

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

Creating an ingredient from a file

The --ingredient option creates an ingredient report. When used with the --output folder, it extracts or creates a thumbnail image and a binary .c2pa manifest store containing the C2PA data from the file. The JSON ingredient this produces can be added to a manifest definition to carry the full history and validation record of that asset into a newly-created manifest.

Provide the path to the file as the argument; for example:

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

Adding a manifest to an asset file

Use the --manifest / -m option to add the C2PA manifest definition file specified in the argument to the asset file to be signed. Specify the output file as the argument to the --output / -o option. The output extension type must match the source. The tool will not convert between file types. For example:

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

The tool generates a new manifest using the values given in the file and displays the manifest store to standard output (stdout).

Warning

If the output file is the same as the source file, the tool will overwrite the source file.

For full details on configuring signers — including how to write a subprocess signer, use a remote signing service, or add a CAWG identity assertion — see Signing assets.

Warning

Providing a private key directly in a manifest file or settings file is suitable only for development and testing. In production, use a subprocess signer or remote signing service so that private key material never passes through c2patool.

Specifying a parent file

A parent file represents the state of the image before the current edits were made.

Specify a parent file as the argument to the --parent / -p option; for example:

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

You can pass an ingredient generated with the --ingredient option by giving the folder or ingredient JSON file.

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

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

Specifying manifest intent

Every C2PA manifest records an intent that describes how the content was produced. C2PA Tool supports three intents, controlled by the --create and --update flags:

Intent Flag When to use
Create --create <source-type> The output is a new original creation with no prior editing history.
Edit (default — no flag needed) The output is derived from one or more source assets through an editorial process.
Update --update Non-editorial technical changes were applied to an already-signed asset (e.g., re-encoding or format conversion).

Create intent (--create)

Use --create <source-type> to declare that the output is a new creation. Provide one of the IPTC digital source type values:

c2patool new_image.jpg \
  -c '{"assertions":[]}' \
  --create digitalCapture \
  -o signed_image.jpg

The tool automatically adds a c2pa.created action. --create is mutually exclusive with --update and --parent.

Some common source-type values:

Value Meaning
digitalCapture Original capture from a camera or microphone
algorithmicMedia Produced entirely by an algorithm
trainedAlgorithmicMedia Produced by a trained AI model
compositeWithTrainedAlgorithmicMedia Composite that includes AI-generated elements

See the IPTC digital source type vocabulary for the full list.

Edit intent (default)

When neither --create nor --update is given, the tool applies Edit intent. The source asset is automatically added as a parent ingredient and a c2pa.opened action is injected into the manifest:

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

Use --parent / -p when the parent asset is a different file from the source (see Specifying a parent file).

Update intent (--update)

Use --update to declare that non-editorial changes were applied to an already-signed asset. The source asset must already contain a C2PA manifest.

c2patool source_with_manifest.jpg \
  -c '{"assertions":[]}' \
  --update \
  -o updated_image.jpg

The tool automatically adds a c2pa.opened action and sets the source asset as the parent ingredient. --update is mutually exclusive with --create.

Generating an external manifest

Use the --sidecar / -s option to put the manifest in an external sidecar file in the same location as the output file. The manifest will have the same output filename but with a .c2pa extension. The tool will copy the output file but the original will be untouched.

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

Generating a remote manifest

Use the --remote / -r option to place an HTTP reference to the manifest in the output file. The manifest is returned as an external sidecar file in the same location as the output file with the same filename but with a .c2pa extension. Place the manifest at the location specified by the -r option. When using remote manifests the remote URL should be publicly accessible to be most useful to users. When verifying an asset, remote manifests are automatically fetched.

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

In the example above, the tool will embed the URL http://my_server/myasset.c2pa in signed_image.jpg then fetch the manifest from that URL and save it to signed_image.c2pa.

If you use both the -s and -r options, the tool embeds a manifest in the output file and also adds the remote reference.

Signing with your own signer

Use --signer-path to delegate C2PA claim signing to an external executable, and --identity-signer-path to additionally embed a CAWG identity assertion signed by a separate executable. Both accept a command string (binary path and optional arguments):

c2patool sample/image.jpg            \
    --manifest sample/test.json      \
    --output sample/signed-image.jpg \
    --signer-path ./my-signer        \
    -f

The signer executable must implement the subprocess signing protocol: respond to --signer-info with a JSON object describing its certificate and algorithm, and sign bytes received on stdin by writing the raw signature to stdout. For the full protocol specification, error handling details, and guidance on writing your own signer, see Signing assets.

Providing a manifest definition on the command line

To provide the manifest definition as a command line argument instead of in a file, use the --config / -c option. The JSON format is the same as in a manifest definition file.

For example, the following command adds a custom assertion called "org.contentauth.test".

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

Speeding up signing

By default, c2patool validates the signature immediately after signing a manifest. To disable this and speed up the validation process, use the --no_signing_verify option.

Configuring trust support

Use the trust subcommand to specify trust lists that the tool consults to determine if an asset was signed by a "trusted" certificate, which can be either a certificate on the specified allowed list or a certificate that chains back to a root certificate on the specified trust anchors list.

There are two significant trust lists for signing Content Credentials:

Note

With the trust subcommand, C2PA Tool will make several HTTP requests each time it runs. Since these lists may change without notice (and the allowed list may change quite often), check these lists frequently to stay in sync with the Verify site. However, when performing bulk operations, you may want to cache these files locally to avoid a large number of network calls that might affect performance.

Bootstrapping trust files with init trust

Instead of passing trust subcommand options on every run, you can use init trust to fetch a trust list once and cache it next to your settings file. C2PA Tool automatically loads these cached files on every subsequent run and enables trust checks, so you don't need to repeat any trust options.

init does not take an <ASSET_PATH>, so run it on its own:

c2patool init trust

This fetches the official C2PA trust list and writes it to c2pa-trust-list.pem in the same directory as the settings file (the --settings option, or C2PATOOL_SETTINGS, or the default settings path if neither is set).

To also fetch the legacy interim trust anchors, EKU store configuration, and allowed list, add --legacy:

c2patool init trust --legacy

This additionally writes c2pa-trust-list-legacy.pem, c2pa-trust-store.cfg, and c2pa-trust-allowed.sha256.txt to the same directory.

On the next run of any command, C2PA Tool automatically loads whichever of these files it finds next to the settings file and enables trust checks — no trust subcommand options are required. Re-run c2patool init trust at any time to refresh the cached files with the latest trust list contents.

Note

init trust requires network access to fetch the trust list, so it is not available on WASI targets.

Trust subcommand options

Enable trust support by using the trust subcommand, as follows:

c2patool <ASSET_PATH> trust [OPTIONS]

If C2PA Tool can't validate any of the claims in the asset against the specified trust lists, the JSON output will contain a validation_status field whose value is an array of objects, each describing a validation problem.

Several additional CLI options are available with the trust sub-command, as described in the following table. You can also use environment variables to specify these values.

Option Environment variable Description
--trust_anchors C2PATOOL_TRUST_ANCHORS URL or relative path to a file containing a list of trust anchors (in PEM format) used to validate the manifest certificate chain. To be valid, the manifest certificate chain must lead to a certificate on the trust list. All certificates in the trust anchor list must have the Basic Constraints extension and the CA attribute of this extension must be True.
--allowed_list C2PATOOL_ALLOWED_LIST URL or relative path to a file containing a list of end-entity certificates (in PEM format) to trust. These certificates are used to sign the manifest. Supersedes the trust_anchors setting. The list must NOT contain certificates with the Basic Constraints extension with the CA attribute True.
--trust_config C2PATOOL_TRUST_CONFIG URL or relative path to a file containing the allowed set of custom certificate extended key usages (EKUs). Each entry in the list is an object identifiers in OID dot notation format.
--trust_list_uri C2PATOOL_TRUST_LIST_URI URI that identifies the trust list supplied via --trust_anchors. This URI is included in the validation report's trustListUri field so downstream consumers can identify which trust list validated the signing certificate. If omitted, an identifier is generated automatically.

For example:

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

Another example with URL argument values:

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

To tag a custom trust list with an identifying URI:

c2patool sample/C.jpg trust \
  --trust_anchors https://server.com/anchors.pem \
  --trust_list_uri https://server.com/trust-list-id

Using the official C2PA trust list

To specify the official C2PA trust list use the --trust_anchors option as follows:

c2patool sample/C.jpg trust \
  --trust_anchors='https://raw.githubusercontent.com/c2pa-org/conformance-public/refs/heads/main/trust-list/C2PA-TRUST-LIST.pem' \

The C2PA trust list does not provide "allowed list" of end-entity certificates, nor do you need to specify the --trust_config option.

Alternatively, set the following environment variable on your system:

export C2PATOOL_TRUST_ANCHORS='https://raw.githubusercontent.com/c2pa-org/conformance-public/refs/heads/main/trust-list/C2PA-TRUST-LIST.pem'

Using the interim trust list

To use the legacy interim trust list, specify the CLI options as follows:

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'

Alternatively, set the following environment variables on your system:

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'

You can then run, for example:

c2patool sample/C.jpg trust

Note

This sample image shows a signingCredential.untrusted validation status since the test signing certificate used is not contained on the trust lists above.

Adding a manifest to fragmented BMFF content

The ISO base media file format (BMFF) is a container file format that defines a structure for files that contain time-based multimedia data such as video and audio.

Add a manifest to a fragmented BMFF file by using the fragment subcommand, as follows:

c2patool <PATH | PATTERN> fragment [--fragments_glob]

Where <PATTERN> is a glob pattern.

For example, to add manifest to a video file:

c2patool -m test2.json -o  /1080p_out \
  /Downloads/1080p/avc1/init.mp4 \ 
  fragment --fragments_glob "seg-*[0-9].m4s"

Or to verify a manifest and fragments:

c2patool  /Downloads/1080p_out/avc1/init.mp4 \
  fragment --fragments_glob "seg-*[0-9].m4s"

Additional option for BMFF files

The --fragments_glob option is only available with the fragment subcommand and specifies the glob pattern to find the fragments of the asset. The path is automatically set to be the same as the "init" segment, so the pattern must match only segment file names, not full paths.

WASI

You can run the Wasm binary created for wasm32-wasip2 directly with wasmtime. You can also transpile it into an ECMAScript module for JavaScript execution by using jco as follows:

wasmtime -S cli -S http --dir . c2patool.wasm [OPTIONS] <ASSET_PATH> [COMMAND]