diff --git a/docs/technical-faqs/faqs-to-review.md b/docs/technical-faqs/faqs-to-review.md new file mode 100644 index 00000000..31e91935 --- /dev/null +++ b/docs/technical-faqs/faqs-to-review.md @@ -0,0 +1,134 @@ +--- +hide_table_of_contents: true +--- + +import TOCInline from '@theme/TOCInline'; + +# Technical FAQ topics for review + +These editorial notes are not confirmed FAQ answers. Verify each topic +before publishing guidance. + + + +### Verification website reports invalid content that the SDK reports as trusted + +**Candidate question:** Why does a verification website reject an asset +that the SDK reports as trusted? + +The user reported that the SDK returned successful validation results and +a `Trusted` validation state. Support suspected incomplete website support +for update manifests or timestamp assertions and recommended checking with +the SDK or C2PA Tool. No website fix or support timeline was confirmed. + +Before publication: + +- Identify the affected verification website and version, if available. +- Confirm its current support for update manifests and timestamp assertions. +- Reproduce any remaining discrepancy with the same asset and trust settings. +- Do not present incomplete website support as the cause of every validation + discrepancy. + +Sources: + +- [Initial guidance; April 7, 2026](https://discord.com/channels/983153151341371422/983153550018371595/1491238678410821784) +- [SDK validation result; April 16, 2026](https://discord.com/channels/983153151341371422/983153550018371595/1494485332010209350) +- [Pending website support information; April 20, 2026](https://discord.com/channels/983153151341371422/983153550018371595/1495872312413655162) + +### Server-side assertion validation with a remote signer + +**Candidate question:** How can a remote signer validate assertion values +before signing without receiving the asset bytes? + +Support suggested sending serialized assertions with the claim, checking +their hashes against the claim, and inspecting their contents. The user +reported difficulties accessing assertion salts through `AsyncSigner`. +No complete, confirmed implementation was provided. + +The discussion also distinguished assertion integrity from the broader +security architecture of a distributed implementation. Questions about +whether the proposed architecture satisfied conformance requirements were +referred to the C2PA conformance program. + +Before publication: + +- Confirm the current APIs for accessing serialized assertions and salts. +- Develop and test a complete example of server-side assertion validation. +- Distinguish hash integrity checks from validation of assertion values. +- Obtain authoritative guidance on the applicable conformance requirements; + do not infer that client authentication alone is sufficient. + +Sources: + +- [Proposed approach; August 10, 2026](https://discord.com/channels/983153151341371422/983153550018371595/1536422380207996989) +- [API limitations; August 11, 2026](https://discord.com/channels/983153151341371422/983153550018371595/1536634968212774962) +- [Security architecture; August 11, 2026](https://discord.com/channels/983153151341371422/983153550018371595/1536713305916440648) +- [Conformance referral; August 17, 2026](https://discord.com/channels/983153151341371422/983153550018371595/1538923231476457533) + +### Rust SDK 1.0 release timeline + +**Candidate question:** When will the Rust SDK reach 1.0? + +On June 8, 2026, support said the team was not ready to share a timeline. +This is a dated roadmap response, not a permanent FAQ answer. + +Before publication, check current release information and obtain an +approved roadmap statement from the team. + +Source: [June 8, 2026](https://discord.com/channels/983153151341371422/983153550018371595/1513639744167219280) + +### Build failure caused by a yanked dependency + +**Candidate question:** What should I do about the yanked dependency +build failure? + +An October 16, 2026, announcement directed affected source builds to +upgrade to `c2pa-rs` 0.91.3 because of a yanked `zip` dependency. The +announcement named `zip` 8.6.0 and described 0.91.2 and earlier SDK +versions as affected. These details have not been independently verified. + +Before publication: + +- Verify the dependency version and the exact affected SDK releases. +- Confirm the first release containing the dependency update. +- Check how existing lockfiles affect reproducibility. +- Prefer a dated troubleshooting notice over an evergreen FAQ entry. + +Source: [October 16, 2026](https://discord.com/channels/983153151341371422/983153550018371595/1560738950807687341) + +### Ingredient digital source type and remote-signer certificate chains + +**Candidate questions:** + +- Does the SDK support the ingredient `digitalSourceType` field? +- Has the remote signer's PEM certificate-chain parsing issue been fixed? + +A contributor reported missing ingredient `digitalSourceType` support and +linked [PR #2078](https://github.com/contentauth/c2pa-rs/pull/2078) and +[issue #2077](https://github.com/contentauth/c2pa-rs/issues/2077). +The contributor also linked +[PR #2075](https://github.com/contentauth/c2pa-rs/pull/2075) for parsing a +remote signer's PEM certificate chain into individual DER certificates. +The export does not confirm merge or release status for either fix. + +Before publication, verify each PR's status, identify the first release +containing the change, and test a minimal example of the reported behavior. +Treat these as separate FAQ entries if both remain useful. + +Sources: + +- [Ingredient field; May 4, 2026](https://discord.com/channels/983153151341371422/983153550018371595/1500953348722131055) +- [Certificate-chain parsing; May 4, 2026](https://discord.com/channels/983153151341371422/983153550018371595/1500953982431133827) + +### Building the C SDK for 32-bit Windows + +**Candidate question:** How do I build the C SDK for 32-bit Windows? + +A user reported receiving an x64 DLL when attempting to build the C SDK +for Win32 x86. No resolution appears in the export. The later resolution +of a C2PA Tool version mismatch does not resolve this separate build issue. + +Before publication, confirm supported targets and toolchain requirements, +reproduce the build, and verify the architecture of the resulting DLL. + +Source: [April 21, 2026](https://discord.com/channels/983153151341371422/983153550018371595/1496248252767670272) diff --git a/docs/technical-faqs/index.md b/docs/technical-faqs/index.md new file mode 100644 index 00000000..a20ddf9f --- /dev/null +++ b/docs/technical-faqs/index.md @@ -0,0 +1,21 @@ +--- +hide_table_of_contents: true +--- + +# Technical FAQs + +- [General FAQs](./tech-faq-general.md) +- [Rust library FAQs](./tech-faq-rust.md) +- [C2PA Tool FAQs](./tech-faq-c2pa-tool.md) +- [Node.js library FAQs](./tech-faq-node.md) +- [Claim-signing certificate FAQs](./tech-faq-certificates.md) +- [CAWG identity FAQs](./tech-faq-cawg.md) +- [C2PA conformance FAQs](./tech-faq-conformance.md) + +These FAQs are derived from discussions in the [public CAI Discord server](https://discord.gg/CAI) from the latter part of 2026. + +Always check the version of the library that you're using and if possible use the latest version to get the latest features anb bug fixes. + +:::note +Links to source Discord messages require a Discord account and joining the [public CAI Discord server](https://discord.gg/CAI). +::: diff --git a/docs/technical-faqs/tech-faq-c2pa-tool.md b/docs/technical-faqs/tech-faq-c2pa-tool.md new file mode 100644 index 00000000..1b230496 --- /dev/null +++ b/docs/technical-faqs/tech-faq-c2pa-tool.md @@ -0,0 +1,192 @@ +--- +hide_table_of_contents: true +--- + +import TOCInline from '@theme/TOCInline'; + +# C2PA Tool FAQs + + + +### How can I inspect a file locally using C2PA Tool? + +Use the open-source C2PA Tool CLI to inspect a file on your own machine: + +```sh +c2patool file.jpg --detailed +``` + +This avoids uploading the asset to a web inspection service. It is not a +promise that every configuration or operation is network-free; for example, +the trust initialization command fetches trust lists. Local +inspection also does not by itself establish that the signer is trusted +or that the depicted content is true. + +Source: [Local CLI inspection command; September 11, 2026](https://discord.com/channels/983153151341371422/986451330992320512/1548138360139419719) + +### How do I load trust lists with C2PA Tool? + +You have to initialize trust lists explicitly. Earlier versions required supplying trust +anchors through settings or the command line. Use `c2patool init trust` to fetch or update trust lists and store them for future calls: + +```sh +c2patool init trust +``` + +Use a raw PEM URL when supplying a trust-anchor link. + +For more control, pass a settings file with `--settings`; TOML settings are +passed through to the SDK. Supply the concatenated CA and TSA lists when needed to include TSA intermediate certificates. +Trust sidecars are loaded automatically on subsequent runs from the same +directory as the settings file. + +For ingredient validation during signing, configure both the C2PA Trust List +and C2PA TSA Trust List. + +Sources: + +- [Explicit trust configuration; April 1, 2026](https://discord.com/channels/983153151341371422/983153390781616159/1488985307343884348) +- [Trust initialization; June 19, 2026](https://discord.com/channels/983153151341371422/983153390781616159/1517556047324250223) +- [Ingredient and timestamp trust; May 27, 2026](https://discord.com/channels/983153151341371422/983153390781616159/1509239917262405742) +- [Raw PEM URL; August 6, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1534942946212708522) +- [Initialization command; August 6, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1534943626499719369) +- [Settings option; August 6, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1534945015598678176) +- [Persistence and concatenated lists; August 6, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1534995351101116646) + +### Does a new manifest automatically inherit its parent's title? + +No. The `parentOf` ingredient's title is not automatically assigned to the +new claim's `dc:title`. Without an explicit title in the manifest definition, +the output filename is used. + +Set the desired title in the new manifest definition rather than relying on +inheritance. This sets the active manifest's title; changing an ingredient's +title is a separate operation. + +Sources: + +- [Default title behavior; April 7, 2026](https://discord.com/channels/983153151341371422/983153390781616159/1491244347075727431) +- [Explicit title confirmation; April 30, 2026](https://discord.com/channels/983153151341371422/983153390781616159/1499462978687209482) + +### How can I override an ingredient's title? + +Export a signed asset as an ingredient using the `--ingredient` option. +The resulting folder contains ingredient JSON, a thumbnail, and the manifest binary. Edit the title in the ingredient JSON, then reference the folder through `ingredient_paths` in the new manifest definition like this: + +```json +"ingredient_paths": ["./ingredient-folder"] +``` + +Sources: + +- [Ingredient export and title workflow; April 30, 2026](https://discord.com/channels/983153151341371422/983153390781616159/1499513543291305995) +- [Successful result; May 1, 2026](https://discord.com/channels/983153151341371422/983153390781616159/1499846501948456980) + +### Does the overall validation state describe only the active manifest? + +No. `validation_state` also considers ingredient deltas, so an ingredient +failure can affect the overall state. + +For the active manifest alone, inspect the success, informational, and +failure arrays in `validation_results.activeManifest`. Do not interpret +an aggregate `Invalid` result as proof that the active manifest itself +has a signature failure. + +Display each manifest's state independently and distinguish +valid-but-untrusted manifests from trusted ones. That is +presentation guidance, not a rule that cryptographic validity establishes +signer trust. + +Sources: + +- [Aggregate state clarification; May 27, 2026](https://discord.com/channels/983153151341371422/983153390781616159/1509250331320778864) +- [Active-manifest results; May 28, 2026](https://discord.com/channels/983153151341371422/983153390781616159/1509555410921590835) +- [Ingredient deltas; May 28, 2026](https://discord.com/channels/983153151341371422/983153390781616159/1509555776585465907) +- [Per-manifest presentation guidance; May 27, 2026](https://discord.com/channels/983153151341371422/983153390781616159/1509374914510196737) + +### How do I supply my own thumbnail? + +Add a `thumbnail` object to the manifest definition. Its `identifier` is +a file path relative to the manifest +definition file: + +```json +"thumbnail": { + "format": "image/jpeg", + "identifier": "thumbnail.jpg" +} +``` + +This is a field excerpt to include in a complete manifest definition. +For example: + +```sh +c2patool sample.mp4 -m manifest.json -o sample-signed.mp4 +``` + +Use the same approach to define ingredient thumbnails. This +provides an explicit thumbnail; it does not explain or promise automatic +thumbnail generation for every input format. + +Source: [custom thumbnails and relative paths, August 31, 2026](https://discord.com/channels/983153151341371422/983153390781616159/1543975786468352150) + +### How can I sign a TIFF sample and configure created assertions? + +C2PA Tool supports reading and writing TIFF files. For example: + +```sh +c2patool sample.tiff \ + --settings settings.toml \ + --manifest manifest.json \ + --output signed.tiff +``` + +For that command, the source asset becomes a `parentOf` +ingredient and the tool automatically adds the `c2pa.opened` action. +You can omit settings when using the default key and certificate, but do +not assume those defaults are trusted or qualify a product for conformance. + +When the implementation needs to designate created rather than gathered +assertions, use settings such as: + +```toml +[builder] + +created_assertion_labels = [ + "c2pa.actions", + "c2pa.ingredient" +] +``` + +This is just an example. Select the assertions appropriate to the implementation. + +Sources: + +- [TIFF signing command and defaults; September 15, 2026](https://discord.com/channels/983153151341371422/983153390781616159/1549488757898616973) +- [Created assertion settings; September 15, 2026](https://discord.com/channels/983153151341371422/983153390781616159/1549489530598588417) + +### Why does C2PA Tool behave differently when launched by my application versus on the command-line? + +Check the **actual executable and version** your application launches, +rather than only the version available in your terminal. + +For example in the reported case, the application launched C2PA Tool **0.26.1**, +although the user expected **0.26.41**. Launching 0.26.41 resolved the +missing timestamp assertion. + +Source: [confirmed resolution, April 22, 2026](https://discord.com/channels/983153151341371422/983153550018371595/1496644840786624614) + +### Can I create sidecar manifests for unsupported file types? + +Yes. To read the asset with its sidecar, use: + +```sh +c2patool file.obj --external-manifest file.c2pa +``` + +Sources: + +- [Implementation; September 16, 2026](https://discord.com/channels/983153151341371422/983153550018371595/1549892485080293416) +- [Read command; September 16, 2026](https://discord.com/channels/983153151341371422/983153550018371595/1549898982988455988) +- [User confirmation; September 17, 2026](https://discord.com/channels/983153151341371422/983153550018371595/1550145681090412695) + diff --git a/docs/technical-faqs/tech-faq-cawg.md b/docs/technical-faqs/tech-faq-cawg.md new file mode 100644 index 00000000..73336d1d --- /dev/null +++ b/docs/technical-faqs/tech-faq-cawg.md @@ -0,0 +1,126 @@ +--- +hide_table_of_contents: true +--- + +import TOCInline from '@theme/TOCInline'; + +# CAWG identity FAQs + + + +### Does c2pa-rs support identity claims aggregation? + +Yes. `c2pa-rs` supports CAWG identity claims aggregation (ICA), with an +implementation also using the Node bindings. You still need to provide an aggregation service that returns the COSE-signed verifiable credential; SDK support does not +supply that service. + +See the Rust [identity module](https://github.com/contentauth/c2pa-rs/tree/main/sdk/src/identity) +and its [tests](https://github.com/contentauth/c2pa-rs/tree/main/sdk/src/identity/tests). +Equivalent ICA support in the Swift or Python SDKs is not confirmed here. + +Source: [Rust and Node ICA support and service responsibilities; August 14, 2026](https://discord.com/channels/983153151341371422/1273777445551603714/1537963403539390495) + +### How can I inspect CAWG certificate fields when common_name is missing? + +Use crJSON to inspect certificate issuer and subject information when +the ordinary CAWG signature report omits `common_name`: + +```sh +c2patool signed.jpg --crjson +``` + +The example places these fields under `cawg.identity.signature.certificateInfo`, including `issuer`, `subject`, and certificate validity dates. The common name is visible through `--crjson`. + +This is a reporting workaround for the issue observed in May 2026, not +evidence that the missing field has since been fixed. Reading a certificate +subject also does not establish that its identity is trusted. + +Sources: + +- [CrJSON workaround; May 8, 2026](https://discord.com/channels/983153151341371422/1273777445551603714/1502369680118124555) +- [Certificate field structure; May 8, 2026](https://discord.com/channels/983153151341371422/1273777445551603714/1502369868396367913) +- [Workaround confirmation; May 8, 2026](https://discord.com/channels/983153151341371422/1273777445551603714/1502377614436995162) + +### Does a CAWG identity certificate need to chain to the C2PA Trust List? + +No. The C2PA Trust List contains roots for claim-signing certificates issued to generator +products that have passed C2PA Conformance. CAWG X.509 identity certificates +use a different model. + +As of August 2026, CAWG's **interim** model used the Mozilla Root Store and +IPTC verified news publisher lists. See the +[CAWG identity 1.3 X.509 trust model](https://cawg.io/identity/1.3/#_trust_model_for_x_509_certificates), +the [Mozilla email-trust roots](https://ccadb.my.salesforce-sites.com/mozilla/IncludedRootsPEMTxt?TrustBitsInclude=Email) and the IPTC [end-entity](https://trust.iptc.org/end-entity-list.pem) and +[anchor](https://trust.iptc.org/anchor-list.pem) lists. + +Do not equate C2PA product trust with CAWG identity trust, or treat the +historical interim model as an independently verified current policy. + +S/MIME certificates are a common CAWG X.509 choice, including +individual-validated, sponsor-validated, and +organization-validated certificates. Having a government-issued identity +certificate does not by itself answer whether it meets CAWG's requirements; +check the CAWG X.509 trust model rather than the C2PA product Trust List. + +Sources: + +- [Distinct C2PA and CAWG X.509 trust models; August 20, 2026](https://discord.com/channels/983153151341371422/1273777445551603714/1540009285424119868) +- [CAWG certificate types and separate identity role; April 1, 2026](https://discord.com/channels/983153151341371422/986451330992320512/1488868534166749375) + +### Why can CAWG identity remain untrusted when the claim signer is trusted? + +CAWG trust anchors need separate SDK configuration. Trust in the C2PA claim +signer does not automatically establish trust in the identity assertion. +Two possible causes are that the validator did not configure CAWG anchors, or using a CAWG certificate that does not chain to the anchors that validator uses. + +Inspect the validation result's assertion URL to determine whether +`signingCredential.untrusted` refers to `cawg.identity` rather than the claim +signature. A successful signature or well-formedness check is not a +substitute for the identity trust check. + +Sources: + +- [Possible validator configuration causes; August 24, 2026](https://discord.com/channels/983153151341371422/1273777445551603714/1541459686690267136) +- [Separate configuration and local leaf workaround; September 7, 2026](https://discord.com/channels/983153151341371422/1273777445551603714/1546545082130370620) +- [Merged trust-list fix report; September 10, 2026](https://discord.com/channels/983153151341371422/1273777445551603714/1547575185790603264) +- [Configured-root test result; September 10, 2026](https://discord.com/channels/983153151341371422/1273777445551603714/1547641280048275550) + +### Are there source-linked guides for CAWG on mobile? + +For a Proofmode Android workflow using CAWG X.509 assertions and SSL.com +identity-validated certificates with captured photos and videos, see the +[user guide](https://proofmode.org/cawg_user_guide). This functionality was +available in a Proofmode Android release in October 2026. + +For SDK integration, see the [CAWG mobile SDK developer guide](../cawg-mobile.mdx). +These resources are not independently reviewed instructions or a guarantee of support across all mobile SDKs, certificate authorities, or identity mechanisms. + +Sources: + +- [Android implementation and user guide announcement; October 16, 2026](https://discord.com/channels/983153151341371422/1273777445551603714/1560673010854264932) +- [Mobile developer guide; October 16, 2026](https://discord.com/channels/983153151341371422/1273777445551603714/1560673133684457494) + +### What should I use instead of CreativeWork for creator-related data? + +Use CAWG identity and metadata assertions instead of `stds.schema-org.CreativeWork` for creator-related data. See +[cawg.io](https://cawg.io). Identity trust must still be evaluated separately. + +Source: [CAWG identity and metadata recommendation; August 31, 2026](https://discord.com/channels/983153151341371422/986451330992320512/1543982994082238568) + +### Can my organization's identity certificate identify all my users? + +No. With the CAWG X.509 method, each user +would need a CAWG certificate issued with that user's own name or organization. +Your organization's certificate asserts your organization's identity, not +the identities of all its users. Consider **Identity Claims Aggregation** +for platforms. + +Becoming a C2PA CA is a separate role: issuing signing certificates to +conforming products. To attach artist, creator, or publisher identity, use the +[CAWG identity assertion](https://cawg.io/identity/1.3/), using an X.509 +certificate or Identity Claims Aggregation. + +Sources: + +- [Per-user X.509 identity; August 13, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1537519938552733766) +- [CA versus creator identity; October 9, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1558191343988117524) \ No newline at end of file diff --git a/docs/technical-faqs/tech-faq-certificates.md b/docs/technical-faqs/tech-faq-certificates.md new file mode 100644 index 00000000..4354fa41 --- /dev/null +++ b/docs/technical-faqs/tech-faq-certificates.md @@ -0,0 +1,144 @@ +--- +hide_table_of_contents: true +--- + +import TOCInline from '@theme/TOCInline'; + +# Claim-signing certificate FAQs + + + +### How can an implementation obtain a broadly recognized signing certificate? + +Pass C2PA generator conformance to obtain a signing certificate intended +for broad recognition by validators. After passing conformance, a generator can obtain a conforming +product certificate from a certificate authority whose root is on the +C2PA Trust List. + +The process starts with a completed implementation and an +expression of interest, followed by a legal agreement and intake form. +Prepare a Generator Product Security Architecture Document and Diagram, +plus signed interoperability samples. + +See [C2PA conformance program](../conformance/index.mdx) for more information. + +### Is a C2PA claim-signing certificate the same as a creator identity certificate? + +No. Trusted C2PA +claim-signing certificates are issued for conforming hardware or software +products, rather than to establish the creator's identity. + +Use [CAWG](https://cawg.io), which complements C2PA by attaching verified identity through a CAWG identity assertion in the manifest. Treat the product-signing and identity roles separately; +obtaining a product certificate does not by itself establish who created, edited, or published the content. + +Source: [Product certificates versus creator identity; May 14, 2026](https://discord.com/channels/983153151341371422/1276934105858314404/1504655459725082675) + +### Does renewing an Interim Trust List certificate preserve its listing? + +No. Renewal produces a new PEM and PEM hash, so +validators do not recognize the renewed certificate as the one on the +Interim Trust List (ITL). + +Do not treat the renewed certificate as the certificate to add to the +official C2PA Trust List after conformance. +Instead, passing conformance enables issuance of a conforming product +certificate from a CA with its root on the C2PA Trust List. + +This distinguishes the particular certificate recognized by the ITL from +the CA-root-based route for the C2PA Trust List. The ITL was frozen at the +start of 2026; do not assume a current renewal or migration exception exists. + +Sources: + +- [Renewal changes PEM recognition; June 16, 2026](https://discord.com/channels/983153151341371422/1276934105858314404/1516516354125987991) +- [Renewed certificate is not the C2PA Trust List route; June 16, 2026](https://discord.com/channels/983153151341371422/1276934105858314404/1516525716341264394) +- [Conforming product certificate issuance; June 16, 2026](https://discord.com/channels/983153151341371422/1276934105858314404/1516525798838767719) +- [Historical ITL freeze; April 6, 2026](https://discord.com/channels/983153151341371422/1276934105858314404/1490788225294536734) + +### Can conformance interoperability samples use a test certificate? + +Yes. Sign interoperability samples with a test certificate. A renewed ITL +certificate can also be used for these samples. + +Permission to use that certificate for samples is distinct from production +trust. A renewed ITL certificate is not the route to the official C2PA Trust List. + +Sources: + +- [Certificates for interoperability samples; June 16, 2026](https://discord.com/channels/983153151341371422/1276934105858314404/1516516612000186498) +- [Production trust distinction; June 16, 2026](https://discord.com/channels/983153151341371422/1276934105858314404/1516525716341264394) + +### Which certificates should the signer include in x5chain? + +Pass the certificate chain to the signer in this order: +**leaf first, then the intermediate CA certificate +(ICA), without the root**. The signer populates `x5chain` in the COSE +signature; the validator obtains the root from its trust list. + +The trust list is therefore not a replacement for supplying the signing +chain's intermediate. Ensure the intermediate belongs to the leaf's chain; +including an unrelated intermediate will not establish trust. Chain order +alone does not diagnose every leaf/intermediate mismatch. + +Sources: + +- [Chain order and root source; September 4, 2026](https://discord.com/channels/983153151341371422/1276934105858314404/1545416331376066621) +- [Private follow-up without published resolution; September 7, 2026](https://discord.com/channels/983153151341371422/1276934105858314404/1546538935709208576) + +### What trust-anchor configuration was recommended for a custom validator? + +Concatenate the C2PA Trust List PEM and C2PA TSA Trust List PEM, then pass +the combined contents as `trust_anchors` in the tool's `trust` settings. Include +both claim-signing and timestamp-authority trust anchors. + +This is configuration guidance, not a guarantee that a particular asset +will be trusted or that an expired certificate's status is resolved merely +by adding a list. Cryptographic validity and trust remain separate checks. + +Source: [combined signing and timestamp trust anchors, July 9, 2026](https://discord.com/channels/983153151341371422/1276934105858314404/1524771146631872583) + +### Can a conforming product rotate its signing certificate and key? + +With Trufo, a product can request a new certificate or rotate a certificate +at any time, with APIs available to automate the process. See +[Trufo's certificate documentation](https://trufo.ai/documentation#certificates). + +This is provider-specific experience, not a published statement of every +CA's issuance rules or all conformance requirements for key rotation. The +applicable rotation interval and key-management procedure depend on your +provider and product requirements. + +Source: [Trufo rotation and automation experience, August 12, 2026](https://discord.com/channels/983153151341371422/986451330992320512/1537108990797025280) + +### What requirements apply to a C2PA credential issuer? + +Distinguish the certificate's technical profile from the policy governing +issuance by a trusted CA: + +- The specification's + [certificate profiles](https://spec.c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html#_certificate_profiles) + define the certificate profile acceptable as a signing credential. +- The + [C2PA Certificate Policy](https://github.com/c2pa-org/conformance-public/blob/main/docs/v0.2/C2PA%20Certificate%20Policy.pdf) + governs issuance by CAs with roots on the C2PA Trust List. + +Meeting the technical profile alone is not the same as establishing +recognized trust. These are requirements references, not a +reference implementation of a credential-issuer service or a list of +required service endpoints. + +Source: [certificate profile versus CA issuance policy, September 28, 2026](https://discord.com/channels/983153151341371422/986451330992320512/1554122925026840576) + +### Was a free production certificate option announced? + +As of June 23, 2026, SSL.com offered a free tier for qualifying C2PA-conformant +generator products: an Assurance Level 1 claim-signing certificate valid +for one year and up to 10,000 trusted timestamps. See +[SSL.com's C2PA page](https://ssl.com/c2pa) for details and applications. + +This was a dated provider offer, not a guarantee of current pricing, +eligibility, availability, or renewal terms. It did not remove the +conformance prerequisite and was not an offer of an individual creator +identity certificate. + +Source: [provider free-tier announcement, June 23, 2026](https://discord.com/channels/983153151341371422/986451330992320512/1519016971486761040) diff --git a/docs/technical-faqs/tech-faq-conformance.md b/docs/technical-faqs/tech-faq-conformance.md new file mode 100644 index 00000000..188f0ff4 --- /dev/null +++ b/docs/technical-faqs/tech-faq-conformance.md @@ -0,0 +1,361 @@ +--- +hide_table_of_contents: true +--- + +import TOCInline from '@theme/TOCInline'; + +# C2PA conformance FAQs + + + +### How do I start the conformance process? + +Start with the [C2PA Conformance Program](https://c2pa.org/conformance/) +and its expression of interest form. See the +[program document](https://github.com/c2pa-org/conformance-public/blob/main/docs/v0.2/C2PA%20Conformance%20Program.pdf) +for details. + +A generator product must pass conformance before it can +obtain a signing certificate from an CA that has a root cert on the C2PA Trust List. +You can use test certificates while preparing for evaluation; however, they +are not trusted production credentials. + +Sources: + +- [Certificate prerequisite; September 30, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1554850060112498779) +- [Program document; September 30, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1554850126449737808) +- [Expression of interest form; September 30, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1554850450874834964) +- [Evaluation certificates; September 10, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1547716234173222962) + +### How do I follow up on an application or correct its media types? + +Contact the conformance administrator at **conformance@c2pa.org** for +application-specific issues. For a missing response to an expression of +interest, provide the representative email address used in the submission. +There is no guaranteed response time. + +If a generator application incorrectly omits validation capabilities, request +a revision listing both the input media types it validates and the output +media types it generates. For example, a product could validate JPEG and PNG +ingredients while generating signed JPEG, PNG, WebP, and AVIF assets. Declare +your actual capabilities, not this example's list. + +Sources: + +- [Application follow-up; July 2, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1522236996553146399) +- [Resolution; July 2, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1522288127408865310) +- [Correcting media types; June 21, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1518382298482081872) + +### Does conformance apply to the product or to each end user? + +Conformance is associated with a generator or validator product, whether +software or hardware, rather than an individual user. + +Creator identity is a separate concern. Use a separately-signed CAWG identity assertion when a product needs to identify its users. Product conformance alone does not establish a user's identity. + +Source: [Product conformance and identity; August 12, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1537131310424784896) + +### Does a conformance listing mean the public product already uses production certificates? + +Not necessarily. A product can appear on the conforming products list +before public launch. There can +also be a delay between listing and deploying a production certificate: +the selected CA must verify conformance and the applicant's legal identity. + +Listing alone does not make a beta certificate trusted. Evaluate the certificate actually used to sign an asset rather than inferring its trust from the product's listing alone. + +Source: [Listing, launch, and certificate deployment distinction; May 23, 2026](https://discord.com/channels/983153151341371422/986451330992320512/1507727660401295360) + +### Why does a generator application ask about validation? + +A generator that ingests assets and creates or appends manifests must invoke +validation logic against the C2PA CA and TSA Trust Lists as part of that +process. Its declared **validate** media types describe those inputs; its +**generate** media types describe the outputs for which it creates manifests. + +This ingredient validation is distinct from applying as a standalone +validator product, which validates assets without generating manifests. +Apply separately as a validator product if you are also building a +verification tool. + +Sources: + +- [Generator validation scope; July 16, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1527310749628891176) +- [Separate verification tool; August 12, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1537127081672974486) + +### How do I choose between backend, distributed, and separate product submissions? + +A distributed generator can divide asset generation, assertions, claim +generation, and signing between edge and backend subsystems while functioning +as one product. Use mutual authentication between the subsystems and a +backend check that the caller is a valid instance of +the edge subsystem. + +Cooperating subsystems might be submitted as one distributed product, +while components that independently generate assets, +claims, and signatures would probably require separate submissions. + +Do not classify a customer-hosted component solely by whether it runs on a +server. Classification requires an assessment of the architecture. +Submit an architecture summary and diagram to conformance@c2pa.org, identifying +the **Target of Evaluation**, the components included in the generator +product, and how objects submitted for signing are authenticated. +Dependency vulnerability scanning requirements can also be a challenge for +customer-hosted deployments. + +Sources: + +- [Cooperating subsystems; May 15, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1504810186504671304) +- [Independent generators; May 15, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1504810688638484660) +- [Distributed authentication; August 27, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1542545382997893230) +- [Customer-hosted architecture caveats; August 27, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1542586446815170750) +- [Definitive assessment requires an architecture; August 28, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1542842626947154031) + +### Does using the latest SDK make my product conformant? + +No. Use the latest SDK, but remember that SDKs are tools for building +products and must be used in a conformant way. Conformance also covers areas beyond software implementation, such as security architecture and key management practices. You also have to submit interoperability test assets as part of the conformance process. + +Some common problem areas to check include: + +- Configuring created versus gathered assertions deliberately. +- Using `c2pa.created` and `c2pa.opened` appropriately. Do not describe an + existing asset uploaded by a user as newly-created by your product. +- Validating ingredients with the C2PA Trust List configured. + +Sources: + +- [Test assets; May 15, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1504806955154280601) +- [SDK recommendation and limitation; May 15, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1504807032341925918) +- [Preparation checks; May 15, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1504807213145784443) + +### How do I configure trust for ingredient validation? + +Load both the [C2PA Trust List](https://raw.githubusercontent.com/c2pa-org/conformance-public/refs/heads/main/trust-list/C2PA-TRUST-LIST.pem) +and the [C2PA TSA Trust List](https://raw.githubusercontent.com/c2pa-org/conformance-public/refs/heads/main/trust-list/C2PA-TSA-TRUST-LIST.pem). +Fetch their PEM contents, concatenate them, and supply the resulting PEM +string through `trust.trust_anchors`. + +For SDK integrations, pass the settings to the builder through a context. +Do not use deprecated thread-local settings. + +The C2PA Trust List alone may appear to work for timestamp trust because +the lists share roots. Include the TSA list to pick up intermediate CA +certificates. This is +trust-anchor configuration guidance, not a complete answer to every +certificate-expiration or point-in-time validation scenario. + +Sources: + +- [PEM configuration; May 22, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1507426136596942962) +- [Context-based follow-up; May 23, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1507741760820871250) +- [TSA intermediate certificates; August 19, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1539661485234724864) + +### Which timestamp endpoints are recommended for C2PA trust? + +As of August 10, 2026, these SSL.com endpoints are free for general use +with roots on the C2PA TSA Trust List: + +- `http://ts-c2pa.ssl.com/rsa` +- `http://ts-c2pa.ssl.com/ecc` + +Trufo's service requires payment and authentication. See the +[Trufo timestamping documentation](https://trufo.ai/documentation#timestamping). + +Sources: + +- [SSL.com endpoints; August 10, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1536414294198059132) +- [Trufo documentation; August 11, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1536747888305242223) +- [Trufo access conditions; August 11, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1536748051287248998) + +### Can evaluation samples use test certificates and still report untrusted? + +Yes. Use SDK test certificates, CA-provided test certificates, or +certificates you generate yourself, but evaluation signing certificates +cannot be self-signed. Do not interpret +"generate your own" as permission to use a self-signed signing certificate. + +See the +[SDK test certificates](https://github.com/contentauth/c2pa-rs/tree/main/sdk/tests/fixtures/certs) +and a [certificate creation walkthrough](https://learn.contentauthenticity.org/private-keys-and-certificates). + +Getting a `signingCredential.untrusted` error is normal +before obtaining a conforming product certificate and does not itself prevent +passing conformance. + +Sources: + +- [Evaluation certificate constraints; September 10, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1547716234173222962) +- [Certificate creation walkthrough; September 10, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1547720168149352558) +- [SDK fixtures; September 10, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1547720257018269826) +- [Expected untrusted status; October 9, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1558172948022698065) + +### Does adding a trusted manifest remove warnings about earlier untrusted manifests? + +Do not assume that it does. Validators generally show a notice when an +asset contains manifests signed with +untrusted certificates. The notice may apply to individual manifests, the +manifest store, or both, depending on the validator. + +When a subsequent conforming generator validates such an asset as an +ingredient, it includes the ingredient validation results. If it uses only +the C2PA Trust List, an ingredient signed with a certificate from an +untrusted private CA will produce `signingCredential.untrusted`. + +This explains a trust-display consequence of a mixed pipeline. It is not a +blanket ruling that every trusted/untrusted pipeline is prohibited. + +Source: [Mixed-pipeline trust behavior; September 10, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1547716234173222962) + +### How do I put the actions assertion in created assertions? + +Configure `builder.created_assertion_labels` using **base assertion labels**. +For the Node bindings, use: + +```js +const settings = { + builder: { + created_assertion_labels: ['c2pa.actions'], + }, +}; + +const builder = Builder.withJson(manifestDefinition, settings); +``` + +Use `c2pa.actions`, not `c2pa.actions.v2`. Likewise, do not include assertion +instance suffixes such as those in `c2pa.ingredient.v3__2`. + +With only `c2pa.actions` in that setting, the actions assertion and the +automatically created hard binding are created +assertions; other assertions are gathered. Add other base labels as +appropriate for your implementation. This is not a universal conformance +configuration. + +As of August 2026, the Reader output flattened created and gathered +assertions into one list. Inspect the raw claim bytes to verify placement +if your version has this limitation. + +Sources: + +- [Base labels and automatic hard binding; August 19, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1539665498835517531) +- [Successful verification and Reader limitation; August 19, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1539705852968177734) +- [Node settings; September 2, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1544696112101728396) +- [Passing settings to the builder; September 2, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1544696724411645972) + +### Should ingredient assertions be created or gathered? + +Mark an ingredient assertion as created in most cases because the claim +generator validates it. This is +implementation-dependent guidance, not a statement that every assertion +associated with an input asset must be created. + +Configure assertion placement deliberately rather than relying on the +SDK default, which places assertions other than the hard binding in +gathered assertions. + +Sources: + +- [Ingredient recommendation; July 9, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1524768241518641272) +- [SDK default; May 15, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1504807213145784443) + +### What does digitalSourceType describe, and when is it needed? + +The `digitalSourceType` property describes the nature +of how an **action** was performed, such as human, AI, or algorithmic activity. +It is not one asset-wide value to copy unchanged through every edit. +C2PA 2.4 also allows it to describe an ingredient. + +Actions affecting the asset's editorial nature need +a digital source type, whereas an unbound watermarking action does not. +An original asset should still be referenced as the ingredient associated +with `c2pa.opened`; that action does not require a digital source type. + +`c2pa.created` requires an appropriate `digitalSourceType` in both C2PA 2.2 +and 2.4. See the +[specification requirement](https://spec.c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html#_mandatory_presence_of_at_least_one_actions_assertion) +and section 2.4 of the +[Additional Conformance Requirements](https://github.com/c2pa-org/conformance-public/blob/main/docs/v0.2/Additional%20Conformance%20Requirements%20Against%20the%20Content%20Credentials%20Specification.pdf). +Do not infer that the field is optional merely because an older validator +did not report its absence. + +Sources: + +- [Action and ingredient semantics; July 14, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1526686021004296334) +- [Editorial actions; July 14, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1526686436689055785) +- [Opened action and ingredient; July 14, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1526686633561428018) +- [Created action requirement; August 20, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1540014008319610961) + +### How should I describe visible and invisible watermarking? + +For invisible watermarking, use `c2pa.watermarked.bound` +or `c2pa.watermarked.unbound`, depending on whether a `c2pa.soft-binding` +assertion is used with it. + +For a visible logo, represent it as a `componentOf` +ingredient and recording `c2pa.placed` with a parameter referencing that +ingredient. For a text-only visible watermark, consider +`c2pa.addedText`. + +Do not map all visible watermarking to `c2pa.edited` with a `composite` +source type. + +Source: [Watermarking guidance; July 9, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1524768241518641272) + +### Which action describes publishing an already signed asset? + +Use `c2pa.published` when releasing an asset to a wider audience, together +with any other actions that actually occurred. There is no `c2pa.signed` +action. + +Use the [official action definitions](https://spec.c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html#_actions) +to describe the operation, rather than inventing an action solely because +another signature was produced. + +Source: [Publication action; May 17, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1505616834148303099) + +### How should I represent a user's training and mining preferences? + +For a seller opt-out workflow, put `cawg.training-mining` in gathered +assertions. It remains cryptographically protected there, but is not attributable to the C2PA claim +generator or signer. + +This placement is covered by the manifest signature. If you want +to connect the preference to a CAWG identity, reference the assertion through +the `referenced_assertions` array of `cawg.identity`. + +This answers attribution and cryptographic protection; it does not claim +that the assertion enforces a user's preference on downstream systems. + +Companies do not necessarily respect training-and-mining assertions. Treat the +assertion as a statement of preference, not a technical block on scraping +or a guarantee against undesired AI use. + +Sources: + +- [Gathered preference assertion and optional identity link; June 8, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1513597018038206725) +- [Practical enforcement limitation; August 11, 2026](https://discord.com/channels/983153151341371422/986451330992320512/1536753197203587175) + +### Why can crJSON show different specVersion values? + +The fields describe different specification versions: + +- `claim_generator_info.specVersion` in the claim describes the specification + version declared by the generator. +- `validationResults.specVersion` describes the specification version against + which validation was performed. It is not copied from the generator's field. + +As of August 2026, a claim could declare `2.4.0` while validation results +reported `2.3.0` because the validation value was hard-coded in the SDK +implementation. Check the generator value in +`claim.v2` rather than trying to change the report's validation version +through generator metadata. + +This distinction explains the field mismatch, not every conformance check. +Matching the generator field or passing a rubric alone is not presented +here as proof that a product has passed the program. + +Sources: + +- [Field definitions; August 11, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1536901977655742567) +- [Reproduced version mismatch; August 11, 2026](https://discord.com/channels/983153151341371422/1403049797023174828/1536918406375276704) + diff --git a/docs/technical-faqs/tech-faq-general.md b/docs/technical-faqs/tech-faq-general.md new file mode 100644 index 00000000..82c80c0d --- /dev/null +++ b/docs/technical-faqs/tech-faq-general.md @@ -0,0 +1,113 @@ +--- +hide_table_of_contents: true +--- + +import TOCInline from '@theme/TOCInline'; + +# General FAQs + + + +### Where can I find signed sample assets? + +Use Proofmode's public +[Baseline repository](https://proofmode.org/baseline/) has signed sample +assets, but be aware that much of its content uses older C2PA 1.x support. Use the [`contentauth/example-assets` repository](https://github.com/contentauth/example-assets) to submit signed assets for testing. Neither repository guarantees a +complete, current conformance test suite. + +For location metadata, see the Proofmode +[Android 3.0.2 release candidate](https://github.com/guardianproject/proofmode-android/releases/tag/3.0.2-RC-2) +and its use of `c2pa.metadata` to include geolocation as a created assertion. +Older conformance samples used `stds.exif`, described as deprecated but +still valid. See the +[Kotlin metadata-generation code](https://github.com/guardianproject/proofmode-android/blob/main/android-libproofmode/src/main/java/org/witness/proofmode/c2pa/C2PAManager.kt#L840). + +Sources: + +- [Baseline and older sample versions; April 3, 2026](https://discord.com/channels/983153151341371422/986451330992320512/1489689553886384228) +- [Android geolocation implementation; April 3, 2026](https://discord.com/channels/983153151341371422/986451330992320512/1489689681653141634) +- [Older sample assertion format; April 3, 2026](https://discord.com/channels/983153151341371422/986451330992320512/1489690080623726795) +- [Metadata-generation code; April 3, 2026](https://discord.com/channels/983153151341371422/986451330992320512/1489690402805125372) +- [Shared signed-asset repository; April 3, 2026](https://discord.com/channels/983153151341371422/986451330992320512/1489693250133430272) + +### How can I get started with Content Credentials on Android or iOS? + +Use the [mobile SDKs](../mobile.md) for Android and iOS. + +### Does a Valid validation state mean that the signer is trusted? + +No. There are three manifest states: +**well-formed**, **valid**, and **trusted**. Trusted manifests are also +valid, and valid manifests are also well-formed. The reverse does not follow. + +A manifest signed with a test certificate can have a `Valid` state while +`validation_results.activeManifest.failure` contains +`signingCredential.untrusted`. This follows the manifest-state model. + +Do not label a manifest trusted merely because its state is `Valid`. +Inspect the trust-related validation results, and distinguish trust that +was not evaluated from a failed trust check. An issuer name alone does +not establish trust. + +See the +[manifest states specification](https://spec.c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html#_manifest_states). + +Sources: + +- [Valid-but-untrusted result; July 29, 2026](https://discord.com/channels/983153151341371422/1168635192680923206/1532235743022288977) +- [State hierarchy; July 30, 2026](https://discord.com/channels/983153151341371422/1168635192680923206/1532378030276612178) +- [Specification reference; July 30, 2026](https://discord.com/channels/983153151341371422/1168635192680923206/1532378218420633610) + +### Can a manifest carry custom sensor or verification information? + +Yes. You can add custom assertions to a C2PA manifest. A validator +that understands that assertion could use its information to identify where +changes occurred. + +That is an extensibility mechanism, not endorsement of the proposal's +claimed security guarantees or a promise that existing validators understand +it. A camera/editor workflow needs compatible implementations; custom +assertions alone do not provide that coordination. + +Source: [custom assertions and validator support, April 20, 2026](https://discord.com/channels/983153151341371422/986451330992320512/1495831402938110155) + +### Where are embedding rules for TIFF-based and base-media file formats documented? + +See the **Embedded Formats annex** +of the +[Content Credentials specification](https://c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html). +for embedding rules relevant to TIFF-based Sony formats and the +base-media-based Canon CR3 format. + +This is a specification pointer, not confirmation that every raw camera +format is supported by a particular SDK or that camera samples are available. + +Source: [Embedded Formats annex, August 17, 2026](https://discord.com/channels/983153151341371422/986451330992320512/1538922552007589898) + +### Where can I report a CAI security concern? + +Use the [CAI contact form](https://contentauthenticity.org/contact) to report +a security concern. Do not assume a dedicated security inbox, a response +deadline, or public status updates are available. + +Sources: + +- [Reporting contact; October 19, 2026](https://discord.com/channels/983153151341371422/986451330992320512/1561895003670716528) +- [Routing and status limitations; October 19, 2026](https://discord.com/channels/983153151341371422/986451330992320512/1561895701028536405) + +### Why might an HEIC thumbnail not appear in Verify? + +Signing and display are separate issues. If a thumbnail's format changes to +`application/octet-stream` during signing, use a v2 claim: set +`claim_version` to `2`, or omit it if your version defaults to v2. + +Display also depends on browser support. As of September 2026, +`image/heic` thumbnails displayed in macOS Safari but not Chrome. +A correctly embedded thumbnail therefore did not guarantee display in +every browser. These observations are historical, not a current browser +compatibility matrix. + +Sources: + +- [V2 claims and browser-dependent display; September 1, 2026](https://discord.com/channels/983153151341371422/983153390781616159/1544362081107578961) +- [Successful result; September 2, 2026](https://discord.com/channels/983153151341371422/983153390781616159/1544907804417064970) \ No newline at end of file diff --git a/docs/technical-faqs/tech-faq-node.md b/docs/technical-faqs/tech-faq-node.md new file mode 100644 index 00000000..00dce854 --- /dev/null +++ b/docs/technical-faqs/tech-faq-node.md @@ -0,0 +1,96 @@ +--- +hide_table_of_contents: true +--- + +import TOCInline from '@theme/TOCInline'; + +# Node.js library FAQs + + + +### How do I configure created versus gathered assertions? + +Use `builder.created_assertion_labels` to identify the assertions attributed +to your claim generator. For example: + +```js +const settings = { + builder: { + created_assertion_labels: [ + "c2pa.actions", + "c2pa.thumbnail.claim", + "c2pa.thumbnail.ingredient", + "c2pa.ingredient" + ] + } +}; +``` + +Choose labels that reflect your implementation; this is not a universal +conformance configuration. Assertions are gathered by default, except for +the hard binding, which is always created. + +Use only **base assertion labels**, without version or instance suffixes. +For example, use `c2pa.ingredient`, not `c2pa.ingredient.v3`. The SDK +handles the version. + +Update to the latest Node SDK release to avoid a bug in an earlier release. +The first release containing that fix is not identified here. An upgrade does not replace +the need to configure assertion placement. + +Sources: + +- [Assertion settings; April 2, 2026](https://discord.com/channels/983153151341371422/1168635192680923206/1489395644274839582) +- [Release guidance; April 2, 2026](https://discord.com/channels/983153151341371422/1168635192680923206/1489396659451592754) +- [Base labels; April 2, 2026](https://discord.com/channels/983153151341371422/1168635192680923206/1489400012369694912) + +### How do I configure signing-certificate and timestamp trust? + +Load the C2PA Trust List and C2PA TSA Trust List, combine their PEM contents, +and enable both trust checks. With those PEM +strings already loaded as `c2paTrustList` and `c2paTsaTrustList`, pass the +settings to both the reader and builder: + +```js +const settings = { + trust: { + trust_anchors: c2paTrustList + c2paTsaTrustList, + }, + verify: { + verify_trust: true, + verify_timestamp_trust: true, + }, +}; + +const reader = await Reader.fromAsset({ path: "photo.jpg" }, settings); +const builder = Builder.withJson({ title: "photo.jpg" }, settings); +``` + +This is a configuration excerpt, not a complete program: it assumes the +reader and builder bindings are imported and the PEM contents have been +fetched or read. It comes from the replacement package discussed above, +not the deprecated `c2pa-node` 0.5.26 API. + +Sources: + +- [Reader and builder trust settings; July 29, 2026](https://discord.com/channels/983153151341371422/1168635192680923206/1532214117342122025) +- [User confirmation; July 29, 2026](https://discord.com/channels/983153151341371422/1168635192680923206/1532235743022288977) + +### Should I pass a PEM file path or its contents as trust anchors? + +Pass the **PEM contents as a string**, not a file path. C2PA Tool's +`load_trust_resource()` is a convenience for loading PEM data from a path +or URL; do not assume that behavior applies to the Node SDK. + +The `loadSettingsFromFile()` function loads the whole settings file; it +does not imply that an individual trust-anchor setting accepts a PEM path. + +Supply PEM strings through `trust.trust_anchors`, as shown above. Changing +the input format does not necessarily resolve every trust failure. + +Sources: + +- [PEM contents; April 4, 2026](https://discord.com/channels/983153151341371422/1168635192680923206/1490086610321145876) +- [Settings-file distinction; April 4, 2026](https://discord.com/channels/983153151341371422/1168635192680923206/1490087412364218409) +- [C2PA Tool convenience method; April 4, 2026](https://discord.com/channels/983153151341371422/1168635192680923206/1490090813227536416) +- [Later PEM-string example; July 29, 2026](https://discord.com/channels/983153151341371422/1168635192680923206/1532214117342122025) diff --git a/docs/technical-faqs/tech-faq-rust.md b/docs/technical-faqs/tech-faq-rust.md new file mode 100644 index 00000000..7f5f224d --- /dev/null +++ b/docs/technical-faqs/tech-faq-rust.md @@ -0,0 +1,180 @@ +--- +hide_table_of_contents: true +--- + +import TOCInline from '@theme/TOCInline'; + +# Rust library FAQs + + + +### Can I configure trust anchors using a URL? + +The Rust SDK expects trust anchors as a **PEM string**, not a URL or file +path. Your application must fetch or read the PEM data and pass its contents +to the SDK. + +In contrast, C2PA Tool accepts URLs and paths as command-line arguments because it +retrieves the data before passing it to the SDK. + +For example: + +```rust +let pem = reqwest::blocking::get("https://example.com/trust_anchors.pem")? + .text()?; + +c2pa::settings::Settings::from_toml( + &toml::toml! { + [trust] + trust_anchors = pem + } + .to_string(), +)?; +``` + +Source: [Trust anchors: April 7, 2026](https://discord.com/channels/983153151341371422/983153550018371595/1491236748653494503) + +### How do I mark assertions as created rather than gathered? + +Use the `builder.created_assertion_labels` setting to identify assertions +attributed to your claim generator. For example: + +```toml +[builder] +created_assertion_labels = [ + "c2pa.actions", + "c2pa.thumbnail.claim", + "c2pa.thumbnail.ingredient", + "c2pa.ingredient" +] +``` + +Choose labels appropriate to your implementation. This example is not a +universal conformance configuration. The hard-binding assertion is always +a created assertion. + +See [Created versus gathered assertions](../manifest/writing/assertions-actions.md#created-versus-gathered-assertions) +for more information. + +Source: [Created assertions config; June 16, 2026](https://discord.com/channels/983153151341371422/983153550018371595/1516521499517779978) + +### How do I preserve an existing asset's assertions when editing it? + +Include the original asset as a **`parentOf` ingredient**. If the asset is +signed, its manifest and assertions are carried forward through that +ingredient. You generally do not need to copy those assertions into your +new manifest as gathered assertions. + +For a typical editing workflow, use: + +```rust +builder.set_intent(BuilderIntent::Edit); +``` + +The `Edit` intent automatically adds the `c2pa.opened` action and uses the source +as the parent if you do not specify one. Do not manually add a duplicate +`c2pa.opened` action. + +It is normal for a simple open-and-edit workflow to have no gathered +assertions. If you intentionally reuse metadata as a new gathered assertion, +verify that it still applies to the edited asset. + +Sources: + +- [Parent handling; October 14, 2026](https://discord.com/channels/983153151341371422/983153550018371595/1559968978376593439) +- [Gathered-assertion clarification; October 14, 2026](https://discord.com/channels/983153151341371422/983153550018371595/1560080821287657594) + +Use the `Edit` intent when an existing asset produces +`assertion.action.malformed: first action must be created or opened` +or `assertion.action.ingredientMismatch`. Ensure manually defined +`actions` are nested inside `assertions` and the workflow includes +a referenced `parentOf` ingredient. Do not assume an "Invalid Manifest" error is a trust +problem without inspecting its validation details. + +Sources: + +- [action structure and edit-intent fix, October 15, 2026](https://discord.com/channels/983153151341371422/986451330992320512/1560317418574839849) +- [successful result, October 15, 2026](https://discord.com/channels/983153151341371422/986451330992320512/1560344798165074072) + +### How do I add timestamps for existing ingredient manifests? + +Enable automatic timestamp assertions with these settings: + +```toml +[builder.auto_timestamp_assertion] +enabled = true +fetch_scope = "all" +``` + +Choose the builder intent according to the operation: + +- Use **update intent** when the asset content has not changed and you only + need to add a timestamp assertion. +- Use **edit intent** when you are also editing or reformatting the asset. + +Add the timestamp assertion while the relevant signing +certificate is still within its validity period. + +Sources: + +- [settings, April 20, 2026](https://discord.com/channels/983153151341371422/983153550018371595/1495826791313571900) +- [intent selection, April 20, 2026](https://discord.com/channels/983153151341371422/983153550018371595/1495827650026147952) +- [certificate validity, April 7, 2026](https://discord.com/channels/983153151341371422/983153550018371595/1491238678410821784) + +### Why is no thumbnail generated even though thumbnails are enabled? + +The SDK skips automatic thumbnail generation for **update manifests**, +even when thumbnail generation is enabled. The specification does not +permit update manifests to contain thumbnail +assertions. + +Source: [Thumbnail auto-generation, April 19, 2026](https://discord.com/channels/983153151341371422/983153550018371595/1495464171934974002) + +### How do I avoid sidecar filename collisions? + +Assets with the same base name can produce the same default sidecar +filename. For example, `file.obj` and `file.mtl` can both produce +`file.c2pa`. + +Rename each sidecar immediately after creating it to preserve the original +extension, for example: + +```text +file.obj.c2pa +file.mtl.c2pa +``` + +When reading an asset, explicitly provide the corresponding sidecar using +`--external-manifest`. + +Source: [Renaming sidecars, September 16, 2026](https://discord.com/channels/983153151341371422/983153550018371595/1549894561537466399) + +### Why does manifest compression barely reduce a long existing chain? + +Compression applies to the current manifest being written, not retroactively to every manifest in an +existing chain. To compare compressed and uncompressed chains, enable +`prefer_compress_manifests` while writing each generation. + +In a test of 10 manifests containing a repetitive text custom assertion, +the final manifest-store size was 154,638 bytes without compression and +52,583 bytes with compression enabled at each generation. Repetitive test +data would likely compress better +than real-world content. This is not a promised compression ratio or a way +to shrink all prior manifests by appending one compressed manifest. + +Sources: + +- [Compression scope and test recommendation, October 15, 2026](https://discord.com/channels/983153151341371422/986451330992320512/1560358414264172585) +- [Controlled comparison and data caveat, October 15, 2026](https://discord.com/channels/983153151341371422/986451330992320512/1560370962875285566) + +### Can I use the Rust implementation from a JVM backend? + +The SDK does not provide a supported Java binding. +And the Android bindings focus on Android-specific needs: Adapting them for a +JVM service would require additional work; they are not an existing, +maintained general-purpose Java package. + +You could use the Rust implementation's +[C API](https://github.com/contentauth/c2pa-rs/tree/main/c2pa_c_ffi) to integrate through JNI. + +Source: [Android scope and C API integration route, September 14, 2026](https://discord.com/channels/983153151341371422/986451330992320512/1549054456258240674) diff --git a/sidebars.js b/sidebars.js index fe2ccfe4..4de39ee6 100644 --- a/sidebars.js +++ b/sidebars.js @@ -138,6 +138,43 @@ const sidebars = { ...getRemoteSidebarItems('tasks'), ], }, + { + type: 'category', + label: 'Technical FAQs', + link: { type: 'doc', id: 'technical-faqs/index' }, + collapsed: true, + items: [ + { + type: 'doc', + id: 'technical-faqs/tech-faq-general', + }, + { + type: 'doc', + id: 'technical-faqs/tech-faq-rust', + }, + { + type: 'doc', + id: 'technical-faqs/tech-faq-node', + }, + { + type: 'doc', + id: 'technical-faqs/tech-faq-c2pa-tool', + }, + { + type: 'doc', + id: 'technical-faqs/tech-faq-conformance', + }, + { + type: 'doc', + id: 'technical-faqs/tech-faq-cawg', + }, + { + type: 'doc', + id: 'technical-faqs/tech-faq-certificates', + label: 'Signing certificate FAQs', + }, + ], + }, { type: 'category', label: 'Signing and certificates',