# dotnet-devcert-trust

Walks through why .NET and Aspire reject the HTTPS dev certificate on Linux and gets it into the system CA bundle.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 434 installs · ★ 1238
- Author: Aaronontheweb
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/Aaronontheweb/dotnet-skills/tree/HEAD/skills/dotnet-devcert-trust/SKILL.md
- Updated: 2026-10-11
- HTML: https://affpapa.org/en/nevibecode/skills/dotnet-devcert-trust

## What it does

On Windows and macOS, `dotnet dev-certs https --trust` handles the whole job. On Linux it generates the certificate into the user store and stops there: nothing is exported to the system CA directory, `update-ca-certificates` never runs, and browser NSS stores stay untouched. The `--trust` flag still exits clean, so `--check` reports the cert exists while OpenSSL, curl and .NET keep rejecting it.

The skill runs five checks in order: cert existence, permissions and stale files under `/usr/local/share/ca-certificates/`, inclusion in `/etc/ssl/certs/ca-certificates.crt`, the `SSL_CERT_DIR`, `SSL_CERT_FILE` and `DOTNET_SSL_CERT_DIR` variables, and broken symlinks. You stop at the first failure and apply its fix. Distro-specific steps follow for Ubuntu, Fedora, Arch and WSL2, plus a full recovery sequence for a clean slate.

Why this bites now: from Aspire 13.1.0 onward Redis runs with TLS, so a cert that isn't trusted at the system level kills the connection with `UntrustedRoot`. Every fix needs `sudo`, so have root access ready before you start.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add Aaronontheweb/dotnet-skills --skill dotnet-devcert-trust -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/dotnet-devcert-trust/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/dotnet-devcert-trust/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add Aaronontheweb/dotnet-skills --skill dotnet-devcert-trust -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/dotnet-devcert-trust/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add Aaronontheweb/dotnet-skills --skill dotnet-devcert-trust -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/dotnet-devcert-trust/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install Aaronontheweb/dotnet-skills dotnet-devcert-trust
```

2. **Manually: put the files in place**
- File: `.github/skills/dotnet-devcert-trust/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add Aaronontheweb/dotnet-skills --skill dotnet-devcert-trust -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/Aaronontheweb/dotnet-skills --path skills/dotnet-devcert-trust
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/dotnet-devcert-trust/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add Aaronontheweb/dotnet-skills --skill dotnet-devcert-trust -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/Aaronontheweb/dotnet-skills/tree/HEAD/skills/dotnet-devcert-trust/SKILL.md

## When to use it
- fix Redis TLS failures in Aspire that report UntrustedRoot
- restore trust after running `dotnet dev-certs https --clean`
- spot stale certificate files under `/usr/local/share/ca-certificates/`
- rebuild the CA bundle when the cert exists but won't verify
- set up HTTPS development on a fresh Linux box or inside WSL2

## Example prompts
- Redis in Aspire fails with UntrustedRoot — sort out the dev certificate
- \`dotnet dev-certs https --check --trust` exits with code 7, fix trust on Linux
- Check whether the dev cert made it into the system CA bundle

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: add7cf2710679693.

BEGIN THIRD-PARTY FILE add7cf2710679693
````text
---
name: dotnet-devcert-trust
description: Diagnose and fix .NET HTTPS dev certificate trust issues on Linux. Covers the full certificate lifecycle from generation to system CA bundle inclusion, with distro-specific guidance for Ubuntu, Fedora, Arch, and WSL2.
user-invocable: false
---

# .NET Dev Certificate Trust on Linux

## When to Use This Skill

Use this skill when:
- Redis TLS connections fail with `UntrustedRoot` or `RemoteCertificateNameMismatch` in Aspire
- `dotnet dev-certs https --check --trust` returns exit code 7
- HTTPS localhost connections fail with certificate validation errors
- After running `dotnet dev-certs https --clean` and needing to restore trust
- Setting up a new Linux dev machine for .NET HTTPS development
- Aspire dashboard or inter-service gRPC calls fail with TLS errors
- Upgrading from Aspire < 13.1.0 (which didn't use TLS on Redis by default)

## The Problem

On Windows and macOS, `dotnet dev-certs https --trust` handles everything automatically — it generates the certificate, installs it in the user store, and adds it to the system trust store. On Linux, **it does almost nothing useful**. The command generates the cert and places it in the user store, but:

1. It does **not** export the certificate to the system CA directory
2. It does **not** run `update-ca-certificates` to rebuild the CA bundle
3. It does **not** add the cert to browser trust stores (NSS/NSSDB)
4. The `--trust` flag silently succeeds but the cert remains untrusted

This means .NET applications, OpenSSL, curl, and browsers all reject the dev certificate — even though `dotnet dev-certs https --check` reports it exists.

### Why This Surfaces with Aspire 13.1.0+

Prior to Aspire 13.1.0, Redis connections used plaintext. Starting with 13.1.0, Aspire enables TLS on Redis by default. If your dev cert isn't trusted at the system level, Redis connections fail immediately with:

```
System.Security.Authentication.AuthenticationException:
  The remote certificate is invalid because of errors in the certificate chain: UntrustedRoot
```

## How Linux Certificate Trust Works

Understanding the architecture prevents cargo-cult debugging:

```
┌─────────────────────────────────────────────────────┐
│ Application (.NET, curl, OpenSSL)                   │
│   reads: /etc/ssl/certs/ca-certificates.crt         │
````
END THIRD-PARTY FILE add7cf2710679693

The third-party file has ended. Everything between the add7cf2710679693 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2460 of 16544 bytes. © Aaronontheweb · MIT · https://github.com/Aaronontheweb/dotnet-skills/tree/HEAD/skills/dotnet-devcert-trust/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md