saltstack · dwoz · May 16, 2026 · May 14, 2026 · May 14, 2026 · May 15, 2026
@@ -0,0 +1 @@
+Added `use_os_truststore` configuration option (default `False`) that instructs Salt to use the native operating system certificate store (Windows Certificate Store, macOS Keychain, or Linux system trust) for SSL/TLS verification instead of the bundled certifi CA bundle. Requires the `truststore` package (Python 3.10+). Also adds the `ca_truststore` grain that reports which store is active (`certifi` or `os`).
@@ -2360,6 +2360,72 @@ compatibility.
 See :ref:`tls-encryption-optimization` for detailed configuration and security
 information.
 
+.. conf_master:: use_os_truststore
+
+``use_os_truststore``
+----------------------
+
+.. versionadded:: 3008.0
+
+Default: ``False``
+
+If ``True``, Salt will use the native operating system certificate store for
+SSL/TLS verification instead of the bundled ``certifi`` CA bundle.  This is
+the recommended setting for environments with transparent proxies or internal
+root CAs deployed via Group Policy or a device-management system.
+
+Platform mapping:
+
+- **Windows** — Local Machine Certificate Store (CryptoAPI)
+- **macOS** — Keychain
+- **Linux** — ``/etc/ssl/certs`` or ``/etc/pki/tls``
+
+.. code-block:: yaml
+
+    use_os_truststore: True
+
+.. rubric:: Requirements
+
+The ``truststore`` package must be installed (Python 3.10 or newer).
+If the package is not present, Salt logs a warning and falls back to
+``certifi``.  The ``ca_truststore`` grain reports which store is active.
+
+.. warning::
+
+    Do **not** install ``pip-system-certs`` into the Salt Python environment.
+    That package ships a ``.pth`` file that unconditionally activates the OS
+    trust store on every Python startup, before Salt reads its configuration,
+    completely bypassing this setting.
+
+.. rubric:: Interaction with ``ca_bundle``
+
+An explicit ``ca_bundle: /path/to/bundle.pem`` setting always takes
+precedence over ``use_os_truststore``.  Use ``ca_bundle`` when you need to
+pin a specific certificate file regardless of the OS store.
+
+.. rubric:: PKI architecture
+
+This setting has **no effect** on Salt's master/minion key authentication
+system (``pki_dir``, AES session keys, minion key acceptance).  It only
+affects outbound HTTPS/TLS connections made by Salt — HTTP runner, gitfs,
+fileserver backends, cloud drivers, and similar components.
+
+.. note::
+
+    On Windows, the ``LocalSystem`` service account (the default account
+    for the salt-master and salt-minion Windows services) only has access to
+    the **Local Machine** certificate store, not the Current User store.
+    Certificates must be deployed to the Local Machine store, for example
+    via Group Policy, to be visible to Salt.
+
+.. note::
+
+    On Windows, certificate verification is performed via a CryptoAPI service
+    call rather than a simple file read.  This may add a small amount of
+    latency on the first TLS connection made by a new process compared with
+    the simple file read used with ``certifi``.  On Linux and macOS the
+    performance difference is negligible.
+
 .. conf_master:: preserve_minion_cache
 
 ``preserve_minion_cache``

@@ -3257,6 +3257,72 @@ compatibility.
 See :ref:`tls-encryption-optimization` for detailed configuration and security
 information.
 
+.. conf_minion:: use_os_truststore
+
+``use_os_truststore``
+----------------------
+
+.. versionadded:: 3008.0
+
+Default: ``False``
+
+If ``True``, Salt will use the native operating system certificate store for
+SSL/TLS verification instead of the bundled ``certifi`` CA bundle.  This is
+the recommended setting for environments with transparent proxies or internal
+root CAs deployed via Group Policy or a device-management system.
+
+Platform mapping:
+
+- **Windows** — Local Machine Certificate Store (CryptoAPI)
+- **macOS** — Keychain
+- **Linux** — ``/etc/ssl/certs`` or ``/etc/pki/tls``
+
+.. code-block:: yaml
+
+    use_os_truststore: True
+
+.. rubric:: Requirements
+
+The ``truststore`` package must be installed (Python 3.10 or newer).
+If the package is not present, Salt logs a warning and falls back to
+``certifi``.  The ``ca_truststore`` grain reports which store is active.
+
+.. warning::
+
+    Do **not** install ``pip-system-certs`` into the Salt Python environment.
+    That package ships a ``.pth`` file that unconditionally activates the OS
+    trust store on every Python startup, before Salt reads its configuration,
+    completely bypassing this setting.
+
+.. rubric:: Interaction with ``ca_bundle``
+
+An explicit ``ca_bundle: /path/to/bundle.pem`` setting always takes
+precedence over ``use_os_truststore``.  Use ``ca_bundle`` when you need to
+pin a specific certificate file regardless of the OS store.
+
+.. rubric:: PKI architecture
+
+This setting has **no effect** on Salt's master/minion key authentication
+system (``pki_dir``, AES session keys, minion key acceptance).  It only
+affects outbound HTTPS/TLS connections made by Salt — HTTP runner, gitfs,
+fileserver backends, cloud drivers, and similar components.
+
+.. note::
+
+    On Windows, the ``LocalSystem`` service account (the default account
+    for the salt-minion Windows service) only has access to the **Local
+    Machine** certificate store, not the Current User store.  Certificates
+    must be deployed to the Local Machine store, for example via Group
+    Policy, to be visible to Salt.
+
+.. note::
+
+    On Windows, certificate verification is performed via a CryptoAPI service
+    call rather than a simple file read.  This may add a small amount of
+    latency on the first TLS connection made by a new process compared with
+    the simple file read used with ``certifi``.  On Linux and macOS the
+    performance difference is negligible.
+
 ``encryption_algorithm``
 ------------------------
 

@@ -21,3 +21,4 @@ grains modules
     pending_reboot
     resources
     rest_sample
+    truststore
@@ -0,0 +1,5 @@
+salt.grains.truststore
+======================
+
+.. automodule:: salt.grains.truststore
+    :members:
@@ -58,6 +58,7 @@ setproctitle>=1.2.3
 timelib>=0.2.5; python_version < '3.11'
 timelib>=0.3.0; python_version >= '3.11'
 tornado>=6.5.5
+truststore>=0.10.0; python_version >= "3.10"
 urllib3>=1.26.20,<2.0.0; python_version < '3.10'
 urllib3>=2.7.0; python_version >= '3.10'
 virtualenv

@@ -731,6 +731,11 @@ trustme==1.1.0
     # via
     #   -c requirements/static/ci/py3.10/linux.txt
     #   -r requirements/pytest.txt
+truststore==0.10.4
+    # via
+    #   -c requirements/static/ci/py3.10/linux.txt
+    #   -c requirements/static/pkg/py3.10/linux.txt
+    #   -r requirements/base.txt
 types-pyyaml==6.0.1
     # via
     #   -c requirements/static/ci/py3.10/linux.txt

@@ -507,6 +507,10 @@ transitions==0.9.0
     # via junos-eznc
 trustme==1.1.0
     # via -r requirements/pytest.txt
+truststore==0.10.4
+    # via
+    #   -c requirements/static/pkg/py3.10/darwin.txt
+    #   -r requirements/base.txt
 types-pyyaml==6.0.1
     # via responses
 typing-extensions==4.15.0

@@ -310,6 +310,10 @@ tornado==6.5.5
     # via
     #   -c requirements/static/ci/py3.10/linux.txt
     #   -r requirements/base.txt
+truststore==0.10.4
+    # via
+    #   -c requirements/static/ci/py3.10/linux.txt
+    #   -r requirements/base.txt
 typing-extensions==4.15.0
     # via
     #   -c requirements/static/ci/py3.10/linux.txt

@@ -567,6 +567,10 @@ transitions==0.9.0 ; sys_platform != 'win32'
     # via junos-eznc
 trustme==1.1.0
     # via -r requirements/pytest.txt
+truststore==0.10.4
+    # via
+    #   -c requirements/static/pkg/py3.10/freebsd.txt
+    #   -r requirements/base.txt
 types-pyyaml==6.0.1
     # via responses
 typing-extensions==4.15.0

@@ -723,6 +723,11 @@ transitions==0.9.0
     # via
     #   -c requirements/static/ci/py3.10/linux.txt
     #   junos-eznc
+truststore==0.10.4
+    # via
+    #   -c requirements/static/ci/py3.10/linux.txt
+    #   -c requirements/static/pkg/py3.10/linux.txt
+    #   -r requirements/base.txt
 twilio==9.10.5
     # via
     #   -c requirements/static/ci/py3.10/linux.txt

@@ -571,6 +571,10 @@ transitions==0.9.0
     # via junos-eznc
 trustme==1.1.0
     # via -r requirements/pytest.txt
+truststore==0.10.4
+    # via
+    #   -c requirements/static/pkg/py3.10/linux.txt
+    #   -r requirements/base.txt
 twilio==9.10.5
     # via -r requirements/static/ci/linux.in
 types-pyyaml==6.0.1

@@ -511,6 +511,10 @@ tornado==6.5.5
     #   -r requirements/base.txt
 trustme==1.1.0
     # via -r requirements/pytest.txt
+truststore==0.10.4
+    # via
+    #   -c requirements/static/pkg/py3.10/windows.txt
+    #   -r requirements/base.txt
 typer==0.24.1
     # via
     #   -c requirements/static/pkg/py3.10/windows.txt

@@ -717,6 +717,11 @@ trustme==1.1.0
     # via
     #   -c requirements/static/ci/py3.11/linux.txt
     #   -r requirements/pytest.txt
+truststore==0.10.4
+    # via
+    #   -c requirements/static/ci/py3.11/linux.txt
+    #   -c requirements/static/pkg/py3.11/linux.txt
+    #   -r requirements/base.txt
 types-pyyaml==6.0.12.12
     # via
     #   -c requirements/static/ci/py3.11/linux.txt

@@ -498,6 +498,10 @@ transitions==0.9.0
     # via junos-eznc
 trustme==1.1.0
     # via -r requirements/pytest.txt
+truststore==0.10.4
+    # via
+    #   -c requirements/static/pkg/py3.11/darwin.txt
+    #   -r requirements/base.txt
 types-pyyaml==6.0.12.12
     # via responses
 typing-extensions==4.14.1

@@ -306,6 +306,10 @@ tornado==6.5.5
     # via
     #   -c requirements/static/ci/py3.11/linux.txt
     #   -r requirements/base.txt
+truststore==0.10.4
+    # via
+    #   -c requirements/static/ci/py3.11/linux.txt
+    #   -r requirements/base.txt
 typing-extensions==4.14.1
     # via
     #   -c requirements/static/ci/py3.11/linux.txt

@@ -541,6 +541,10 @@ transitions==0.9.0 ; sys_platform != 'win32'
     # via junos-eznc
 trustme==1.1.0
     # via -r requirements/pytest.txt
+truststore==0.10.4
+    # via
+    #   -c requirements/static/pkg/py3.11/freebsd.txt
+    #   -r requirements/base.txt
 types-pyyaml==6.0.12.12
     # via responses
 typing-extensions==4.14.1

@@ -710,6 +710,11 @@ transitions==0.9.0
     # via
     #   -c requirements/static/ci/py3.11/linux.txt
     #   junos-eznc
+truststore==0.10.4
+    # via
+    #   -c requirements/static/ci/py3.11/linux.txt
+    #   -c requirements/static/pkg/py3.11/linux.txt
+    #   -r requirements/base.txt
 twilio==9.10.5
     # via
     #   -c requirements/static/ci/py3.11/linux.txt

@@ -560,6 +560,10 @@ transitions==0.9.0
     # via junos-eznc
 trustme==1.1.0
     # via -r requirements/pytest.txt
+truststore==0.10.4
+    # via
+    #   -c requirements/static/pkg/py3.11/linux.txt
+    #   -r requirements/base.txt
 twilio==9.10.5
     # via -r requirements/static/ci/linux.in
 types-pyyaml==6.0.12.12

@@ -502,6 +502,10 @@ tornado==6.5.5
     #   -r requirements/base.txt
 trustme==1.1.0
     # via -r requirements/pytest.txt
+truststore==0.10.4
+    # via
+    #   -c requirements/static/pkg/py3.11/windows.txt
+    #   -r requirements/base.txt
 typer==0.24.1
     # via
     #   -c requirements/static/pkg/py3.11/windows.txt

@@ -712,6 +712,11 @@ trustme==1.1.0
     # via
     #   -c requirements/static/ci/py3.12/linux.txt
     #   -r requirements/pytest.txt
+truststore==0.10.4
+    # via
+    #   -c requirements/static/ci/py3.12/linux.txt
+    #   -c requirements/static/pkg/py3.12/linux.txt
+    #   -r requirements/base.txt
 types-pyyaml==6.0.12.12
     # via
     #   -c requirements/static/ci/py3.12/linux.txt

@@ -494,6 +494,10 @@ transitions==0.9.0
     # via junos-eznc
 trustme==1.1.0
     # via -r requirements/pytest.txt
+truststore==0.10.4
+    # via
+    #   -c requirements/static/pkg/py3.12/darwin.txt
+    #   -r requirements/base.txt
 types-pyyaml==6.0.12.12
     # via responses
 typing-extensions==4.14.1

@@ -302,6 +302,10 @@ tornado==6.5.5
     # via
     #   -c requirements/static/ci/py3.12/linux.txt
     #   -r requirements/base.txt
+truststore==0.10.4
+    # via
+    #   -c requirements/static/ci/py3.12/linux.txt
+    #   -r requirements/base.txt
 typing-extensions==4.14.1
     # via
     #   -c requirements/static/ci/py3.12/linux.txt

@@ -537,6 +537,10 @@ transitions==0.9.0 ; sys_platform != 'win32'
     # via junos-eznc
 trustme==1.1.0
     # via -r requirements/pytest.txt
+truststore==0.10.4
+    # via
+    #   -c requirements/static/pkg/py3.12/freebsd.txt
+    #   -r requirements/base.txt
 types-pyyaml==6.0.12.12
     # via responses
 typing-extensions==4.14.1

@@ -705,6 +705,11 @@ transitions==0.9.0
     # via
     #   -c requirements/static/ci/py3.12/linux.txt
     #   junos-eznc
+truststore==0.10.4
+    # via
+    #   -c requirements/static/ci/py3.12/linux.txt
+    #   -c requirements/static/pkg/py3.12/linux.txt
+    #   -r requirements/base.txt
 twilio==9.10.5
     # via
     #   -c requirements/static/ci/py3.12/linux.txt

@@ -556,6 +556,10 @@ transitions==0.9.0
     # via junos-eznc
 trustme==1.1.0
     # via -r requirements/pytest.txt
+truststore==0.10.4
+    # via
+    #   -c requirements/static/pkg/py3.12/linux.txt
+    #   -r requirements/base.txt
 twilio==9.10.5
     # via -r requirements/static/ci/linux.in
 types-pyyaml==6.0.12.12
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Added `use_os_truststore` configuration option (default `False`) that instructs Salt to use the native operating system certificate store (Windows Certificate Store, macOS Keychain, or Linux system trust) for SSL/TLS verification instead of the bundled certifi CA bundle. Requires the `truststore` package (Python 3.10+). Also adds the `ca_truststore` grain that reports which store is active (`certifi` or `os`).