Add reusable certificate and file validation helpers

Fix process-name ownership and module lookup outputs, add explicit SPKI hashing and bounded chain access, and improve WDM integration. Deprecate superseded entry points with migration guidance and align branch code and tests with the library style. Add CI validation helpers with explicit signature selection and owned results Document runtime-confirmed CI signer selection and crypto reuse Expand CI compatibility matrix to twenty verified samples Extend CI export matrix with Windows 11 x64 and ARM64 samples Document CI API availability and historical mincrypt layouts Add explicit Authenticode workflows and correct CI helper contracts Document CI validation flag 0x20 and add kernel probe Harden CI digest parsing and failure cleanup
2026-10-27 00:17:25 +01:00
1 parent 7985b23be5
commit 3fbfe31d15
@@ -0,0 +1,184 @@
+# CI API compatibility matrix
+
+This matrix records **named export presence in 20 exact `ci.dll` files**,
+with architecture stated separately for each sample.
+**Yes** means the complete PE export directory contains the name; **No** means
+it does not. Neither result is inferred from a header, import library or PDB.
+Export presence alone does not establish a compatible ABI or successful verification.
+
+Versions in the tables are **CI file versions**, not necessarily the kernel version.
+In particular, the Windows 10 22H2 consumer ISO contains CI **19041.1865**.
+Do not extrapolate a cell to every servicing revision of that Windows release.
+
+[Machine-readable matrix](ci-api-compatibility.json) includes exact SHA-256 identities,
+all per-API results and canonical JSON hashes of the retained source inventories.
+Source hashes ignore whitespace and line-ending differences between checkouts;
+the binary SHA-256 identities always cover the exact original bytes.
+
+The tables use numeric `VS_FIXEDFILEINFO` versions. The original modern x64
+sample has **fixed version 26100.9444** but its string `FileVersion` reports
+**26100.8328**. Original research/header labels retain that string version;
+they identify the same SHA-256 file, not two different CI samples.
+
+## Windows 10 1507–1803 x64 samples
+
+| API | 10240.16463 | 10586.0 | 14393.2189 | 15063.0 | 16299.125 | 17134.1130 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `CiCheckSignedFile` | Yes | Yes | Yes | Yes | Yes | Yes |
+| `CiFindPageHashesInCatalog` | Yes | Yes | Yes | Yes | Yes | Yes |
+| `CiFindPageHashesInSignedFile` | Yes | Yes | Yes | Yes | Yes | Yes |
+| `CiFreePolicyInfo` | Yes | Yes | Yes | Yes | Yes | Yes |
+| `CiGetCertPublisherName` | No | No | No | No | No | No |
+| `CiGetPEInformation` | Yes | Yes | Yes | Yes | Yes | Yes |
+| `CiInitialize` | Yes | Yes | Yes | Yes | Yes | Yes |
+| `CiSetTrustedOriginClaimId` | No | No | No | Yes | Yes | Yes |
+| `CiValidateFileObject` | Yes | Yes | Yes | Yes | Yes | Yes |
+| `CiVerifyHashInCatalog` | Yes | Yes | Yes | Yes | Yes | Yes |
+
+## Later Windows 10 x64 samples
+
+| API | 17763.1 | 17763.348 | 18362.1 | 18362.329 | 18362.418 | 19041.1 | 19041.1865 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `CiCheckSignedFile` | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
+| `CiFindPageHashesInCatalog` | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
+| `CiFindPageHashesInSignedFile` | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
+| `CiFreePolicyInfo` | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
+| `CiGetCertPublisherName` | No | No | No | No | No | No | Yes |
+| `CiGetPEInformation` | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
+| `CiInitialize` | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
+| `CiSetTrustedOriginClaimId` | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
+| `CiValidateFileObject` | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
+| `CiVerifyHashInCatalog` | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
+
+## Windows 11 x64 samples
+
+| API | 22000.318 | 22621.2792 | 26100.9444 |
+| --- | --- | --- | --- |
+| `CiCheckSignedFile` | Yes | Yes | Yes |
+| `CiFindPageHashesInCatalog` | Yes | Yes | Yes |
+| `CiFindPageHashesInSignedFile` | Yes | Yes | Yes |
+| `CiFreePolicyInfo` | Yes | Yes | Yes |
+| `CiGetCertPublisherName` | Yes | Yes | Yes |
+| `CiGetPEInformation` | Yes | Yes | Yes |
+| `CiInitialize` | Yes | Yes | Yes |
+| `CiSetTrustedOriginClaimId` | Yes | Yes | Yes |
+| `CiValidateFileObject` | Yes | Yes | Yes |
+| `CiVerifyHashInCatalog` | Yes | Yes | Yes |
+
+## Windows 10 ARM64 samples
+
+| API | 19041.1566 | 19041.2965 |
+| --- | --- | --- |
+| `CiCheckSignedFile` | Yes | Yes |
+| `CiFindPageHashesInCatalog` | Yes | Yes |
+| `CiFindPageHashesInSignedFile` | Yes | Yes |
+| `CiFreePolicyInfo` | Yes | Yes |
+| `CiGetCertPublisherName` | Yes | Yes |
+| `CiGetPEInformation` | Yes | Yes |
+| `CiInitialize` | Yes | Yes |
+| `CiSetTrustedOriginClaimId` | Yes | Yes |
+| `CiValidateFileObject` | Yes | Yes |
+| `CiVerifyHashInCatalog` | Yes | Yes |
+
+## Windows 11 ARM64 samples
+
+| API | 22621.1702 | 26100.1591 |
+| --- | --- | --- |
+| `CiCheckSignedFile` | Yes | Yes |
+| `CiFindPageHashesInCatalog` | Yes | Yes |
+| `CiFindPageHashesInSignedFile` | Yes | Yes |
+| `CiFreePolicyInfo` | Yes | Yes |
+| `CiGetCertPublisherName` | Yes | Yes |
+| `CiGetPEInformation` | Yes | Yes |
+| `CiInitialize` | Yes | Yes |
+| `CiSetTrustedOriginClaimId` | Yes | Yes |
+| `CiValidateFileObject` | Yes | Yes |
+| `CiVerifyHashInCatalog` | Yes | Yes |
+
+## Exact sample identities
+
+- Windows 10 1507: **10.0.10240.16463 x64**, SHA-256
+  `e83d900f4675c6e6ffc3fb7dcd3074610876a1398e495796769988df810fd3bc`.
+- Windows 10 1511: **10.0.10586.0 x64**, SHA-256
+  `f949bfa614addea6174b28c3818c56b327c9290fd41bd91dfc545414b3df6783`.
+- Windows 10 1607: **10.0.14393.2189 x64**, SHA-256
+  `ef0c02ecbd0818e84be9f61421f919825f96a3c59199460cab08548eee2881df`.
+- Windows 10 1703: **10.0.15063.0 x64**, SHA-256
+  `3705aaf408f05326e028621380aa5c96a1f3583a2de8a139b188da4b82577863`.
+- Windows 10 1709: **10.0.16299.125 x64**, SHA-256
+  `1db7ae5a08bd2361fc7fcdd373fb980e8d680035e67b02e5967095db0443effd`.
+- Windows 10 1803: **10.0.17134.1130 x64**, SHA-256
+  `8ce3b8fe38c23b699f30b045383640019a429d3a9d513285c655bffe03a796d9`.
+- Windows 10 1809 initial x64 ISO: **10.0.17763.1 x64**, SHA-256
+  `eb177481f2aea3cae0c2f97f7058e7447c0695e4489428406598f168d4dcc5e8`.
+- Windows 10 1809 October v2 x64 ISO: **10.0.17763.348 x64**, SHA-256
+  `da8282173cbce7ea38f8fca64db0972c3d9614ddbca98f6b96d11a4cadde92ad`.
+- Windows 10 1903 v1 x64 ISO: **10.0.18362.1 x64**, SHA-256
+  `5d01bb84fa516e23c25def8ea03fc6b696082ccc67a61575fd00d1fe7c273d72`.
+- Windows 10 1903 v2 x64 ISO: **10.0.18362.329 x64**, SHA-256
+  `d12131f14f781f8c314a795384e02afc3c2902bf67da9c2e75d8163c891bdd89`.
+- Windows 10 1909 x64 ISO: **10.0.18362.418 x64**, SHA-256
+  `c3c5d32da42fa69b0795cd0f8c57252670d673fb036685db5c7d6392ffee0293`.
+- Windows 10 2004 ISO: **10.0.19041.1 x64**, SHA-256
+  `2955710d34db26e352e62b20861ba338f0216cc36b378d128057be955e184282`.
+- Windows 10 22H2 consumer ISO: **10.0.19041.1865 x64**, SHA-256
+  `d0408a9f64eafb72e8aa1cf127d07d919f0cab38a6bdf2b406255909c85e3a8d`.
+- Windows 11 English x64 v1 ISO: **10.0.22000.318 x64**, SHA-256
+  `301ae49ac5b87cf1cbe07d9d3c6486a066d045b6bf55fc8eb392d52951ec69ff`.
+- Windows 11 23H2 English ISO: **10.0.22621.2792 x64**, SHA-256
+  `9ed77b8a53946ced8c3540edb26a765060dff908544634e7b069aa49f2b41559`.
+- Windows 11 24H2 sample: **10.0.26100.9444 x64**, SHA-256
+  `c7d23814f3202c51fb23e3ca3d4328855787383cee5d14c4a986a13ec2aeda0b`.
+  String FileVersion: **10.0.26100.8328** (original research label).
+- Windows 10 21H2 ARM64 ISO (archive Raspberry Pi folder): **10.0.19041.1566 ARM64**, SHA-256
+  `a35f651261691cc67acc9c8bfd00bba7a64dd9f16d2c4b6fe1d183e34aeead78`.
+- Windows 10 22H2.7 ARM64 ISO: **10.0.19041.2965 ARM64**, SHA-256
+  `33f2d1256f60392bbb84c4251d6435461dfa852a100e065376f83dc8a4dd2ec6`.
+- Windows 11 22H2.9 ARM64 ISO: **10.0.22621.1702 ARM64**, SHA-256
+  `4164ac08fd19628c5ab6cbca6234265ac2bf7f39d5149f57d3845646d8a8ad60`.
+- Windows 11 24H2 ARM64 ISO: **10.0.26100.1591 ARM64**, SHA-256
+  `a0eba64a9a3f2006d5832079412eca42cc1b9ed66d19b9b0adb7e59ea354415d`.
+
+## What callers can rely on
+
+- `CiValidateFileObject` is already exported in the sampled Windows 10 1507 file.
+- `CiSetTrustedOriginClaimId` is present in the sampled 1703 file and absent in
+  the three earlier samples. This does not prove its first introduction build.
+- On sampled x64 files, `CiGetCertPublisherName` is absent in 19041.1
+  and present in 19041.1865.
+  Its first Windows 10 servicing update remains unknown. It is also present
+  in the sampled 22000.318 and 26100.9444 fixed-version files.
+- The Windows 10 ARM64 21H2 sample already exports the publisher-name API
+  in CI 19041.1566. That does not establish x64 availability at that revision.
+- CI entry points currently use static imports from `ci.lib`. An unavailable
+  import can prevent driver loading; this matrix does not add an automatic
+  `STATUS_NOT_IMPLEMENTED` fallback. Supporting these older samples requires
+  avoiding unavailable imports or implementing optional resolution.
+- Choose structures using a verified runtime profile. The sampled x64 chain
+  headers differ: 1507 uses 56 bytes, 1511 uses 72, and 1607–1803 use 104.
+  Export presence, compile-target `NTDDI_VERSION` and total allocation `Size`
+  do not select a compatible layout. See [mincrypt contracts](mincrypt-contracts.md).
+
+## Coverage gaps and evidence
+
+**Unknown / not sampled:** x86 export availability; pre-Windows-10;
+earlier Windows 10 ARM64 releases; and other servicing revisions
+or architecture/release combinations absent from these tables.
+These are gaps, not negative export results. No interval between
+two samples is certified. Runtime verification and cross-version ABI checks
+remain in the [implementation ledger](implementation-status.md).
+
+The tables cover every named export found in these samples, including
+`CiInitialize`; inclusion is not a recommendation to call initialization or
+global-policy routines. Each sample also has three ordinal-only exports,
+which are outside this named-API matrix. Private `Mincrypt*` PDB symbols are
+not automatically callable exports.
+
+Source inventories are retained in the companion
+[CodeIntegrity-RE repository](https://git.nefarius.at/nefarius/CodeIntegrity-RE):
+`corpus-index.json` (VM samples), `iso-corpus-index.json` (ISO samples), and
+`ci-26100.8328-evidence.json` with `manifest.json` (original 26100 sample).
+Regenerate with its `generate_compatibility_matrix.py --output <Domito/docs>`.
+ARM64 cells establish export presence only; the historical x64 layout views
+must not be selected for ARM64 solely because the same API name is exported.
+No Windows binary or PDB is distributed with the matrix.