Understand C2PA

The Coalition for Content Provenance and Authenticity (C2PA) is a specification to provide transparency and trust in digital content. By integrating C2PA into your workflows and applications, you can enhance the credibility of your digital media. Although Truepic simplifies C2PA integration and you do not need to read the specification in order to get started, understanding the core C2PA structures can help you better utilize its features.

Tooling roles

C2PA provides a framework for adding provenance information to digital assets. There are two key roles within this framework that are essential to understand:

  • A claim generator manages the signing process and embeds C2PA metadata into the file. Claim generators are responsible for adding C2PA data such as signatures and hashes and also takes input from the software doing the signing.
    • Claim generators also connect to a timestamping authority, which provides a secure signature timestamp that shows that the file was signed during the time that the signing certificate was valid.
  • A validator extracts, formats, and verifies the data, which can be output into a JSON report. This validation report contains a combination of exact and reformatted data from the file, as well as additional information and determinations that are not actually in the file itself.

The same Truepic tool can be used for both signing and validating functions.

Optionally, a Content Credentials display takes some of the data from this validation report and maps it into fields in a consumer-friendly user interface.

Now that you know that C2PA data may be represented both in a JSON validation report and visualized in a Content Credentials display, let's look at some of the key C2PA structures. We'll show you how these structures look in both formats, and discuss their role and how they get added into the file.

Structure overview

Manifest Store
└── Manifest
    ├── Assertions
    │   ├── Assertion
    │   ├── ...
    │   └── Ingredient
    │       └── ...
    ├── Claim
    ├── Signature
    └── ...
└── ...

Within a file, provenance information is represented through a set of statements called assertions, which disclose information like how an asset was created, edited, generated, and captured. These assertions are collected and supplemented with additional data to form a digital unit known as a claim. The claim is then signed by a trusted party, producing a claim signature. The signer is the credential holder of a private key that is used to sign the claim.

All these elements—the assertions, the claim, and the claim signature—are brought together into a complete and verifiable unit known as a C2PA manifest. Each time a file is signed, a new manifest is created. The asset and the C2PA structure is cryptographically hashed so it can be verified later that the hash, and therefore the file, has not changed. This kind of hashing is referring to in C2PA as a hard binding.

The collection of C2PA manifests are held within a store in the file, and together are known as its content credentials. To sign a new version of a file, the previous version, along with any additional assets introduced, referred to as ingredients, are included. The new version would also include any assertions regarding the changes to the file.

Manifest store and manifests

A manifest store is the top-level container for all C2PA data and is represented at the highest level in a validation report. It holds manifests, each containing specific, signed details about the file's provenance.

Here’s what a collapsed JSON validation report would look like for a file containing 3 manifests, indicating that the file has been signed three times.

{
  "manifest_store": [
    ▶ {  },
    ▶ {  },
    ▶ {  }
  ]
}

The nontechnical, consumer-facing word we use in our Content Credentials display for manifests is records. Here you see the same count for the file with three manifests:

If we were to uncollapse one of the manifests in the validation report, here is what we would find at the next level. We'll review many of these in upcoming sections. Additional sections, such as validation_statuses and ai are covered in Verifying C2PA.

{
  "manifest_store": [
    ▼ { "URI": "com.truepic:urn:uuid:d3ea02c1-45f0-4d60-a6fc-229dc9f19b52",
      ▶ "assertions": { },
      ▶ "certificate": { },
      ▶ "certificate_chain": [ ],
      ▶ "claim": { },
      "is_active": true,
      ▶ "signature": { },
      ▶ "trusted_timestamp": { },
      ▶ "validation_statuses": [ ],
      ▶ "ai": { }
  }
...

🔄

How it's added to the file

When a file is signed for the first time, Truepic’s tools automatically create a new manifest store. Each subsequent signing operation involves the tool creating a new manifest structure and adding it to the existing manifest store. The tool handles the creation and management of both the manifest store and the manifest structures, so you don't need to define these elements yourself.

Assertions

Assertions are data structures which contain statements either made or gathered by the signer about the asset. Assertions can be categorized as one of the below. Unless otherwise specified, each assertion accepts only specific fields defined in the C2PA specification and is validated against the spec at signing time.

  1. Metadata, such as EXIF
  2. Actions performed on the asset
  3. Thumbnail of the asset or its ingredients
  4. Cryptographic hashes
  5. Custom assertions, which take any data structure, but as such are not validated, and may not visible in Content Credentials displays

This example shows an uncollapsed assertions object in the validation report, with all five assertion types. We also opened the actions assertion to see what those look like.

{
  ▼ "assertions": [
    ▶ "com.truepic.libc2pa": [ ], // custom assertion
    ▶ "c2pa.thumbnail.claim.jpeg": [ ], // thumbnail
    ▼ "c2pa.actions.v2": [ // actions
      {
        "status": "VALID",
        "instance_index": 0,
       "data": {
          "actions": [
            {
              "action": "c2pa.created",
              "when": "2024-08-14T21:00:06Z",
              "digitalSourceType": "https://cv.iptc.org/newscodes/digitalsourcetype/digitalCapture"
            }
          ]
        }
      }
    ],
    ▶ "stds.metadata": [ ]  // metadata
    ▶ "c2pa.hash.boxes": [ ] // cryptographic hashes
  ]
}

Here's how that information may be used in a Content Credentials display:

  • Metadata - make, model, created date displayed on an original capture, though Truepic's display doesn't currently use this information
  • Actions - list of actions as "Edits and activity," created date, AI-generated or camera-captured flag
  • Thumbnail - used throughout to reflect that manifest, as well as to allow the user to examine that version of the image, like below.

Cryptographic hashes are used to validate the content credential, but are not displayed. Custom metadata is also not displayed.

🔄

How it’s added to the file

  • Actions, metadata, and custom assertions are added by the signer (your app or workflow). Besides the assets themselves, this is the other core responsibility of your integration to provide. Learn which information to add and how to format it in Add Assertions.
    • Truepic's Lens SDK automatically adds actions, metadata, and custom assertions to original captures created with the authentic camera.
  • Truepic's tools can automatically generate and add thumbnails for some file formats, but others need to be added manually by the signer. You'll find documentation on this within each
  • Truepic's tools generate and add hash assertions automatically.

Ingredients

In C2PA, ingredients refer to any asset that has contributed to the current file being signed.

In a simple case, an ingredient is the immediately previous version of the file before the latest modifications were made. For example, let's say you started with an image of a blue cup, which you then edited to appear as a purple cup. Now that you have finished editing it, you want to sign the purple cup file. The "before" version, which is the unmodified blue cup file, would be considered an ingredient for the purple cup file that you are currently signing. Whenever you re-sign an image, the previous version of the file should be included as an ingredient.

Ingredients can also include any elements that were added to the file. For example, suppose you start with a blank canvas and import three photos of a dog, a cat, and a duck, and then composite them together. Each of those photos would be considered ingredients for the final image when you export and save it.

Ingredients may be signed files with their own manifests, or unsigned, meaning they do not have a manifest.

When adding ingredients, the specification requires action assertions to describe the changes to the file.

Ingredients are included in a validation report as children of assertions. A reference to the file name as well as its thumbnail is added. The file in the example report below has three ingredients.

{
  "manifest_store": [
    ▼ { ...
      ▼ "assertions": {
        ...
        ▶ "c2pa.ingredient": [ 3 items ],
        ▶ "c2pa.thumbnail.ingredient": [ 3 items ]
      }
...

A Content Credentials display shows thumbnails of the ingredients, sourced directly from the validation report. Since the ingredients are unsigned, the display flags them as having an unknown origin. Additionally, when multiple ingredients are present, the display adds a combined assets flag, indicating that these ingredients were used together to create the file. Finally, the display surfaces the required actions assertions from the report, highlighting that assets were added and combined.

🔄

How it’s added to the file

It’s up to the integrator to provide the ingredients and required actions to the Truepic tool during the signing process. Each tool includes functions and parameters that allow you to specify these details at signing time.

Certificate, claim, signature, timestamp

The last structures we'll review in this guide involve the signing, which is the core feature of C2PA. A signer first obtains a certificate, which is provided to the tool at signing time. The private key and certificate are used to sign a claim, ensuring the asset's integrity and authenticity. A trusted timestamp is then retrieved from a server, confirming when the signing occurred.

Truepic's tools have out-of-the-box integration with Truepic-issued certificates and timestamping authority, simplifying this process for you.

The validation report includes key details from the certificate, ensuring transparency and trust in the asset's provenance. It also provides the name of the claim generator, which is the app or software used with this asset (that's you!). A few sections are repetitive. For example, the signing tool will automatically set signature.signed_by based on certificate.organization.name. The signed_on and timestamp fields also match.

{
  "manifest_store": [
    ▼ ...
      ▼ "certificate": { 
        "subject_name": "Truepic Lens SDK v1.8.0 in Demo v1.8.0",
        "organization_name": "Demo Org",
        "organization_unit_name": "Demo Org",
        "issuer_name": "AndroidClaimSigningCA",
        "issuer_org": "Truepic",
        "valid_not_before": "2024-08-14T20:50:05Z",
        "valid_not_after": "2024-08-15T20:50:04Z",
        ...
      },
      ▶ "certificate_chain": [ ],
      ▼ "claim": {
        "claim_generator": "LensDemo_Dev/1.8.0",
        "dc:format": "image/jpeg",
        "claim_generator_info": [
          {
            "name": "Demo",
            "version": "1.8.0"
          }
        ],
        ...
      },
      ...
      ▼ "signature": {
        "signed_by": "Demo Org",
        "status": "VALID",
        "signed_on": "2024-08-14T21:00:07Z"
      },
      ▼ "trusted_timestamp": {
        "TSA": "Truepic Lens Time-Stamping Authority",
        "status": "VALID",
        "timestamp": "2024-08-14T21:00:07Z"
      },
      ...
    }
  ]
}

A Content Credentials display surfaces this information automatically. Most importantly, "Signed by," (sometimes also referred to as "Issued by") comes from the signature block. The "Created with" (sometimes also referred to as "App or device used") field comes from the claim_generator.

Truepic’s display also shows certificate and timestamp information at the record level. In C2PA, a certificate that has expired does not invalidate the file's content credential, as long as the signature timestamp falls within the validity window of the certificate (i.e., between the date the certificate was issued and its expiration date). If a signature is applied without a timestamp, the media is considered valid only during the certificate's validity period.

🔄

How it's added to the file

The implementor provides the name of their software. The other details and the claim are automatically generated by Truepic's tools from the certificate details.


What’s Next

Now that you’ve grasped the core structures and how they are represented, it's time to learn how to sign.