|
| 1 | +# Windows TLS root updates |
| 2 | + |
| 3 | +When Fluent Bit verifies a peer using a Windows certificate store and cannot |
| 4 | +find a trusted issuer, it asks Windows to build the peer's chain in the |
| 5 | +background. Windows may install a missing public root according to the |
| 6 | +machine's Automatic Root Certificates Update policy. Fluent Bit supplies the |
| 7 | +peer's certificates and disables retrieval from their AIA URLs. |
| 8 | + |
| 9 | +The triggering handshake fails verification. A new connection reads the |
| 10 | +certificate store again and can succeed after the update. For an output, |
| 11 | +configure retries if a buffered batch must survive the first failed handshake. |
| 12 | +New connections import the currently selected anchors and exclude certificates |
| 13 | +explicitly listed in the Windows Disallowed store. An established TLS |
| 14 | +connection keeps the result of its original verification. |
| 15 | +OpenSSL performs certificate verification on each new handshake. |
| 16 | + |
| 17 | +Each TLS context schedules at most one lookup per minute and runs at most one |
| 18 | +lookup at a time. At debug level Fluent Bit logs when it schedules a lookup. |
| 19 | +After Windows successfully builds the chain, the next connection logs the |
| 20 | +result at info level. An explicit CA file or directory bypasses this lookup. |
| 21 | + |
| 22 | +Set the process environment variable `FLB_WINDOWS_AUTO_ROOT_UPDATE=off` to |
| 23 | +disable background lookups in Fluent Bit. Windows administrators can also |
| 24 | +[configure trusted root updates through Group Policy](https://learn.microsoft.com/en-us/windows-server/identity/ad-cs/configure-trusted-roots-disallowed-certificates). |
| 25 | + |
| 26 | +The Windows x64 integration tests exercise retries against an isolated store. |
| 27 | +To test an actual Windows Update download on a networked Windows host, set |
| 28 | +`FLUENT_BIT_BINARY` to the executable and `FLB_TEST_WINDOWS_ROOT_DOWNLOAD=1` |
| 29 | +and run `python -m pytest tests/integration/scenarios/tls/tests/test_windows_root_update.py`. |
| 30 | +The test skips roots already installed and leaves newly installed public roots |
| 31 | +under Windows management. |
0 commit comments