From d21ff91e5b89d3c79789d06740b856431549afb6 Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Fri, 15 Nov 2024 13:53:53 -0800 Subject: [PATCH 01/14] Initial commit for doc reorg --- README.md | 103 +++------------------ 2024_API_NOTES.md => docs/release-notes.md | 71 +++++++------- docs/supported-formats.md | 28 ++++++ docs/testing.md | 12 +++ docs/usage.md | 51 ++++++++++ 5 files changed, 138 insertions(+), 127 deletions(-) rename 2024_API_NOTES.md => docs/release-notes.md (76%) create mode 100644 docs/supported-formats.md create mode 100644 docs/testing.md create mode 100644 docs/usage.md diff --git a/README.md b/README.md index c09210371..c83fece0b 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,14 @@
-The **[Coalition for Content Provenance and Authenticity](https://c2pa.org)** (C2PA) addresses the prevalence of misleading information online through the development of technical standards for certifying the source and history (or provenance) of media content. Adobe and other contributors created the C2PA Rust library as part of the [Content Authenticity Initiative](https://contentauthenticity.org) and [released it to open source](https://contentauthenticity.org/blog/cai-releases-suite-of-open-source-tools-to-advance-digital-content-provenance) in June, 2022. +The **[Coalition for Content Provenance and Authenticity](https://c2pa.org)** (C2PA) addresses the prevalence of misleading information online through the development of technical standards for certifying the source and history (or provenance) of media content. The C2PA Rust library is part of the [Content Authenticity Initiative](https://contentauthenticity.org) open-source SDK. + +Additional documentation: + +- [Usage](usage.md) +- [Supported formats](supported-formats.md) +- [Release notes](release-notes.md) +- [Testing](testing.md)
@@ -19,104 +26,23 @@ The library enables a desktop, mobile, or embedded application to: The library supports several common C2PA [assertions](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_c2pa_standard_assertions) and [hard bindings](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_hard_bindings). -## State of the project - -This is a beta release (version 0.x.x) of the project. The minor version number (0.x.0) is incremented when there are breaking API changes, which may happen frequently. +For details on what you can do with the library, see [Using the Rust library](usage.md). -### New API - -The library has a new API in development that will eventually replace the existing methods of reading and writing C2PA data. Ultimately, it will support all language bindings and build environments. To use this API, enable the `unstable_api` feature; for example: - -``` -c2pa = {version="0.33.1", features=["unstable_api"]} -``` +## State of the project -The new API focuses on streaming I/O and supports the following structs: -- [Builder](https://docs.rs/c2pa/latest/c2pa/struct.Builder.html) -- [Reader](https://docs.rs/c2pa/latest/c2pa/struct.Reader.html) -- [ManifestDefinition](https://docs.rs/c2pa/latest/c2pa/struct.ManifestDefinition.html) +This is a beta release (version 0.x.x) of the project. The minor version number (0.x.0) is incremented when there are breaking API changes, which may happen frequently. -For some informal development and ussage notes, see [2024_API_NOTES.md](https://github.com/contentauth/c2pa-rs/blob/main/2024_API_NOTES.md). +NOTE: The current release includes a new API that replaces old methods of reading and writing C2PA data, which are deprecated. See the [release notes](release-notes.md) for more information. Refer to the [CHANGELOG](https://github.com/contentauth/c2pa-rs/blob/main/CHANGELOG.md) for detailed changes derived from Git commit history. ### Contributions and feedback We welcome contributions to this project. For information on contributing, providing feedback, and about ongoing work, see [Contributing](https://github.com/contentauth/c2pa-rs/blob/main/CONTRIBUTING.md). -## Requirements - -The library requires **Rust version 1.76.0** or newer. - -### Supported platforms - -The library has been tested on the following operating systems: - -* Windows (Intel only) -* MacOS (Intel and Apple silicon) -* Ubuntu Linux (64-bit Intel and ARM v8) -* WebAssembly (Wasm) - -## Supported file formats - - | Extensions | MIME type | - | ------------- | ----------------------------------------------------------------------------- | - | `avi` | `video/msvideo`, `video/x-msvideo`, `video/avi`, `application/x-troff-msvideo`| - | `avif` | `image/avif` | - | `c2pa` | `application/x-c2pa-manifest-store` | - | `dng` | `image/x-adobe-dng` | - | `heic` | `image/heic` | - | `heif` | `image/heif` | - | `jpg`, `jpeg` | `image/jpeg` | - | `m4a` | `audio/mp4` | - | `mp4` | `video/mp4`, `application/mp4` | - | `mov` | `video/quicktime` | - | `png` | `image/png` | - | `svg` | `image/svg+xml` | - | `tif`,`tiff` | `image/tiff` | - | `wav` | `audio/wav` | - | `webp` | `image/webp` | - | `mp3` | `audio/mpeg` | - | `gif` | `image/gif` | - -## Usage - -Add this to your `Cargo.toml`: - -```toml -[dependencies] -c2pa = "0.36.1" -``` - -If you want to read or write a manifest file, add the `file_io` dependency to your `Cargo.toml`. -The `add_thumbnails` feature will generate thumbnails for JPEG and PNG files. - For example: -``` -c2pa = { version = "0.25.0", features = ["file_io", "add_thumbnails"] } -``` - -NOTE: If you are building for WASM, omit the `file_io` dependency. - -## Crate features - -The Rust library crate provides: - -* `file_io` enables manifest generation, signing via OpenSSL, and embedding manifests in various file formats. -* `add_thumbnails` will generate thumbnails automatically for JPEG and PNG files. (no longer included with `file_io`) -* `serialize_thumbnails` includes binary thumbnail data in the [Serde](https://serde.rs/) serialization output. -* `no_interleaved_io` forces fully-synchronous I/O; otherwise, the library uses threaded I/O for some operations to improve performance. -* `fetch_remote_manifests` enables the verification step to retrieve externally referenced manifest stores. External manifests are only fetched if there is no embedded manifest store and no locally adjacent .c2pa manifest store file of the same name. -* `json_schema` is used by `make schema` to produce a JSON schema document that represents the `ManifestStore` data structures. -* `psxxx_ocsp_stapling_experimental` this is an demonstration feature that will attempt to fetch the OCSP data from the OCSP responders listed in the manifest signing certificate. The response becomes part of the manifest and is used to prove the certificate was not revoked at the time of signing. This is only implemented for PS256, PS384 and PS512 signatures and is intended as a demonstration. -* `openssl_ffi_mutex` prevents multiple threads from accessing the C OpenSSL library simultaneously. (This library is not re-entrant.) In a multi-threaded process (such as Cargo's test runner), this can lead to unpredictable behavior. - -## Example code - -The [sdk/examples](https://github.com/contentauth/c2pa-rs/tree/main/sdk/examples) directory contains some minimal example code. The [client/client.rs](https://github.com/contentauth/c2pa-rs/blob/main/sdk/examples/client/client.rs) is the most instructive and provides and example of reading the contents of a manifest store, recursively displaying nested manifests. - ## License The `c2pa` crate is distributed under the terms of both the [MIT license](https://github.com/contentauth/c2pa-rs/blob/main/LICENSE-MIT) and the [Apache License (Version 2.0)](https://github.com/contentauth/c2pa-rs/blob/main/LICENSE-APACHE). -Some components and dependent crates are licensed under different terms; please check the license terms for each crate and component for details. +Some components and dependent crates are licensed under different terms; please check their licenses for details. ## Nightly builds @@ -138,7 +64,4 @@ version = "0.25.3-nightly+2023-08-28-2f33ab3" Please note that there is no formal support for code from a nightly release, but if you become aware of any issues, we would appreciate a bug report including this version number. -## Changelog - -Refer to the [CHANGELOG](https://github.com/contentauth/c2pa-rs/blob/main/CHANGELOG.md) for detailed changes derived from Git commit history. diff --git a/2024_API_NOTES.md b/docs/release-notes.md similarity index 76% rename from 2024_API_NOTES.md rename to docs/release-notes.md index 6a56f6c52..ff5bf59a2 100644 --- a/2024_API_NOTES.md +++ b/docs/release-notes.md @@ -1,32 +1,48 @@ -## 2024 API Notes +# Release notes -### Goals -Provide a consistent flexible well tested API focusing on core functionality. +### 1.0 + +The version 1.0 release has a new API that replaces the previous methods of reading and writing C2PA data, which are still supported but are deprecated. + +The goals of this release are to provide a consistent, flexible, well-tested API; specifically: - Move toward a JSON + binary resources model that ports well to multiple languages. - Eliminate multiple variations of functions for file/memory/stream, sync/async & etc. -- Have one stream based version of each function that works sync and async. -- Design APIs keeping in mind support for multiple language bindings. -- Enable sign only/verify only and no openssl configuration. +- Have one stream-based version of each function that works sync and async. +- Design APIs that work well for multiple language bindings. +- Enable sign-only/verify-only and support usage without OpenSSL. - Support Box Hash and Data Hashed signing models. - Enable builds for cameras and other embedded environments. - Provide a consistent model for setting runtime options. -- Write unit tests, integration tests and documentation for all the v2 APIs. +- Write thorough unit tests, integration tests and documentation; see [Testing](testing.md) for details. - Keep porting as simple as possible. -### Resource References + +To use this API, enable the `unstable_api` feature; for example: + +``` +c2pa = {version="0.33.1", features=["unstable_api"]} +``` + +The new API focuses on streaming I/O and supports the following structs: +- [Builder](https://docs.rs/c2pa/latest/c2pa/struct.Builder.html) +- [Reader](https://docs.rs/c2pa/latest/c2pa/struct.Reader.html) +- [ManifestDefinition](https://docs.rs/c2pa/latest/c2pa/struct.ManifestDefinition.html) + +### Resource references + A resource reference in the API is associated with a HashedUri as a superset. -- The c2pa spec refers to both a hashed-uri-map and a hashed-ext-uri-map +- The C2PA specification refers to both a hashed-uri-map and a hashed-ext-uri-map - In some cases either one can be used. - The resource reference is a superset of both. - It also adds local references to things like the filesystem or any abstracted storage. -I've been using the identifier field to distinguish from the url field, but they are really the same. However, the spec will only allow for JUMBF and http/https references, so if the external identifier is not http/https, it must be converted to +I've been using the identifier field to distinguish from the url field, but they are really the same. However, the specification will only allow for JUMBF and http/https references, so if the external identifier is not http/https, it must be converted to a JUMBF reference before embedding into a manifest. When defining a resource for the ManifestStoreBuilder, existing resources in other manifests may be identified via JUMBF urls. This allows a new manifest to inherit an existing thumbnail and is also used to reference parent ingredients. The API will generally do this resolution as needed so users do not need to know about JUMBF URL referencing on manifest creation. -The spec will often require adding a hashed-uri to an assertion. Since the JUMBF uris for a new manifest are not known when defining the manifest, this creates a chicken and egg scenario. We resolve this with local resource references. When constructing the JUMBF for a manifest, the api will convert all local uri references into JUMBF references and fixup the associated cross references. +The specification often requires adding a hashed-uri to an assertion. Since the JUMBF uris for a new manifest are not known when defining the manifest, this creates a chicken and egg scenario. We resolve this with local resource references. When constructing the JUMBF for a manifest, the api will convert all local uri references into JUMBF references and fixup the associated cross references. URI schemes in a resource reference could take the following forms: - self#jumbf= an internal JUMBF reference @@ -39,8 +55,9 @@ Note that the file: and app: schemes are only used in the context of ManifestSto Lack of a scheme will be interpreted as a file:/// reference when file_io is enabled, otherwise as an app: reference. -### Source asset vs Parent asset -- The source asset isn't always the parent asset. +### Source asset vs parent asset + +The source asset isn't always the parent asset. The source asset is the asset that we will hash and sign. It can the output from an editing application that has not preserved the manifest store from the parent. In that case the application should have extracted a parent ingredient from the parent asset and added that to the manifest definition. - Parent asset: with a manifest store. @@ -51,8 +68,9 @@ The source asset is the asset that we will hash and sign. It can the output from If there is no parent ingredient defined, and the source has a manifest store, the sdk will generate a parent ingredient from the parent. ### Remote URLs and embedding -The default operation of c2pa signing is to embed a c2pa manifest store into an asset. -We also return the c2pa manifest store so that it can be written to a sidecar or uploaded to a remote service. + +The default operation of C2PA signing is to embed a C2PA manifest store into an asset. +We also return the C2PA manifest store so that it can be written to a sidecar or uploaded to a remote service. - The API supports embedding a remote url reference into the asset. - The remote URL is stored in different ways depending on the asset, but is often stored in XMP data. - The remote URL must be added to the asset before signing so that it can be hashed along with the asset. @@ -62,28 +80,7 @@ We also return the c2pa manifest store so that it can be written to a sidecar or - The remote url can be set with builder.remote_url. - If embedding is not needed, set the builder.no_embed flag to true. - -## Testing -We need a more comprehensive set of tests for the rust codebase. - -The plan is to build a solid set of tests on the new streams based API. -Then we will build everything else on top of that as stable base. -The current set of unit tests are helpful but many are out of date. -I've had a long standing issue to generate the test images from clean non-c2pa images. -When we check in images with manifests, they rapidly get out of date. -We do need some set of older manifests and third party images to test with -but I'm not sure if those need to be in the SDK. - -- A test assets folder with one public domain image in each asset format we support. -- A tool, like make_test_images, to generate different kinds of manifests for testing. -We should maintain an archive of the manifest_store json generated by the previous build -and compare the old build with the new ones for any significant deltas. -The tool needs to ignore changes due to new GUIDs, dates, and json object field order. - -The make_test_images crate has been updated to do this by default. We may make a policy to run the test comparison nightly. - - -The 2024 API List +## Language bindings for 1.0 API methods | Module | Method | C++ | Python | WASM | Node | | -------- | ---------------------------------- |----- | ------ | ---- | ----- | diff --git a/docs/supported-formats.md b/docs/supported-formats.md new file mode 100644 index 000000000..a69c1568d --- /dev/null +++ b/docs/supported-formats.md @@ -0,0 +1,28 @@ +# Supported file formats + +The following table summarizes the media (asset) file formats that the CAI Rust library supports. +Other libraries in the SDK support the same set of formats, unless noted otherwise. + + + | Extensions | MIME type | + | ------------- | ----------------------------------------------------------------------------- | + | `avi` | `video/msvideo`, `video/x-msvideo`, `video/avi`, `application/x-troff-msvideo`| + | `avif` | `image/avif` | + | `c2pa` | `application/x-c2pa-manifest-store` | + | `dng` | `image/x-adobe-dng` | + | `gif` | `image/gif` | + | `heic` | `image/heic` | + | `heif` | `image/heif` | + | `jpg`, `jpeg` | `image/jpeg` | + | `m4a` | `audio/mp4` | + | `mp3` | `audio/mpeg` | + | `mp4` | `video/mp4`, `application/mp4` | + | `mov` | `video/quicktime` | + | `png` | `image/png` | + | `svg` | `image/svg+xml` | + | `tif`,`tiff` | `image/tiff` | + | `wav` | `audio/wav` | + | `webp` | `image/webp` | + + + diff --git a/docs/testing.md b/docs/testing.md new file mode 100644 index 000000000..d53e2c147 --- /dev/null +++ b/docs/testing.md @@ -0,0 +1,12 @@ +# Testing + +The current set of unit tests are helpful but many are out of date. We need a more comprehensive set of tests for the Rust library. The plan is to build a solid set of tests on the new streams-based API, then build everything else on that. + +There is an open issue to generate test images from clean non-c2pa images. When images are checked in with manifests, they rapidly get out of date. A set of older manifests and third-party images is still needed for testing, but they need not be in the SDK. + +We need: + +- A test assets folder with one public domain image in each asset format we support. +- A tool, like `make_test_images`, to generate different kinds of manifests for testing. We should maintain an archive of the manifest_store JSON generated by the previous build and compare the old build with the new ones for any significant deltas. The tool needs to ignore changes due to new GUIDs, dates, and JSON object field order. + +The `make_test_images` crate has been updated to do this by default. We may make a policy to run the test comparison nightly. \ No newline at end of file diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 000000000..8b97e40e7 --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,51 @@ +# Using the Rust library + +## Supported platforms + +The C2PA Rust library has been tested on the following operating systems: + +* Windows (Intel only) +* MacOS (Intel and Apple silicon) +* Ubuntu Linux (64-bit Intel and ARM v8) +* WebAssembly (Wasm) + +## Requirements + +The C2PA Rust library requires **Rust version 1.76.0** or newer. + +To use the library, add this to your `Cargo.toml`: + +```toml +[dependencies] +c2pa = "0.36.1" +``` + +To read or write a manifest file, add the `file_io` dependency to your `Cargo.toml`. + + + +Add the `add_thumbnails` dependency to generate thumbnails for JPEG and PNG files. For example: + +``` +c2pa = { version = "0.25.0", features = ["file_io", "add_thumbnails"] } +``` + +NOTE: If you are building for WASM, omit the `file_io` dependency. + +## Crate features + +The Rust library crate provides the following capabilities: + +* `file_io` enables manifest generation, signing via OpenSSL, and embedding manifests in [supported file formats](supported-formats.md). +* `add_thumbnails` will generate thumbnails automatically for JPEG and PNG files. (no longer included with `file_io`) +* `serialize_thumbnails` includes binary thumbnail data in the [Serde](https://serde.rs/) serialization output. +* `no_interleaved_io` forces fully-synchronous I/O; otherwise, the library uses threaded I/O for some operations to improve performance. +* `fetch_remote_manifests` enables the verification step to retrieve externally referenced manifest stores. External manifests are only fetched if there is no embedded manifest store and no locally adjacent .c2pa manifest store file of the same name. +* `json_schema` is used by `make schema` to produce a JSON schema document that represents the `ManifestStore` data structures. +* `psxxx_ocsp_stapling_experimental` this is an demonstration feature that will attempt to fetch the OCSP data from the OCSP responders listed in the manifest signing certificate. The response becomes part of the manifest and is used to prove the certificate was not revoked at the time of signing. This is only implemented for PS256, PS384 and PS512 signatures and is intended as a demonstration. +* `openssl_ffi_mutex` prevents multiple threads from accessing the C OpenSSL library simultaneously. (This library is not re-entrant.) In a multi-threaded process (such as Cargo's test runner), this can lead to unpredictable behavior. + +## Example code + +The [sdk/examples](https://github.com/contentauth/c2pa-rs/tree/main/sdk/examples) directory contains some minimal example code. The [client/client.rs](https://github.com/contentauth/c2pa-rs/blob/main/sdk/examples/client/client.rs) is the most instructive and provides and example of reading the contents of a manifest store, recursively displaying nested manifests. + From a2cc3bc11d1c210dceff59748c4f6934f10ef954 Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Fri, 15 Nov 2024 15:33:21 -0800 Subject: [PATCH 02/14] Move v1 notes into usage and edit --- docs/release-notes.md | 71 +++++++++---------------------------------- docs/usage.md | 53 ++++++++++++++++++++++++++++++-- 2 files changed, 64 insertions(+), 60 deletions(-) diff --git a/docs/release-notes.md b/docs/release-notes.md index ff5bf59a2..6eb7e93eb 100644 --- a/docs/release-notes.md +++ b/docs/release-notes.md @@ -1,8 +1,12 @@ # Release notes -### 1.0 +## Version 1.0 -The version 1.0 release has a new API that replaces the previous methods of reading and writing C2PA data, which are still supported but are deprecated. +The version 1.0 release has a new API that replaces the previous methods of reading and writing C2PA data, which are still supported but are deprecated. To use the deprecated API, enable the `v1_api` feature; for example: + +``` +c2pa = {version="1.0.0", features=["v1_api"]} +``` The goals of this release are to provide a consistent, flexible, well-tested API; specifically: @@ -14,73 +18,26 @@ The goals of this release are to provide a consistent, flexible, well-tested API - Support Box Hash and Data Hashed signing models. - Enable builds for cameras and other embedded environments. - Provide a consistent model for setting runtime options. -- Write thorough unit tests, integration tests and documentation; see [Testing](testing.md) for details. - Keep porting as simple as possible. - - -To use this API, enable the `unstable_api` feature; for example: - -``` -c2pa = {version="0.33.1", features=["unstable_api"]} -``` - The new API focuses on streaming I/O and supports the following structs: - [Builder](https://docs.rs/c2pa/latest/c2pa/struct.Builder.html) - [Reader](https://docs.rs/c2pa/latest/c2pa/struct.Reader.html) - [ManifestDefinition](https://docs.rs/c2pa/latest/c2pa/struct.ManifestDefinition.html) -### Resource references - -A resource reference in the API is associated with a HashedUri as a superset. -- The C2PA specification refers to both a hashed-uri-map and a hashed-ext-uri-map -- In some cases either one can be used. -- The resource reference is a superset of both. -- It also adds local references to things like the filesystem or any abstracted storage. -I've been using the identifier field to distinguish from the url field, but they are really the same. However, the specification will only allow for JUMBF and http/https references, so if the external identifier is not http/https, it must be converted to -a JUMBF reference before embedding into a manifest. +### Enabling -When defining a resource for the ManifestStoreBuilder, existing resources in other manifests may be identified via JUMBF urls. This allows a new manifest to inherit an existing thumbnail and is also used to reference parent ingredients. The API will generally do this resolution as needed so users do not need to know about JUMBF URL referencing on manifest creation. + -The specification often requires adding a hashed-uri to an assertion. Since the JUMBF uris for a new manifest are not known when defining the manifest, this creates a chicken and egg scenario. We resolve this with local resource references. When constructing the JUMBF for a manifest, the api will convert all local uri references into JUMBF references and fixup the associated cross references. - -URI schemes in a resource reference could take the following forms: -- self#jumbf= an internal JUMBF reference -- file:/// a local file reference -- app://contentauth/ a working store reference -- http:// remote uri -- https:// remote secure uri - -Note that the file: and app: schemes are only used in the context of ManifestStoreBuilder and will never be in JUMBF data. This is proposal, currently there is no implementation for file or app schemes and we do not yet handle http/https schemes this way. - -Lack of a scheme will be interpreted as a file:/// reference when file_io is enabled, otherwise as an app: reference. - -### Source asset vs parent asset - -The source asset isn't always the parent asset. -The source asset is the asset that we will hash and sign. It can the output from an editing application that has not preserved the manifest store from the parent. In that case the application should have extracted a parent ingredient from the parent asset and added that to the manifest definition. - -- Parent asset: with a manifest store. -- Parent ingredient: generated from that parent asset (hashed and validated) -- Source asset: may be a generated rendition after edits from the parent asset (manifest?) -- Signed output which will include the source asset, and the new manifest store with parent ingredient. - -If there is no parent ingredient defined, and the source has a manifest store, the sdk will generate a parent ingredient from the parent. +To use this API, enable the `unstable_api` feature; for example: -### Remote URLs and embedding +``` +c2pa = {version="1.0.0", features=["unstable_api"]} +``` -The default operation of C2PA signing is to embed a C2PA manifest store into an asset. -We also return the C2PA manifest store so that it can be written to a sidecar or uploaded to a remote service. -- The API supports embedding a remote url reference into the asset. -- The remote URL is stored in different ways depending on the asset, but is often stored in XMP data. -- The remote URL must be added to the asset before signing so that it can be hashed along with the asset. -- Not all file formats support embedding remote URLs or embedding manifests stores. -- If you embed a manifest or a remote URL, a new asset will be created with the new data embedded. -- If you don't embed, then the original asset is unmodified and there is no need to write one out. -- The remote url can be set with builder.remote_url. -- If embedding is not needed, set the builder.no_embed flag to true. +## Language binding support -## Language bindings for 1.0 API methods + | Module | Method | C++ | Python | WASM | Node | | -------- | ---------------------------------- |----- | ------ | ---- | ----- | diff --git a/docs/usage.md b/docs/usage.md index 8b97e40e7..afd77676d 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -32,19 +32,66 @@ c2pa = { version = "0.25.0", features = ["file_io", "add_thumbnails"] } NOTE: If you are building for WASM, omit the `file_io` dependency. -## Crate features +## Features The Rust library crate provides the following capabilities: * `file_io` enables manifest generation, signing via OpenSSL, and embedding manifests in [supported file formats](supported-formats.md). -* `add_thumbnails` will generate thumbnails automatically for JPEG and PNG files. (no longer included with `file_io`) +* `add_thumbnails` generates thumbnails automatically for JPEG and PNG files. (no longer included with `file_io`) * `serialize_thumbnails` includes binary thumbnail data in the [Serde](https://serde.rs/) serialization output. * `no_interleaved_io` forces fully-synchronous I/O; otherwise, the library uses threaded I/O for some operations to improve performance. * `fetch_remote_manifests` enables the verification step to retrieve externally referenced manifest stores. External manifests are only fetched if there is no embedded manifest store and no locally adjacent .c2pa manifest store file of the same name. * `json_schema` is used by `make schema` to produce a JSON schema document that represents the `ManifestStore` data structures. -* `psxxx_ocsp_stapling_experimental` this is an demonstration feature that will attempt to fetch the OCSP data from the OCSP responders listed in the manifest signing certificate. The response becomes part of the manifest and is used to prove the certificate was not revoked at the time of signing. This is only implemented for PS256, PS384 and PS512 signatures and is intended as a demonstration. +* `psxxx_ocsp_stapling_experimental` enables a demonstration feature that attempts to fetch the OCSP data from the OCSP responders listed in the manifest signing certificate. The response becomes part of the manifest and is used to prove the certificate was not revoked at the time of signing. This is only implemented for PS256, PS384 and PS512 signatures and is intended as a demonstration. * `openssl_ffi_mutex` prevents multiple threads from accessing the C OpenSSL library simultaneously. (This library is not re-entrant.) In a multi-threaded process (such as Cargo's test runner), this can lead to unpredictable behavior. +### Resource references + +A resource reference is a superset of a `HashedUri`, which the C2PA specification refers to as both `hashed-uri-map` and `hashed-ext-uri-map`. In some cases either can be used. + +A resource reference also adds local references to things like the file system or any abstracted storage. You can use the identifier field to distinguish from the URL field, but they are really the same. However, the specification will only allow for JUMBF and HTTP(S) references, so if the external identifier is not HTTP(S), it must be converted to a JUMBF reference before embedding into a manifest. + +When defining a resource for the [ManifestStoreBuilder](https://docs.rs/c2pa/latest/c2pa/struct.Builder.html), existing resources in other manifests may be identified via JUMBF URLs. This allows a new manifest to inherit an existing thumbnail and is also used to reference parent ingredients. The API will generally do this resolution as needed, so you do not need to know about JUMBF URL references when creating a manifest. + +The specification often requires adding a `HashedUri` to an assertion. Since the JUMBF URIs for a new manifest are not known when defining the manifest, this creates a "chicken and egg" scenario, resolved with local resource references. When constructing the JUMBF for a manifest, the library converts all local URI references into JUMBF references and corrects the the associated cross references. + +URI schemes in a resource reference can have the following forms: +- `self#jumbf` - An internal JUMBF reference +- `file:///` - A local file reference +- `app://contentauth/` - A working store reference +- `http://` - Remote URI +- `https://` - Remote secure URI + +Note that the `file:` and `app:` schemes are only used in the context of ManifestStoreBuilder and will never be in JUMBF data. This is proposal, currently there is no implementation for file or app schemes and we do not yet handle http/https schemes this way. + + + +When `file_io` is enabled, the lack of a scheme will be interpreted as a `file:///` reference, otherwise as an `app:` reference. + +### Source asset vs parent asset + +The source asset isn't always the parent asset: The source asset is the asset that is hashed and signed. It can be the output from an editing application that has not preserved the manifest store from the parent. In that case, the application should have extracted a parent ingredient from the parent asset and added that to the manifest definition. + +- Parent asset: with a manifest store. +- Parent ingredient: generated from that parent asset (hashed and validated) +- Source asset: may be a generated rendition after edits from the parent asset (manifest?) +- Signed output which will include the source asset, and the new manifest store with parent ingredient. + +If there is no parent ingredient defined, and the source has a manifest store, the sdk will generate a parent ingredient from the parent. + +### Remote URLs and embedding + +The default operation of C2PA signing is to embed a C2PA manifest store into an asset. The library also returns the C2PA manifest store so that it can be written to a sidecar or uploaded to a remote service. +- The API supports embedding a remote URL reference into the asset. +- The remote URL is stored in different ways depending on the asset, but is often stored in XMP data. +- The remote URL must be added to the asset before signing so that it can be hashed along with the asset. +- Not all file formats support embedding remote URLs or embedding manifests stores. +- If you embed a manifest or a remote URL, a new asset will be created with the new data embedded. +- If you don't embed, then the original asset is unmodified and there is no need to write one out. +- The remote URL can be set with `builder.remote_url`. +- If embedding is not needed, set the `builder.no_embed` flag to `true`. + + ## Example code The [sdk/examples](https://github.com/contentauth/c2pa-rs/tree/main/sdk/examples) directory contains some minimal example code. The [client/client.rs](https://github.com/contentauth/c2pa-rs/blob/main/sdk/examples/client/client.rs) is the most instructive and provides and example of reading the contents of a manifest store, recursively displaying nested manifests. From e8ca0587a2c300ac2f42074509fa5682879b17dd Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Mon, 18 Nov 2024 14:13:05 -0800 Subject: [PATCH 03/14] Clarify release number --- docs/release-notes.md | 28 ++++++++++++++++------------ docs/usage.md | 22 +++++++++++++++++++++- 2 files changed, 37 insertions(+), 13 deletions(-) diff --git a/docs/release-notes.md b/docs/release-notes.md index 6eb7e93eb..50e453545 100644 --- a/docs/release-notes.md +++ b/docs/release-notes.md @@ -1,12 +1,15 @@ # Release notes -## Version 1.0 +## New API -The version 1.0 release has a new API that replaces the previous methods of reading and writing C2PA data, which are still supported but are deprecated. To use the deprecated API, enable the `v1_api` feature; for example: +The current release has a new API that replaces the previous methods of reading and writing C2PA data, which are still supported but will be deprecated. -``` -c2pa = {version="1.0.0", features=["v1_api"]} -``` +The new API focuses on streaming I/O and supports the following structs: +- [Builder](https://docs.rs/c2pa/latest/c2pa/struct.Builder.html) +- [Reader](https://docs.rs/c2pa/latest/c2pa/struct.Reader.html) +- [ManifestDefinition](https://docs.rs/c2pa/latest/c2pa/struct.ManifestDefinition.html) + +### Goals The goals of this release are to provide a consistent, flexible, well-tested API; specifically: @@ -20,19 +23,20 @@ The goals of this release are to provide a consistent, flexible, well-tested API - Provide a consistent model for setting runtime options. - Keep porting as simple as possible. -The new API focuses on streaming I/O and supports the following structs: -- [Builder](https://docs.rs/c2pa/latest/c2pa/struct.Builder.html) -- [Reader](https://docs.rs/c2pa/latest/c2pa/struct.Reader.html) -- [ManifestDefinition](https://docs.rs/c2pa/latest/c2pa/struct.ManifestDefinition.html) - ### Enabling -To use this API, enable the `unstable_api` feature; for example: +To use the new API, enable the `unstable_api` feature; for example: + +``` +c2pa = {version="0.39.0", features=["unstable_api"]} +``` + +When version 1.0 of the library is released, the new API will become the default, but you will still be able to use the deprecated API by enabling the `v1_api` feature; for example: ``` -c2pa = {version="1.0.0", features=["unstable_api"]} +c2pa = {version="0.39.0", features=["v1_api"]} ``` ## Language binding support diff --git a/docs/usage.md b/docs/usage.md index afd77676d..417857ed5 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -27,7 +27,7 @@ To read or write a manifest file, add the `file_io` dependency to your `Cargo.to Add the `add_thumbnails` dependency to generate thumbnails for JPEG and PNG files. For example: ``` -c2pa = { version = "0.25.0", features = ["file_io", "add_thumbnails"] } +c2pa = { version = "0.39.0", features = ["file_io", "add_thumbnails"] } ``` NOTE: If you are building for WASM, omit the `file_io` dependency. @@ -45,6 +45,26 @@ The Rust library crate provides the following capabilities: * `psxxx_ocsp_stapling_experimental` enables a demonstration feature that attempts to fetch the OCSP data from the OCSP responders listed in the manifest signing certificate. The response becomes part of the manifest and is used to prove the certificate was not revoked at the time of signing. This is only implemented for PS256, PS384 and PS512 signatures and is intended as a demonstration. * `openssl_ffi_mutex` prevents multiple threads from accessing the C OpenSSL library simultaneously. (This library is not re-entrant.) In a multi-threaded process (such as Cargo's test runner), this can lead to unpredictable behavior. +### New API + +### Enabling + + + +The current release has a new API that replaces the previous methods of reading and writing C2PA data, which are still supported but will be deprecated. + +To use the new API, enable the `unstable_api` feature; for example: + +``` +c2pa = {version="0.39.0", features=["unstable_api"]} +``` + +When version 1.0 of the library is released, the new API will become the default, but you will still be able to use the deprecated API by enabling the `v1_api` feature; for example: + +``` +c2pa = {version="0.39.0", features=["v1_api"]} +``` + ### Resource references A resource reference is a superset of a `HashedUri`, which the C2PA specification refers to as both `hashed-uri-map` and `hashed-ext-uri-map`. In some cases either can be used. From 29365f80830df3a2384ad3f3ff6e1fd3119d3d78 Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Mon, 18 Nov 2024 14:54:54 -0800 Subject: [PATCH 04/14] Fix links to other md files --- README.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index c83fece0b..7dc5c26fb 100644 --- a/README.md +++ b/README.md @@ -8,16 +8,16 @@ The **[Coalition for Content Provenance and Authenticity](https://c2pa.org)** (C Additional documentation: -- [Usage](usage.md) -- [Supported formats](supported-formats.md) -- [Release notes](release-notes.md) -- [Testing](testing.md) +- [Usage](docs/usage.md) +- [Supported formats](docs/supported-formats.md) +- [Release notes](docs/release-notes.md) +- [Testing](docs/testing.md) ## Key features -The C2PA Rust library (previously referred to as the "Rust SDK") implements a subset of the [C2PA technical specification](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html). +The C2PA Rust library implements a subset of the [C2PA technical specification](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html). The library enables a desktop, mobile, or embedded application to: * Create and sign C2PA [claims](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_claims) and [manifests](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_manifests). @@ -26,13 +26,15 @@ The library enables a desktop, mobile, or embedded application to: The library supports several common C2PA [assertions](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_c2pa_standard_assertions) and [hard bindings](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_hard_bindings). -For details on what you can do with the library, see [Using the Rust library](usage.md). + + +For details on what you can do with the library, see [Using the Rust library](docs/usage.md). ## State of the project This is a beta release (version 0.x.x) of the project. The minor version number (0.x.0) is incremented when there are breaking API changes, which may happen frequently. -NOTE: The current release includes a new API that replaces old methods of reading and writing C2PA data, which are deprecated. See the [release notes](release-notes.md) for more information. Refer to the [CHANGELOG](https://github.com/contentauth/c2pa-rs/blob/main/CHANGELOG.md) for detailed changes derived from Git commit history. +NOTE: The current release includes a new API that replaces old methods of reading and writing C2PA data, which are deprecated. See the [release notes](docs/release-notes.md) for more information. Refer to the [CHANGELOG](https://github.com/contentauth/c2pa-rs/blob/main/CHANGELOG.md) for detailed changes derived from Git commit history. ### Contributions and feedback From 061c4917804bc5719868ca434a8300a8de48641a Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Tue, 19 Nov 2024 15:00:33 -0800 Subject: [PATCH 05/14] Replace outdated info about PR/commit messages --- CONTRIBUTING.md | 41 ++++++++++++++++++++++++++++++++--------- 1 file changed, 32 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7b2879147..1f21cb7e6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,7 +6,7 @@ Before you start, we ask that you understand the following guidelines. ## Code of conduct -This project adheres to the Adobe [code of conduct](../CODE_OF_CONDUCT.md). By participating, +This project adheres to the Adobe [code of conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to [Grp-opensourceoffice@adobe.com](mailto:Grp-opensourceoffice@adobe.com). @@ -18,14 +18,13 @@ consensus around project direction and issue solutions within issue threads ### Current areas of work -The Adobe CAI team has been using this crate as the foundation of Adobe's Content Authenticity Initiative-related products and services since late 2020. As we shift toward making this crate available for open usage, we're aware that there is quite a bit of work to do to create what we'd feel comfortable calling a 1.0 release. We've decided to err on the side of releasing earlier so that people can experiment with it and give us feedback. - -We expect to do work on a number of areas in the next few months while we remain in prerelease (0.x) versions. Some broad categories of work (and thus things you might expect to change) are: +The Adobe CAI team has been using this crate as the foundation of Adobe's Content Authenticity Initiative-related products and services since late 2020. We're aware that there is quite a bit of work to do for a robust 1.0 release. +Some broad categories of work (and thus things you might expect to change) are: * We'll be reviewing and refining our APIs for ease of use and comprehension. We'd appreciate feedback on areas that you find confusing or unnecessarily difficult. * We'll also be reviewing our APIs for compliance with Rust community best practices. There are some areas (for example, use of public fields and how we take ownership vs references) where we know some work is required. * Our documentation is incomplete. We'll be working on refining the documentation. -* Our testing infrastructure is incomplete. We'll be working on improving test coverage, memory efficiency, and performance benchmarks. +* Our testing infrastructure is incomplete. We'll be working on improving test coverage, memory efficiency, and performance benchmarks. See [docs/testing.md] for more details. ### Desired feedback @@ -61,11 +60,35 @@ This will give us an opportunity to discuss API design and avoid duplicate effor ### Pull request titles -The build process automatically adds a pull request (PR) to the [CHANGELOG](CHANGELOG.md) unless the title of the PR begins with `(IGNORE)`. Start PR titles with `(IGNORE)` for minor documentation updates and other trivial fixes that you want to specifically exclude from the CHANGELOG. +The build process automatically adds a pull request (PR) to the [CHANGELOG](CHANGELOG.md) unless the title of the PR begins with `(IGNORE)`. + +Titles of pull requests that target a long-lived branch such as _main_ or a release-specific branch should follow [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/#specification). This means that the first word of the pull request title should be one of the following: + + * `build` + * `chore` + * `ci` + * `docs` + * `feat` + * `fix` + * `perf` + * `refactor` + * `revert` + * `style` + * `test` + +Optionally, but preferred, a scope can be added in parentheses after the type. The scope should be the name of the module or component that the commit affects. For example, `feat(api): Introduce a new API to validate 1.0 claims`. + +If more detail is warranted, add a blank line and then continue with sentences (these sentences should be punctuated as such) and paragraphs as needed to provide that detail. There is no need to word-wrap this message. + +For example: + +```text +feat(api): Introduce a new API to validate 1.0 claims + +Repurpose existing v2 API for 0.8 compatibility (read: no validation) mode. +``` -Additionally, the build process takes specific actions if the title of a PR begins with certain special strings: -- `(MINOR)`: Increments the minor version, per [semantic versioning](https://semver.org/) convention. **IMPORTANT:** This flag should be used for any API change that breaks compatibility with previous releases while this crate is in prerelease (version 0.x) status. -- `(MAJOR)`: Increments the major version number, per [semantic versioning](https://semver.org/) convention. +The conventional commit message requirement does not apply to individual commits within a pull request, provided that those commits will be squashed when the PR is merged and the resulting squash commit does follow the conventional commit requirement. This may require the person merging the PR to verify the commit message syntax when performing the squash merge. TIP: For single-commit PRs, ensure the commit message conforms to the conventional commit requirement, since by default that will also be the title of the PR. ## From contributor to committer From 9913a65f3fda7b5565ca737b4b8956de5fae079e Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Tue, 19 Nov 2024 15:09:11 -0800 Subject: [PATCH 06/14] More edits and reorg --- CONTRIBUTING.md | 6 ++++-- README.md | 24 ++--------------------- docs/project-contributions.md | 36 +++++++++++++++++++++++++++++++++++ docs/release-notes.md | 2 ++ docs/testing.md | 12 ------------ 5 files changed, 44 insertions(+), 36 deletions(-) create mode 100644 docs/project-contributions.md delete mode 100644 docs/testing.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1f21cb7e6..740ebc200 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -46,7 +46,7 @@ as part of the project. [Sign our CLA](https://opensource.adobe.com/cla.html). Y only need to submit an Adobe CLA one time, so if you have submitted one previously, you are good to go! -## Code reviews +### Code reviews All submissions should come in the form of pull requests and need to be reviewed by project committers. Read [GitHub's pull request documentation](https://help.github.com/articles/about-pull-requests/) @@ -88,7 +88,9 @@ feat(api): Introduce a new API to validate 1.0 claims Repurpose existing v2 API for 0.8 compatibility (read: no validation) mode. ``` -The conventional commit message requirement does not apply to individual commits within a pull request, provided that those commits will be squashed when the PR is merged and the resulting squash commit does follow the conventional commit requirement. This may require the person merging the PR to verify the commit message syntax when performing the squash merge. TIP: For single-commit PRs, ensure the commit message conforms to the conventional commit requirement, since by default that will also be the title of the PR. +The conventional commit message requirement does not apply to individual commits within a pull request, provided that those commits will be squashed when the PR is merged and the resulting squash commit does follow the conventional commit requirement. This may require the person merging the PR to verify the commit message syntax when performing the squash merge. + +TIP: For single-commit PRs, ensure the commit message conforms to the conventional commit requirement, since by default that will also be the title of the PR. ## From contributor to committer diff --git a/README.md b/README.md index 7dc5c26fb..346940787 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ Additional documentation: - [Usage](docs/usage.md) - [Supported formats](docs/supported-formats.md) - [Release notes](docs/release-notes.md) -- [Testing](docs/testing.md) +- [Contributing to the project](docs/project-contributions.md) @@ -26,15 +26,13 @@ The library enables a desktop, mobile, or embedded application to: The library supports several common C2PA [assertions](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_c2pa_standard_assertions) and [hard bindings](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_hard_bindings). - - For details on what you can do with the library, see [Using the Rust library](docs/usage.md). ## State of the project This is a beta release (version 0.x.x) of the project. The minor version number (0.x.0) is incremented when there are breaking API changes, which may happen frequently. -NOTE: The current release includes a new API that replaces old methods of reading and writing C2PA data, which are deprecated. See the [release notes](docs/release-notes.md) for more information. Refer to the [CHANGELOG](https://github.com/contentauth/c2pa-rs/blob/main/CHANGELOG.md) for detailed changes derived from Git commit history. +NOTE: The current release includes a new API that replaces old methods of reading and writing C2PA data, which are deprecated. See the [release notes](docs/release-notes.md) for more information. ### Contributions and feedback @@ -46,24 +44,6 @@ The `c2pa` crate is distributed under the terms of both the [MIT license](https: Some components and dependent crates are licensed under different terms; please check their licenses for details. -## Nightly builds - -In most cases, you should depend on this crate as published via [crates.io](https://crates.io/crates/c2pa). - -The Adobe team produces nightly snapshots of this crate via a `nightly` branch, which we use for testing the impact of pending changes to upstream dependencies. - -You may wish to use these builds for your own testing ahead of our releases, you may include the library via the following `Cargo.toml` entry: - -```toml -c2pa = { git = "https://github.com/contentauth/c2pa-rs.git", branch = "nightly", features = [...]} -``` - -Commits in this branch have a modified `sdk/Cargo.toml` entry which includes a version number similar to the following: - -```toml -version = "0.25.3-nightly+2023-08-28-2f33ab3" -``` -Please note that there is no formal support for code from a nightly release, but if you become aware of any issues, we would appreciate a bug report including this version number. diff --git a/docs/project-contributions.md b/docs/project-contributions.md new file mode 100644 index 000000000..809036c87 --- /dev/null +++ b/docs/project-contributions.md @@ -0,0 +1,36 @@ +# Contributing to the project + +The information in this page is primarily for those who wish to contribute to the c2pa-rs library project itself, rather than those who simply wish to use it in an application. For general contribution guidelines, see [CONTRIBUTING.md](../CONTRIBUTING.md). + +## Nightly builds + +In most cases, you should depend on this crate as published via [crates.io](https://crates.io/crates/c2pa). + +The Adobe team produces nightly snapshots of this crate via a `nightly` branch to test the impact of pending changes to upstream dependencies. + +To use these builds for your own testing ahead of our releases, include the library by adding the following `Cargo.toml` entry: + +```toml +c2pa = { git = "https://github.com/contentauth/c2pa-rs.git", branch = "nightly", features = [...]} +``` + +Commits in this branch have a modified `sdk/Cargo.toml` entry which includes a version number similar to the following: + +```toml +version = "0.25.3-nightly+2023-08-28-2f33ab3" +``` + +There is no formal support for code from a nightly release, but if you become aware of any issues, we would appreciate a bug report including this version number. + +## Testing + +The current set of unit tests are helpful but many are out of date. We need a more comprehensive set of tests: The plan is to build a solid set of tests on the new streams-based API, then build everything else on that. + +There is an open issue to generate test images from clean non-c2pa images. When images are checked in with manifests, they rapidly get out of date. A set of older manifests and third-party images is still needed for testing, but they need not be in the SDK. + +We need: + +- A test assets folder with one public domain image in each asset format we support. +- A tool, like `make_test_images`, to generate different kinds of manifests for testing. We should maintain an archive of the manifest_store JSON generated by the previous build and compare the old build with the new ones for any significant deltas. The tool needs to ignore changes due to new GUIDs, dates, and JSON object field order. + +The `make_test_images` crate has been updated to do this by default. We may make a policy to run the test comparison nightly. \ No newline at end of file diff --git a/docs/release-notes.md b/docs/release-notes.md index 50e453545..5aa0439bc 100644 --- a/docs/release-notes.md +++ b/docs/release-notes.md @@ -1,5 +1,7 @@ # Release notes +Refer to the [CHANGELOG](https://github.com/contentauth/c2pa-rs/blob/main/CHANGELOG.md) for detailed changes derived from Git commit history. + ## New API The current release has a new API that replaces the previous methods of reading and writing C2PA data, which are still supported but will be deprecated. diff --git a/docs/testing.md b/docs/testing.md deleted file mode 100644 index d53e2c147..000000000 --- a/docs/testing.md +++ /dev/null @@ -1,12 +0,0 @@ -# Testing - -The current set of unit tests are helpful but many are out of date. We need a more comprehensive set of tests for the Rust library. The plan is to build a solid set of tests on the new streams-based API, then build everything else on that. - -There is an open issue to generate test images from clean non-c2pa images. When images are checked in with manifests, they rapidly get out of date. A set of older manifests and third-party images is still needed for testing, but they need not be in the SDK. - -We need: - -- A test assets folder with one public domain image in each asset format we support. -- A tool, like `make_test_images`, to generate different kinds of manifests for testing. We should maintain an archive of the manifest_store JSON generated by the previous build and compare the old build with the new ones for any significant deltas. The tool needs to ignore changes due to new GUIDs, dates, and JSON object field order. - -The `make_test_images` crate has been updated to do this by default. We may make a policy to run the test comparison nightly. \ No newline at end of file From 8fb9c210cf6408da1b16a2d85dc68fec60df8a9e Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Wed, 20 Nov 2024 09:30:55 -0800 Subject: [PATCH 07/14] Update CONTRIBUTING.md --- CONTRIBUTING.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 740ebc200..0369f43b0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,8 +18,8 @@ consensus around project direction and issue solutions within issue threads ### Current areas of work -The Adobe CAI team has been using this crate as the foundation of Adobe's Content Authenticity Initiative-related products and services since late 2020. We're aware that there is quite a bit of work to do for a robust 1.0 release. -Some broad categories of work (and thus things you might expect to change) are: +The Adobe CAI team has been using this crate as the foundation of Adobe's Content Authenticity Initiative-related products and services since late 2020. +Groad categories of work (and thus things you might expect to change) are: * We'll be reviewing and refining our APIs for ease of use and comprehension. We'd appreciate feedback on areas that you find confusing or unnecessarily difficult. * We'll also be reviewing our APIs for compliance with Rust community best practices. There are some areas (for example, use of public fields and how we take ownership vs references) where we know some work is required. @@ -60,8 +60,6 @@ This will give us an opportunity to discuss API design and avoid duplicate effor ### Pull request titles -The build process automatically adds a pull request (PR) to the [CHANGELOG](CHANGELOG.md) unless the title of the PR begins with `(IGNORE)`. - Titles of pull requests that target a long-lived branch such as _main_ or a release-specific branch should follow [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/#specification). This means that the first word of the pull request title should be one of the following: * `build` From b2b5ea73f1c515d4880329e1581e990add9a515c Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Wed, 20 Nov 2024 11:24:29 -0800 Subject: [PATCH 08/14] add xref to doc site --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 346940787..4da20bb6c 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,8 @@ Additional documentation: - [Release notes](docs/release-notes.md) - [Contributing to the project](docs/project-contributions.md) +For additional documentation, please see the [CAI open-source SDK documentation](https://opensource.contentauthenticity.org/docs/introduction/). + ## Key features From 579eb1f39a4ff008120018f55bd1f5bb63d492e5 Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Wed, 20 Nov 2024 13:22:56 -0800 Subject: [PATCH 09/14] Link to supported formats --- README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 4da20bb6c..f7131a6d3 100644 --- a/README.md +++ b/README.md @@ -23,8 +23,8 @@ The C2PA Rust library implements a subset of the [C2PA technical specification]( The library enables a desktop, mobile, or embedded application to: * Create and sign C2PA [claims](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_claims) and [manifests](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_manifests). -* Embed manifests in certain file formats. -* Parse and validate manifests found in certain file formats. +* Embed manifests in [supported file formats](docs/supported-formats.md). +* Parse and validate manifests found in [supported file formats](docs/supported-formats.md). The library supports several common C2PA [assertions](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_c2pa_standard_assertions) and [hard bindings](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_hard_bindings). @@ -34,11 +34,13 @@ For details on what you can do with the library, see [Using the Rust library](do This is a beta release (version 0.x.x) of the project. The minor version number (0.x.0) is incremented when there are breaking API changes, which may happen frequently. +### New API + NOTE: The current release includes a new API that replaces old methods of reading and writing C2PA data, which are deprecated. See the [release notes](docs/release-notes.md) for more information. ### Contributions and feedback -We welcome contributions to this project. For information on contributing, providing feedback, and about ongoing work, see [Contributing](https://github.com/contentauth/c2pa-rs/blob/main/CONTRIBUTING.md). +We welcome contributions to this project. For information on contributing, providing feedback, and about ongoing work, see [Contributing](https://github.com/contentauth/c2pa-rs/blob/main/CONTRIBUTING.md). For additional information on nightly builds and testing, see [Contributing to the project](docs/project-contributions.md). ## License From 029abc3b23fec746dcdd534ff325336bbae56564 Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Thu, 21 Nov 2024 13:49:40 -0800 Subject: [PATCH 10/14] footnotes for supported formats, add pdf read support --- docs/supported-formats.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/supported-formats.md b/docs/supported-formats.md index a69c1568d..e1a27f8a9 100644 --- a/docs/supported-formats.md +++ b/docs/supported-formats.md @@ -16,13 +16,17 @@ Other libraries in the SDK support the same set of formats, unless noted otherwi | `jpg`, `jpeg` | `image/jpeg` | | `m4a` | `audio/mp4` | | `mp3` | `audio/mpeg` | - | `mp4` | `video/mp4`, `application/mp4` | + | `mp4` | `video/mp4`, `application/mp4` * | | `mov` | `video/quicktime` | + | `pdf` | `application/pdf` ** | | `png` | `image/png` | | `svg` | `image/svg+xml` | | `tif`,`tiff` | `image/tiff` | | `wav` | `audio/wav` | | `webp` | `image/webp` | +NOTES: +* Fragmented MP4 is not yet supported. +** Read-only From 0dc930119d302221b5ab850a6e4c03d3d391a8a4 Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Fri, 22 Nov 2024 14:47:36 -0800 Subject: [PATCH 11/14] clarify fragmented MP4 support --- docs/supported-formats.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/supported-formats.md b/docs/supported-formats.md index e1a27f8a9..62b219c0d 100644 --- a/docs/supported-formats.md +++ b/docs/supported-formats.md @@ -26,7 +26,7 @@ Other libraries in the SDK support the same set of formats, unless noted otherwi | `webp` | `image/webp` | NOTES: -* Fragmented MP4 is not yet supported. +* Fragmented MP4 (DASH) is supported only for file-based operations from the Rust library. ** Read-only From 55817f728766f6ff3e878cf075e7eb5b6f97ed63 Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Mon, 25 Nov 2024 15:23:45 -0800 Subject: [PATCH 12/14] formatting --- docs/supported-formats.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/supported-formats.md b/docs/supported-formats.md index 62b219c0d..2c1d45698 100644 --- a/docs/supported-formats.md +++ b/docs/supported-formats.md @@ -1,7 +1,6 @@ # Supported file formats -The following table summarizes the media (asset) file formats that the CAI Rust library supports. -Other libraries in the SDK support the same set of formats, unless noted otherwise. +The following table summarizes the supported media (asset) file formats. This information is based on what the Rust library supports; other libraries in the SDK support the same formats, unless noted otherwise. | Extensions | MIME type | @@ -27,6 +26,6 @@ Other libraries in the SDK support the same set of formats, unless noted otherwi NOTES: * Fragmented MP4 (DASH) is supported only for file-based operations from the Rust library. - +
** Read-only From ae56e3ce55b04379060ef8e7b492cc4b00a465de Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Mon, 25 Nov 2024 18:30:13 -0800 Subject: [PATCH 13/14] Change GH only blurb --- README.md | 10 ++-------- docs/supported-formats.md | 3 +-- 2 files changed, 3 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index f7131a6d3..3b8aadb1a 100644 --- a/README.md +++ b/README.md @@ -6,20 +6,18 @@ The **[Coalition for Content Provenance and Authenticity](https://c2pa.org)** (C2PA) addresses the prevalence of misleading information online through the development of technical standards for certifying the source and history (or provenance) of media content. The C2PA Rust library is part of the [Content Authenticity Initiative](https://contentauthenticity.org) open-source SDK. -Additional documentation: +For the best experience, read the docs on the [CAI Open Source SDK documentation website](https://opensource.contentauthenticity.org/docs/c2pa-node/). Some additional documentation for this repository is also available on GitHub: - [Usage](docs/usage.md) - [Supported formats](docs/supported-formats.md) - [Release notes](docs/release-notes.md) - [Contributing to the project](docs/project-contributions.md) -For additional documentation, please see the [CAI open-source SDK documentation](https://opensource.contentauthenticity.org/docs/introduction/). - ## Key features -The C2PA Rust library implements a subset of the [C2PA technical specification](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html). +[The c2pa-rs repository](https://github.com/contentauth/c2pa-rs) implements a subset of the [C2PA technical specification](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html) in the Rust programming language. The library enables a desktop, mobile, or embedded application to: * Create and sign C2PA [claims](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_claims) and [manifests](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_manifests). @@ -47,7 +45,3 @@ We welcome contributions to this project. For information on contributing, prov The `c2pa` crate is distributed under the terms of both the [MIT license](https://github.com/contentauth/c2pa-rs/blob/main/LICENSE-MIT) and the [Apache License (Version 2.0)](https://github.com/contentauth/c2pa-rs/blob/main/LICENSE-APACHE). Some components and dependent crates are licensed under different terms; please check their licenses for details. - - - - diff --git a/docs/supported-formats.md b/docs/supported-formats.md index 2c1d45698..f526446e2 100644 --- a/docs/supported-formats.md +++ b/docs/supported-formats.md @@ -1,6 +1,6 @@ # Supported file formats -The following table summarizes the supported media (asset) file formats. This information is based on what the Rust library supports; other libraries in the SDK support the same formats, unless noted otherwise. +The following table summarizes the supported media (asset) file formats. This information is based on what the Rust library supports; other libraries in the SDK support the same formats unless noted otherwise. | Extensions | MIME type | @@ -28,4 +28,3 @@ NOTES: * Fragmented MP4 (DASH) is supported only for file-based operations from the Rust library.
** Read-only - From fa3455ab22bd062e0e74e38ef097bd47c235e5ee Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Mon, 2 Dec 2024 13:13:45 -0800 Subject: [PATCH 14/14] clarify conv commits requirements --- CONTRIBUTING.md | 20 +++++++------------- 1 file changed, 7 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0369f43b0..60f5baae8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -60,19 +60,13 @@ This will give us an opportunity to discuss API design and avoid duplicate effor ### Pull request titles -Titles of pull requests that target a long-lived branch such as _main_ or a release-specific branch should follow [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/#specification). This means that the first word of the pull request title should be one of the following: - - * `build` - * `chore` - * `ci` - * `docs` - * `feat` - * `fix` - * `perf` - * `refactor` - * `revert` - * `style` - * `test` +Titles of pull requests that target a long-lived branch such as _main_ or a release-specific branch should follow [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/#specification). The repository's [commit lint rules](https://github.com/contentauth/c2pa-rs/blob/main/.commitlintrc.yml) require that the first word of the pull request title must be one of the following: + +- `fix` +- `feat` +- `chore` +- `update` +- `doc` Optionally, but preferred, a scope can be added in parentheses after the type. The scope should be the name of the module or component that the commit affects. For example, `feat(api): Introduce a new API to validate 1.0 claims`.