Patching Outdated Third-Party Applications on Windows

Background

This guide explains the documented third-party patch workflow using the OESIS Framework. It is intended for customer implementation guidance.

Goal

• Identify the installed third-party product and how far behind the latest available version it is.
• Resolve and, where supported, download the applicable installer.
• Validate and install the patch, then confirm the resulting state.

Scope

The workflow covers third-party patching on Windows through LoadPatchDatabase, ConsumeOfflineVmodDatabase, DetectProducts, GetProductPatchLevel, GetLatestInstaller, and InstallFromFiles.

Usage

1. Flow at a glance

1. Initialize the databases: Before running detection or patching operations, load the required databases:

   • Call LoadPatchDatabase(50302) with patch.dat or patchv2.dat.
   • Call ConsumeOfflineVmodDatabase(50520) with v2mod.dat.

2. Identify the installed product and patch level: Use DetectProducts(0) to identify the installed product and obtain its product-specific signature ID. Pass that signature ID to GetProductPatchLevel(50500) to determine whether the product is current and, if not, how far behind the latest available version it is.

3. Obtain the installer: When automatic patching is supported, use GetLatestInstaller(50300) to resolve the applicable patch and, when requested, download the installer. For products that support only manual patching, obtain the installer through a trusted process and continue from InstallFromFiles. See Automatic and manual patching.

4. Validate and install: Use InstallFromFiles(50301) with the installer path and any validation parameters required by your implementation.

5. Confirm the result: Detect the product again and compare the installed version with the target version. Use GetVersion or GetProductPatchLevel to confirm the installed version or current patch level.

Missing setup	Affected call	Error returned
LoadPatchDatabase(50302)	GetLatestInstaller(50300) InstallFromFiles(50301)	WA_VMOD_ERROR_PRODUCT_NOT_SUPPORTED (-1026)
ConsumeOfflineVmodDatabase(50520)	GetProductPatchLevel(50500)	WA_VMOD_ERROR_OFFLINEVMOD_NOT_INITIALIZED (-1019)

important

GetLatestInstaller and InstallFromFiles operate independently. Values returned by GetLatestInstaller are not automatically inherited by InstallFromFiles. Pass expected_installer_sha256 and skip_signature_check: 0 explicitly when your workflow requires them. Passing the hash calculated from a file downloaded by GetLatestInstaller into InstallFromFiles confirms that the local file did not change between the two calls; it is not an independent authenticity check for the original download. See the FAQ entry about dynamic SHA-256 pass-through and Signature-verification coverage and known limitations for more detail.

2. Resolve the patch with GetLatestInstaller

GetLatestInstaller resolves patch metadata for the selected product signature. Its behavior depends on the value of the download parameter.

Checksum and other validation checks

API and mode	Checksum behavior	Other documented checks
GetLatestInstaller with download: 0	No installer is downloaded, so no local-file hash is calculated and no checksum comparison is performed.	Patch metadata is resolved for the selected product signature. The response may include the target version and installer metadata.
GetLatestInstaller with download: 1	The downloaded file's SHA-1, SHA-256, and MD5 values are computed and returned as sha1, sha256, and md5 respectively.	For download: 1, the SDK may validate the downloaded installer against the public-key or certificate information recorded for the applicable patch. When this standard engine-level check is supported and the required signer information is available, a mismatch may return WAAPI_ERROR_INVALID_SIGNATURE (-47). Signature-verification coverage is not currently uniform across the full catalog.
GetLatestInstaller with download: 2	No installer is downloaded, so no local-file hash is calculated and no checksum comparison is performed.	download: 2 is a metadata-only option for GetLatestInstaller(50300). It resolves the applicable patch without downloading the installer. Use it when the caller only needs identifiers such as patch_id or related patch metadata for correlation or a separate download process.

Important distinction

A calculated hash is not the same as a validated hash. GetLatestInstaller can calculate and return file hashes. InstallFromFiles performs checksum validation only when the caller supplies expected_installer_sha256. Signature verification is a separate control; it does not fall back to checksum comparison when signature verification is skipped, unavailable, or fails. For signature-check behavior, see Signature validation: skip_signature_check.

Installer's expected hash values

When the optional database ap_checksum.dat was provided to LoadPatchDatabase(50302), the installer's expected hashes could appear as separate fields: expected_sha1, expected_sha256, expected_md5, and expected_sha512. GetLatestInstaller does not compare or enforce these values; the caller must perform the comparison if needed.

Common resolution and download errors for GetLatestInstaller

GetLatestInstaller reports resolution and download failures through its return code. For the full list — each code, what typically causes it, and the recommended action — see Result codes for GetLatestInstaller.

One constraint is specific to this workflow: third-party patching supports a single installer entry only. Always call GetLatestInstaller with index: 0, or omit index; do not loop or iterate over index. If index: 0 does not return a usable installer, treat the product as not resolvable through automatic patching — refresh the patch data, or use the manual patch flow.

3. Validate and install with InstallFromFiles

InstallFromFiles installs a file already on disk. The file may have been downloaded by GetLatestInstaller or delivered by another mechanism. The call requires Administrator privilege. OPSWAT recommends installing one product at a time — do not call InstallFromFiles concurrently for more than one signature.

Signature validation: skip_signature_check

Value	Behavior
1 (default)	Signature verification is skipped.
0	Signature verification is requested. Any verification failure halts installation before execution.

With skip_signature_check: 1 (the default), signature verification is skipped. With skip_signature_check: 0, the SDK requests signature verification before execution. Where the applicable patch data contains signing information and the standard engine-level check is supported, the SDK compares the installer's public key or certificate with the information recorded in the patch database. If they differ, the operation may return WAAPI_ERROR_INVALID_SIGNATURE (-47). This applies to installers downloaded by GetLatestInstaller and to installers supplied through another trusted process. This signature check is separate from checksum handling; it does not compare sha256 with expected_sha256 and does not automatically fall back to checksum validation.

Treat skip_signature_check: 0 as a request rather than a guarantee. For a small number of products the patch data itself disables the engine-level check — typically where the product's own install script performs the verification instead — and in that case the check does not run even though you passed 0. Where the outcome matters, combine it with checksum verification; see What is the recommended best practice if no static checksum or OPSWAT signature check is available for a product?.

For additional context on skip_signature_check, see the OPSWAT KB article Skip signature check in the InstallFromFiles method.

Common resolution and errors for InstallFromFiles

InstallFromFiles reports validation and installation outcomes through its return code. For the full list — each code, what typically causes it, and the recommended action — see Result codes for InstallFromFiles.

One outcome shapes the rest of this workflow: an installation can complete and still require a restart, reported as the special success codes WA_VMOD_INSTALLATION_NEED_RESTART (1003) (operating-system restart) and WA_VMOD_INSTALLATION_NEED_APPLICATION_RESTART (1005) (application restart). Treat both as successful installs, prompt for the matching restart, then confirm the version as described in 4. Version confirmation. For the distinction between the two, see the OPSWAT KB article How the OESIS SDK distinguishes OS restart and application restart when patching products.

4. Version confirmation

1. Use minimum_version returned by GetLatestInstaller as the baseline version floor for the resolved patch. After patching, the installed version should be equal to or greater than minimum_version. For products using common installer links, such as Google Chrome, the vendor may deliver a build newer than minimum_version; this is expected behavior. If your deployment policy requires locking to a specific version, use requested_version or supply a known expected_installer_sha256. See the FAQ entry Why does GetLatestInstaller return minimum_version rather than an exact target version? for more detail.
2. InstallFromFiles performs a post-install version check in normal installation scenarios. If the detected version does not change as expected, the operation may return WA_VMOD_ERROR_INSTALLATION_FAILED (-1034). When installation completion requires a restart, the final version may not be visible immediately. As a final workflow step, detect the product again and use GetVersion or GetProductPatchLevel to confirm the resulting state.

5. Workflow diagram

Automatic and manual patching

Not every product supports OPSWAT-managed installer retrieval. Where GetLatestInstaller can resolve and, optionally, download the installer, use it as described above. Where a product supports only manual patching, the customer obtains the installer through its own trusted process and continues the workflow from InstallFromFiles onward; manual patching skips only the GetLatestInstaller step, not the rest of the workflow. For more details, see the OPSWAT KB article How to Identify Automatic vs Manual Patching Using Analog Files.

FAQ

Why does GetLatestInstaller return minimum_version rather than an exact target version?

For applications using common installer links, such as Google Chrome, the vendor download URL always delivers the latest build available from the vendor at the time of download. This build may be newer than the static version currently indexed in OPSWAT patch data. For that reason, minimum_version represents the minimum expected version floor, not a guaranteed exact version match. If your deployment policy requires a specific version, use requested_version where supported, or validate against a known expected_installer_sha256.

What validation checks are performed during GetLatestInstaller when download is 1?

When download: 1 is set, the SDK downloads the installer and performs the following operations:

• Digital signature verification: Where the applicable patch data contains signing information and the standard engine-level check is supported, the engine validates the installer's code signature against the certificate metadata in patch.dat / patchv2.dat. A mismatch returns WAAPI_ERROR_INVALID_SIGNATURE (-47).
• Hash calculation: SHA-1, SHA-256, and MD5 hashes are computed and returned to the caller. GetLatestInstaller does not compare these hashes against catalog values. If checksum validation is required, perform it in InstallFromFiles by passing expected_installer_sha256.

For GetLatestInstaller with download 1, are there exceptions where OPSWAT digital signature verification is skipped?

Yes. Digital signature verification is skipped under the following conditions:

• Scripted downloads (type_id = 3): Patches fetched via specialized scripts (such as Windows Defender signature updates or Office C2R) do not undergo engine-level digital signature checks.
• Missing certificate metadata: Where the patch data records no certificate paths (certPaths) or public keys (pubKeys), GetLatestInstaller returns success without verifying the installer's origin — including when the installer is unsigned. Some vendors do not sign their installers, and the check is deliberately permissive in that case.

InstallFromFiles behaves differently in the same situation: with skip_signature_check: 0 and no recorded signer information, it returns WA_VMOD_ERROR_CANNOT_VERIFY (-1043) rather than proceeding. Verify an installer before installing it, not only after downloading it.

What happens if a product has no pre-recorded static SHA-256 checksum in OPSWAT patch data?

When no static checksum is available, GetLatestInstaller may still verify the installer by digital signature if the patch is eligible for that check and the required signer information exists in the patch data. If the required signer information is missing, the call may still return success even though no OPSWAT digital-signature verification was performed.

What does skip_signature_check 0 actually verify in InstallFromFiles?

When skip_signature_check: 0 is set, InstallFromFiles requests engine-level verification before launching the installer:

• OS trust check: Calls Windows WinVerifyTrust (WINTRUST_ACTION_GENERIC_VERIFY_V2) to verify the binary is cryptographically intact and trusted by the local OS certificate store.
• Revocation behavior: Online revocation checks are disabled (WTD_REVOKE_NONE), allowing verification to function consistently on offline endpoints.
• Vendor matching: Matches the signer's identity against patch.dat / patchv2.dat metadata (checking Subject/Issuer chain, then Thumbprint, then Public Key in priority order).

note

This check runs only for direct-binary installers where signer metadata exists in the patch database. Scripted downloads (type_id = 3) and products without recorded certificate metadata do not undergo engine-level checks. For full details, see the OPSWAT KB article Skip signature check in the InstallFromFiles method.

Does passing the dynamic sha256 returned by GetLatestInstaller into InstallFromFiles guarantee authenticity?

Passing the dynamically calculated sha256 into expected_installer_sha256 ensures local file continuity (confirming the file was not modified on disk between download and installation). However, it does not independently authenticate the original download source if signature checks were skipped or unavailable.

What is the recommended best practice if no static checksum or OPSWAT signature check is available for a product?

OPSWAT recommends a defense-in-depth strategy:

1. Enforce static checksum verification (expected_installer_sha256) whenever available in patch data.
2. Enable signature checks (skip_signature_check: 0).
3. For products lacking catalog checksums or code signatures, download and test installers in an isolated environment, record their SHA-256 hashes, and distribute them internally via manual patching workflows.

Related OPSWAT KB articles

The following knowledge-base articles on the OPSWAT documentation site are referenced above:

• Skip signature check in the InstallFromFiles method
• How the OESIS SDK distinguishes OS restart and application restart when patching products
• How to Identify Automatic vs Manual Patching Using Analog Files