v11 update: Auto-trust development certificates in WSL

[wadepickett]

Target repository: dotnet/AspNetCore.Docs
Analyzed at commit: 4986136881f2bbf1879f10106467769df5a49932
Product source verified at: dotnet/aspnetcore @ 1fcd7ef305697a1888f3ede076010350ae9f4f8d
Source release note: Auto-trust development certificates in WSL

---

🎯 Goal

Tell developers using ASP.NET Core inside Windows Subsystem for Linux (WSL) that the existing dotnet dev-certs https --trust command now attempts to trust the development certificate in both the Linux trust locations and the Windows Current User Root store when WSL interop is available. The current .NET 9+ HTTPS article documents generic Linux trust behavior, and the older .NET 6–8 includes still contain a manual WSL export/import workaround, but no current-version article explains that the WSL-specific manual Windows step is no longer the recommended path in .NET 11.

Gaps this report closes:

1. Add WSL-specific .NET 11 guidance to the current HTTPS development certificate article.
2. State that dotnet dev-certs https --trust is the command to run from WSL.
3. Clarify that older PFX export/import steps are for earlier versions/manual fallback, not the .NET 11 default path.

---

✅ Coverage status summary

Legend: ✅ already documented · ✏️ update needed · 🟣 could not determine

#	Feature element from What's New	Status	Where
1	WSL auto-trust behavior: --trust attempts Linux trust and Windows trust-store installation from WSL	✏️	1. Update — security/enforcing-ssl.md L275–L281
2	The dotnet dev-certs https --trust command is the WSL command for .NET 11	✏️	1. Update — same insertion point; generic command is shown at security/enforcing-ssl.md L225–L229, but not tied to WSL.
3	Prior manual WSL export/import guidance is obsolete for the .NET 11 default path	✏️	1. Update — the manual workaround exists only in historical includes, for example enforcing-ssl8.md L548–L568.

---

🔢 Version applicability

Applies to: CURRENT-ONLY
Target moniker: >= aspnetcore-11.0
Earlier versions affected: None — the automatic Windows trust-store step from WSL is new in .NET 11. Earlier-version include files should keep their historical/manual WSL guidance.

Article	monikerRange	Moniker state
security/enforcing-ssl.md	'>= aspnetcore-3.0'	State D — the insertion point after L279 sits inside the broader >= aspnetcore-9.0 body zone (L26–L513). Close >= aspnetcore-9.0, open >= aspnetcore-11.0, add the WSL note, close it, then reopen >= aspnetcore-9.0.
security/enforcing-ssl/includes/enforcing-ssl8.md	included only by the article for = aspnetcore-8.0	Historical coverage only — it contains the old WSL export/import workaround at L548–L568 and isn't an edit target for .NET 11.

There is a tab group in the article's project-template opt-out section (L194–L208), but the proposed insertion point is well after that group's closing ---, so no :::moniker directive is placed inside a tab group.

---

📋 Coverage gap summary

A developer running an ASP.NET Core app from WSL reaches security/enforcing-ssl.md to solve HTTPS certificate trust. The current article says the generic dotnet dev-certs https --trust command exists and explains Linux trust stores, but it never says that .NET 11 also pushes the public certificate into the Windows Current User Root store when WSL interop is enabled. The only WSL-specific docset text is in older include files and recommends exporting a PFX from Windows and importing it into WSL, which is no longer the primary guidance for .NET 11.

Feature announced in What's New:

The development certificate setup now automatically trusts certificates in WSL (Windows Subsystem for Linux) environments. When you run dotnet dev-certs https --trust in WSL, the certificate is automatically installed and trusted in both the WSL environment and Windows, eliminating manual trust configuration.

Product source confirms the WSL behavior with an important caveat: after the Unix trust steps, UnixCertificateManager checks for WSL interop (/proc/sys/fs/binfmt_misc/WSLInterop, WSLInterop-late, or WSL_INTEROP) and then invokes powershell.exe to add the public certificate to the Windows Current User Root store. If that step fails, trust is partial rather than full.

Breaking change: No — this is an additive CLI behavior change.

---

📁 Affected files

Item	Path	Lines	Section
1.	security/enforcing-ssl.md	after 279	"Linux-specific considerations"

Target article uids: security/enforcing-ssl

---

📝 Proposed changes

✏️ 1. Update — security/enforcing-ssl.md, add WSL-specific trust behavior after line 279

Applies to: >= aspnetcore-11.0
Location: Line 279, immediately after the paragraph beginning "If you run dotnet dev-certs as a different user".

Before (lines 275–281):

### Using sudo

As on other platforms, development certificates are stored and trusted separately for each user. 

If you run `dotnet dev-certs` as a different user (for example, by using `sudo`), then _that_ specific user (for example `root`) trusts the development certificate.

### Trust HTTPS certificate on Linux with linux-dev-certs

After:

### Using sudo

As on other platforms, development certificates are stored and trusted separately for each user. 

If you run `dotnet dev-certs` as a different user (for example, by using `sudo`), then _that_ specific user (for example `root`) trusts the development certificate.

:::moniker-end

:::moniker range=">= aspnetcore-11.0"

### Trust the certificate from Windows Subsystem for Linux

In .NET 11 or later, run the normal trust command from the WSL distribution:

```dotnetcli
dotnet dev-certs https --trust
```

When WSL interop is enabled, the command trusts the ASP.NET Core HTTPS development certificate in the Linux trust locations described in this section and also adds the public certificate to the Windows Current User Root certificate store. You no longer need to export a PFX from Windows and import it into WSL for the common development setup.

If Windows trust isn't established, confirm that WSL interop is enabled and rerun the command. The Linux trust steps are still per-user and can require the OpenSSL, NSS, or browser-specific configuration described in this article.

:::moniker-end

:::moniker range=">= aspnetcore-9.0"

### Trust HTTPS certificate on Linux with linux-dev-certs

Rationale: security/enforcing-ssl.md is the article developers already use for ASP.NET Core HTTPS development certificate trust. The change is WSL-specific and current-only, while the surrounding Linux guidance remains applicable to .NET 9 and later, so the insertion requires a State D four-directive split.

---

✅ 2. Update — TOC

No TOC change required. The edit adds a subsection to an existing article that already appears in the Security node.

---

✅ Action plan

1. Confirm the three ✏️ rows: generic --trust coverage exists, but WSL-specific .NET 11 behavior doesn't.
2. Apply change 1 as a State D split. After editing, verify the current article has balanced moniker directives: the original >= aspnetcore-9.0 zone is closed and reopened exactly once around the new >= aspnetcore-11.0 section.
3. Build and confirm the new WSL section renders under the .NET 11 selector and doesn't appear for .NET 9 or .NET 10.
4. Confirm the nested dotnetcli fence renders correctly inside the inserted markdown.
5. Resolve any OpenPublishing.Build warnings.

---

⚠️ Review considerations

• 🟣 Release-note wording is broader than the implementation. Product source attempts Windows trust only when WSL interop is detected, and a failed Windows-store add produces partial trust. The proposed wording says "when WSL interop is enabled" rather than promising that every WSL environment is fully trusted in Windows.
• Historical includes stay unchanged. enforcing-ssl6.md, enforcing-ssl7.md, and enforcing-ssl8.md still document the manual WSL export/import workaround for their versioned content. Updating them would make earlier-version guidance inaccurate.

---

🔗 References

• What's New section: Auto-trust development certificates in WSL
• Existing docset command coverage: security/enforcing-ssl.md L225–L229
• Existing historical WSL workaround: security/enforcing-ssl/includes/enforcing-ssl8.md L548–L568
• Product source: src/Tools/dotnet-dev-certs/src/Program.cs L398–L439 — --trust flows into EnsureAspNetCoreHttpsDevelopmentCertificate(..., trust: true, ...).
• Product source: src/Shared/CertificateGeneration/UnixCertificateManager.cs L204–L242, L268–L304, and L417–L441 — Linux trust plus WSL Windows-store trust attempt.
• Product source: src/Shared/CertificateGeneration/UnixCertificateManager.cs L638–L697 — WSL detection and powershell.exe Windows Current User Root-store add.