Settings reference
This is a beta release of this reference. It is a work in progress and may have issues or errors.
Settings
Settings for configuring all aspects of c2pa-rs.
Settings::default is used as the thread-local configuration by default.
Use Settings::new together with builder-style methods such as
with_toml to construct a configuration without modifying thread-local
state.
Properties
| Property | Type | Description | Required? | Default Value |
|---|---|---|---|---|
| builder | BuilderSettings | Settings for configuring the | NO | See BuilderSettings |
| cawg_trust | Trust | Settings for configuring the CAWG trust lists. | NO | See Trust |
| cawg_x509_signer | Either SignerSettings or Null | Settings for configuring the CAWG x509 signer, accessible via | NO | N/A |
| core | Core | Settings for configuring core features. | NO | See Core |
| signer | Either SignerSettings or Null | Settings for configuring the base C2PA signer, accessible via | NO | N/A |
| trust | Trust | Settings for configuring the C2PA trust lists. | NO | See Trust |
| verify | Verify | Settings for configuring verification. | NO | See Verify |
| version | Integer | Version of the configuration. | NO | 1 |
Definitions
ActionsSettings
Settings for configuring the "base" Actions assertion.
The reason this setting exists only for an Actions assertion is because of its mandations and reusable fields.
| Property | Type | Description | Required? | Default Value |
|---|---|---|---|---|
| all_actions_included | Boolean | Whether or not to set the Actions::all_actions_included field. | NO | N/A |
| auto_created_action | AutoActionSettings | Whether to automatically generate a c2pa.created Action assertion or error that it doesn't already exist. For more information about the mandatory conditions for a c2pa.created action assertion, see the C2PA Technical Specification. | YES | See AutoActionSettings |
| auto_opened_action | AutoActionSettings | Whether to automatically generate a c2pa.opened Action assertion or error that it doesn't already exist. For more information about the mandatory conditions for a c2pa.opened action assertion, see the C2PA Technical Specification. | YES | See AutoActionSettings |
| auto_placed_action | AutoActionSettings | Whether to automatically generate a c2pa.placed Action assertion or error that it doesn't already exist. For more information about the mandatory conditions for a c2pa.placed action assertion, see Relationship - C2PA Technical Specification | YES | See AutoActionSettings |
| templates | Array of ActionTemplateSettings | Templates to be added to the Actions::templates field. | NO | N/A |
ActionTemplateSettings
Settings for an action template.
| Property | Type | Description | Required? | Default Value |
|---|---|---|---|---|
| action | String | The label associated with this action. See (c2pa_action). | YES | N/A |
| description | String | Description of the template. | NO | N/A |
| icon | Either ResourceRef or Null | Reference to an icon. | NO | N/A |
| software_agent | Either ClaimGeneratorInfoSettings or Null | The software agent that performed the action. | NO | N/A |
| software_agent_index | Integer | 0-based index into the softwareAgents array | NO | N/A |
| source_type | Either DigitalSourceType or Null | One of the defined URI values at | NO | N/A |
| template_parameters | Object | Additional parameters for the template | NO | N/A |
AssetType
| Property | Type | Description | Required? | Default Value |
|---|---|---|---|---|
| type | String | N/A | YES | N/A |
| version | String | N/A | NO | N/A |
AutoActionSettings
Settings for the auto actions (e.g. created, opened, placed).
| Property | Type | Description | Required? | Default Value |
|---|---|---|---|---|
| enabled | Boolean | Whether to enable this auto action or not. | YES | false |
| source_type | Either DigitalSourceType or Null | The default source type for the auto action. | NO | N/A |
BuilderIntent
Represents the type of builder flow being used.
This determines how the builder will be used, such as creating a new asset, opening an existing asset, or updating an existing asset.
| Type | Description | Value |
|---|---|---|
| Object | This is a new digital creation, a DigitalSourceType is required. The Manifest must not have have a parent ingredient.
A | Object (see below) |
| String | This is an edit of a pre-existing parent asset. The Manifest must have a parent ingredient. A parent ingredient will be generated from the source stream if not otherwise provided. A `c2pa.opened action will be tied to the parent ingredient. | edit |
| String | A restricted version of Edit for non-editorial changes. There must be only one ingredient, as a parent. No changes can be made to the hashed content of the parent. There are additional restrictions on the types of changes that can be made. | update |
| Property | Type | Description | Required? | Default Value |
|---|---|---|---|---|
| create | DigitalSourceType | N/A | YES | N/A |
BuilderSettings
Settings for the Builder.
| Property | Type | Description | Required? | Default Value |
|---|---|---|---|---|
| actions | ActionsSettings | Settings for configuring fields in an Actions assertion. For more information on the reasoning behind this field see ActionsSettings. | YES | See ActionsSettings |
| auto_timestamp_assertion | TimeStampSettings | Settings for configuring auto-generation of the | YES | See TimeStampSettings |
| certificate_status_fetch | Either OcspFetchScope or Null | Whether to create The default is to not fetch them at all. For more information, see Certificate status assertion - C2PA Technical Specification. | NO | null |
| certificate_status_should_override | Boolean | Whether to only use The default value is false. | NO | null |
| claim_generator_info | Either ClaimGeneratorInfoSettings or Null | When set, used as | NO | N/A |
| created_assertion_labels | Array of String | Assertions with a base label included in this list will be automatically marked as a created assertion. Assertions not in this list will be automatically marked as gathered. Note that the label should be a base label, not including the assertion version nor instance. See more information on the difference between created vs gathered assertions in the spec here: fields - C2PA Technical Specification | NO | null |
| generate_c2pa_archive | Boolean | Whether to generate a C2PA archive (instead of zip) when writing the manifest builder. Now always defaults to true - the ability to disable it will be removed in the future. | NO | true |
| intent | Either BuilderIntent or Null | The default See | NO | null |
| prefer_box_hash | Boolean | When Formats that support Defaults to | YES | false |
| thumbnail | ThumbnailSettings | Various settings for configuring automatic thumbnail generation. | YES | See ThumbnailSettings |
| vendor | String | The name of the vendor creating the content credential. | NO | null |
ClaimGeneratorInfoOperatingSystem
| Type | Description | Value |
|---|---|---|
| Null | Whether or not to automatically infer the operating system. This option will attempt to following the [LLVM "triples"] conventions. For more information,
see | N/A |
| String | The name of the operating system. It is recommended to follow the [LLVM "triples"] conventions to define the operating system,
with the format | N/A |
ClaimGeneratorInfoSettings
Settings for the claim generator info.
| Property | Type | Description | Required? | Default Value |
|---|---|---|---|---|
| icon | Either ResourceRef or Null | Reference to an icon. | NO | N/A |
| name | String | A human readable string naming the claim_generator. | YES | N/A |
| operating_system | Either ClaimGeneratorInfoOperatingSystem or Null | Settings for the claim generator info's operating system field. | NO | N/A |
| version | String | A human readable string of the product's version. | NO | N/A |
Core
Settings to configure core features.
| Property | Type | Description | Required? | Default Value |
|---|---|---|---|---|
| allowed_network_hosts | Array of HostPattern |
The CAWG identity assertion does not currently respect this setting.
See Issue #1645.
List of host patterns that are allowed for network requests. Each pattern may include:
- A scheme (e.g. Matching is case-insensitive. A wildcard pattern such as The behavior is as follows:
- Pattern: Pattern: These settings are applied by the SDK's HTTP resolvers to restrict network requests. When network requests occur depends on the operations being performed (reading manifests, validating credentials, timestamping, etc.). | NO | null |
| backing_store_memory_threshold_in_mb | Integer | Maximum amount of data in megabytes that will be loaded into memory before being stored in temporary files on the disk. This option defaults to 512MB and can result in noticeable performance improvements. | NO | 512 |
| decode_identity_assertions | Boolean | Whether to decode CAWG This option defaults to true. | NO | true |
| max_decompressed_manifest_size_in_mb | Integer | Maximum size in megabytes of a Brotli-decompressed JUMBF manifest. Limits memory consumption from decompression bomb attacks. The default is 32 MB. | NO | 32 |
| merkle_tree_chunk_size_in_kb | Integer | Size of the This option is associated with the See more information in the spec here: bmff_based_hash - C2PA Technical Specification | NO | null |
| merkle_tree_max_proofs | Integer | Maximum number of proof hashes stored in UUID merkle boxes when generating a This option defaults to 5. See more information in the spec here: bmff_based_hash - C2PA Technical Specification | NO | 5 |
| prefer_compress_manifests | Boolean | Whether to prefer compressing manifests. This can reduce the size of the manifest. Compressed manifest are not always possible and will default back to uncompressed if the manifest contains features that are not compatible with compression. The default value is false. See more information in the spec here: Compressed manifests - C2PA Technical Specification | NO | false |
DigitalSourceType
Description of the source of an asset.
The digital source type must be either a value from the IPTC Digital Source Types or a C2PA-specific value as given in the C2PA Technical Specification.
| Type | Description | Value |
|---|---|---|
| String | Media whose digital content is effectively empty, such as a blank canvas or zero-length video. | http://c2pa.org/digitalsourcetype/empty |
| String | Data that is the result of algorithmically using a model derived from sampled content and data.
Differs from IPTC Digital Source Type | http://c2pa.org/digitalsourcetype/trainedAlgorithmicData |
| String | The media was captured from a real-life source using a digital camera or digital recording device. | http://cv.iptc.org/newscodes/digitalsourcetype/digitalCapture |
| String | The media is the result of capturing multiple frames from a real-life source using a digital camera or digital recording device, then automatically merging them into a single frame using digital signal processing techniques and/or non-generative AI. Includes High Dynamic Range (HDR) processing common in smartphone camera apps. | http://cv.iptc.org/newscodes/digitalsourcetype/computationalCapture |
| String | The media was digitised from a negative on film or other transparent medium. | http://cv.iptc.org/newscodes/digitalsourcetype/negativeFilm |
| String | The media was digitised from a positive on a transparency or other transparent medium. | http://cv.iptc.org/newscodes/digitalsourcetype/positiveFilm |
| String | The media was digitised from a non-transparent medium such as a photographic print. | http://cv.iptc.org/newscodes/digitalsourcetype/print |
| String | Minor augmentation or correction by a human, such as a digitally-retouched photo used in a magazine. | http://cv.iptc.org/newscodes/digitalsourcetype/minorHumanEdits |
| String | Augmentation, correction or enhancement by one or more humans using non-generative tools. | http://cv.iptc.org/newscodes/digitalsourcetype/humanEdits |
| String | Augmentation, correction or enhancement using a Generative AI model, such as with inpainting or outpainting operations. | http://cv.iptc.org/newscodes/digitalsourcetype/compositeWithTrainedAlgorithmicMedia |
| String | Modification or correction by algorithm without changing the main content of the media, initiated or configured by a human, such as sharpening or applying noise reduction. | http://cv.iptc.org/newscodes/digitalsourcetype/algorithmicallyEnhanced |
| String | The digital image was created by computer software. | http://cv.iptc.org/newscodes/digitalsourcetype/softwareImage |
| String | Media created by a human using digital tools. | http://cv.iptc.org/newscodes/digitalsourcetype/digitalArt |
| String | Media created by a human using non-generative tools. | http://cv.iptc.org/newscodes/digitalsourcetype/digitalCreation |
| String | Digital media representation of data via human programming or creativity. | http://cv.iptc.org/newscodes/digitalsourcetype/dataDrivenMedia |
| String | Digital media created algorithmically using an Artificial Intelligence model trained on captured content. | http://cv.iptc.org/newscodes/digitalsourcetype/trainedAlgorithmicMedia |
| String | Media created purely by an algorithm not based on any sampled training data, e.g. an image created by software using a mathematical formula. | http://cv.iptc.org/newscodes/digitalsourcetype/algorithmicMedia |
| String | A capture of the contents of the screen of a computer or mobile device. | http://cv.iptc.org/newscodes/digitalsourcetype/screenCapture |
| String | Live recording of virtual event based on Generative AI and/or captured elements. | http://cv.iptc.org/newscodes/digitalsourcetype/virtualRecording |
| String | Mix or composite of several elements, any of which may or may not be generative AI. | http://cv.iptc.org/newscodes/digitalsourcetype/composite |
| String | Mix or composite of several elements that are all captures of real life. | http://cv.iptc.org/newscodes/digitalsourcetype/compositeCapture |
| String | Mix or composite of several elements, at least one of which is Generative AI. | http://cv.iptc.org/newscodes/digitalsourcetype/compositeSynthetic |
| String | An unknown digital source type. | N/A |
HostPattern
A host/scheme pattern used to restrict network requests.
Each pattern may include:
- A scheme (e.g. https:// or http://)
- A hostname or IP address (e.g. contentauthenticity.org or 192.0.2.1)
- The hostname may contain a single leading wildcard (e.g. .contentauthenticity.org)
- An optional port (e.g. contentauthenticity.org:443 or 192.0.2.1:8080)
Matching is case-insensitive. A wildcard pattern such as .contentauthenticity.org matches
sub.contentauthenticity.org, but does not match contentauthenticity.org or fakecontentauthenticity.org.
If a scheme is present in the pattern, only URIs using the same scheme are considered a match. If the scheme
is omitted, any scheme is allowed as long as the host matches.
Pattern: *.contentauthenticity.org
- Does match:
- https://sub.contentauthenticity.org
- http://api.contentauthenticity.org
- Does not match:
- https://contentauthenticity.org (no subdomain)
- https://sub.fakecontentauthenticity.org (different host)
Pattern: http://192.0.2.1:8080
- Does match:
- http://192.0.2.1:8080
- Does not match:
- https://192.0.2.1:8080 (scheme mismatch)
- http://192.0.2.1 (port omitted)
- http://192.0.2.2:8080 (different IP address)
| Property | Type | Description | Required? | Default Value |
|---|---|---|---|---|
| type | String | A host/scheme pattern used to restrict network requests. Each pattern may include:
- A scheme (e.g. Matching is case-insensitive. A wildcard pattern such as Pattern: Pattern: | NO | N/A |
OcspFetchScope
The scope of which manifests to fetch for OCSP.
| Type | Description | Value |
|---|---|---|
| String | Fetch OCSP for all manifests. | all |
| String | Fetch OCSP for the active manifest only. | active |
ResourceRef
A reference to a resource to be used in JSON serialization.
The underlying data can be read as a stream via Reader::resource_to_streamcrate::Reader::resource_to_stream.
| Property | Type | Description | Required? | Default Value |
|---|---|---|---|---|
| alg | String | The algorithm used to hash the resource (if applicable). | NO | N/A |
| data_types | Array of AssetType | More detailed data types as defined in the C2PA spec. | NO | N/A |
| format | String | The mime type of the referenced resource. | YES | N/A |
| hash | String | The hash of the resource (if applicable). | NO | N/A |
| identifier | String | A URI that identifies the resource as referenced from the manifest. This may be a JUMBF URI, a file path, a URL or any other string. Relative JUMBF URIs will be resolved with the manifest label. Relative file paths will be resolved with the base path if provided. | YES | N/A |
SignerSettings
Settings for configuring a local or remote Signer.
| Type | Description | Value |
|---|---|---|
| Object | A signer configured locally. | local |
| Object | A signer configured remotely. | remote |
signer.local
| Property | Type | Description | Required? | Default Value |
|---|---|---|---|---|
| alg | SigningAlgSchema | Algorithm to use for signing. | YES | N/A |
| private_key | String | Private key used for signing (PEM format). | YES | N/A |
| referenced_assertions | Array of String | Referenced assertions for CAWG identity signing (optional). | NO | N/A |
| roles | Array of String | Roles for CAWG identity signing (optional). | NO | N/A |
| sign_cert | String | Certificate used for signing (PEM format). | YES | N/A |
| tsa_url | String | Time stamp authority URL for signing. | NO | N/A |
signer.remote
| Property | Type | Description | Required? | Default Value |
|---|---|---|---|---|
| alg | SigningAlgSchema | Algorithm to use for signing. | YES | N/A |
| referenced_assertions | Array of String | Referenced assertions for CAWG identity signing (optional). | NO | N/A |
| roles | Array of String | Roles for CAWG identity signing (optional). | NO | N/A |
| sign_cert | String | Certificate used for signing (PEM format). | YES | N/A |
| tsa_url | String | Time stamp authority URL for signing. | NO | N/A |
| url | String | URL that the signer will use for signing. A POST request with a byte-stream will be sent to this URL. | YES | N/A |
SigningAlgSchema
JSON Schema proxy for SigningAlg.
c2pa_raw_crypto::SigningAlg intentionally does not depend on schemars,
so it does not implement schemars::JsonSchema. SDK types that expose a
SigningAlg in their JSON schema reference this mirror (whose variants match
SigningAlg's serialized form) via #[schemars(with = "...")].
| Property | Type | Description | Required? | Default Value |
|---|---|---|---|---|
| type | Enum (Es256, Es384, Es512, Ps256, Ps384, Ps512, Ed25519) | JSON Schema proxy for
| NO | N/A |
ThumbnailFormat
Possible output types for automatic thumbnail generation.
These formats are a combination of types supported in image-rs and types defined by the IANA registry media type (as defined in the spec).
| Type | Description | Value |
|---|---|---|
| String | An image in PNG format. | png |
| String | An image in JPEG format. | jpeg |
| String | An image in GIF format. | gif |
| String | An image in WEBP format. | webp |
| String | An image in TIFF format. | tiff |
ThumbnailQuality
Quality of the thumbnail.
| Type | Description | Value |
|---|---|---|
| String | Low quality. | low |
| String | Medium quality. | medium |
| String | High quality. | high |
ThumbnailSettings
Settings for controlling automatic thumbnail generation.
| Property | Type | Description | Required? | Default Value |
|---|---|---|---|---|
| enabled | Boolean | Whether or not to automatically generate thumbnails. The default value is true.
This setting is only applicable if the crate is compiled with the add_thumbnails feature.
| YES | true |
| format | Either ThumbnailFormat or Null | Format of the thumbnail. If this field isn't specified, the thumbnail format will correspond to the input format. The default value is None. | NO | N/A |
| ignore_errors | Boolean | Whether to ignore thumbnail generation errors. This may occur, for instance, if the thumbnail media type or color layout isn't supported. The default value is true. | YES | true |
| long_edge | Integer | The size of the longest edge of the thumbnail. This function will resize the input to preserve aspect ratio. The default value is 1024. | YES | 1024 |
| prefer_smallest_format | Boolean | Whether or not to prefer a smaller sized media format for the thumbnail. Note that ThumbnailSettings::format takes precedence over this field. In addition, if the output format is unsupported, it will default to the smallest format regardless of the value of this field. For instance, if the source input type is a PNG, but it doesn't have an alpha channel, the image will be converted to a JPEG of smaller size. The default value is true. | YES | true |
| quality | ThumbnailQuality | The output quality of the thumbnail. This setting contains sensible defaults for things like quality, compression, and algorithms for various formats. The default value is | YES | "medium" |
TimeStampFetchScope
The scope of manifests to fetch timestamps for.
See TimeStampSettings for more information.
| Type | Description | Value |
|---|---|---|
| String | Fetch timestamps for only the parent manifest. | parent |
| String | Fetch timestmaps for all manifests in the manifest store. | all |
TimeStampSettings
Settings for configuring auto-generation of the TimeStamp assertion.
Useful when a manifest was signed offline and you want to attach a trusted timestamp to it later.
| Property | Type | Description | Required? | Default Value |
|---|---|---|---|---|
| enabled | Boolean | Whether to auto-generate a Note that for this setting to take effect, a timestamping authority URL must be set in the
The default value is false. | YES | false |
| fetch_scope | TimeStampFetchScope | Which manifests to fetch timestamps for. The default value is | YES | "all" |
| skip_existing | Boolean | Whether to skip fetching timestamps for manifests that already have one. This setting will account for both existing The default value is true. | YES | true |
Trust
Settings to configure the trust list.
| Property | Type | Description | Required? | Default Value |
|---|---|---|---|---|
| allowed_list | String | List of explicitly allowed certificates as a PEM bundle. | NO | null |
| trust_anchors | String | List of default trust anchor root certificates as a PEM bundle. Normally this option contains the official C2PA-recognized trust anchors found here: https://github.com/c2pa-org/conformance-public/tree/main/trust-list | NO | null |
| trust_config | String | List of allowed extended key usage (EKU) object identifiers (OID) that certificates must have. | NO | null |
| trusted_ica_issuers | Array of String | Exact-match allow-list of trusted CAWG identity claims aggregation (ICA) issuer DIDs. Each entry is a full DID string (any DID method) that is compared, after
stripping any fragment, against the The default value is empty, meaning that NO ICA issuer is trusted. This
is a deliberate secure default: a self-issued | NO | null |
| user_anchors | String | List of additional user-provided trust anchor root certificates as a PEM bundle. | NO | null |
| verify_trust_list | Boolean | Whether to verify certificates against the trust lists specified in The default value is true.
Verifying trust is REQUIRED by the CAWG spec. This option should only be used for development or testing.
| NO | true |
Verify
Settings to configure the verification process.
| Property | Type | Description | Required? | Default Value |
|---|---|---|---|---|
| ocsp_fetch | Boolean | Whether to fetch the certificates OCSP status during validation. Revocation status is checked in the following order:
1. The OCSP staple stored in the COSE claim of the manifest
2. Otherwise if The default value is false. | NO | false |
| remote_manifest_fetch | Boolean | Whether to fetch remote manifests in the following scenarios:
- Constructing a The default value is true.
This setting is only applicable if the crate is compiled with the fetch_remote_manifests feature.
| NO | true |
| skip_ingredient_conflict_resolution | Boolean | Whether to skip ingredient conflict resolution when multiple ingredients have the same manifest identifier. This settings is only applicable for C2PA v2 validation. The default value is false. See more information in the spec here: versioning_manifests_due_to_conflicts - C2PA Technical Specification | NO | false |
| strict_v1_validation | Boolean | Whether to do strictly C2PA v1 validation or otherwise the latest validation. The default value is false. | NO | false |
| verify_after_reading | Boolean | Whether to verify the manifest after reading in the The default value is true.
Disabling validation can improve reading performance, BUT it carries the risk of reading an invalid
manifest.
| NO | true |
| verify_after_sign | Boolean | Whether to verify the manifest after signing in the The default value is false. In the future, this setting will default to true.
Disabling validation can improve signing performance, BUT it carries the risk of signing an invalid
manifest.
| NO | true |
| verify_after_sign_hash | Boolean | Whether to include asset hash validation when verifying after signing. The default value is false. Has no effect when | NO | false |
| verify_timestamp_trust | Boolean | Whether to verify the timestamp certificates against the trust lists specified in The default value is true.
Verifying timestamp trust is REQUIRED by the C2PA spec. This option should only be used for development or testing.
| NO | true |
| verify_trust | Boolean | Whether to verify certificates against the trust lists specified in The default value is true.
Verifying trust is REQUIRED by the C2PA spec. This option should only be used for development or testing.
| NO | true |