c2patool is a command line tool for working with C2PA manifests and media assets (image or video files).
Use the tool to:
PREREQUISITE: Install Rust.
Enter this command to install or update the tool:
shell
cargo install c2patool
To ensure you have the latest version, enter this command:
c2patool -V
The tool will display the version installed. Compare the version number displayed with the latest release version shown in the repository releases page. To update to the latest version, use the installation command shown above.
The tool works with the following types of asset files (also referred to as assets).
| MIME type | extensions | read only |
| ----------------- | ----------- | --------- |
| image/jpeg | jpg, jpeg | |
| image/png | png | |
| image/avif | avif | X |
| image/heic | heic | X |
| image/heif | heif | X |
| video/mp4 | mp4 | |
| application/mp4 | mp4 | |
| audio/mp4 | m4a | |
| application/c2pa| c2pa | X |
| video/quicktime | mov | |
NOTE: Quicktime (.mov) format is not yet fully supported.
The tool's command-line syntax is:
c2patool [OPTIONS] [path]
Where <path> is the path to the asset to read or embed a manifest into.
The following table describes the command-line options.
| CLI option | Short version | Argument | Description |
|-----|----|----|----|
| --config | -c | <config> | Specifies a manifest definition as a JSON string. See Providing a manifest definition on the command line. |
| --detailed | -d | N/A | Display detailed C2PA-formatted manifest data. See Displaying a detailed manifest report. |
| --force | -f | N/A | Force overwriting output file. See Forced overwrite. |
| --help | -h | N/A | Display CLI help information. |
| --output | -o | <output_file> | Specifies path to output file. See Adding a manifest to an asset file. |
| --manifest | -m | <manifest_file> | Specifies a manifest file to add to an asset file. See Adding a manifest to an asset file.
| --parent | -p | <parent_file> | Specifies path to parent file. See Specifying a parent file. |
| --remote | -r | <manifest_url> | Specify URL for remote manifest available over HTTP. See Generating a remote manifest|
| --sidecar | -s | N/A | Put manifest in external "sidecar" file with .c2pa extension. See Generating an external manifest. |
| --version | -V | N/A | Display version information. |
To display the manifest associated with an asset file, provide the path to the file as the argument; for example:
shell
c2patool sample/C.jpg
The tool displays the manifest JSON to standard output (stdout).
To display a detailed report describing the internal C2PA format of manifests contained in the asset, use the -d option; for example, using one of the example images in the sample directory:
shell
c2patool -d sample/C.jpg
The tool displays the detailed report to standard output (stdout).
The --info option will print a high level report about any c2pa content in the file.
For a cloud manifest it will display the url to the manifest.
For embedded manifests, the size of the manifest store and number of manifests will be displayed. It will also report if the manifest validated or any errors encountered in validation.
shell
c2patool sample/C.jpg --info
The tool displays the info report to standard output (stdout).
To add C2PA manifest data to a file, use the --manifest / -m option with a manifest JSON file as the option argument and the path to the asset file to be signed. Specify the output file as the argument to the --output / -o option. For example:
shell
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).
CAUTION: If the output file is the same as the source file, the tool will overwrite the source file.
If you do not use the --output / -o option, then the tool will display the generated manifest but will not save it to a 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:
shell
c2patool sample/image.jpg -m sample/test.json -p sample/c.jpg -o signed_image.jpg
You can also specify a parent file in the manifest definition.
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:
shell
c2patool sample/image.jpg -m sample/test.json -f -o signed_image.jpg
To display a preview of the generated manifest and ensure you've formatted the manifest definition correctly, provide the path to a manifest file as the argument with no other options or flags; for example:
shell
c2patool sample/image.jpg -m sample/test.json
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.
shell
c2patool image.jpg -s -m sample/test.json -o signed_image.jpg
Use the --remote / -r option to places 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.
shell
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.
To provide the manifest definition in a command line argument instead of a file, use the --config / -c option.
For example, the following command adds a custom assertion called "org.contentauth.test".
shell
c2patool sample/image.json -c '{"assertions": [{"label": "org.contentauth.test", "data": {"my_key": "whatever I want"}}]}'
The manifest definition file is a JSON formatted file with a .json extension.
Relative file paths are interpreted as relative to the location of the definition file unless you specify a base_path field.
The schema for the manifest definition file is shown below.
json
{
"$schema": "http://json-schema.org/draft-07/schema",
"$id": "http://ns.adobe.com/c2patool/claim-definition/v1",
"type": "object",
"description": "Definition format for claim created with c2patool",
"examples": [
{
"alg": "es256",
"private_key": "es256_private.key",
"sign_cert": "es256_certs.pem",
"ta_url": "http://timestamp.digicert.com",
"vendor": "myvendor",
"claim_generator": "MyApp/0.1",
"parent": "image.jpg",
"ingredients": [],
"assertions": [
{
"label": "my.assertion",
"data": {
"any_tag": "whatever I want"
}
}
],
}
],
"required": [
"assertions",
],
"properties": {
"vendor": {
"type": "string",
"description": "Typically an Internet domain name (without the TLD) for the vendor (i.e. `adobe`, `nytimes`). If provided this will be used as a prefix on generated manifest labels."
},
"claim_generator": {
"type": "string",
"description": "A UserAgent string that will let a user know what software/hardware/system produced this Manifest - names should not contain spaces (defaults to c2patool)."
},
"title": {
"type": "string",
"description": "A human-readable string to be displayed as the title for this Manifest (defaults to the name of the file this manifest was embedded in)."
},
"credentials": {
"type": "object",
"description": "An array of W3C verifiable credentials objects defined in the c2pa assertion specification. Section 7."
},
"parent": {
"type": "string",
"format": "Local file system path",
"description": "A file path to the state of the asset prior to any changes declared in the manifest definition."
},
"Ingredients": {
"type": "array of string",
"format": "Array of local file system paths",
"description": "File paths to assets that were used to modify the asset referenced by this Manifest (if any)."
},
"assertions": {
"type": "object",
"description": "Objects with label, and data - standard c2pa labels must match values as defined in the c2pa assertion specification."
},
"alg": {
"type": "string",
"format": "Local file system path",
"description": "Signing algorithm: one of [ ps256 | ps384 | ps512 | es256 | es384 | es512 | ed25519]. Defaults to es256."
},
"ta_url": {
"type": "string",
"format": "http URL",
"description": "A URL to an RFC3161 compliant Time Stamp Authority. If missing there will no secure timestamp."
},
"private_key": {
"type": "string",
"format": "Local file system path",
"description": "File path to a private key file."
},
"sign_cert": {
"type": "string",
"format": "Local file system path",
"description": "File path to signing cert file."
},
"base_path": {
"type": "string",
"format": "Local file system path",
"description": "File path to a folder to use as the base for relative paths in this file."
},
},
"additionalProperties": false
}
Here's an example of a manifest definition that inserts a CreativeWork author assertion. Copy this JSON into a file to use as a test manifest.
json
{
"ta_url": "http://timestamp.digicert.com",
"claim_generator": "TestApp",
"assertions": [
{
"label": "stds.schema-org.CreativeWork",
"data": {
"@context": "https://schema.org",
"@type": "CreativeWork",
"author": [
{
"@type": "Person",
"name": "Joe Bloggs"
}
]
}
}
]
}