C2PAVerifier Class

Properties   Methods   Events   Config Settings   Errors  

Extracts and validates the C2PA Manifests embedded in an asset.

Syntax

ipworksllm.C2PAVerifier

Remarks

The C2PAVerifier class reads the Content Credentials embedded in an asset and reports what can be established about them: whether the signature is intact, whether the signer is trusted, and whether the asset bytes still match what was signed.

Supported Formats

JPEG, PNG and PDF are supported. The format is detected from the asset itself, and an asset in any other format is refused rather than reported as carrying no provenance, since those are different answers.

The PDF reader locates the manifest by its file specification's AFRelationship, so it reads manifests written by any conforming tool, not only those this product produced.

Validating an Asset

Set InputFile to the asset and call Verify. Every manifest found is then added to the Manifests collection, and one entry per check performed is added to ValidationResults.

C2PAVerifier verifier = new C2PAVerifier(); verifier.InputFile = "photo-signed.jpg"; verifier.Verify(); foreach (C2PAValidationResult result in verifier.ValidationResults) Console.WriteLine(result.Severity + " " + result.Code + ": " + result.Explanation);

Reading the Results

Validation is not a single boolean. The C2PA specification defines a status code for each individual check, and the class reports them verbatim so an application can decide how much weight to give each one. A signature that verifies but whose signer is not on a trust list is a different situation from one whose content binding fails.

Each entry in ValidationResults carries a Severity of success, informational, or failure. Codes such as claimSignature.validated and assertion.dataHash.match are successes; assertion.dataHash.mismatch means the asset was altered after signing; signingCredential.untrusted means the signature is intact but the signer does not chain to any configured trust anchor.

The ValidationStatus event fires once for each result as it is produced, which is convenient when validation should be reported incrementally rather than inspected afterwards.

The Provenance Chain

An asset may carry more than one manifest: the active manifest describes the most recent edit, and earlier manifests describe the ingredients it was built from. All of them appear in Manifests, with ActiveManifestIndex identifying the active one.

verifier.Verify(); C2PAManifest active = verifier.Manifests[verifier.ActiveManifestIndex]; Console.WriteLine("Produced by " + active.ClaimGenerator + ", signed by " + active.SignerSubject);

Trust Anchors

By default the class validates signing certificates against the built-in C2PA trust list. Additional anchors are supplied through the TrustedCerts collection, and are used in addition to the built-in list rather than instead of it, as the C2PA specification prescribes. Setting UseC2PATrustList to False restricts validation to the supplied anchors alone, which is the correct configuration for a private PKI.

Setting CheckRevocation to True additionally performs online revocation checking. Revocation information stapled into the manifest by the signer is always used when present, whether or not online checking is enabled.

Property List

---

The following is the full list of the properties of the class with short descriptions. Click on the links for further details.

Method List

---

The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

Event List

---

The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.

Config Settings

---

The following is a list of config settings for the class with short descriptions. Click on the links for further details.

ActiveManifestIndex Property (C2PAVerifier Class)

The index of the active manifest in the Manifests collection.

Syntax

public int getActiveManifestIndex();

Default Value

-1

Remarks

This property identifies which item in Manifests is the active manifest, the one describing how the asset reached its current state. The C2PA specification fixes the active manifest as the last one in the manifest store.

The value is -1 when no manifest was found.

This property is read-only and not available at design time.

CheckRevocation Property (C2PAVerifier Class)

Whether online revocation checking is performed.

Syntax

public boolean isCheckRevocation();
public void setCheckRevocation(boolean checkRevocation);

Default Value

False

Remarks

This property controls whether the class contacts OCSP responders or downloads CRLs to determine whether the signing certificate has been revoked.

Revocation information stapled into the manifest by the signer is always used when present, whether or not this property is set. Setting it to True additionally performs an online check, which requires network access and makes verification slower.

When revocation cannot be determined, verification does not fail; an informational result such as signingCredential.ocsp.inaccessible or signingCredential.ocsp.skipped is reported so the application can decide what that is worth.

The default value is False.

This property is not available at design time.

Ingredients Property (C2PAVerifier Class)

The ingredients the active Manifest declares.

Syntax

public C2PAIngredientList getIngredients();

Remarks

Each entry is an asset that went into the one being verified, together with the relationship between them. This is how an application follows provenance backwards: what this content was made from, and what that in turn came from.

The collection is empty for content that was captured rather than assembled, which is the ordinary case for a photograph straight out of a camera.

ManifestLabel names the ingredient's own Manifest when the producer embedded it. That Manifest appears in Manifests alongside the active one, so the chain can be walked without the original source asset. When ManifestLabel is empty, the producer recorded the source without embedding its Manifest and the chain stops there.

Example. Walking the provenance chain:

C2PAVerifier verifier = new C2PAVerifier(); verifier.InputFile = "edited-signed.jpg"; verifier.Verify(); Console.WriteLine("Signed by " + verifier.Manifests[verifier.ActiveManifestIndex].SignerSubject); for (int i = 0; i < verifier.Ingredients.Count; i++) { C2PAIngredient source = verifier.Ingredients[i]; Console.WriteLine(" " + source.Relationship + ": " + source.Title + " (" + source.Format + ")"); if (source.ManifestLabel.Length == 0) continue; // Its manifest travels in the same store; find who signed that one. for (int j = 0; j < verifier.Manifests.Count; j++) { if (verifier.Manifests[j].ManifestLabel == source.ManifestLabel) { Console.WriteLine(" originally signed by " + verifier.Manifests[j].SignerSubject); } } }

This property is not available at design time.

Please refer to the C2PAIngredient type for a complete list of fields.

InputData Property (C2PAVerifier Class)

The asset to process, held in memory.

Syntax

public byte[] getInputData();
public void setInputData(byte[] inputData);

Default Value

""

Remarks

This property specifies the asset to be processed as a byte array, for applications that do not work with files on disk.

When both InputFile and this property are set, InputFile takes precedence.

InputFile Property (C2PAVerifier Class)

The asset to process.

Syntax

public String getInputFile();
public void setInputFile(String inputFile);

Default Value

""

Remarks

This property specifies the asset to be processed. Set it to the full or relative path of the file.

When both this property and InputData are set, this property takes precedence.

Manifests Property (C2PAVerifier Class)

The C2PA Manifests found in the asset.

Syntax

public C2PAManifestList getManifests();

Remarks

This collection is populated by Verify with one C2PAManifest item for each manifest present in the asset.

An asset normally carries more than one: the active manifest describes the most recent edit, and the manifests before it describe the ingredients that edit was built from. Together they form the provenance chain. ActiveManifestIndex identifies the active one.

This property is read-only and not available at design time.

Please refer to the C2PAManifest type for a complete list of fields.

TrustedCerts Property (C2PAVerifier Class)

Additional trust anchors used to validate signing certificates.

Syntax

public CertificateList getTrustedCerts();

Remarks

This collection holds trust anchors supplied by the application. They are used in addition to the built-in C2PA trust list, not instead of it, which is what the C2PA specification prescribes for a validator.

Setting UseC2PATrustList to False restricts validation to the anchors in this collection alone. That is the correct configuration when validating assets signed under a private PKI, where the public C2PA trust list is irrelevant.

A signing certificate that chains to none of the active anchors produces a signingCredential.untrusted result. The signature itself may still be intact; the two conditions are reported separately so an application can tell them apart.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

UseC2PATrustList Property (C2PAVerifier Class)

Whether the built-in C2PA trust list is used.

Syntax

public boolean isUseC2PATrustList();
public void setUseC2PATrustList(boolean useC2PATrustList);

Default Value

True

Remarks

This property controls whether signing certificates are validated against the C2PA trust list built into the class, in addition to any anchors in TrustedCerts.

The default value is True, which is the configuration the C2PA specification describes for a validator: the trust anchors for the claim signing extended key usage include the C2PA trust list, and a user may configure further anchors on top of it.

Set this property to False to validate against TrustedCerts alone, which is appropriate for a private PKI where the public list has no bearing.

The built-in list is a snapshot taken when the class was built. Query the TrustListVersion and TrustListDate configuration settings to determine how current that snapshot is; supply newer anchors through TrustedCerts when it has aged.

This property is not available at design time.

ValidationResults Property (C2PAVerifier Class)

The outcome of each validation check performed.

Syntax

public C2PAValidationResultList getValidationResults();

Remarks

This collection is populated by Verify with one C2PAValidationResult item per check.

Validation is deliberately not reduced to a single boolean. The C2PA specification defines a status code for each individual check, and the class reports those codes verbatim, because the situations behind them differ in kind. A signature that verifies but whose signer is unknown is a question about trust; a content binding that fails is evidence the asset was altered. An application should decide for itself how to weigh them.

Each item carries a Severity of success, informational, or failure. Verification does not throw when a check fails; the failure appears as a result so the whole picture is available at once.

This property is read-only and not available at design time.

Please refer to the C2PAValidationResult type for a complete list of fields.

Config Method (C2PAVerifier Class)

Sets or retrieves a configuration setting.

Syntax

public String config(String configurationString);

Remarks

Config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

Reset Method (C2PAVerifier Class)

This method will reset the class.

Syntax

public void reset();

Remarks

This method will reset the class's properties to their default values.

Verify Method (C2PAVerifier Class)

Extracts and validates the C2PA Manifests in the asset.

Syntax

public void verify();

Remarks

This method reads the asset named by InputFile (or held in InputData), locates the C2PA Manifest Store, and validates it. Manifests and ValidationResults are populated when it returns.

For the active manifest, the class verifies the claim signature, builds a certificate path from the signing certificate to the active trust anchors, and recomputes the content binding hash over the asset to confirm the bytes still match what was signed.

C2PAVerifier verifier = new C2PAVerifier(); verifier.InputFile = "photo-signed.jpg"; verifier.Verify(); foreach (C2PAValidationResult result in verifier.ValidationResults) Console.WriteLine(result.Severity + " " + result.Code + ": " + result.Explanation);

A failed check does not throw. It is reported through ValidationResults and the ValidationStatus event, so that a partially trustworthy asset can be described accurately rather than merely rejected. An error is thrown only when the asset cannot be read at all, or carries no C2PA Manifest.

Error Event (C2PAVerifier Class)

Fired when information is available about errors during data delivery.

Syntax

public class DefaultC2PAVerifierEventListener implements C2PAVerifierEventListener {
  ...
  public void error(C2PAVerifierErrorEvent e) {}
  ...
}

public class C2PAVerifierErrorEvent {
  public int errorCode;
  public String description;
}

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the class throws an exception.

The ErrorCode parameter contains an error code, and the Description parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

Log Event (C2PAVerifier Class)

This event fires once for each log message.

Syntax

public class DefaultC2PAVerifierEventListener implements C2PAVerifierEventListener {
  ...
  public void log(C2PAVerifierLogEvent e) {}
  ...
}

public class C2PAVerifierLogEvent {
  public int logLevel;
  public String message;
  public String logType;
}

Remarks

This event fires once for each log message generated by the class. The verbosity is controlled by the LogLevel setting.

LogLevel indicates the level of message. Possible values are as follows:

Message is the log entry.

LogType identifies the type of log entry. Possible values are Info, Manifest, Signature, and Validation.

ManifestFound Event (C2PAVerifier Class)

Fires once for each C2PA Manifest found in the asset.

Syntax

public class DefaultC2PAVerifierEventListener implements C2PAVerifierEventListener {
  ...
  public void manifestFound(C2PAVerifierManifestFoundEvent e) {}
  ...
}

public class C2PAVerifierManifestFoundEvent {
  public String manifestLabel;
  public String claimGenerator;
  public String signerSubject;
  public boolean isActive;
}

Remarks

This event fires as each manifest is located, before validation of that manifest completes.

ManifestLabel is the manifest's identifier, a urn:c2pa value. ClaimGenerator names the tool that produced it. SignerSubject is the subject of the certificate that signed the claim. IsActive is True for the active manifest, which is the last one in the store.

The same information is available afterwards through the Manifests collection; this event is for applications that would rather report provenance as it is discovered.

ValidationStatus Event (C2PAVerifier Class)

Fires once for each validation status code produced.

Syntax

public class DefaultC2PAVerifierEventListener implements C2PAVerifierEventListener {
  ...
  public void validationStatus(C2PAVerifierValidationStatusEvent e) {}
  ...
}

public class C2PAVerifierValidationStatusEvent {
  public String code;
  public String explanation;
  public int severity;
  public String manifestLabel;
}

Remarks

This event fires as each check completes, giving the same information that is appended to ValidationResults.

Code is the status code defined by the C2PA specification, reported verbatim. Common values are claimSignature.validated and assertion.dataHash.match on success, assertion.dataHash.mismatch when the asset was altered after signing, and signingCredential.untrusted when the signature is intact but the signer chains to no configured trust anchor.

Explanation is a human-readable description of the check.

Severity is 0 (success), 1 (informational), or 2 (failure).

ManifestLabel identifies which manifest the result applies to.

C2PAIngredient Type

An asset that went into the one being described.

Remarks

This type represents an ingredient: another asset that was used to produce this one, together with the relationship between them.

Ingredients are what turn individual manifests into a provenance chain. When an editor opens a photograph and places it into a composite, the composite's manifest records the photograph as an ingredient, carrying that photograph's own manifest with it. A consumer can then walk backwards through the chain to the original capture.

• Format
• InstanceId
• ManifestLabel
• Relationship
• Title

Fields

Constructors

public C2PAIngredient();

C2PAManifest Type

One C2PA Manifest found in an asset.

Remarks

This type describes a single manifest recovered by Verify: what claimed to produce the asset at that point in its history, and who signed that claim.

An asset's manifests together form its provenance chain. The last one in the store is the active manifest, describing the most recent edit; the ones before it came along with the ingredients that edit consumed.

• ClaimGenerator
• IsActive
• ManifestLabel
• SignerSubject
• SigningTime

Fields

Constructors

public C2PAManifest();

C2PAValidationResult Type

The outcome of one validation check.

Remarks

This type holds a single result produced by Verify: one C2PA status code, what it means, and how serious it is.

The C2PA specification defines a status code per check rather than an overall verdict, because the failures differ in kind. An intact signature from an unknown signer is a question about trust; a broken content binding is evidence of tampering. Reporting them separately lets an application weigh them itself.

• Code
• Explanation
• ManifestLabel
• Severity

Fields

Constructors

public C2PAValidationResult();

Certificate Type

This is the digital certificate being used.

Remarks

This type describes the current digital certificate. The certificate may be a public or private key. The fields are used to identify or select certificates.

• EffectiveDate
• ExpirationDate
• ExtendedKeyUsage
• Fingerprint
• FingerprintSHA1
• FingerprintSHA256
• Issuer
• KeyPassword
• PrivateKey
• PrivateKeyAvailable
• PrivateKeyContainer
• PublicKey
• PublicKeyAlgorithm
• PublicKeyLength
• SerialNumber
• SignatureAlgorithm
• Store
• StorePassword
• StoreType
• SubjectAltNames
• ThumbprintMD5
• ThumbprintSHA1
• ThumbprintSHA256
• Usage
• UsageFlags
• Version
• Subject
• Encoded

Fields

Constructors

public Certificate();

public Certificate(String certificateFile);

public Certificate(byte[] encoded);

public Certificate(int storeType, String store, String storePassword, String subject);

public Certificate(int storeType, String store, String storePassword, String subject, String configurationString);

public Certificate(int storeType, String store, String storePassword, byte[] encoded);

public Certificate(int storeType, byte[] store, String storePassword, String subject);

public Certificate(int storeType, byte[] store, String storePassword, String subject, String configurationString);

public Certificate(int storeType, byte[] store, String storePassword, byte[] encoded);

Config Settings (C2PAVerifier Class)

The class accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

C2PAVerifier Config Settings

Base Config Settings

Trappable Errors (C2PAVerifier Class)

C2PAVerifier Errors