Skip to content

Commit 1892277

Browse files
cosmo0920edsiper
authored andcommitted
tls: document Windows root updates and retry behavior
Signed-off-by: Hiroshi Hatake <hiroshi@chronosphere.io>
1 parent 1aa8a22 commit 1892277

1 file changed

Lines changed: 31 additions & 0 deletions

File tree

‎docs/windows-tls.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
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

Comments
 (0)