From 1127106645bc7bf180817bad8fb75186b4cfd3ea Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Thu, 18 Aug 2022 16:34:36 -0700 Subject: [PATCH 1/4] Update README.md --- README.md | 184 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 120 insertions(+), 64 deletions(-) diff --git a/README.md b/README.md index 05f35e91..56b877b7 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,39 @@ # c2patool - C2PA command line tool -c2patool is a command line tool for working with C2PA [manifests](https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_manifests). Currently, the tool supports: +`c2patool` is a command line tool for working with C2PA [manifests](https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_manifests) and media assets (image or video files). + +Use the tool to: + +- Read a JSON report of C2PA manifests in [supported file formats](#supported-file-formats). +- Read a low-level report of C2PA manifest data in [supported file formats](#supported-file-formats). +- Preview manifest data from a [manifest definition](#manifest-definition-file). +- Add a C2PA manifest to [supported file formats](#supported-file-formats). + +## Installation + +PREREQUISITE: Install [Rust](https://www.rust-lang.org/tools/install). + +Enter this command to install or update the tool: + +```shell +cargo install c2patool +``` + +### Updating + +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](https://github.com/contentauth/c2patool/releases). To update to the latest version, use the installation command shown above. -- Reading a JSON report of C2PA manifests in [supported file formats](#supported-file-formats) -- Reading a low-level report of C2PA manifest data in [supported file formats](#supported-file-formats) -- Previewing manifest data from a [manifest definition](#manifest-definition-format) -- Adding a C2PA manifest to [supported file formats](#supported-file-formats) ## Supported file formats + +The tool works with the following types of asset files (also referred to as _assets_). + | MIME type | extensions | read only | | ----------------- | ----------- | --------- | | `image/jpeg` | `jpg, jpeg` | | @@ -21,127 +47,133 @@ c2patool is a command line tool for working with C2PA [manifests](https://c2pa.o | `application/c2pa`| `c2pa` | X | | `video/quicktime` | `mov` | | -## Installation +NOTE: Quicktime (`.mov`) format is not yet fully supported. -If you have [Rust](https://www.rust-lang.org/tools/install) installed, you can install or update c2patool using: +## Usage -```shell -cargo install c2patool +The tool's command-line syntax is: + +``` +c2patool [OPTIONS] [path] ``` -## Usage +Where `` is the path to the asset to read, or a JSON configuration file. + +The following table describes the command-line options. + +| CLI option          | Short version | Argument | Description | +|-----|----|----|----| +| `--config` | `-c` | `` | Specifies a manifest definition as a JSON string. See [Providing a manifest definition on the command line](#providing-a-manifest-definition-on-the-command-line). | +| `--detailed` | `-d` | N/A | Display detailed C2PA-formatted manifest data. See [Displaying a detailed manifest report](#displaying-a-detailed-manifest-report). | +| `--force` | `-f` | N/A | Force overwriting output file. See [Forced overwrite](#forced-overwrite). | +| `--help` | `-h` | N/A | Display CLI help information. | +| `--output` | `-o` | `` | Specifies path to output file. See [Adding a manifest to an asset file](#adding-a-manifest-to-an-asset-file). | +| `--manifest` | `-m` | `` | Specifies a manifest file to add to an asset file. See [Adding a manifest to an asset file](#adding-a-manifest-to-an-asset-file). +| `--parent` | `-p` | `` | Specifies path to parent file. See [Specifying a parent file](#specifying-a-parent-file). | +| `--remote` | `-r` | `` | Specify remote manifest available over HTTP. See [Generating a remote manifest](#generating-a-remote-manifest)| +| `--sidecar` | `-s` | N/A | Put manifest in external "sidecar" file with `.c2pa` extension. See [Generating an external manifest](#generating-an-external-manifest). | +| `--version` | `-V` | N/A | Display version information. | ### Displaying manifest data -Invoking the tool with a path to an asset will print a report describing the manifests contained in the file in JSON format to stdout. +To display the manifest associated with an asset file, provide the relative path to the file as the argument; for example: ```shell c2patool image.jpg ``` -### Detailed manifest report +The tool displays the manifest JSON to standard output (stdout). -The `-d` or `--detailed` option will print a detailed report describing the internal C2PA format of manifests contained in the file in JSON format to stdout. -```shell -c2patool image.jpg -d -``` +### Displaying a detailed manifest report -### Adding a manifest to a file +To display a detailed report describing the internal C2PA format of manifests contained in the asset, use the `-d` option; for example: -To add C2PA data to a file, use the `-m` or `--manifest` option and provide a manifest definition JSON file as the argument. The tool generates a new manifest using the values given in the file. +```shell +c2patool -d image.jpg +``` -The file path must reference the asset to be signed. +The tool displays the detailed report to standard output (stdout). -The output file is specified on the command line via the `-o` or `--output` flag. If the output is the same as the source, it will be overwritten. Use this with caution. If no output is given you can preview the generated manifest but nothing is written. +### Adding a manifest to an asset file -The generated manifest store will also be reported in JSON format to stdout. +To add C2PA manifest data to a file, use the `--manifest` (or `-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 `-o` or `--output` option. For example: ```shell c2patool image.jpg -m sample/test.json -o signed_image.jpg ``` -A parent file can be specified with the `-p` or `--parent` option or in the manifest definition. The parent file represents the state of the asset before any edits were made. +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 `-o` or `--output` option, then the tool will display the generated manifest but will not save it to a file. + +#### Specifying a parent file + +A _parent file_ represents the state of the image before any edits were made. + +Specify a parent file as the argument to the `--parent`/`-p` option; for example: ```shell c2patool image.jpg -m sample/test.json -p parent.jpg -o signed_image.jpg ``` +You can also specify a parent file in the manifest definition. + #### Forced overwrite -The tool will return an error if the output file already exists. The `-f` or `--force` flag may be used to override this behavior. Use this with caution. + +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 image.jpg -m sample/test.json -f -o signed_image.jpg ``` -#### Manifest preview feature +### Previewing a manifest -If the output file is not specified, the tool will generate a preview of the generated manifest. This can be used to make sure you have formatted the manifest definition correctly. +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 image.jpg -m sample/test.json +c2patool sample/test.json ``` ### Generating an external manifest -The `-s` or `--sidecar` option puts 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 output file will be copied but untouched. +Use the `--sidecar` (or `-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 ``` ### Generating a remote manifest -The `-r` or `--remote` option places an http reference to manifest in the output file. The manifest is returned as 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 manifest should then be placed 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. +Use the `--remote` (or `-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 image.jpg -r http://my_server/myasset.c2pa -m sample/test.json -o signed_image.jpg ``` -In the example above c2patool will try to fetch the manifest for new_manifest.jpg from http://my_server/myasset.c2pa during validation. +In the example above, the tool tries to fetch the manifest for `new_manifest.jpg` from `http://my_server/myasset.c2pa` during validation. -Note: It is possible to combine the `-s` and `-r` options. When used together a manifest will be embedded in the output files and the remote reference will also be added. +If you use both the `-s` and `-r` options, the tool embeds a manifest in the output files and also adds the remote reference. -#### Example of a manifest definition file +### Providing a manifest definition on the command line -Here's an example of a manifest definition that inserts a CreativeWork author assertion. If you copy this into a JSON file, you can use it as a test manifest definition. +To provide the [manifest definition](#manifest-definition-file) in a command line argument instead of a file, use the `--config` (or `-c`) option. -```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" - } - ] - } - } - ] -} -``` -### Manifest definition on command line - -The [manifest definition](#manifest-definition-format) can also be passed on the command line as a string using the `-c` or `--config` option. - -In this example we are adding a custom assertion called "org.contentauth.test". +For example, the following command adds a custom assertion called "org.contentauth.test". ```shell -c2patool image.json -c '{"assertions": [{"label": "org.contentauth.test", "data": {"my_key": "whatever I want"}}]}' +c2patool -c '{"assertions": [{"label": "org.contentauth.test", "data": {"my_key": "whatever I want"}}]}' ``` -### Manifest definition format +## Manifest definition file + +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 manifest definition file is a JSON formatted file with a .json extension. -Any relative file paths will be treated as relative to the location of the definition file unless a `base_path` field is specified. +### Schema + +The schema for the manifest definition file is shown below. -The schema for this type is as follows: ```json { "$schema": "http://json-schema.org/draft-07/schema", @@ -232,4 +264,28 @@ The schema for this type is as follows: } ``` +#### Example manifest definition file + +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" + } + ] + } + } + ] +} +``` From 6dbbd12fbc29ee96ada59b563cb7853ccccea98f Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Thu, 1 Sep 2022 10:27:30 -0700 Subject: [PATCH 2/4] Address comments from @scouten-adobe --- README.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 37d1ce66..61d044de 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ 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](https://github.com/contentauth/c2patool/releases). To update to the latest version, use the installation command shown above. +The tool will display the version installed. Compare the version number displayed with the latest release version shown in the [repository releases page](https://github.com/contentauth/c2patool/releases). To update to the latest version, use the installation command shown above. ## Supported file formats @@ -57,26 +57,26 @@ The tool's command-line syntax is: c2patool [OPTIONS] [path] ``` -Where `` is the path to the asset to read, or a JSON configuration file. +Where `` is the path to the asset to read, or a JSON configuration file. The following table describes the command-line options. | CLI option          | Short version | Argument | Description | |-----|----|----|----| | `--config` | `-c` | `` | Specifies a manifest definition as a JSON string. See [Providing a manifest definition on the command line](#providing-a-manifest-definition-on-the-command-line). | -| `--detailed` | `-d` | N/A | Display detailed C2PA-formatted manifest data. See [Displaying a detailed manifest report](#displaying-a-detailed-manifest-report). | +| `--detailed` | `-d` | N/A | Display detailed C2PA-formatted manifest data. See [Displaying a detailed manifest report](#displaying-a-detailed-manifest-report). | | `--force` | `-f` | N/A | Force overwriting output file. See [Forced overwrite](#forced-overwrite). | | `--help` | `-h` | N/A | Display CLI help information. | | `--output` | `-o` | `` | Specifies path to output file. See [Adding a manifest to an asset file](#adding-a-manifest-to-an-asset-file). | | `--manifest` | `-m` | `` | Specifies a manifest file to add to an asset file. See [Adding a manifest to an asset file](#adding-a-manifest-to-an-asset-file). -| `--parent` | `-p` | `` | Specifies path to parent file. See [Specifying a parent file](#specifying-a-parent-file). | +| `--parent` | `-p` | `` | Specifies path to parent file. See [Specifying a parent file](#specifying-a-parent-file). | | `--remote` | `-r` | `` | Specify remote manifest available over HTTP. See [Generating a remote manifest](#generating-a-remote-manifest)| | `--sidecar` | `-s` | N/A | Put manifest in external "sidecar" file with `.c2pa` extension. See [Generating an external manifest](#generating-an-external-manifest). | | `--version` | `-V` | N/A | Display version information. | ### Displaying manifest data -To display the manifest associated with an asset file, provide the relative path to the file as the argument; for example: +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 @@ -94,7 +94,7 @@ The tool displays the detailed report to standard output (stdout). ### Adding a manifest to an asset file -To add C2PA manifest data to a file, use the `--manifest` (or `-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 `-o` or `--output` option. For example: +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 @@ -104,13 +104,13 @@ The tool generates a new manifest using the values given in the file and display 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 `-o` or `--output` option, then the tool will display the generated manifest but will not save it to a 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. #### Specifying a parent file -A _parent file_ represents the state of the image before any edits were made. +A _parent file_ represents the state of the image before any edits were made. -Specify a parent file as the argument to the `--parent`/`-p` option; for example: +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 @@ -120,7 +120,7 @@ You can also specify a parent file in the manifest definition. #### 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: +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 image.jpg -m sample/test.json -f -o signed_image.jpg @@ -136,14 +136,14 @@ c2patool sample/test.json ### Generating an external manifest -Use the `--sidecar` (or `-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. +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 ``` ### Generating a remote manifest -Use the `--remote` (or `-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. +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 @@ -155,7 +155,7 @@ If you use both the `-s` and `-r` options, the tool embeds a manifest in the out ### Providing a manifest definition on the command line -To provide the [manifest definition](#manifest-definition-file) in a command line argument instead of a file, use the `--config` (or `-c`) option. +To provide the [manifest definition](#manifest-definition-file) 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". From 2703691f7338cb78cc789b8003f060760721b25d Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Thu, 1 Sep 2022 13:00:46 -0700 Subject: [PATCH 3/4] Addressing comments from @gpeacock --- README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 61d044de..ed8dc588 100644 --- a/README.md +++ b/README.md @@ -70,7 +70,7 @@ The following table describes the command-line options. | `--output` | `-o` | `` | Specifies path to output file. See [Adding a manifest to an asset file](#adding-a-manifest-to-an-asset-file). | | `--manifest` | `-m` | `` | Specifies a manifest file to add to an asset file. See [Adding a manifest to an asset file](#adding-a-manifest-to-an-asset-file). | `--parent` | `-p` | `` | Specifies path to parent file. See [Specifying a parent file](#specifying-a-parent-file). | -| `--remote` | `-r` | `` | Specify remote manifest available over HTTP. See [Generating a remote manifest](#generating-a-remote-manifest)| +| `--remote` | `-r` | `` | Specify URL for remote manifest available over HTTP. See [Generating a remote manifest](#generating-a-remote-manifest)| | `--sidecar` | `-s` | N/A | Put manifest in external "sidecar" file with `.c2pa` extension. See [Generating an external manifest](#generating-an-external-manifest). | | `--version` | `-V` | N/A | Display version information. | @@ -84,10 +84,10 @@ 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: +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/image.jpg +c2patool -d sample/C.jpg ``` The tool displays the detailed report to standard output (stdout). @@ -108,7 +108,7 @@ If you do not use the `--output` / `-o` option, then the tool will display the g #### Specifying a parent file -A _parent file_ represents the state of the image before any edits were made. +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: @@ -131,7 +131,7 @@ c2patool 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/test.json +c2patool sample/image.jpg -m sample/test.json ``` ### Generating an external manifest @@ -149,9 +149,9 @@ Use the `--remote` / `-r` option to places an HTTP reference to the manifest in c2patool sample/image.jpg -r http://my_server/myasset.c2pa -m sample/test.json -o signed_image.jpg ``` -In the example above, the tool tries to fetch the manifest for `new_manifest.jpg` from `http://my_server/myasset.c2pa` during validation. +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 files and also adds the remote reference. +If you use both the `-s` and `-r` options, the tool embeds a manifest in the output file and also adds the remote reference. ### Providing a manifest definition on the command line From 9fc37ce3e2dff461d0dfc1a0736ca799dd262d2f Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Fri, 2 Sep 2022 12:07:40 -0700 Subject: [PATCH 4/4] Edits from review by @gpeacock --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index ed8dc588..4ea9cd92 100644 --- a/README.md +++ b/README.md @@ -57,7 +57,7 @@ The tool's command-line syntax is: c2patool [OPTIONS] [path] ``` -Where `` is the path to the asset to read, or a JSON configuration file. +Where `` is the path to the asset to read or embed a manifest into. The following table describes the command-line options. @@ -123,7 +123,7 @@ 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 image.jpg -m sample/test.json -f -o signed_image.jpg +c2patool sample/image.jpg -m sample/test.json -f -o signed_image.jpg ``` ### Previewing a manifest @@ -160,7 +160,7 @@ To provide the [manifest definition](#manifest-definition-file) in a command lin For example, the following command adds a custom assertion called "org.contentauth.test". ```shell -c2patool -c '{"assertions": [{"label": "org.contentauth.test", "data": {"my_key": "whatever I want"}}]}' +c2patool sample/image.json -c '{"assertions": [{"label": "org.contentauth.test", "data": {"my_key": "whatever I want"}}]}' ``` ## Manifest definition file