Skip to content

usage.md

Latest commit

 

History

History
209 lines (146 loc) · 8.25 KB

usage.md

File metadata and controls

209 lines (146 loc) · 8.25 KB

Using the C++ library

To use this library, include the header file in your code as follows:

#include "c2pa.hpp"

Read and validate an istream

Use the Reader constructor to read C2PA data from a stream. This constructor examines the specified stream for C2PA data in the given format and its return value is a Reader that can be used to extract more information. Exceptions are thrown on errors.

  c2pa::Context context;  // or Context(settings) or Context(json_string)
  auto reader = c2pa::Reader(context, <"FORMAT">, <"STREAM">);

The parameters are:

For example:

c2pa::Context context;
std::ifstream ifs("tests/fixtures/C.jpg", std::ios::binary);

// the Reader supports streams or file paths
auto reader = c2pa::Reader(context, "image/jpeg", ifs);

// print out the Manifest Store information
printf("Manifest Store = %s", reader.json())

// write the thumbnail into a file
std::ofstream ofs("test_thumbnail.jpg", std::ios::binary);
reader.get_resource("self#jumbf=c2pa.assertions/c2pa.thumbnail.claim.jpeg", ofs);
ifs.close();

Creating a manifest JSON definition

The manifest JSON string defines the C2PA manifest to add to the file.

A sample JSON manifest is provided in tests/fixtures/training.json.

For example:

const std::string manifest_json = R"{
    "claim_generator_info": [
      {
        "name": "c2pa-cpp test",
        "version": "0.1"
      }
    ],
    "assertions": [
    {
      "label": "c2pa.training-mining",
      "data": {
        "entries": {
          "c2pa.ai_generative_training": { "use": "notAllowed" },
          "c2pa.ai_inference": { "use": "notAllowed" },
          "c2pa.ai_training": { "use": "notAllowed" },
          "c2pa.data_mining": { "use": "notAllowed" }
        }
      }
    }
  ]
 };

Using settings

The behavior of the SDK can be configured through various settings loaded from JSON config files or JSON strings directly in the code.

SDK settings are set on the Context objects used by the Builder and Reader objects. For full details see Configuring the SDK with Context and Settings.

[!NOTE] If you don't specify a value for a property, then the SDK will use the default value. If you specify a value of null, then the property will be set to null, not the default.

Creating a Context

The Context class manages C2PA SDK configuration. There are two ways to create a context: direct construction and using ContextBuilder.

Direct construction

// Default settings
c2pa::Context context;

// From a Settings object
c2pa::Settings settings;
settings.set("builder.thumbnail.enabled", "true");
c2pa::Context context(settings);

// From a JSON configuration string
c2pa::Context context(R"({
  "builder": {
    "thumbnail": {
      "enabled": true
    }
  }
})");

Using a Context

Contexts are passed by reference to Builder and Reader constructors. The context is used only at construction; the implementation copies context state into the reader/builder, so the context does not need to outlive them.

c2pa::Context context;
c2pa::Builder builder(context, manifest_json);
c2pa::Reader reader(context, "image.jpg");

Creating a Builder

Use the Builder constructor to create a Builder instance. A Context is required as the first parameter.

  c2pa::Context context;
  auto builder = c2pa::Builder(context, "<MANIFEST_JSON>");

The parameters are:

  • context - A Context (or any IContextProvider) that configures SDK behavior. See Configuring the SDK with Context and Settings.
  • <MANIFEST_JSON> - A string in JSON format as described above, defining the manifest to be generated.

For example:

  c2pa::Context context;
  auto builder = c2pa::Builder(context, manifest_json);

Creating a Signer

For testing, you can create a signer using any supported algorithm by a Signer constructor. For the list of supported signing algorithms, see Creating and using an X.509 certificate.

There are multiple constructor forms; this example shows how to create a signer with a public/private key pair.

  Signer signer = Signer("<SIGNING_ALG>", "<PUBLIC_CERTS>",  "<PRIVATE_KEY>", "<TIMESTAMP_URL>");

The parameters are:

  • <SIGNING_ALG>- The C2paSigningAlg from c2pa.h associated with the signing function.
  • <PUBLIC_CERTS>- A buffer containing the public cert chain in PEM format.
  • <PRIVATE_KEY>- A buffer containing the private_key in PEM format.
  • <TIMESTAMP_URL>- An optional parameter containing a URL to a public Time Stamp Authority service.

For example:

Signer signer = c2pa::Signer("Es256", certs, private_key, "http://timestamp.digicert.com");

Warning

Do not access a private key and certificate directly like this in production because it's not secure. Instead use a hardware security module (HSM) and optionally a Key Management Service (KMS) to access the key; for example as shown in the C2PA Python Example.

Signing and embedding a manifest

A media file may contain many manifests in a manifest store. The active_manifest property in the manifest store identifies the most recently-added manifest. For a comprehensive reference to the JSON manifest structure, see the CAI manifest store reference.

  auto manifest_data = builder.sign(image_path, output_path, signer);

The parameters are:

  • <SOURCE_ASSET>- A file path or an istream referencing the asset to sign.
  • <OUTPUT_ASSET>- A file path or an iostream referencing the asset to generate.
  • <SIGNER> - A Signer instance.

For example:

  auto manifest_data = builder.sign("source_asset.jpg", "output_asset.jpg", signer);

CAWG identity

The C++ library can validate CAWG identity assertions.

On trust configurations

C2PA maintains two trust lists to verify the authenticity and integrity of Content Credentials attached to digital media: the C2PA trust list and the C2PA time-stamping authority (TSA) trust list. The C2PA trust list is a list of X.509 certificate trust anchors (either root or subordinate certification authorities) that issue certificates to conforming generator products under the C2PA Certificate Policy. The C2PA time-stamping authority (TSA) trust list is a list of X.509 certificate trust anchors (either root or subordinate certification authorities) that issue time-stamp signing certificates to TSAs.

Configure trust lists using the Settings and Context APIs. Using the Context API ensures proper propagation of settings (and trust) to Builder and Reader objects.

Trust affects manifest validation status: a manifest whose trust chain was verified will be flagged as Trusted.

More examples

The C++ example in examples/training.cpp uses the JSON for Modern C++ library class.

Build and run the example by entering this make command:

make examples

This example adds the manifest tests/fixtures/training.json to the image file tests/fixtures/A.jpg using the sample private key and certificate in the tests/fixtures directory.

The example displays some text to standard out that summarizes whether AI training is allowed based on the specified manifest and then saves the resulting image file with attached manifest to build/examples/training.jpg.