c2pie 0.1.0rc2

c2pie is a Python library that provides C2PA standard functionality.

---

c2pie is an open‑source Python library for constructing C2PA Content Credentials manifests that validate with c2patool and other common C2PA consumers.

The package supports building claims, assertions, and COSE signatures and embedding the manifest store into JPG/JPEG and PDF files.

🔸 Supported file extensions: JPG, JPEG, PDF

🔸 Supported Python versions: 3.9.2 - 3.14.0

🔸 C2PA Spec Version: 1.4

For more detailed feature specification, please look at the Features section.

[!WARNING] This library helps you build valid manifests, but trust decisions (anchors, allow/deny lists, TSA) are your responsibility. For production, you must provide a certificate chain anchored to an accepted trust root and configure validation policy accordingly.

For more information on generating certificates and keys for file signing proceed to the Certificates section.

Table of Contents

• 🥧 Quick start
  • Running signing from a Docker container
  • Running from your local environment using globally installed Python
    • Prerequisites
    • Usage
      • Command Line Interface
      • Code
  • Running example apps with Docker Compose
  • Validation
    • C2PA Verify Tool
    • c2patool
      • Validating test image with a Docker container
• 🥧 Certificates
  • Generating test credentials
  • Getting credentials for production
• 🥧 For developers
  • First steps
    • Using Dev Containers
    • Using a Local Environment
  • Run test applications
  • Run tests
  • Lint & format
• 🥧 Features
  • Workflow of test applications
  • Notes for PDF vs JPG/JPEG
• 🥧 Relevant links
• 🥧 Contributing
• 🥧 License

🥧 Quick start

Running signing from a Docker container

1. Run a Docker container from a Python image:

docker run --rm -it --entrypoint bash --name c2pie-test python:3.12   

2. Inside the container execute the following bash commands:

# Generate private key and certificate chain:
openssl genpkey \
-algorithm RSA-PSS \
-pkeyopt rsa_keygen_bits:2048 \
-pkeyopt rsa_pss_keygen_md:sha256 \
-pkeyopt rsa_pss_keygen_mgf1_md:sha256 \
-pkeyopt rsa_pss_keygen_saltlen:32 \
-out private_key.key

openssl req -new -x509 \
-key private_key.key \
-sha256 -days 825 \
-subj "/C=US/ST=CA/L=Somewhere/O=C2PA Test Signing Cert/OU=FOR TESTING_ONLY/CN=C2PA PSS Signer/emailAddress=[e-mail]" \
-addext "basicConstraints=critical,CA:false" \
-addext "keyUsage=critical,digitalSignature,nonRepudiation" \
-addext "extendedKeyUsage=critical,emailProtection" \
-out certificate_chain.pem

# Export created private key and certificate chain files into env variables:
export C2PIE_PRIVATE_KEY_FILE=./private_key.key
export C2PIE_CERTIFICATE_CHAIN_FILE=./certificate_chain.pem

# Install package
pip install c2pie 

# Download test image from this repo
wget https://raw.githubusercontent.com/TourmalineCore/c2pie/refs/heads/master/example_app/test_files/test_image.jpg

# Sign downloaded image
c2pie sign --input_file ./test_image.jpg

3. In a separate terminal, execute the following commands to copy the file from the container to the folder you're currently in:

docker cp c2pie-test:signed_test_image.jpg .

[!NOTE] You can use the c2pie-test container to experiment with other JPG/JPEG or PDF files.

Once you exit the container, it will be deleted automatically.

After being copied to host machine, signed files can then be validated using either of the methods from Validation section: C2PA Verify Tool or c2patool.

Running from your local environment using globally installed Python

Prerequisites

1. Python environment. Currently supported Python versions: 3.9.2 - 3.14.0. Make sure to create and activate virtual environment to avoid installing packages globally and any errors caused by that.

2. Private key and certificate chain pair. The repo contains pre-generated mock credentials in tests/credentials. You can either download and use them for a quick start or go to Certificates for instructions on how to generate a similar key-certificate pair.

3. Key and certificate filepaths exported into the current environment with:

   export C2PIE_PRIVATE_KEY_FILE=private-key.pem
   export C2PIE_CERTIFICATE_CHAIN_FILE=certificate-chain.pub
   

4. c2pie package installed in your current environment:

   pip install c2pie
   

Usage

Command Line Interface

You can run the following command to sign an input JPG or PDF file:

c2pie sign --input_file path/to/input_file

By default, signed file will be saved to the same directory as the input file with the signed_ prefix. To explicitly set output path, use:

c2pie sign --input_file path/to/input_file --output_file path/to/output_file

If the file has been successfully signed, you'll see a message like this:

Successfully signed the file tests/test_files/test_doc.pdf!
The result was saved to tests/test_files/signed_test_doc.pdf.

Code

To sign a file and save the output to the same directory:

from c2pie.signing import sign_file

input_file_path = "path/to/file"
sign_file(input_path=input_file_path)

To set a custom output path:

from c2pie.signing import sign_file

input_file_path = "path/to/file"
output_file_path = "path/to/another/file/"
sign_file(input_path=input_file_path, output_path=output_file_path)

If the file has been successfully signed, you'll see a message like this:

Successfully signed the file tests/test_files/test_doc.pdf!
The result was saved to tests/test_files/signed_test_doc.pdf.

Running example apps with Docker Compose

For a quick test of c2pie's functionality with pre-prepared environment, test files and credentials, you can run our example apps.

[!IMPORTANT] Docker is essential for running example apps.

Follow the steps:

1. Clone the c2pie repository.

2. Go to example_app directory:

   cd example_app
   

[!NOTE] By default, example apps use the latest available stable c2pie version. If you'd like to test some particular version, you can change the value of C2PIE_PACKAGE_VERSION in example_app/.example-app-env.

3. To test signing a JPG file, run:

   docker compose up c2pie-test-signing-jpg
   

   To test signing a PDF file, run:

   docker compose up c2pie-test-signing-pdf
   

   After running either of these commands, you'll see a resulting signed file appear in example_app/test_files directory with a signed- prefix and a corresponding message with c2patool validation results in your terminal like this:

   Successfully signed the file test_files/test_image.jpg!
   The result was saved to test_files/signed_test_image.jpg. 
   c2patool_validation_results:
   {
       "active_manifest": "urn:uuid:f0ce8560b76342d1bb3085cfbe6cc5e9",
       "manifests": {
       "urn:uuid:f0ce8560b76342d1bb3085cfbe6cc5e9": {
           "claim_generator": "c2pie",
       ................
   },
   "validation_results": {
       "activeManifest": {
       "success": [
           {
               "code": "claimSignature.insideValidity",
               "url": "self#jumbf=/c2pa/urn:uuid:f0ce8560b76342d1bb3085cfbe6cc5e9/c2pa.signature",
               "explanation": "claim signature valid"
           },
       ................
       },
       "validation_state": "Valid" 
   }
   

You can also set up a Jupyter Lab environment and test c2pie there by running:

docker compose up c2pie-notebooks

After running this command you should be able to access Jupyter Lab at localhost:8888 from your browser.

The existing notebooks directory already contains an example notebook with commands to test signing functionality.

Validation

C2PA Verify Tool

You can verify signed files using Verify tool.

Simply upload the file you'd like to verify.

[!IMPORTANT] Files embedded with self-signed certificates (like the ones this repository contains) won't be verified.

You'll get the following message:

The Content Credential issuer couldn’t be recognized. This file may not come from where it claims to.

Please proceed to production credentials section to find out about generating verifiable credentials.

c2patool

c2patool is a command line tool for working with C2PA manifests and media assets (audio, image or video files) provided by the C2PA Rust Library.

If you already have Rust, install c2patool with:

cargo install c2patool

To validate files with c2patool, run:

c2patool path/to/your_output.jpg
c2patool path/to/your_output.pdf

If the file has been correctly signed and validation is successful, the results you'll see in the terminal will look similar to this:

c2patool_validation_results:
{
    "active_manifest": "urn:uuid:f0ce8560b76342d1bb3085cfbe6cc5e9",
    "manifests": {
    "urn:uuid:f0ce8560b76342d1bb3085cfbe6cc5e9": {
        "claim_generator": "c2pie",
    ................
},
"validation_results": {
    "activeManifest": {
    "success": [
        {
            "code": "claimSignature.insideValidity",
            "url": "self#jumbf=/c2pa/urn:uuid:f0ce8560b76342d1bb3085cfbe6cc5e9/c2pa.signature",
            "explanation": "claim signature valid"
        },
    ................
    },
    "validation_state": "Valid" 
}

Validating test image with a Docker container

1. Run a container with Rust:

docker run --rm -it --entrypoint bash --name c2pie-validate rust:1.90.0-bullseye

2. Install c2patool in the container:

cargo install c2patool

1. To test the imaged previously signed using a Docker containerand copied to your working directory:

   In a separate terminal, copy it into the Rust container:

   docker cp ./signed_test_image.jpg c2pie-validate:signed_test_image.jpg
   

   Then validate the copied image with:

   c2patool signed_test_image.jpg
   

   If the validation was successful, you'll get an output similar to this:

   c2patool_validation_results:
   {
       "active_manifest": "urn:uuid:f0ce8560b76342d1bb3085cfbe6cc5e9",
       "manifests": {
       "urn:uuid:f0ce8560b76342d1bb3085cfbe6cc5e9": {
           "claim_generator": "c2pie",
       ................
   },
   "validation_results": {
       "activeManifest": {
       "success": [
           {
               "code": "claimSignature.insideValidity",
               "url": "self#jumbf=/c2pa/urn:uuid:f0ce8560b76342d1bb3085cfbe6cc5e9/c2pa.signature",
               "explanation": "claim signature valid"
           },
       ................
       },
       "validation_state": "Valid" 
   }
   

[!NOTE] You can validate other files in the same c2pie-validate container.

Once you exit, the container will be deleted automatically.

🥧 Certificates

Example certificate chain and key file are located in tests/credentials.

[!WARNING] This repository's credentials are suitable for development only!

Generating test credentials

You can generate your own private key and certificate chain pair for testing the package by following these steps:

1. Generate a private key:

   openssl genpkey \
   -algorithm RSA-PSS \
   -pkeyopt rsa_keygen_bits:2048 \
   -pkeyopt rsa_pss_keygen_md:sha256 \
   -pkeyopt rsa_pss_keygen_mgf1_md:sha256 \
   -pkeyopt rsa_pss_keygen_saltlen:32 \
   -out private_key.key
   

2. Generate a Self-Signed Certificate:

   openssl req -new -x509 \
   -key private_key.key \
   -sha256 -days 825 \
   -subj "/C=US/ST=CA/L=Somewhere/O=C2PA Test Signing Cert/OU=FOR TESTING_ONLY/CN=C2PA PSS Signer/emailAddress=[e-mail]" \
   -addext "basicConstraints=critical,CA:false" \
   -addext "keyUsage=critical,digitalSignature,nonRepudiation" \
   -addext "extendedKeyUsage=critical,emailProtection" \
   -out certificate_chain.pem
   

[!IMPORTANT] Remember to update environment variables C2PIE_PRIVATE_KEY_FILE and C2PIE_CERTIFICATE_CHAIN_FILE to use your newly generated key (private_key.key) and certificate chain (certificate_chain.pem) files.

[!NOTE] You can change certificate's validity period with -days option at the last step.

Getting credentials for production

🔸 Use a real document‑signing certificate (RSA‑PSS or ECDSA per C2PA);

🔸 Provide a leaf + intermediates bundle (no root);

🔸 Configure trust anchors/allow‑lists in your validator environment.

For detailed information on signing and certificates please explore the corresponding section in the Content Authenticity Initiative (CAI) documentation.

🥧 For developers

First steps

To contribute to the c2pie package development, you can use one of the following approaches after cloning the repository.

Using Dev Containers

1. Make sure you have installed Docker and Dev Containers extension for VS code.

2. Open the repo in VS Code and Reopen in Container. The container installs Python, Poetry, the package in editable mode, and configures Ruff as a default formatter, which provides linting and formatting and enables auto-fixing files on save (see .devcontainer/devcontainer.json).

Using a Local Environment

[!NOTE] We strongly recommend using Dev Containers in order to automatically create an isolated Python environment with all dependencies installed, environment variables exported and some helpful development tools included.

1. Make sure the environment you're currently in has Python and Poetry installed and their versions meet the requirements of the project. You can verify that by running:

   python --version
   poetry --version
   

2. Go to the repository's folder in terminal and run:

   poetry install
   

   This will automatically create and activate a poetry shell with project's dependencies installed.

3. To run any Python command related to the project's dependencies, remember to add poetry run in front of the command. For example:

   poetry run c2pie sign --input_file tests/test_files/test_doc.pdf
   
   poetry run ruff check
   

[!WARNING] Commands in further sections don't include poetry run by default as they are intended to be run from a Dev Container. Remember to add poetry run.

Run test applications

To run test applications, you need to fill out TEST_PDF_PATH and/or TEST_IMAGE_PATH in values in .env. Test scripts use these filepaths as input files for signing.

Also make sure that you have test certificate chain and public key in tests/credentials. They should be there by default if you've cloned the repository. If needed, you can change their filepaths in .env as well.

You can test the signing workflow with the following VS Code tasks:

🔸 Run JPG test application

🔸 Run PDF test application

Run tests

Run from terminal:

pytest

Or use the VC Code task Run unit tests. Note that the task excludes the e2e test.

Or if you'd like to get info on test coverage, use:

pytest --cov

Lint & format

You can check if there are any issues to deal with them manually:

ruff format --check .
ruff check .

Or check and automatically fix where possible:

ruff format .
ruff check . --fix

The latter option is also available via the VC Code task Lint and Format

🥧 Features

🔸 C2PA Claim (c2pa.claim) with canonical CBOR, dc:format, alg, and hashed‑URIs for assertions.

🔸 C2PA Signature (c2pa.signature) using COSE_Sign1 (PS256) with detached payload and x5chain in protected header.

🔸 Assertion Store with common assertions (e.g., c2pa.hash.data hard‑binding, schema.org CreativeWork, etc.).

🔸 Embedding

• JPG via APP11 segments (size‑driven iterative layout).
• PDF via incremental update at EOF (xref/trailer preserved; /AF + /Names/EmbeddedFiles).

🔸 Validation with c2patool (structure + signatures).

Workflow of test applications

1. Load a sample asset (tests/test_files/..);

2. Build a manifest with c2pie_GenerateAssertion, c2pie_GenerateHashDataAssertion, c2pie_GenerateManifest;

3. Embed the manifest (c2pie_EmplaceManifest);

4. Write a new asset with C2PA.

Notes for PDF vs JPG/JPEG

🔸 PDF: we append an incremental update. The c2pa.hash.data exclusion starts at len(original_pdf) and its length equals the final tail size (computed iteratively).

🔸 JPG/JPEG: we insert APP11 segments. The exclusion start is the APP11 insertion offset; the length is the final APP11 payload length (also computed iteratively).

The library takes care of iterative sizing, so the c2pa.hash.data matches exactly, otherwise validators return assertion.dataHash.mismatch.

🥧 Relevant links

∗ CAI documentation

∗ C2PA spec

∗ c2patool for validation

∗ C2PA Verify Tool

🥧 Contributing

🔸 Use Conventional Commits (e.g., feat:, fix:, style(ruff):, ci:).

🔸 Run Lint and Format task before committing.

🔸 Add unit tests for new behavior.

🥧 License

Apache License. See c2pie repository's license for more information.