c2pa¶

Submodules¶

Exceptions¶

C2paError

Exception raised for C2PA errors.

Classes¶

`Builder`	High-level wrapper for C2PA Builder operations.
`Reader`	High-level wrapper for C2PA Reader operations.
`C2paSigningAlg`	Supported signing algorithms.
`C2paSignerInfo`	Configuration for a Signer.
`Signer`	High-level wrapper for C2PA Signer operations.
`Stream`

Functions¶

`sdk_version`()	Returns the underlying c2pa-rs/c2pa-c-ffi version string
`read_ingredient_file`(path, data_dir)	Read a file as C2PA ingredient (deprecated).

Package Contents¶

class c2pa.Builder(manifest_json)¶

High-level wrapper for C2PA Builder operations.

Parameters:: manifest_json (Any)

classmethod get_supported_mime_types()¶

Get the list of supported MIME types for the Builder. This method retrieves supported MIME types from the native library.

Returns:: List of supported MIME type strings
Raises:: C2paError – If there was an error retrieving the MIME types
Return type:: list[str]

classmethod from_json(manifest_json)¶

Create a new Builder from a JSON manifest.

Parameters:: manifest_json (Any) – The JSON manifest definition
Returns:: A new Builder instance
Raises:: C2paError – If there was an error creating the builder
Return type:: Builder

classmethod from_archive(stream)¶

Create a new Builder from an archive stream.

Parameters:: stream (Any) – The stream containing the archive (any Python stream-like object)
Returns:: A new Builder instance
Raises:: C2paError – If there was an error creating the builder from archive
Return type:: Builder

close()¶

Release the builder resources.

This method ensures all resources are properly cleaned up, even if errors occur during cleanup. Errors during cleanup are logged but not raised to ensure cleanup. Multiple calls to close() are handled gracefully.

set_no_embed()¶

Set the no-embed flag.

When set, the builder will not embed a C2PA manifest store into the asset when signing. This is useful when creating cloud or sidecar manifests.

set_remote_url(remote_url)¶

Set the remote URL.

When set, the builder embeds a remote URL into the asset when signing. This is useful when creating cloud based Manifests.

Parameters:: remote_url (str) – The remote URL to set
Raises:: C2paError – If there was an error setting the remote URL

add_resource(uri, stream)¶

Add a resource to the builder.

Parameters:

uri (str) – The URI to identify the resource
stream (Any) – The stream containing the resource data (any Python stream-like object)

Raises:

C2paError – If there was an error adding the resource

add_ingredient(ingredient_json, format, source)¶

Add an ingredient to the builder (facade method). The added ingredient’s source should be a stream-like object (for instance, a file opened as stream).

Parameters:

ingredient_json (Union[str, dict]) – The JSON ingredient definition (either a JSON string or a dictionary)
format (str) – The MIME type or extension of the ingredient
source (Any) – The stream containing the ingredient data (any Python stream-like object)

Raises:

C2paError – If there was an error adding the ingredient
C2paError.Encoding – If the ingredient JSON contains invalid UTF-8 characters

Example

with open(ingredient_file_path, 'rb') as a_file:
    builder.add_ingredient(ingredient_json, "image/jpeg", a_file)

add_ingredient_from_stream(ingredient_json, format, source)¶

Add an ingredient from a stream to the builder. Explicitly named API requiring a stream as input parameter.

Parameters:

ingredient_json (Union[str, dict]) – The JSON ingredient definition (either a JSON string or a dictionary)
format (str) – The MIME type or extension of the ingredient
source (Any) – The stream containing the ingredient data (any Python stream-like object)

Raises:

C2paError – If there was an error adding the ingredient
C2paError.Encoding – If the ingredient JSON or format contains invalid UTF-8 characters

add_ingredient_from_file_path(ingredient_json, format, filepath)¶

Add an ingredient from a file path to the builder (deprecated). This is a legacy method.

Deprecated since version 0.13.0: This method is deprecated and will be removed in a future version. Use add_ingredient() with a file stream instead.

Parameters:

ingredient_json (Union[str, dict]) – The JSON ingredient definition (either a JSON string or a dictionary)
format (str) – The MIME type or extension of the ingredient
filepath (Union[str, pathlib.Path]) – The path to the file containing the ingredient data (can be a string or Path object)

Raises:

C2paError – If there was an error adding the ingredient
C2paError.Encoding – If the ingredient JSON or format contains invalid UTF-8 characters
FileNotFoundError – If the file at the specified path does not exist

add_action(action_json)¶

Add an action to the builder, that will be placed in the actions assertion array in the generated manifest.

Parameters:

action_json (Union[str, dict]) – The JSON action definition (either a JSON string or a dictionary)

Raises:

C2paError – If there was an error adding the action
C2paError.Encoding – If the action JSON contains invalid UTF-8 chars

Return type:

None

to_archive(stream)¶

Write an archive of the builder to a stream.

Parameters:: stream (Any) – The stream to write the archive to (any Python stream-like object)
Raises:: C2paError – If there was an error writing the archive
Return type:: None

sign(signer, format, source, dest=None)¶

Sign the builder’s content and write to a destination stream.

Parameters:

format (str) – The MIME type or extension of the content
source (Any) – The source stream (any Python stream-like object)
dest (Any) – The destination stream (any Python stream-like object), opened in w+b (write+read binary) mode.
signer (Signer) – The signer to use

Returns:

Manifest bytes

Raises:

C2paError – If there was an error during signing

Return type:

bytes

sign_file(source_path, dest_path, signer)¶

Sign a file and write the signed data to an output file.

Parameters:

source_path (Union[str, pathlib.Path]) – Path to the source file. We will attempt to guess the mimetype of the source file based on the extension.
dest_path (Union[str, pathlib.Path]) – Path to write the signed file to
signer (Signer) – The signer to use

Returns:

Manifest bytes

Raises:

C2paError – If there was an error during signing

Return type:

bytes

exception c2pa.C2paError(message='')¶

Bases: Exception

Exception raised for C2PA errors.

Parameters:: message (str)

message = ''¶

exception Assertion¶

Bases: Exception

Exception raised for assertion errors.

exception AssertionNotFound¶

Bases: Exception

Exception raised when an assertion is not found.

exception Decoding¶

Bases: Exception

Exception raised for decoding errors.

exception Encoding¶

Bases: Exception

Exception raised for encoding errors.

exception FileNotFound¶

Bases: Exception

Exception raised when a file is not found.

exception Io¶

Bases: Exception

Exception raised for IO errors.

exception Json¶

Bases: Exception

Exception raised for JSON errors.

exception Manifest¶

Bases: Exception

Exception raised for manifest errors.

exception ManifestNotFound¶

Bases: Exception

Exception raised when a manifest is not found.

exception NotSupported¶

Bases: Exception

Exception raised for unsupported operations.

exception Other¶

Bases: Exception

Exception raised for other errors.

exception RemoteManifest¶

Bases: Exception

Exception raised for remote manifest errors.

exception ResourceNotFound¶

Bases: Exception

Exception raised when a resource is not found.

exception Signature¶

Bases: Exception

Exception raised for signature errors.

exception Verify¶

Bases: Exception

Exception raised for verification errors.

class c2pa.Reader(format_or_path, stream=None, manifest_data=None)¶

High-level wrapper for C2PA Reader operations.

Example

with Reader("image/jpeg", output) as reader:
    manifest_json = reader.json()

Where output is either an in-memory stream or an opened file.

Parameters:

format_or_path (Union[str, pathlib.Path])
stream (Optional[Any])
manifest_data (Optional[Any])

classmethod get_supported_mime_types()¶

Get the list of supported MIME types for the Reader. This method retrieves supported MIME types from the native library.

Returns:: List of supported MIME type strings
Raises:: C2paError – If there was an error retrieving the MIME types
Return type:: list[str]

close()¶

Release the reader resources.

json()¶

Get the manifest store as a JSON string.

Returns:: The manifest store as a JSON string
Raises:: C2paError – If there was an error getting the JSON
Return type:: str

get_active_manifest()¶

Get the active manifest from the manifest store.

This method retrieves the full manifest JSON and extracts the active manifest based on the active_manifest key.

Returns:: A dictionary containing the active manifest data, including claims, assertions, ingredients, and signature information, or None if no manifest is found or if there was an error parsing the JSON.
Raises:: KeyError – If the active_manifest key is missing from the JSON
Return type:: Optional[dict]

get_manifest(label)¶

Get a specific manifest from the manifest store by its label.

This method retrieves the manifest JSON and extracts the manifest that corresponds to the provided manifest label/ID.

Parameters:: label (str) – The manifest label/ID to look up in the manifest store
Returns:: A dictionary containing the manifest data for the specified label, or None if no manifest is found or if there was an error parsing the JSON.
Raises:: KeyError – If the manifests key is missing from the JSON
Return type:: Optional[dict]

get_validation_state()¶

Get the validation state of the manifest store.

This method retrieves the full manifest JSON and extracts the validation_state field, which indicates the overall validation status of the C2PA manifest.

Returns:: The validation state as a string, or None if the validation_state field is not present or if no manifest is found or if there was an error parsing the JSON.
Return type:: Optional[str]

get_validation_results()¶

Get the validation results of the manifest store.

This method retrieves the full manifest JSON and extracts the validation_results object, which contains detailed validation information.

Returns:: The validation results as a dictionary containing validation details, or None if the validation_results field is not present or if no manifest is found or if there was an error parsing the JSON.
Return type:: Optional[dict]

resource_to_stream(uri, stream)¶

Write a resource to a stream.

Parameters:

uri (str) – The URI of the resource to write
stream (Any) – The stream to write to (any Python stream-like object)

Returns:

The number of bytes written

Raises:

C2paError – If there was an error writing the resource to stream

Return type:

int

is_embedded()¶

Check if the reader was created from an embedded manifest. This method determines whether the C2PA manifest is embedded directly in the asset file or stored remotely. :returns: True if the reader was created from an embedded manifest,

False if it was created from a remote manifest

Raises:: C2paError – If there was an error checking the embedded status
Return type:: bool

get_remote_url()¶

Get the remote URL of the manifest if it was obtained remotely. This method returns the URL from which the C2PA manifest was fetched if the reader was created from a remote manifest. If the manifest is embedded in the asset, this will return None. :returns: The remote URL as a string if the manifest was obtained remotely,

None if the manifest is embedded or no remote URL is available

Raises:: C2paError – If there was an error getting the remote URL
Return type:: Optional[str]

class c2pa.C2paSigningAlg¶

Bases: enum.IntEnum

Supported signing algorithms.

ES256 = 0¶

ES384 = 1¶

ES512 = 2¶

PS256 = 3¶

PS384 = 4¶

PS512 = 5¶

ED25519 = 6¶

class c2pa.C2paSignerInfo(alg, sign_cert, private_key, ta_url)¶

Bases: ctypes.Structure

Configuration for a Signer.

class c2pa.Signer(signer_ptr)¶

High-level wrapper for C2PA Signer operations.

Parameters:: signer_ptr (ctypes.POINTER(C2paSigner))

classmethod from_info(signer_info)¶

Create a new Signer from signer information.

Parameters:: signer_info (C2paSignerInfo) – The signer configuration
Returns:: A new Signer instance
Raises:: C2paError – If there was an error creating the signer
Return type:: Signer

classmethod from_callback(callback, alg, certs, tsa_url=None)¶

Create a signer from a callback function.

Parameters:

callback (Callable[[bytes], bytes]) – Function that signs data and returns the signature
alg (C2paSigningAlg) – The signing algorithm to use
certs (str) – Certificate chain in PEM format
tsa_url (Optional[str]) – Optional RFC 3161 timestamp authority URL

Returns:

A new Signer instance

Raises:

C2paError – If there was an error creating the signer
C2paError.Encoding – If the certificate data or TSA URL contains invalid UTF-8 characters

Return type:

Signer

close()¶

Release the signer resources.

This method ensures all resources are properly cleaned up, even if errors occur during cleanup.

Note

Multiple calls to close() are handled gracefully. Errors during cleanup are logged but not raised to ensure cleanup.

reserve_size()¶

Get the size to reserve for signatures from this signer.

Returns:: The size to reserve in bytes
Raises:: C2paError – If there was an error getting the size
Return type:: int

class c2pa.Stream(file_like_stream)¶

close()¶

Release the stream resources.

write_to_target(dest_stream)¶

property closed: bool¶

Check if the stream is closed.

Returns:: True if the stream is closed, False otherwise
Return type:: bool

property initialized: bool¶

Check if the stream is properly initialized.

Returns:: True if the stream is initialized, False otherwise
Return type:: bool

c2pa.sdk_version()¶

Returns the underlying c2pa-rs/c2pa-c-ffi version string

Return type:: str

c2pa.read_ingredient_file(path, data_dir)¶

Read a file as C2PA ingredient (deprecated). This creates the JSON string that would be used as the ingredient JSON.

Deprecated since version 0.11.0: This function is deprecated and will be removed in a future version. To read C2PA metadata, use the c2pa.c2pa.Reader class. To add ingredients to a manifest, use c2pa.c2pa.Builder.add_ingredient() instead.

Parameters:

path (Union[str, pathlib.Path]) – Path to the file to read
data_dir (Union[str, pathlib.Path]) – Directory to write binary resources to

Returns:

The ingredient as a JSON string

Raises:

C2paError – If there was an error reading the file

Return type:

str