Document CI API availability and historical mincrypt layouts

2026-10-26 19:23:08 +01:00
1 parent 7aa23f50be
commit cb23a31adb
@@ -0,0 +1,104 @@
+# CI API compatibility matrix
+
+This matrix records **named export presence in ten exact x64 `ci.dll` files**.
+**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 hashes of the retained source inventories.
+
+## Windows 10 1507–1803 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 and Windows 11 samples
+
+| API | 19041.1 | 19041.1865 | 22000.318 | 26100.8328 |
+| --- | --- | --- | --- | --- |
+| `CiCheckSignedFile` | Yes | Yes | Yes | Yes |
+| `CiFindPageHashesInCatalog` | Yes | Yes | Yes | Yes |
+| `CiFindPageHashesInSignedFile` | Yes | Yes | Yes | Yes |
+| `CiFreePolicyInfo` | Yes | Yes | Yes | Yes |
+| `CiGetCertPublisherName` | No | Yes | Yes | Yes |
+| `CiGetPEInformation` | Yes | Yes | Yes | Yes |
+| `CiInitialize` | Yes | Yes | Yes | Yes |
+| `CiSetTrustedOriginClaimId` | Yes | Yes | Yes | Yes |
+| `CiValidateFileObject` | Yes | Yes | Yes | Yes |
+| `CiVerifyHashInCatalog` | Yes | Yes | 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 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 24H2 sample: **10.0.26100.8328 x64**, SHA-256
+  `c7d23814f3202c51fb23e3ca3d4328855787383cee5d14c4a986a13ec2aeda0b`.
+
+## 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.
+- `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.8328 files.
+- 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 and ARM64 export availability; pre-Windows-10;
+Windows 10 1809/1903/1909; other 19041 servicing revisions; and Windows 11
+22621/22631. 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>`.
+No Windows binary or PDB is distributed with the matrix.