chore(ci): harden docs API and test coverage

.github/workflows/ci.yml

@@ -87,6 +87,12 @@ jobs:
         run: cargo clippy --all-targets -- -D warnings
       - name: cargo clippy --no-default-features (warnings)
         run: cargo clippy --no-default-features --all-targets -- -D warnings
+      - name: cargo clippy --features fips (warnings)
+        run: cargo clippy --features fips --all-targets -- -D warnings
+      - name: cargo doc (warnings)
+        run: cargo doc --no-deps
+        env:
+          RUSTDOCFLAGS: -D warnings
 
   coverage:
     name: Coverage

Cargo.toml

@@ -22,7 +22,6 @@ rustls = { version = "0.23.20", default-features = false, features = ["std"] }
 sec1 = "0.8.1"
 windows = { version = "0.61.3", features = [
     "Win32_Security_Cryptography",
-    "Win32_System_WinRT",
 ] }
 zeroize = "1.8.1"
 

README.md

@@ -21,6 +21,13 @@ Full test coverage requires Windows because the provider calls Windows CNG APIs:
 cargo test
 ```
 
+This crate only builds for Windows targets. From non-Windows hosts, run check and documentation workflows with an explicit Windows target:
+
+```bash
+cargo check --target x86_64-pc-windows-msvc
+RUSTDOCFLAGS='-D warnings' cargo doc --no-deps --target x86_64-pc-windows-msvc
+```
+
 Run formatting checks before submitting changes:
 
 ```bash

build.rs

@@ -0,0 +1,13 @@
+// Unless explicitly stated otherwise all files in this repository are licensed under the MIT License.
+//
+// This product includes software developed at Datadog (https://www.datadoghq.com/)
+// Copyright 2026 Datadog, Inc.
+
+fn main() {
+    if std::env::var("CARGO_CFG_TARGET_OS").as_deref() != Ok("windows") {
+        panic!(
+            "rustls-cng-crypto uses Windows CNG APIs and only builds for Windows targets; \
+             use --target x86_64-pc-windows-msvc when checking from non-Windows hosts"
+        );
+    }
+}

src/fips.rs

@@ -3,31 +3,10 @@
 // This product includes software developed at Datadog (https://www.datadoghq.com/)
 // Copyright 2026 Datadog, Inc.
 
-//! # FIPS support
-//!
-//! To use rustls with this crate in FIPS mode, perform the following actions.
-//!
-//! ## 1. Enable FIPS mode for Windows
-//!
-//! See [Microsoft documentation](https://learn.microsoft.com/en-us/windows/security/security-foundations/certification/fips-140-validation).
-//!
-//! ## 2. Enable the `fips` feature, or explicitly use the [crate::fips_provider()] function
-//!
-//! The fips feature changes the behaviour of [crate::default_provider()] to use FIPS-approved cipher suites and key exchange groups.
-//! Or you can explicitly use the [crate::fips_provider()] function to create a provider with FIPS-approved cipher suites and key exchange groups.
-//! If Windows is not running in FIPS mode, the provider will be empty.
-//!
-//! ## 3. Specify `require_ems` when constructing [rustls::ClientConfig] or [rustls::ServerConfig]
-//!
-//! See [rustls documentation](https://docs.rs/rustls/latest/rustls/client/struct.ClientConfig.html#structfield.require_ems) for rationale.
-//!
-//! ## 4. Validate the FIPS status of your ClientConfig or ServerConfig at runtime
-//! See [rustls documentation on FIPS](https://docs.rs/rustls/latest/rustls/manual/_06_fips/index.html#3-validate-the-fips-status-of-your-clientconfigserverconfig-at-run-time).
-
 use rustls::crypto::CryptoProvider;
 use windows::Win32::Security::Cryptography::BCryptGetFipsAlgorithmMode;
 
-use crate::{KeyProvider, SecureRandom, ALL_CIPHER_SUITES, ALL_KX_GROUPS, SUPPORTED_SIG_ALGS};
+use crate::{kx, KeyProvider, SecureRandom, ALL_CIPHER_SUITES, SUPPORTED_SIG_ALGS};
 
 pub(crate) fn enabled() -> bool {
     let mut enabled = 0u8;
@@ -39,6 +18,21 @@ pub(crate) fn enabled() -> bool {
 
 /// Returns a CNG-based [`CryptoProvider`] using FIPS-approved cipher suites and key exchange groups.
 ///
+/// To use rustls with this provider in FIPS mode:
+///
+/// 1. Enable FIPS mode for Windows. See Microsoft's
+///    [FIPS 140 Validation](https://learn.microsoft.com/en-us/windows/security/security-foundations/certification/fips-140-validation)
+///    documentation.
+/// 2. Enable this crate's `fips` feature, or explicitly use [`crate::fips_provider()`]. The `fips`
+///    feature changes [`crate::default_provider()`] to use FIPS-approved cipher suites and key
+///    exchange groups.
+/// 3. Specify `require_ems` when constructing [`rustls::ClientConfig`] or
+///    [`rustls::ServerConfig`]. See the rustls
+///    [FIPS manual](https://docs.rs/rustls/latest/rustls/manual/_06_fips/index.html)
+///    for rationale.
+/// 4. Validate the FIPS status of your `ClientConfig` or `ServerConfig` at runtime. See the rustls
+///    [FIPS status documentation](https://docs.rs/rustls/latest/rustls/manual/_06_fips/index.html#3-validate-the-fips-status-of-your-clientconfigserverconfig-at-run-time).
+///
 /// Usage requires that Windows is running in FIPS mode, otherwise the provider will be empty.
 pub fn provider() -> CryptoProvider {
     CryptoProvider {
@@ -47,10 +41,9 @@ pub fn provider() -> CryptoProvider {
             .filter(|cs| cs.fips())
             .cloned()
             .collect(),
-        kx_groups: ALL_KX_GROUPS
-            .iter()
+        kx_groups: kx::default_kx_groups()
+            .into_iter()
             .filter(|kx| kx.fips())
-            .cloned()
             .collect(),
         signature_verification_algorithms: SUPPORTED_SIG_ALGS,
         secure_random: &SecureRandom,

src/lib.rs

@@ -53,7 +53,31 @@
 //!
 //! # Features
 //! - `tls12`: Enables TLS 1.2 cipher suites. Enabled by default.
-//! - `fips`: Changes the default provider to use FIPS-approved cipher suites and key exchange groups. See [fips].
+//! - `fips`: Changes the default provider to use FIPS-approved cipher suites and key exchange groups.
+//!   See [`fips_provider()`] and [FIPS support](#fips-support).
+//!
+//! ## FIPS support
+//!
+//! To use rustls with this crate in FIPS mode:
+//!
+//! 1. Enable FIPS mode for Windows. See Microsoft's
+//!    [FIPS 140 Validation](https://learn.microsoft.com/en-us/windows/security/security-foundations/certification/fips-140-validation)
+//!    documentation.
+//! 2. Enable this crate's `fips` feature, or explicitly use [`fips_provider()`]. The `fips`
+//!    feature changes [`default_provider()`] to use FIPS-approved cipher suites and key exchange
+//!    groups. If Windows is not running in FIPS mode, the provider will be empty.
+//! 3. Specify `require_ems` when constructing [`rustls::ClientConfig`] or
+//!    [`rustls::ServerConfig`]. See the rustls
+//!    [FIPS manual](https://docs.rs/rustls/latest/rustls/manual/_06_fips/index.html)
+//!    for rationale.
+//! 4. Validate the FIPS status of your `ClientConfig` or `ServerConfig` at runtime. See the rustls
+//!    [FIPS status documentation](https://docs.rs/rustls/latest/rustls/manual/_06_fips/index.html#3-validate-the-fips-status-of-your-clientconfigserverconfig-at-run-time).
+//!
+//! ## Platform support
+//!
+//! This crate uses Windows CNG APIs and only builds for Windows targets. From non-Windows hosts,
+//! run checks and documentation builds with an explicit Windows target such as
+//! `--target x86_64-pc-windows-msvc`.
 #![warn(missing_docs)]
 use rustls::crypto::{CryptoProvider, GetRandomFailed, SupportedKxGroup};
 use rustls::SupportedCipherSuite;
@@ -88,7 +112,9 @@ pub mod cipher_suite {
     pub use super::tls12::{
         TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256, TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,
     };
-    pub use super::tls13::{TLS13_AES_128_GCM_SHA256, TLS13_AES_256_GCM_SHA384};
+    pub use super::tls13::{
+        TLS13_AES_128_GCM_SHA256, TLS13_AES_256_GCM_SHA384, TLS13_CHACHA20_POLY1305_SHA256,
+    };
 }
 
 pub use alg::ShutdownHandle;

tests/api.rs

@@ -0,0 +1,21 @@
+// Unless explicitly stated otherwise all files in this repository are licensed under the MIT License.
+//
+// This product includes software developed at Datadog (https://www.datadoghq.com/)
+// Copyright 2026 Datadog, Inc.
+
+use rustls::CipherSuite;
+use rustls_cng_crypto::{custom_provider, kx_group};
+
+#[test]
+fn tls13_chacha20_poly1305_sha256_is_available_for_custom_providers() {
+    let provider = custom_provider(
+        vec![rustls_cng_crypto::cipher_suite::TLS13_CHACHA20_POLY1305_SHA256],
+        vec![kx_group::SECP256R1],
+    );
+
+    assert_eq!(provider.cipher_suites.len(), 1);
+    assert_eq!(
+        provider.cipher_suites[0].suite(),
+        CipherSuite::TLS13_CHACHA20_POLY1305_SHA256
+    );
+}