Struct Builder 

pub struct Builder {
    pub definition: ManifestDefinition,
    pub remote_url: Option<String>,
    pub no_embed: bool,
    pub base_path: Option<PathBuf>,
    pub intent: Option<BuilderIntent>,
    pub timestamp_manifest_labels: HashSet<String>,
    /* private fields */
}

Use a Builder to add a signed manifest to an asset.

Example: Adding a signed manifest to an asset

use std::io::Cursor;

use c2pa::{settings::Settings, Builder, SigningAlg};
use serde::Serialize;

#[derive(Serialize)]
struct Test {
    my_tag: usize,
}

{
    Settings::from_toml(include_str!("../tests/fixtures/test_settings.toml"))?;
    let mut builder = Builder::from_json(r#"{"title": "Test"}"#)?;
    builder.add_assertion("org.contentauth.test", &Test { my_tag: 42 })?;

    // embed a manifest using the signer
    let mut source = std::fs::File::open("tests/fixtures/C.jpg")?;
    let mut dest = Cursor::new(Vec::new());
    let signer = Settings::signer()?;
    let _c2pa_data = builder.sign(&signer, "image/jpeg", &mut source, &mut dest)?;
}

Fields

definition: ManifestDefinition

A collection of ingredients and assertions used to define a claim that can be signed and embedded into a file. In most cases, you create this from a JSON manifest definition.

remote_url: Option<String>

Optional remote URL for the manifest.

no_embed: bool

If true, the manifest store will not be embedded in the asset on sign.

base_path: Option<PathBuf>

👎Deprecated:

Use set_base_path() instead

Available on crate feature file_io only.

Base path to search for resources.

intent: Option<BuilderIntent>

👎Deprecated:

Use set_intent() to set or intent()

A builder should construct a created, opened or updated manifest.

timestamp_manifest_labels: HashSet<String>

Manifest labels to fetch timestamps for.

Examples of a manifest label may include:

• contentauth:urn:uuid:c2677d4b-0a93-4444-876f-ed2f2d40b8cf
• urn:c2pa:fa479510-2a7d-c165-7b26-488a267f4c6a

Implementations

impl Builder

pub fn new() -> Self

👎Deprecated:

Use Builder::default() for default settings, or Builder::from_context(context) and pass settings in the Context.

Creates a new Builder struct using thread-local settings.

Use Builder::default() for a builder with default settings, or Builder::from_context(context) to pass an explicit Context.

Returns

• A new Builder.

pub fn from_context(context: Context) -> Self

Creates a new Builder struct from a Context.

This method takes ownership of the Context and wraps it in an Arc internally. Use this for single-use contexts where you don’t need to share the context.

Use Builder::default() when no special configuration is needed. Use Builder::from_shared_context to share a context across multiple builders.

Arguments

• context - The Context to use for this Builder.

Returns

• A new Builder.

Example

// With default settings (no explicit context needed):
let builder = Builder::default();

// With custom settings:
let context = Context::new().with_settings(r#"{"verify": {"verify_after_sign": true}}"#)?;
let builder = Builder::from_context(context);

pub fn from_shared_context(context: &Arc<Context>) -> Self

Creates a new Builder struct from a shared Context.

This method allows sharing a single Context across multiple builders or readers. The Arc is cloned internally, so you pass a reference.

Arguments

• context - A reference to an Arc<Context> to share.

Returns

• A new Builder.

Example

// Create a shared context once
let ctx = Arc::new(Context::new().with_settings(r#"{"verify": {"verify_after_sign": true}}"#)?);

// Share it across multiple builders
let builder1 = Builder::from_shared_context(&ctx);
let builder2 = Builder::from_shared_context(&ctx);

pub fn context(&self) -> &Arc<Context>

Returns a reference to the Context used by this Builder.

This allows access to settings, signers, and other context configuration.

Examples

let context = Context::new();
let builder = Builder::from_context(context);

// Access settings
let settings = builder.context().settings();

pub fn set_intent(&mut self, intent: BuilderIntent) -> &mut Self

Sets the BuilderIntent for this Builder.

An intent lets the API know what kind of manifest to create. and check that you are doing the right thing. It can also do things for you, like add parent ingredients from the source asset and automatically add required c2pa.created or c2pa.opened actions. Intents are Create, Edit, or Update:

• Create requires a DigitalSourceType and is used for assets without a parent ingredient.
• Edit requires a parent ingredient and is used for most assets that are being edited.
• Update is a special case with many restrictions but is more compact than Edit.

Arguments

• intent - The BuilderIntent for this Builder.

Returns

• A mutable reference to the Builder.

pub fn intent(&self) -> Option<BuilderIntent>

Returns the current BuilderIntent for this Builder, if set. If not set, it will use the Settings default intent.

pub fn from_json(json: &str) -> Result<Self>

👎Deprecated:

Use Builder::from_context(context).with_definition(json) instead, passing a Context explicitly rather than relying on thread-local settings.

Creates a new Builder from a JSON ManifestDefinition string using thread-local settings.

Use Builder::from_context(context).with_definition(json) instead, passing an explicit Context rather than relying on thread-local settings.

Arguments

• json - A JSON string representing the ManifestDefinition.

Returns

• A new Builder.

Errors

• Returns an Error if the JSON is malformed or incorrect.

pub fn with_definition<D>(self, definition: D) -> Result<Self>

where D: TryInto<ManifestDefinition>, Error: From<D::Error>,

Sets the ManifestDefinition for this Builder.

This method accepts anything that can be converted into a ManifestDefinition, including JSON strings, ManifestDefinition objects, and serde_json::Values.

Arguments

• definition - Anything that can be converted into a ManifestDefinition:
  • A JSON string: r#"{"title": "My Image"}"#
  • A ManifestDefinition object
  • A serde_json::Value

Returns

• The modified Builder.

Errors

• Returns an Error if the definition cannot be converted.

Notes

• This will overwrite any existing definition in the Builder.

Examples

// From JSON string
let builder = Builder::new().with_definition(r#"{"title": "My Image"}"#)?;

// From ManifestDefinition
let mut def = ManifestDefinition::default();
def.title = Some("My Image".to_string());
let builder = Builder::new().with_definition(def)?;

pub fn supported_mime_types() -> Vec<String>

Returns a Vec of MIME types that the API is able to sign.

pub fn claim_version(&self) -> u8

Returns the claim version for this builder.

If not set, defaults to 2.

pub fn set_claim_generator_info<I>( &mut self, claim_generator_info: I, ) -> &mut Self

where I: Into<ClaimGeneratorInfo>,

Sets the ClaimGeneratorInfo for this Builder.

Examples

let mut builder = Builder::new();
builder.set_claim_generator_info(ClaimGeneratorInfo::new("my_app"));

pub fn set_format<S: Into<String>>(&mut self, format: S) -> &mut Self

Sets the MIME format for this Builder.

Arguments

• format - The format (MIME type) of the asset associated with this Builder.

Returns

• A mutable reference to the Builder.

pub fn set_base_path<P: Into<PathBuf>>(&mut self, base_path: P) -> &mut Self

Available on crate feature file_io only.

⚠️ Deprecated Soon This method is planned to be deprecated in a future release. Usage should be limited and temporary.

Sets the resource directory for this Builder

Arguments

• base_path - The directory to search in to find the resources.

Returns

• A mutable reference to the Builder.

pub fn set_remote_url<S: Into<String>>(&mut self, url: S) -> &mut Self

Sets the remote_url for this Builder.

The URL must return the manifest data and is injected into the destination asset when signing. For remote-only manifests, set the no_embed flag to true.

Arguments

• url - The URL where the manifest will be available.

Returns

• A mutable reference to the Builder.

pub fn set_no_embed(&mut self, no_embed: bool) -> &mut Self

Sets the no_embed flag for this Builder.

If true, the manifest store will not be embedded in the destination asset on sign. This is useful for sidecar and remote manifests.

Arguments

• no_embed - A Boolean flag to set the no_embed flag.

Returns

• A mutable reference to the Builder.

pub fn set_thumbnail<S, R>( &mut self, format: S, stream: &mut R, ) -> Result<&mut Self>

where S: Into<String>, R: Read + Seek + ?Sized,

Sets a thumbnail for the Builder.

The thumbnail should represent the associated asset for this Builder.

Arguments

• format - The format of the thumbnail.
• stream - A stream from which to read the thumbnail.

Returns

• A mutable reference to the Builder.

Errors

• Returns an Error if the thumbnail is not valid.

pub fn add_assertion<S, T>(&mut self, label: S, data: &T) -> Result<&mut Self>

where S: Into<String>, T: Serialize,

Arguments

• label - A label for the assertion.
• data - The data for the assertion. The data can be any Serde-serializable type or an AssertionDefinition.

Returns

• A mutable reference to the Builder.

Errors

• Returns an Error if the assertion is not valid.

pub fn add_assertion_json<S, T>( &mut self, label: S, data: &T, ) -> Result<&mut Self>

where S: Into<String>, T: Serialize,

Adds a JSON assertion to the manifest. Use only when the assertion must be stored in JSON format.

Arguments

• label - A label for the assertion.
• data - The data for the assertion; must be a Serde-serializable type.

Returns

• A mutable reference to the Builder.

Errors

• Returns an Error if the assertion is not valid.

pub fn add_action<T>(&mut self, action: T) -> Result<&mut Self>

where T: Serialize,

Adds a single action to the manifest. This is a convenience method for adding an action to the Actions assertion.

Arguments

• action - The action name as a string.
• data - The data for the action as a Serde-serializable type.

Returns

• A mutable reference to the Builder.

Errors

• Returns an Error if the action is not valid.

Example

use c2pa::Builder;
use serde_json::json;
let created_action = json!({
   "action": "c2pa.placed",
   "digitalSourceType": "http://c2pa.org/digitalsourcetype/empty"
});

let mut builder = Builder::new();
builder.add_action(created_action);

pub fn add_timestamp(&mut self, manifest_label: impl Into<String>) -> &mut Self

Request a trusted timestamp for manifests with the given label.

This only records the label on the builder. During signing, any matching manifest(s) will have a TimeStamp assertion generated using the configured timestamping authority (Signer::time_authority_url) if a timestamp for that manifest does not already exist.

If TimeStampSettings::enabled is specified, the manifest labels specified here and the manifest labels obtained from the setting’s scope will be merged and fetched.

Examples of a manifest label may include:

• contentauth:urn:uuid:c2677d4b-0a93-4444-876f-ed2f2d40b8cf
• urn:c2pa:fa479510-2a7d-c165-7b26-488a267f4c6a

pub fn add_ingredient_from_stream<'a, T, R>( &'a mut self, ingredient_json: T, format: &str, stream: &mut R, ) -> Result<&'a mut Ingredient>

where T: Into<String>, R: Read + Seek + Send,

Adds an Ingredient to the manifest with JSON and a stream.

Arguments

• ingredient_json - A JSON string representing the Ingredient. This ingredient is merged with the ingredient specified in the stream argument, and these values take precedence.
• format - The format of the Ingredient.
• stream - A stream from which to read the Ingredient. This ingredient is merged with the ingredient specified in the ingredient_json argument, whose values take precedence. You can specify values here that are not specified in ingredient_json.

Returns

• A mutable reference to the Ingredient.

Errors

• Returns an Error if the Ingredient is not valid

pub async fn add_ingredient_from_stream_async<'a, T, R>( &'a mut self, ingredient_json: T, format: &str, stream: &mut R, ) -> Result<&'a mut Ingredient>

where T: Into<String>, R: Read + Seek + Send,

Adds an Ingredient to the manifest with JSON and a stream.

Arguments

• ingredient_json - A JSON string representing the Ingredient. This ingredient is merged with the ingredient specified in the stream argument, and these values take precedence.
• format - The format of the Ingredient.
• stream - A stream from which to read the Ingredient. This ingredient is merged with the ingredient specified in the ingredient_json argument, whose values take precedence. You can specify values here that are not specified in ingredient_json.

Returns

• A mutable reference to the Ingredient.

Errors

• Returns an Error if the Ingredient is not valid

pub fn add_ingredient<I>(&mut self, ingredient: I) -> &mut Self

where I: Into<Ingredient>,

Adds an Ingredient to the manifest from an existing Ingredient.

pub fn add_resource( &mut self, id: &str, stream: impl Read + Seek + Send, ) -> Result<&mut Self>

Adds a resource to the manifest.

The ID must match an identifier in the manifest.

Arguments

• id - The identifier for the resource.
• stream - A stream to read the resource from.

Returns

• A mutable reference to the Builder.

Errors

• Returns an Error if the resource is not valid.

pub fn to_archive(&self, stream: impl Write + Seek) -> Result<()>

Creates a builder archive from the builder and writes it to a stream.

This will be stored in the standard application/c2pa .c2pa JUMBF format The legacy zip format will be written if builder.generate_c2pa_archive is set to false See docs/working-stores.md for more information.

Arguments

• stream - A stream to write the C2PA archive or ZIP file into.

Errors

• Returns an Error if the archive cannot be written.

pub fn write_ingredient_archive( &self, ingredient_id: &str, stream: impl Write + Seek, ) -> Result<()>

Writes a JUMBF working-store archive that contains a single ingredient from this builder.

The archive is tagged with org.contentauth.archive.metadata and labels::ARCHIVE_TYPE_INGREDIENT so it can be distinguished from a full builder archive when reading with Self::add_ingredient_from_archive.

The exported manifest is not a lossless slice of the parent: it uses one cloned ingredient and a fresh claim instance id; other ingredients are omitted.

Arguments

• ingredient_id - Ingredient label if set, otherwise instance_id.
• stream - Destination for the application/c2pa bytes.

Errors

• Returns Error::BadParam if the ingredient is not found, or JUMBF archives are disabled in settings.

pub fn with_archive(self, stream: impl Read + Seek + Send) -> Result<Self>

Add manifest store from an archive stream to the Builder.

Archives contain unsigned working stores (signed with BoxHash placeholder), so validation is skipped regardless of the Context’s verify_after_reading setting.

Arguments

• stream - The stream to read the archive from.

Returns

The updated Builder with the loaded archive content.

Errors

Returns an Error if the archive cannot be read.

Example

// Load builder from archive with custom context
let context = Context::new().with_settings(r#"{"verify": {"verify_after_reading": false}}"#)?;

let builder = Builder::from_context(context).with_archive(stream)?;

pub fn from_archive(stream: impl Read + Seek + Send) -> Result<Self>

👎Deprecated:

Use Builder::from_context(context).with_archive(stream) instead, passing a Context explicitly rather than relying on thread-local settings.

Create a Builder from an archive stream using thread-local settings.

Archives contain unsigned working stores (signed with BoxHash placeholder), so validation is skipped.

Use Builder::from_context(context).with_archive(stream) instead, passing an explicit Context rather than relying on thread-local settings.

Arguments

• stream - The stream to read the archive from.

Returns

A new Builder with thread-local context.

Errors

Returns an Error if the archive cannot be read.

Example

let builder = Builder::from_archive(stream)?;

pub fn data_hashed_placeholder( &mut self, reserve_size: usize, format: &str, ) -> Result<Vec<u8>>

Create a placeholder for a hashed data manifest.

This is only used for applications doing their own data_hashed asset management. This function does not support dynamic assertions (e.g., CAWG identity). Use Builder::placeholder if you need dynamic assertion support.

Arguments

• reserve_size - The size to reserve for the signature (taken from the signer).
• format - The format of the target asset, the placeholder will be preformatted for this format.

Returns

• The bytes of the c2pa_manifest placeholder.

Errors

• Returns an Error if the placeholder cannot be created.

pub fn needs_placeholder(&self, format: &str) -> bool

Returns whether a placeholder manifest is required for format.

Most formats need a placeholder: the C2PA manifest is embedded inside the asset (e.g. as a UUID box in BMFF or an APP11 segment in JPEG), so the exact size of the final signed manifest must be reserved in advance.

Formats whose handler implements AssetBoxHash can insert the manifest as a new independent chunk/box without disturbing existing byte offsets. When the prefer_box_hash setting in BuilderSettings is enabled, those formats skip the placeholder step entirely and use the direct-sign workflow (Builder::sign_embeddable Mode 2) instead.

The method also returns false when the builder already contains a BoxHash assertion (regardless of prefer_box_hash), since the caller has explicitly opted into the box-hash path.

Arguments

• format — MIME type or file extension of the target asset.

pub fn hash_type(&self, format: &str) -> HashType

Returns the hash binding type that will be used for the given format. This is a helper function to help know which paths a Builder may need to follow, e.g. in embeddable workflows.

Arguments

• format — MIME type or file extension of the target asset.

pub fn placeholder(&mut self, format: &str) -> Result<Vec<u8>>

Create a placeholder manifest with dynamic assertion support.

Returns composed manifest bytes (ready to embed as a C2PA UUID/APP11 box) for the placeholder manifest. The placeholder JUMBF byte length is stored internally so that Builder::sign_embeddable can zero-pad the signed JUMBF to the same size — callers do not need to retain the placeholder bytes themselves.

The signer is obtained from the Builder’s context.

This method automatically adds an appropriate hash assertion if none exists, based on the asset format. For BMFF formats, it adds a BmffHash; otherwise, it adds a DataHash. If a hash assertion already exists, it is used as-is.

Workflow

1. (Optional) Add a pre-sized hash assertion to the Builder
2. Call this method to get composed placeholder bytes
3. Embed the composed placeholder into your asset
4. Calculate the hash of the asset (excluding the placeholder)
5. Update the hash assertion in the Builder
6. Call Builder::sign_embeddable to sign the manifest

Note on using Merkle trees representation for mdat hashing

The placeholder manifest does not account for the size of the Merkles leaves. This is completely defined by the encoding or the fixed size specified by the user and cannot be known at compile time. The means that the caller must estimate the addition size to reserve in addition to the placeholder manifest size. The size of the manifest will be the size of the placeholder + at least (number of leaves * size of hash). For example, if the caller is using a fixed leaf size and sha256 hashes, then the caller must reserve at least 32 bytes for each fixed leaf chunk of the asset’s mdat in addition to the placeholder manifest size. For sha384 hashes, the caller must reserve at least 48 bytes for each fixed leaf chunk, and for sha512 hashes, the caller must reserve at least 64 bytes for each fixed leaf chunk. For variable leaf sizes, the caller must reserve at least (number of chunks * size of hash). It is OK to over-reserve, but under-reserving will lead to signing failures. Any extra reserved space should be converted to a “free” box since they will be automatically included in the hash calculation. Mekle tree use is optional and only applies to BMFF formats and the caller chooses to use hash_bmff_mdat_bytes.

Returns

• The composed placeholder bytes ready for embedding (format-specific wrapping applied).

Errors

• Returns an Error if the placeholder cannot be created or if multiple hash assertions exist.

pub fn add_bmff_hash_exclusions( &mut self, exclusions: &str, ) -> Result<&mut Self>

Sets the exclusion object for the BmffHash assertion in the Builder.

Call this before Builder::placeholder to register the list of boxes to exclude from the BMFF hash calculation. This is necessary when a composed placeholder was embedded in the asset. This information is needed upfront because BMFF exclusion, e.g. [ { “data”: [ { “value”: b64’2P7D1hsOSDySl1goh37EgQ==’, “offset”: 8 } ], “xpath”: “/uuid” } ] as specified in: https://spec.c2pa.org/specifications/specifications/2.3/specs/C2PA_Specification.html#_bmff_hash_assertion and must be included in the placeholder manifest.

This preserves the existing BmffHash’s name and algorithm; only the exclusions list is updated. Call Builder::update_hash_from_stream afterwards to compute and store the actual asset hash just before signing.

Arguments

• exclusions - JSON string representing the list of boxes to exclude from the BMFF hash calculation.

Returns

• A mutable reference to the Builder for method chaining

Errors

• Returns an Error if no BmffHash assertion exists on the Builder

Example

// set a BMFF hash excluion show how to exclude a UUID box where the value at offset 8 is '2P7D1hsOSDySl1goh37EgQ=='
builder.add_bmff_hash_exclusions(r#"[
    {
        "data": [
            {
                "value": "2P7D1hsOSDySl1goh37EgQ==",
                "offset": 8
            }
        ],
        "xpath": "/uuid"
    }
]"#)?;

pub fn set_bmff_hash_fixed_leaf_size( &mut self, leaf_size_in_kb: usize, ) -> &mut Self

Sets a fixed Merkle leaf size for the BMFF hash calculation in the Builder. This is an optional setting that affects how the BMFF hash is calculated when hashing mdat bytes as they are written (see hash_bmff_mdat_bytes). By default, the Merkle tree is generated with variable length leaves based on the chunk sizes passed in by the client. When a fixed leaf size is set, the SDK will generate Merkle leaves of the specified size (in KB) regardless of the chunk sizes passed in. This can be useful for clients that want to have more control over the Merkle tree structure or want to optimize for certain chunk sizes. This setting should be configured before calling hash_bmff_mdat_bytes and will affect all subsequent BMFF hash calculations for mdat bytes.

Arguments

• leaf_size_in_kb - The fixed leaf size in KB. If not set, the leaf size will be variable based on chunk sizes.

Returns

• A mutable reference to the Builder for method chaining

pub fn hash_bmff_mdat_bytes( &mut self, mdat_id: usize, data: &[u8], large_size: bool, ) -> Result<&mut Self>

Support hashing mdat bytes as the client writes the mdat box. This is an alternative to letting the SDK read and hash the mdat content after the fact, which can be costly for large assets. With this method, the client can pass chunks of data for each mdat, and the SDK will compute the Merkle leaves and store it in the BmffHash assertion. This requires that the placeholder manifest was created with a BmffHash assertion that has a reserved placeholder hash (call Builder::placeholder first to set this up).

This is typically called as chunk data is presented from the rendering engine and writing the output. The Merkle leaf will be the size of the chunk by default generating a Merkle tree with varible length leaves, but the leaf size can be configured by set_bmff_hash_fixed_leaf_size if the client prefers a fixed leaf size. The leaf chunking is handled by the SDK.

The Merkle tree spans a single mdat box. There is one tree per mdat. The mdat_id specifies which mdat box the chunk belongs to, and the SDK will maintain a separate Merkle tree for each mdat. The mdat_id should start from 0 and increment for each mdat box in the asset. The final Merkle tree for each mdat will be stored in the BmffHash assertion, and the client can call hash_bmff_mdat_bytes multiple times as each mdat box is written.

Only the Merkle leaves are stored (one leaf per chunk (fixed or variable)), no UUID proof boxes are generated and nothing extra needs to be appended to the asset.

Arguments

• mdat_id - The index of the mdat box (starting from 0) that the chunk belongs to.
• data - Slice of the chunk of mdat bytes to hash.
• large_size - Whether the mdat box is a large size box (greater than 4GB), which affects the generation rules.

Errors

• Returns an Error if no BmffHash assertion exists (call Builder::placeholder first)

pub fn set_data_hash_exclusions( &mut self, exclusions: Vec<HashRange>, ) -> Result<&mut Self>

Sets the exclusion ranges on the DataHash assertion in the Builder.

Call this after Builder::placeholder to register the byte region where the composed placeholder was embedded in the asset. This information is deferred because the exact offset is only known after the caller writes the placeholder into the file.

This preserves the existing DataHash’s name and algorithm; only the exclusion list is replaced. Call Builder::update_hash_from_stream afterwards to compute and store the actual asset hash.

Arguments

• exclusions - Byte ranges to skip when hashing (typically the embedded manifest region)

Returns

• A mutable reference to the Builder for method chaining

Errors

• Returns an Error if no DataHash assertion exists on the Builder

Example

// After embedding the composed placeholder at `offset` in the asset:
builder.set_data_hash_exclusions(vec![HashRange::new(
    offset as u64,
    composed_placeholder.len() as u64,
)])?;

pub fn update_hash_from_stream<R>( &mut self, format: &str, stream: &mut R, ) -> Result<&mut Self>

where R: Read + Seek + MaybeSend,

Update the hard binding assertion in the Builder by hashing an asset stream.

Automatically detects the type of hard binding on the Builder and updates it:

• BmffHash (BMFF/MP4 assets): uses the assertion’s own path-based exclusions (the C2PA UUID box, and mdat boxes when Merkle hashing is enabled). The algorithm is read from the BmffHash assertion itself.

• BoxHash (JPEG, PNG, GIF and other chunk-based formats): uses AssetBoxHash::get_box_map to enumerate the asset’s structural chunks, hashes each chunk individually, and stores the result. If prefer_box_hash is enabled in BuilderSettings and the format’s handler exposes AssetBoxHash, a BoxHash assertion is auto-created when none is present. If a BoxHash assertion already exists on the builder it is updated in-place.

• DataHash (JPEG, PNG, and other segment-based formats): reads exclusion ranges and the hash algorithm from the existing assertion (if any), hashes the stream excluding those ranges, and stores the result. If no DataHash exists yet the method creates one with no exclusions (hashing the entire stream), which is appropriate for sidecar/remote workflows.

The hash algorithm is resolved in this order:

1. The alg field of the existing hard binding assertion (if a pre-built DataHash or BmffHash was added with a specific algorithm)
2. ManifestDefinition::hash_alg — set this to use a non-default algorithm for all signing operations
3. "sha256" (the C2PA default)

If you need custom exclusion ranges (e.g. the exact byte region where you embedded a composed manifest), call Builder::set_data_hash_exclusions before calling this method:

// Caller embedded the composed placeholder at `offset` in the asset.
builder.set_data_hash_exclusions(vec![HashRange::new(
    offset as u64,
    composed_placeholder.len() as u64,
)])?;
builder.update_hash_from_stream("image/jpeg", &mut stream)?;

Arguments

• format - MIME type or file extension of the asset (e.g. "image/jpeg", "video/mp4"). Required when prefer_box_hash is enabled so the method can look up the format’s AssetBoxHash handler.
• stream - The asset stream to hash

Returns

• A mutable reference to the Builder for method chaining

Errors

• Returns an Error if hashing fails

pub fn sign_embeddable(&self, format: &str) -> Result<Vec<u8>>

Sign the manifest and return composed bytes ready for embedding.

This is the final step in the caller-owned I/O workflow. It operates in two modes depending on whether Builder::placeholder was called:

Mode 1 — placeholder workflow (BMFF streaming, pre-allocated space)

When Builder::placeholder has been called, the Builder knows the exact size of the composed placeholder that was embedded in the asset. This method builds the manifest fresh from Builder state, signs it, and zero-pads the raw JUMBF so the returned composed bytes are exactly the same size as the composed placeholder. The caller can patch them in-place without shifting any data.

Typical steps before calling this method:

1. Builder::placeholder → embed composed bytes into asset at offset O
2. (BMFF + Merkle) Builder::hash_bmff_mdat_bytes with leaf hashes
3. Builder::update_hash_from_stream to compute the asset hash
4. This method → returns composed bytes of identical size; patch asset at offset O

Mode 2 — direct workflow (BoxHash, sidecar, pre-computed bindings)

When no placeholder was generated, the Builder must already contain a valid hard binding assertion (DataHash, BmffHash, or BoxHash with a real hash value) set either by Builder::update_hash_from_stream or directly via Builder::add_assertion. This method signs the manifest as-is and returns composed bytes whose size is determined by the actual manifest content.

Arguments

• format - MIME type of the target asset (e.g. "video/mp4", "image/jpeg")

Returns

• Composed signed manifest bytes. In Mode 1 these are the same byte length as the composed placeholder returned by Builder::placeholder.

Errors

• In Mode 2, returns an Error if no valid hard binding assertion exists.
• Returns an Error if signing fails.

pub fn sign_data_hashed_embeddable( &mut self, signer: &dyn Signer, data_hash: &DataHash, format: &str, ) -> Result<Vec<u8>>

Create a signed data hashed embeddable manifest using a supplied signer.

This is used to create a manifest that can be embedded into a stream. It allows the caller to do the embedding. You must call data_hashed_placeholder first to create the placeholder. The placeholder is then injected into the asset before calculating hashes You must either pass a source stream to generate the hashes or provide the hashes.

Arguments

• signer - The signer to use.
• data_hash - The updated data_hash to use for the manifest.
• format - The format of the stream.
• source - The stream to read from.

Returns

• The bytes of the c2pa_manifest that was created (prep-formatted).

pub async fn sign_data_hashed_embeddable_async( &mut self, signer: &dyn AsyncSigner, data_hash: &DataHash, format: &str, ) -> Result<Vec<u8>>

Create a signed data hashed embeddable manifest using a supplied signer.

This is used to create a manifest that can be embedded into a stream. It allows the caller to do the embedding. You must call data_hashed_placeholder first to create the placeholder. The placeholder is then injected into the asset before calculating hashes You must either pass a source stream to generate the hashes or provide the hashes.

Arguments

• signer - The signer to use.
• data_hash - The updated data_hash to use for the manifest.
• format - The format of the stream.
• source - The stream to read from.

Returns

• The bytes of the c2pa_manifest that was created (prep-formatted).

pub fn sign_box_hashed_embeddable( &mut self, signer: &dyn Signer, format: &str, ) -> Result<Vec<u8>>

Create a signed box hashed embeddable manifest using a supplied signer.

This is used to create a manifest that can be embedded into a stream. It allows the caller to do the embedding. The manifest definition must already include a BoxHash assertion.

Arguments

• signer - The signer to use.

Returns

• The bytes of the c2pa_manifest that was created (prep-formatted).

pub async fn sign_box_hashed_embeddable_async( &mut self, signer: &dyn AsyncSigner, format: &str, ) -> Result<Vec<u8>>

Create a signed box hashed embeddable manifest using a supplied signer.

This is used to create a manifest that can be embedded into a stream. It allows the caller to do the embedding. The manifest definition must already include a BoxHash assertion.

Arguments

• signer - The signer to use.

Returns

• The bytes of the c2pa_manifest that was created (prep-formatted).

pub fn sign<R, W>( &mut self, signer: &dyn Signer, format: &str, source: &mut R, dest: &mut W, ) -> Result<Vec<u8>>

where R: Read + Seek + Send, W: Write + Read + Seek + Send,

Embed a signed manifest into a stream using a supplied signer.

Arguments

• format - The format of the stream.
• source - The source stream from which to read.
• dest - The destination stream to write.
• signer - The signer to use.

Returns

• The bytes of c2pa_manifest that was embedded.

Errors

• Returns an Error if the manifest cannot be signed.

pub async fn sign_async<R, W>( &mut self, signer: &dyn AsyncSigner, format: &str, source: &mut R, dest: &mut W, ) -> Result<Vec<u8>>

where R: Read + Seek + Send, W: Write + Read + Seek + Send,

Embed a signed manifest into a stream using a supplied signer.

Arguments

• format - The format of the stream.
• source - The source stream from which to read.
• dest - The destination stream to write.
• signer - The signer to use.

Returns

• The bytes of c2pa_manifest that was embedded.

Errors

• Returns an Error if the manifest cannot be signed.

pub fn save_to_stream<R, W>( &mut self, format: &str, source: &mut R, dest: &mut W, ) -> Result<Vec<u8>>

where R: Read + Seek + Send, W: Write + Read + Seek + Send,

Save a signed manifest to a stream using the signer from this builder’s context.

This is a convenience method that automatically gets the signer from the builder’s context and signs the manifest. The signer is created from the context’s settings if not explicitly set with Context::with_signer().

This provides a simpler alternative to sign() when you want to use the context’s configured signer rather than providing an explicit signer.

Note: This method is only available for synchronous signing. For async signing, use sign_async() with an explicit async signer.

Arguments

• format - The format of the stream.
• source - The source stream from which to read.
• dest - The destination stream to write.

Returns

• The bytes of c2pa_manifest that was embedded.

Errors

• Returns Error::MissingSignerSettings if no signer is configured in the context.
• Returns an Error if the manifest cannot be signed.

Examples

use serde_json::json;

// Create context with signer configuration
let context = Context::new().with_settings(json!({
    "builder": {
        "claim_generator_info": {"name": "My App"},
        "intent": "edit"
    }
}))?;

let mut builder = Builder::from_context(context)
    .with_definition(json!({"title": "My Image"}))?;

let mut source = std::fs::File::open("tests/fixtures/C.jpg")?;
let mut dest = Cursor::new(Vec::new());

// Save with automatic signer from context
builder.save_to_stream("image/jpeg", &mut source, &mut dest)?;

pub fn sign_fragmented_files<P: AsRef<Path>>( &mut self, signer: &dyn Signer, asset_path: P, fragment_glob: P, output_path: P, ) -> Result<()>

Available on crate feature file_io only.

Sign rendition(s) containing fragmented BMFF files.

Note: Currently this does not support files with existing C2PA manifest.

Arguments

• signer - The signer to use.
• asset_path - The path to the primary asset file or glob pattern if there are mulitple init segments in a set.
• fragment_glob - The glob pattern to the fragmented files. Do not use the full path, only the
• pattern to find the fragmented files in the same directory/subdirectory as the asset file. For example,
• if your fragmented files are named video_1.m4s, video_2.m4s, etc., then the glob pattern should be video_*.m4s.
• output_path - The path to the output file.

Errors

• Returns an Error if the manifest cannot be signed.

pub fn sign_file<S, D>( &mut self, signer: &dyn Signer, source: S, dest: D, ) -> Result<Vec<u8>>

where S: AsRef<Path>, D: AsRef<Path>,

Sign a file using a supplied signer.

Arguments

• source - The path to the source file to read from.
• dest - The path to the destination file to write to (must not already exist).
• signer - The signer to use.

Returns

• The bytes of c2pa_manifest that was created.

Errors

• Returns an Error if the manifest cannot be signed or the destination file already exists.

pub async fn sign_file_async<S, D>( &mut self, signer: &dyn AsyncSigner, source: S, dest: D, ) -> Result<Vec<u8>>

where S: AsRef<Path>, D: AsRef<Path>,

Sign a file using a supplied signer.

Arguments

• source - The path to the source file to read from.
• dest - The path to the destination file to write to (must not already exist).
• signer - The signer to use.

Returns

• The bytes of c2pa_manifest that was created.

Errors

• Returns an Error if the manifest cannot be signed or the destination file already exists.

pub fn save_to_file<S, D>(&mut self, source: S, dest: D) -> Result<Vec<u8>>

where S: AsRef<Path>, D: AsRef<Path>,

Available on crate feature file_io only.

Save a signed manifest to a file using the signer from this builder’s context.

This is a convenience method that automatically gets the signer from the builder’s context and signs the manifest. The signer is created from the context’s settings if not explicitly set with Context::with_signer().

This provides a simpler alternative to sign_file() when you want to use the context’s configured signer rather than providing an explicit signer.

Note: This method is only available for synchronous signing. For async signing, use sign_file_async() with an explicit async signer.

Arguments

• source - Path to the source file.
• dest - Path to the destination file (must not exist).

Returns

• The bytes of c2pa_manifest that was embedded.

Errors

• Returns Error::MissingSignerSettings if no signer is configured in the context.
• Returns an Error if the manifest cannot be signed or destination file already exists.

Examples

use serde_json::json;

let context = Context::new()
    .with_settings(json!({
        "builder": {"claim_generator_info": {"name": "My App"}}
    }))?;

let mut builder = Builder::from_context(context)
    .with_definition(json!({"title": "My Image"}))?;

// Save with automatic signer from context
builder.save_to_file("tests/fixtures/C.jpg", "output.jpg")?;

pub fn composed_manifest(manifest_bytes: &[u8], format: &str) -> Result<Vec<u8>>

Converts a manifest into a composed manifest with the specified format.

This wraps the bytes in the container format of the specified format. So that it can be directly embedded into a stream of that format.

Arguments

• manifest_bytes - The bytes of the manifest to convert.
• format - The format to convert to.

Returns

• The bytes of the composed manifest.

Errors

• Returns an Error if the manifest cannot be converted.

pub fn add_ingredient_from_reader( &mut self, reader: &Reader, ) -> Result<&mut Ingredient>

Add an ingredient to the manifest from a Reader.

Arguments

• reader - The Reader to get the ingredient from.

Returns

• A reference to the added ingredient.

pub fn add_ingredient_from_archive<'a, R>( &'a mut self, stream: &mut R, ) -> Result<&'a mut Ingredient>

where R: Read + Seek + Send,

Adds an ingredient from a JUMBF working-store stream produced by Self::write_ingredient_archive.

The stream must carry org.contentauth.archive.metadata with archive:type set to labels::ARCHIVE_TYPE_INGREDIENT.

Resource entries from the archive manifest (claim-level and per-ingredient) are merged into this builder when their ids are not already present, so thumbnails and similar assertions can resolve when signing.

For other application/c2pa stores, use Self::add_ingredient_from_reader or Self::add_ingredient_from_stream.

pub async fn add_ingredient_from_archive_async<'a, R>( &'a mut self, stream: &mut R, ) -> Result<&'a mut Ingredient>

where R: Read + Seek + Send,

Adds an ingredient from a JUMBF working-store stream produced by Self::write_ingredient_archive.

The stream must carry org.contentauth.archive.metadata with archive:type set to labels::ARCHIVE_TYPE_INGREDIENT.

Resource entries from the archive manifest (claim-level and per-ingredient) are merged into this builder when their ids are not already present, so thumbnails and similar assertions can resolve when signing.

For other application/c2pa stores, use Self::add_ingredient_from_reader or Self::add_ingredient_from_stream.

Trait Implementations

impl AsRef<Builder> for Builder

fn as_ref(&self) -> &Self

Converts this type into a shared reference of the (usually inferred) input type.

impl Debug for Builder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Builder

fn default() -> Builder

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Builder

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Builder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl JsonSchema for Builder

fn schema_name() -> Cow<'static, str>

The name of the generated JSON Schema.

fn schema_id() -> Cow<'static, str>

Returns a string that uniquely identifies the schema produced by this type.

fn json_schema(generator: &mut SchemaGenerator) -> Schema

Generates a JSON Schema for this type.

fn inline_schema() -> bool

Whether JSON Schemas generated for this type should be included directly in parent schemas, rather than being re-used where possible using the $ref keyword.

impl Serialize for Builder

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl TryInto<Builder> for Reader

type Error = Error

The type returned in the event of a conversion error.

fn try_into(self) -> Result<Builder>

Performs the conversion.