Harden docs CI and API exports

Author: thieman

.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

@@ -20,11 +20,12 @@ pkcs1 = { version = "0.7.5", features = ["std"] }
 pkcs8 = "0.11.0"
 rustls = { version = "0.23.20", default-features = false, features = ["std"] }
 sec1 = "0.8.1"
+zeroize = "1.8.1"
+
+[target.'cfg(windows)'.dependencies]
 windows = { version = "0.61.3", features = [
     "Win32_Security_Cryptography",
-    "Win32_System_WinRT",
 ] }
-zeroize = "1.8.1"
 
 [features]
 default = ["tls12"]

README.md

@@ -21,6 +21,19 @@ Full test coverage requires Windows because the provider calls Windows CNG APIs:
 cargo test
 ```
 
+The default test suite is hermetic. The crates.io interoperability test is ignored by default because it requires live network access; run it explicitly when needed:
+
+```bash
+cargo test test_to_internet -- --ignored
+```
+
+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,27 +3,6 @@
 // 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;
 
@@ -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 {

src/kx.rs

@@ -3,6 +3,7 @@
 // This product includes software developed at Datadog (https://www.datadoghq.com/)
 // Copyright 2026 Datadog, Inc.
 
+#[cfg(not(feature = "fips"))]
 use once_cell::sync::Lazy;
 use rustls::crypto::{ActiveKeyExchange, SharedSecret, SupportedKxGroup};
 use rustls::{Error, NamedGroup};
@@ -27,6 +28,7 @@ const MAX_SECRET_SIZE: usize = 48;
 /// * [SECP256R1]
 ///
 pub const ALL_KX_GROUPS: &[&dyn SupportedKxGroup] = &[X25519, SECP256R1, SECP384R1];
+#[cfg(not(feature = "fips"))]
 static DEFAULT_KX_GROUPS: Lazy<Vec<&'static dyn SupportedKxGroup>> = Lazy::new(|| {
     ALL_KX_GROUPS
         .iter()
@@ -75,10 +77,12 @@ impl KxGroup {
     }
 }
 
+#[cfg(not(feature = "fips"))]
 fn usable_kx_group(kx_group: &dyn SupportedKxGroup) -> bool {
     kx_group.name() != NamedGroup::X25519 || cng_supports_x25519()
 }
 
+#[cfg(not(feature = "fips"))]
 fn cng_supports_x25519() -> bool {
     // Windows CNG's Curve25519 public-key import behavior differs by OS version. Windows Server
     // 2022 accepts the X25519 Wycheproof `u = 4` vector, but Windows Server 2025 rejects it with
@@ -112,6 +116,7 @@ pub const SECP256R1: &dyn SupportedKxGroup = &KxGroup::SECP256R1;
 pub const SECP384R1: &dyn SupportedKxGroup = &KxGroup::SECP384R1;
 
 /// Returns key exchange groups usable by the host CNG implementation.
+#[cfg(not(feature = "fips"))]
 pub fn default_kx_groups() -> Vec<&'static dyn SupportedKxGroup> {
     DEFAULT_KX_GROUPS.clone()
 }
@@ -282,6 +287,7 @@ mod test {
 
     use crate::{keys::import_ecdh_private_key, kx::EcKeyExchange};
 
+    #[cfg(not(feature = "fips"))]
     #[test]
     fn default_kx_groups_match_cng_x25519_support() {
         let advertises_x25519 = super::default_kx_groups()
@@ -325,6 +331,7 @@ mod test {
         }
     }
 
+    #[cfg(not(feature = "fips"))]
     #[test]
     fn x25519() {
         if !super::cng_supports_x25519() {

src/lib.rs

@@ -24,8 +24,8 @@
 //! * `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`
 //! * `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`
 //! * `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256`
-//! * `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`
 //! * `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`
+//! * `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`
 //! * `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256`
 //!
 //! ## Supported Key Exchanges
@@ -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;
@@ -79,6 +103,21 @@ mod verify;
 
 pub mod cipher_suite {
     //! Supported cipher suites.
+    //!
+    //! ```rust
+    //! use rustls::CipherSuite;
+    //! use rustls_cng_crypto::{cipher_suite, custom_provider, kx_group};
+    //!
+    //! let provider = custom_provider(
+    //!     vec![cipher_suite::TLS13_CHACHA20_POLY1305_SHA256],
+    //!     vec![kx_group::SECP256R1],
+    //! );
+    //!
+    //! assert_eq!(
+    //!     provider.cipher_suites[0].suite(),
+    //!     CipherSuite::TLS13_CHACHA20_POLY1305_SHA256
+    //! );
+    //! ```
     #[cfg(feature = "tls12")]
     pub use super::tls12::{
         TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
@@ -88,7 +127,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;
@@ -190,8 +231,8 @@ pub fn custom_provider(
 /// * `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`
 /// * `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`
 /// * `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256`
-/// * `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`
 /// * `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`
+/// * `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`
 /// * `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256`
 ///
 /// If the default `tls12` feature is disabled then the TLS 1.2 cipher suites will not be included.

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
+    );
+}

tests/it.rs

@@ -189,6 +189,7 @@ fn test_client_and_server(
     rustls_cng_crypto::kx_group::SECP384R1,
     CipherSuite::TLS13_AES_256_GCM_SHA384
 )]
+#[ignore = "requires live access to index.crates.io"]
 fn test_to_internet(
     #[case] suite: SupportedCipherSuite,
     #[case] group: &'static dyn SupportedKxGroup,