diff --git a/docs/getting-started/index.mdx b/docs/getting-started/index.mdx index 856d580f..f5f5a4f6 100644 --- a/docs/getting-started/index.mdx +++ b/docs/getting-started/index.mdx @@ -6,59 +6,65 @@ import c2pa_terms from '@site/static/img/c2pa-terms.png'; import cai_levels from '@site/static/img/cai-levels.png'; import cr_pin from '@site/static/img/cr-pin.png'; -This is a technical introduction to the Content Authenticity Initiative (CAI) open-source SDK that provides initial context and an overview of the technical aspects of implementing CAI solutions. +This technical introduction explains the concepts behind the Content Authenticity Initiative (CAI) open-source SDK and the basic workflow for reading, validating, and creating Content Credentials. -The CAI open-source SDK is fully compliant with the C2PA specification, but it's important to note that the specification is more general than the SDK, which doesn't support every feature in the specification. +The SDK implements C2PA functionality for supported asset formats and platforms. Feature coverage depends on the library and release; not every feature in the specification is supported. ## Important terminology -To understand how CAI works, you need to understand some basic vocabulary. Having this vocabulary makes it easier to discuss CAI's technical aspects. The definitions below are summarized and slightly simplified from the [Glossary in the C2PA specification](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_glossary). This document is meant to convey the general concepts and may not cover all technical details or edge cases that the specification addresses. +These simplified definitions introduce the main concepts. For more detail and additional terms, see the [Glossary](glossary.mdx). -Let's start with a broad definition of _content provenance_ which means information on the creation, authorship, and editing of a digital asset such as an image. _Content Credentials_ include this provenance information, along with the cryptographic means to authenticate that the information is correctly tied to the content and is unchanged from when it was originally added. Sometimes these two terms are used to loosely mean the same thing: Technology to verify the origin and history of a digital asset. +_Content provenance_ is information about the creation, authorship, and editing of a digital asset. _Content Credentials_ record provenance with cryptographic signatures and content bindings that make tampering detectable. -In practice, Content Credentials are kept in a _C2PA manifest store_, and the CAI SDK works with that. A manifest store consists of one or more individual _manifests_, each containing information about the asset. The most recently-added manifest is called the _active manifest_. The active manifest has content bindings that can be validated with the asset; that is, it's hashed with the asset to ensure its validity. - -As illustrated below, the manifest contains _assertions_ about the asset's creation and history, wrapped up with additional information into entities called _claims_ that are digitally signed with an _actor's_ private key (the _claim signature_). +As illustrated below, a _manifest_ contains assertions about an asset, a claim that references those assertions, and a digital signature on the claim. -Now, let's drill down a bit to clarify some of these terms. +**Actor**: A person, hardware device, or software product involved in an asset's lifecycle, such as a camera, editing application, or cloud service. -**Actor**: A human or hardware or software product. For example, a camera, image editing software, cloud service, or the person using such tools. +**Asset**: Digital content, such as an image, video, or audio file or stream. The SDK supports [specific asset formats](../sdk-repos/c2pa-rs/docs/supported-formats.md). -**Asset**: A digital media file or stream of data of [certain specific image, video, or audio formats](../sdk-repos/c2pa-rs/docs/supported-formats.md). A _composed asset_ generalizes this concept, for example an image superimposed on top of another image. +**Action**: An operation performed on an asset, such as creating, cropping, or adjusting it. -**Action**: An operation that an _actor_ performs on an _asset._ For example, "create," "embed," or "change contrast." +**Assertion**: Structured information about an asset. For example, an actions assertion can record editing operations. See the [standard C2PA assertions](https://c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html#_c2pa_standard_assertions). -**Assertion**: Part of the manifest "asserted" by an actor that contains data about an asset's creation, authorship, how it's been edited, and other relevant information. For example, an assertion might be "change image contrast." For a list of standard C2PA assertions, see the [C2PA Specification](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_c2pa_standard_assertions). +**Certificate Authority (CA)**: An organization that issues digitally signed certificates under a defined certificate policy. -**Certificate Authority (CA)**: A trusted third party that verifies the identity of an organization applying for a digital certificate. After verifying the organization's identity, the CA issues a certificate and binds the organization's identity to a public key. A digital certificate can be trusted because it is chained to the CA's root certificate. +**Certificate**: A digitally signed document that binds a public key to a subject under the issuer's policy. A validator must check the certificate and its chain against an appropriate trust policy. -**Certificate** (public key certificate or digital certificate): An electronic document that vouches for the holder's identity. Like a passport, the certificate is issued by a trusted third party (the CA), cannot be forged, and contains identifying information. +**Claim**: The data that is signed in a manifest. It references assertions using cryptographic hashes, making changes to those assertions detectable. -**Claim**: Digitally-signed and tamper-evident data that references a set of _assertions_ by one or more _actors_, concerning an _asset_, and the information necessary to represent the _content binding_. For example, a claim could specify that a particular image was edited by John Doe using Product X on 05/08/2021 at 11am to change the image contrast. +**Claim signature**: A digital signature created with the signer's private key and verified using the corresponding public key. -**Claim signature**: Part of the manifest that is the digital signature on the _claim_ using an _actor's_ private key. +**Content binding**: Information associating a manifest with content. A _hard binding_ uses cryptographic hashes of protected content. A _soft binding_, such as a watermark or perceptual fingerprint, helps locate associated manifests even when metadata has been removed or content has changed. -**Content binding**: Information that associates _digital content_ to a specific manifest associated with a specific _asset_, either as a _hard binding_ or a _soft binding_. +**Ingredient**: A source asset used to create or edit another asset, potentially carrying its own provenance. For example, an edited photograph can reference the original photograph as a parent ingredient. -**Manifest** (C2PA manifest): Information about the provenance of an asset based on the combination of: +**Manifest** (C2PA manifest): A set of assertions, a claim, and a claim signature describing an asset's provenance. -- One or more _assertions_ (including content bindings). -- A single _claim_. -- A _claim signature_. +**Manifest store**: A collection of manifests associated with an asset. The _active manifest_ describes the current asset and contains content bindings that a validator checks against it. -**Manifest store**: A collection of manifests associated with asset. The most recent manifest in the manifest store is the _active manifest_, which has the set of _content bindings_ that are hashed with the asset and thus can be validated. +## How it works -For more definitions and detail, see the [C2PA specification](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_glossary). +A signed manifest store uses the binary JPEG universal metadata box format (JUMBF). The SDK provides JSON definitions for building manifests and JSON reports for reading them; these are interfaces to the binary representation, not the signed artifact itself. See [Working with manifests](../manifest/understanding.md). -## How it works +The SDK records cryptographic hashes of protected asset content in binding assertions. The signer signs the claim using a private key. A validator verifies the signature using the public key in the signing certificate, checks the referenced assertions, and compares the content bindings against the asset. Changes to protected content invalidate the [hard binding](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_binding_to_content). -A _manifest_ is a binary data structure that describes the history and identity data attached to digital asset. The CAI SDK enables applications and websites to attach a manifest to an asset and display it when requested. This helps viewers to understand the origin and evolution of the asset. +A C2PA-enabled editing tool creates a new signed manifest for its output, recording relevant actions and referencing source assets as ingredients. It does not simply rewrite the original signed claim. + +:::info What validation establishes +Successful validation provides evidence of integrity and, when the signer is trusted under the validator's policy, the source of the signature. It does not prove that the depicted content or every assertion is true or complete. Missing Content Credentials do not, by themselves, indicate that content is false. +::: -Although the manifest structure described in the C2PA specification is a complex binary structure, the CAI SDK works with a JSON manifest format that's easier to understand and use. It's essentially a declarative language for representing and creating a manifest in binary format. For more information on the CAI JSON manifest, see [Working with manifests](manifest/understanding.md). +### Basic SDK workflow -The CAI uses _cryptographic asset hashing_ to provide verifiable, tamper-evident signatures to indicate that the asset and metadata haven't been altered since the asset was published with the attached manifest. This means that a hash function converts the digital asset data to a unique "fingerprint," which is signed using a certificate. Once the credentials are signed, if the asset is changed then its fingerprint also changes. That's why it's called "tamper evident." You're not prevented from changing an image that has Content Credentials, but if you do, the credentials are no longer valid unless you change it using a tool that updates and re-hashes the credentials, along with a timestamp and optionally a description of what changed. The C2PA specification refers to this as [hard binding](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_binding_to_content). +Once you've [chosen the SDK library to use](../introduction.mdx) based on your runtime environment, the basic SDK workflow is: + +1. **Read and validate** an asset with a [Reader](../manifest/reading/reading.md). Distinguish missing from invalid Content Credentials. Inspect the validation results and the `Invalid`, `Valid`, or `Trusted` state; see [Validating manifests](../manifest/reading/validation.md). +1. **Build and sign** Content Credentials with a [Builder](../manifest/writing/writing.md), adding relevant assertions and ingredients and supplying a signer. +1. **Preserve and display** the resulting manifest store and validation results using the storage and UI guidance below. + +In the Rust library, a [Context](../sdk-repos/c2pa-rs/docs/context-settings.md) configures verification, trust, network access, and signers. Configure appropriate trust anchors and remote-fetch policies for your application. Equivalent APIs and feature availability vary across language libraries and releases. ## Introduction to public key infrastructure @@ -66,69 +72,57 @@ The CAI uses _cryptographic asset hashing_ to provide verifiable, tamper-evident For a video introduction to certificates and key management in the C2PA ecosystem, see [A closer look at private keys and certificates](https://learn.contentauthenticity.org/private-keys-and-certificates) from the Content Credentials Foundations course. ::: -For authentication, C2PA uses _public key infrastructure_ (PKI) technology, a widely used international standard: The same technology used to secure websites using HTTPS, to secure email using S/MIME, and for many other digital security purposes. C2PA uses the international [X.509](https://en.wikipedia.org/wiki/X.509) standard, the most common format for public key certificates. +For authentication, C2PA uses _public key infrastructure_ (PKI) and [X.509](https://en.wikipedia.org/wiki/X.509) certificates. The private key creates digital signatures; the corresponding public key verifies them. This does not encrypt the asset or restrict access to it. -A signed digital certificate verifies the authenticity of an entity, such as a server, a client, or an application. You typically purchase a certificate from a third-party certificate authority. A certificate can contain the following information to verify the identity of an entity: - -- **Organizational information** that uniquely identifies the owner of the certificate, such as organizational name and address. You supply this information when you get the certificate. -- **Public key**: The receiver of the certificate uses the public key to decipher encrypted data sent by the certificate owner to verify its identity. A public key has a corresponding private key used for encryption. -- **Name of the CA** that uniquely identifies the issuer of the certificate. -- **Digital signature** of the CA that verifies its authenticity. The corresponding CA certificate compares the signature to verify that the certificate originated from a trusted certificate authority. +A certificate binds the signing public key to a subject under the issuing CA's policy. The manifest includes a certificate chain that lets a validator check signatures back to a configured _trust anchor_, which can be a root or intermediate CA. A valid chain alone does not establish content integrity or factual truth; the other validation checks still matter. ## Signing and certificates -A manifest attached to an asset contains information about the origin of the asset, such as the name of the tool that created it (for example, Photoshop) and the name of the _actor_ who created or modified it. Then editing the asset using a supporting tool or site adds a new manifest (indicating the actions taken) that is signed with the certificate of the tool/site; this becomes the _active manifest_, which then references any prior manifests as ingredients. - -Each manifest is digitally signed with the application's or client's credentials. To enable validation of the credentials, the manifest also includes the signing certificate chain. The "chain" of certificates starts with the certificate from the last tool that signed the manifest (known as the "end-entity") followed by the certificate that signed it, and so on, back to the original CA issuer on the trust list. A user can trust that the manifest is valid because there is a "trust chain" that goes back to a trusted root certificate authority. That's why you need to acquire a security certificate from a legitimate certificate authority. +Signing requirements differ between prototyping and production: -In practice, to use a certificate with the CAI SDK, follow this process: +1. **Prototype with development credentials.** [Test certificates and keys](../signing/test-certs.md) let you exercise signing, but do not establish public trust and must not be used in production. +2. **Obtain an appropriate production certificate.** Follow the [C2PA certificate requirements](../signing/get-cert.md) and the requirements of your intended trust ecosystem. Conforming generator products must use a certificate chaining to the C2PA trust list; a generic email or document-signing certificate is not automatically sufficient. +3. **Protect the private key.** Use a suitable signer backed by a hardware security module (HSM) or key management service (KMS) for production. A certificate signing request (CSR) contains the public key; it does not require sharing your private key with the CA. Never include production private keys in browser code or distributed applications. -1. Purchase security credentials (certificate and key) from a certificate authority. Either email protection or document signing certificates are valid. -2. Extract the certificate by using a tool such as OpenSSL (for use during development). In production, you should host the private key in a secure environment like a hardware security module (HSM). -3. Use one of the supporting CAI libraries or C2PA Tool to sign manifests using the certificate and your private key. +A trusted time-stamp from a time-stamping authority (TSA) can establish that the signature existed while the signing certificate was valid, supporting verification after certificate expiry. This is different from a date recorded in an assertion. See [Time-stamps](../manifest/understanding.md#time-stamps). :::info -For more information on getting and using certificates, see [Signing and certificates](signing/index.md). +For the development-to-production workflow, see [Signing and certificates](../signing/index.md). ::: ### Trust lists -import verify_unknown_source from '@site/static/img/verify-cc-unknown-source.png'; +The [C2PA trust list](../conformance/trust-lists.mdx#c2pa-trust-list) contains certificate trust anchors for conforming generator products. A separate TSA trust list supports time-stamp validation. Validators must apply the appropriate trust policy; a cryptographically valid signature is not automatically from a trusted signer. -The _C2PA trust list_ is a curated list of certification authorities (CAs) that are authorized to issue signing certificates for conforming generator products. - -Conforming validator products such as the [Inspect tool on Adobe Content Authenticity (Beta)](https://inspect.cr) use the C2PA trust list to determine whether a Content Credential was issued using a certificate that can be traced back to a CA on the C2PA trust list. - -The [Verify tool](https://verify.contentauthenticity.org) uses both the [the interim trust list](../conformance/trust-lists.mdx#interim-trust-list) and the official [C2PA trust list](conformance/trust-lists.mdx#c2pa-trust-list) to determine which certificates are considered valid and indicates which trust list was used. +For current lists, legacy [interim trust list](../conformance/trust-lists.mdx#interim-trust-list) support, and tool-specific behavior, see [Trust lists](../conformance/trust-lists.mdx). ## Identity -To identify who created or modified an asset, identity needs to be verifiable and bound to an asset and its manifest store. +The identity of the manifest signer is not necessarily the identity of the content creator. A signing certificate may identify an application, device, or organization rather than the person who captured or edited an asset. :::info -The [Creator Assertions Working Group (CAWG)](https://creator-assertions.github.io/) provides a technical specification for an identity assertion for use in the C2PA ecosystem. For more information, see [Reading CAWG identity assertions](manifest/reading/reading-cawg-id.md). +The [Creator Assertions Working Group (CAWG)](https://creator-assertions.github.io/) defines identity assertions that bind identity information and roles to an asset. Their verification and issuer trust are distinct from the enclosing manifest's signature validation. See [Reading CAWG identity assertions](../manifest/reading/reading-cawg-id.md). ::: -In addition, Adobe tools can use the [Connected Accounts service](https://connected-accounts.adobe.com/) to connect social media accounts such as Behance, Instagram, or Twitter to an identity in a manifest. This service uses OAuth, so a user must be able to log in to an Adobe account to connect it. - ## Attaching and storing manifest data -Once you've generated a manifest, you must attach it to the asset for it to be useful. - -### Storing a manifest in file +The manifest store must remain associated with its asset, but it does not have to be embedded. Available options depend on the asset format and SDK: -You can embed a manifest directly in a digital asset (image, audio, or video file). Currently, this is the only approach available to developers other than Adobe, which operates the Content Credentials Cloud store. Adobe tools may both store the manifest in the file and upload it to the cloud. +| Storage | How it works | +| --- | --- | +| **Embedded** | The manifest store is stored inside the asset and travels with the file. | +| **Sidecar** | A separate `.c2pa` file accompanies the asset. Keep both files together and supply them to the reader as required by your SDK. | +| **Remote** | The asset contains a reference to an externally-hosted manifest store. The reader needs access to that location. | -Embedding a manifest in an asset usually increases the size of the file. Two things contribute to this increase: +### Storing a manifest in file -- Whether a thumbnail image is stored and its quality. This typically adds around 100KB – 1MB to the size of the file, depending on the quality of the thumbnail. -- The size of the certificate chain: Signing chain and timestamp certificate chain each may be around 10KB. +Embedding keeps the manifest store self-contained, but increases file size by an amount that depends on assertions, thumbnails, certificates, and other resources. It avoids fetching the manifest itself; trust, revocation, or other resource checks may still require network access, depending on configuration. ### Storing a manifest in the cloud -In addition to storing the manifest with the asset, Adobe tools use the _Adobe Content Credentials Cloud_, a public, persistent storage option for attribution and history data. Publishing to this cloud keeps files smaller and makes Content Credentials more resilient, because if stripped from an asset someone can find them by searching with the [Inspect tool on Adobe Content Authenticity (Beta)](https://inspect.cr). On the other hand, embedding the manifest keeps the file self-contained and means no web access is required to validate. +Any developer can create a cloud manifest storage system to host remote manifest stores; this is not limited to Adobe services. Use HTTPS and preserve the reference in the asset. Adobe Content Credentials Cloud is a separate service used by Adobe tools, not a prerequisite for remote storage. -Currently, Adobe Content Credentials Cloud (ACCC) is only available to Adobe tools, though in the future other credentials clouds may become available if other organizations want to host a credential service. Currently, most manifests will be embedded in assets since ACCC is specific to Adobe. +Remote storage alone does not ensure recovery if the reference is stripped. [Durable Content Credentials](../durable-cr/index.md) combine stored manifests with soft bindings and a lookup service to help rediscover provenance. Finding a matching manifest is not a substitute for checking its signature and applicable content bindings. ## Displaying manifest data @@ -138,19 +132,21 @@ For video walkthroughs on displaying Content Credentials, see the following from - [Progressive disclosure of Content Credentials](https://learn.contentauthenticity.org/progressive-disclosure-of-content-credentials) - [Reading and validating C2PA data with Javascript in the browser](https://learn.contentauthenticity.org/reading-and-validating-content-credentials) - [Formatting C2PA data for L1 - L3 disclosures](https://learn.contentauthenticity.org/formatting-c2pa-data-for-display) - ::: +::: -The manifest is only useful to end users if it can be displayed meaningfully in a user interface. How a UI does that is of course up to the designer, but because the full set of manifest data for an asset can be very complex, there are four recommended _levels of disclosure_: +Present provenance and validation results meaningfully rather than exposing raw manifest data alone. The [C2PA UX recommendations](https://spec.c2pa.org/specifications/specifications/2.2/ux/UX_Recommendations.html#_levels_of_information_disclosure) describe four _levels of disclosure_: - **Level 1**: Indicates that manifest data is present and whether it has been validated. - **Level 2**: Summarizes the manifest data enough to describe how the asset came to its current state. -- **Level 3**: Provides a detailed display of all relevant manifest data, including ingredient manifest. The implementation determines what's relevant and how to display it. +- **Level 3**: Provides a detailed display of relevant manifest data, including ingredient manifests. - **Level 4**: Provides the complete data including full detail of signatures and trust signals, for sophisticated, forensic investigatory use. -The example shown below illustrates one way to implement levels of disclosure: +Your UI should distinguish missing credentials, validation failures, and signer trust. Do not present the presence of a manifest or the Content Credentials pin as proof of trust. + +The illustration below shows one possible progressive-disclosure interface: - The Content Credentials pin shown over the image indicates that the image has Content Credentials (level 1). - Clicking on the pin displays level 2 information, and an **Inspect** button. -- Clicking the **Inspect** button opens the image on [ACA Inpsect](https://inspect.cr/) that provides level 3 information. +- Clicking the **Inspect** button opens a detailed view, such as [Adobe Content Authenticity Inspect](https://inspect.cr/), for level 3 information.