Chilkat.CodeSign Class Overview

Chilkat.CodeSign provides Authenticode signing and verification for Windows executables and DLLs. It can add an Authenticode signature, verify an existing signature, retrieve the signer certificate after verification, and remove an Authenticode signature from a Windows EXE or DLL.

What the Class Is Used For

Use Chilkat.CodeSign when an application needs to work directly with Authenticode signatures on Windows executable files. The class focuses on a small, specific set of operations: signing an EXE or DLL, validating whether a signed EXE or DLL can be trusted, extracting information about the signature, retrieving the signer certificate, and removing an existing signature.

Add Authenticode Signatures Sign a Windows .exe or .dll using a Chilkat Cert and signing options.
Verify Signatures Validate the Authenticode signature of a Windows executable or DLL and receive signature information in a JsonObject.
Retrieve Signer Certificate After verification, obtain the signer certificate when it is fully available.
Remove Signatures Remove the Authenticode signature from a Windows executable or DLL.

Typical Workflow

  1. Choose whether the operation is signing, verification, signer-certificate retrieval, or signature removal.
  2. For signing, prepare a Cert containing or linked to the signing private key, and prepare a JsonObject containing signing options.
  3. Call AddSignature to Authenticode-sign a Windows EXE or DLL.
  4. To validate a signed file, call VerifySignature with the path and a JsonObject to receive signature details.
  5. After VerifySignature, call GetSignerCert when the signer certificate is needed.
  6. To remove an existing signature, call RemoveSignature.
  7. Check LastErrorText after any failure or unexpected result.

Core Concepts

Concept Meaning Important Members
Authenticode Signature A digital signature applied to a Windows executable or DLL so the file’s publisher and integrity can be verified. AddSignature, VerifySignature, RemoveSignature
Signing Certificate The certificate used to create the Authenticode signature. Signing requires the certificate and access to its private key. AddSignature, Cert
Signature Information Verification results and details returned in a JSON object. VerifySignature, JsonObject sigInfo
Signer Certificate The certificate found after verifying a signature, returned when it is fully available. GetSignerCert
Expired Certificate Validation Option A special option can allow Authenticode validation to avoid failing solely because the signing certificate is expired. UncommonOptions, codesign-allow-expired-cert

Core Properties

Property Purpose Guidance
HeartbeatMs Controls the interval, in milliseconds, between AbortCheck event callbacks. Default is 0, meaning no AbortCheck callbacks are triggered. Use when an application needs the ability to abort long-running method calls.
UncommonOptions Catch-all property for uncommon behavior flags. Usually left empty. Can include codesign-allow-expired-cert to avoid failing Authenticode validation because the signing certificate is expired.
LastErrorText Detailed diagnostic text for the last method or property access. Check after failures or unexpected behavior. Diagnostic information may be available even when a method succeeds.

Method Summary

Method Purpose Inputs / Outputs
AddSignature Authenticode signs a Windows DLL or EXE. Input: file path, Cert, and JsonObject options. Returns true for success.
VerifySignature Verifies the Authenticode signature of a Windows executable or DLL. Input: file path. Output: signature information in JsonObject sigInfo. Returns true if the signature verifies and the file can be trusted.
GetSignerCert Retrieves the signer certificate after VerifySignature. Output: supplied Cert object is populated when the signer certificate is fully available.
RemoveSignature Removes the Authenticode signature from a Windows executable or DLL. Input: path to the executable or DLL. Returns true for success.

Signing an EXE or DLL

AddSignature is used to add an Authenticode signature to a Windows executable or DLL.

Argument Type Role
path string Path to the Windows executable or DLL to be signed.
cert Cert Signing certificate used to create the Authenticode signature.
options JsonObject Signing options supplied as JSON.
Certificate requirement: Authenticode signing requires access to the private key associated with the signing certificate. The Cert object passed to AddSignature should provide or be linked to the required private key.

Verifying a Signature

VerifySignature verifies the Authenticode signature of a Windows executable or DLL and returns signature details in a JsonObject.

Argument Type Role
path string Path to the Windows executable or DLL whose signature should be verified.
sigInfo JsonObject Receives information about the Authenticode signature.
Verification result: A true return value indicates that the signature was verified and the EXE or DLL can be trusted. A false return value indicates verification failed; check LastErrorText and inspect the returned sigInfo when available.

Retrieving the Signer Certificate

After calling VerifySignature, call GetSignerCert to retrieve the signer certificate. The method succeeds when the signer certificate is fully available.

Step Method Purpose
1 VerifySignature Verifies the file and discovers signature information.
2 GetSignerCert Copies the signer certificate into a supplied Cert object.
Order matters: GetSignerCert is intended to be called after VerifySignature, because verification is what makes the signer certificate information available.

Removing a Signature

RemoveSignature removes the Authenticode signature from a Windows executable or DLL.

Argument Type Role
path string Path to the signed Windows executable or DLL.
Caution: Removing a signature changes the file’s trust state. Use this operation only when the application intentionally needs to strip the existing Authenticode signature.

Uncommon Options

Option Effect When to Consider It
codesign-allow-expired-cert Prevents Authenticode signature validation from failing solely because the signing certificate is expired. Use only when the application’s trust policy allows validation despite an expired signing certificate.
Default behavior: UncommonOptions defaults to the empty string and should usually remain empty unless a specific compatibility or policy need exists.

Diagnostics and Troubleshooting

Problem Area Member What to Check
Signing failed AddSignature, LastErrorText Confirm the file path, file permissions, certificate, private-key availability, and signing options.
Verification failed VerifySignature, sigInfo, LastErrorText Inspect the returned signature information and diagnostic text to determine why the signature did not verify.
Signer certificate not retrieved VerifySignature, GetSignerCert Make sure VerifySignature was called first and that the signer certificate is fully available.
Operation should be cancellable HeartbeatMs Set a heartbeat interval so AbortCheck event callbacks can occur during supported long-running operations.
Expired certificate policy UncommonOptions Consider whether codesign-allow-expired-cert matches the application’s validation policy.

Common Pitfalls

Pitfall Better Approach
Trying to sign without access to the private key. Ensure the Cert used for AddSignature has access to its associated private key.
Calling GetSignerCert before verification. Call VerifySignature first, then call GetSignerCert.
Assuming signature removal is only metadata cleanup. Treat RemoveSignature as a trust-affecting operation because it removes the Authenticode signature.
Ignoring the returned signature information. Pass a JsonObject to VerifySignature and inspect it for verification details.
Using expired-certificate validation behavior unintentionally. Leave UncommonOptions empty unless the application intentionally allows expired signing certificates.

Best Practices

Recommendation Reason
Verify after signing. Calling VerifySignature after AddSignature confirms the resulting file contains a valid Authenticode signature.
Keep signing options explicit in a JsonObject. It makes the signing configuration clear and easier to log, inspect, or reproduce.
Retrieve and inspect the signer certificate after verification when trust details matter. GetSignerCert provides access to the certificate used to sign the file when it is available.
Leave UncommonOptions empty unless there is a known need. The property is intended for uncommon compatibility or policy options.
Use HeartbeatMs for cancellable operations. It allows applications with event callbacks to abort certain operations before completion.
Check LastErrorText after any failed operation. It provides the most useful diagnostic detail for signing, verification, certificate retrieval, and signature removal failures.

Summary

Chilkat.CodeSign is a focused class for Windows Authenticode operations on executable and DLL files. It signs files with AddSignature, verifies signatures with VerifySignature, retrieves the signer certificate with GetSignerCert, and removes signatures with RemoveSignature.

The most important workflow is: sign or verify the target EXE/DLL, inspect sigInfo for verification details, retrieve the signer certificate when needed, and use LastErrorText for diagnostics when any operation fails.