dotnet-devcert-trust

Name: dotnet-devcert-trust
Author: Aaronontheweb

329installs98forks

How to install dotnet-devcert-trust?

aaronontheweb/dotnet-skills/dotnet-devcert-trust

$npx -y skills add Aaronontheweb/dotnet-skills --skill dotnet-devcert-trust

Installs into the current project.

Summary

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.

Files · 1

View on GitHub

SKILL.md

1	# .NET Dev Certificate Trust on Linux
2
3	## When to Use This Skill
4
5	Use this skill when:
6	- Redis TLS connections fail with `UntrustedRoot` or `RemoteCertificateNameMismatch` in Aspire
7	- `dotnet dev-certs https --check --trust` returns exit code 7
8	- HTTPS localhost connections fail with certificate validation errors
9	- After running `dotnet dev-certs https --clean` and needing to restore trust
10	- Setting up a new Linux dev machine for .NET HTTPS development
11	- Aspire dashboard or inter-service gRPC calls fail with TLS errors
12	- Upgrading from Aspire < 13.1.0 (which didn't use TLS on Redis by default)
13
14	## The Problem
15
16	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:
17
18	1. It does not export the certificate to the system CA directory
19	2. It does not run `update-ca-certificates` to rebuild the CA bundle
20	3. It does not add the cert to browser trust stores (NSS/NSSDB)
21	4. The `--trust` flag silently succeeds but the cert remains untrusted
22
23	This means .NET applications, OpenSSL, curl, and browsers all reject the dev certificate — even though `dotnet dev-certs https --check` reports it exists.
24
25	### Why This Surfaces with Aspire 13.1.0+
26
27	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:
28
29	```
30	System.Security.Authentication.AuthenticationException:
31	The remote certificate is invalid because of errors in the certificate chain: UntrustedRoot
32	```
33
34	## How Linux Certificate Trust Works
35
36	Understanding the architecture prevents cargo-cult debugging:
37
38	```
39	┌─────────────────────────────────────────────────────┐
40	│ Application (.NET, curl, OpenSSL) │
41	│ reads: /etc/ssl/certs/ca-certificates.crt │
42	│ (consolidated CA bundle) │
43	└──────────────────────┬──────────────────────────────┘
44	│ built by
45	┌──────────────────────▼──────────────────────────────┐
46	│ update-ca-certificates │
47	│ reads from: │
48	│ /usr/share/ca-certificates/ (distro CAs) │
49	│ /usr/local/share/ca-certificates/ (local CAs) │
50	│ writes to: │
51	│ /etc/ssl/certs/ca-certificates.crt (bundle) │
52	│ /etc/ssl/certs/*.pem (individual symlinks) │
53	└─────────────────────────────────────────────────────┘
54	```
55
56	Key insight: Placing a `.crt` file in `/usr/local/share/ca-certificates/` is necessary but not sufficient. The consolidated bundle at `/etc/ssl/certs/ca-certificates.crt` must be rebuilt by running `update-ca-certificates`. Applications read the bundle, not the individual files.
57
58	## 5-Point Diagnostic Procedure
59
60	Run these checks in order. Stop at the first FAIL and apply its fix before continuing.
61
62	### Check 1: Dev Cert Existence
63
64	```bash
65	dotnet dev-certs https --check
66	echo "Exit code: $?"
67	```
68
69	\| Exit Code \| Meaning \| Action \|
70	\|-----------\|---------\|--------\|
71	\| 0 \| Cert exists in user store \| PASS — continue \|
72	\| Non-zero \| No valid dev cert \| Run `dotnet dev-certs https` \|
73
74	### Check 2: System Trust Store — Single Cert, Correct Permissions
75
76	```bash
77	ls -la /usr/local/share/ca-certificates/ \| grep -iE 'dotnet\|aspnet'
78	```
79
80	\| Result \| Meaning \|
81	\|--------\|---------\|
82	\| Only `dotnet-dev-cert.crt` with `-rw-r--r--` (644) \| PASS \|
83	\| Multiple cert files, wrong permissions, or stale `aspnet*` files \| FAIL \|
84
85	Common stale files from previous sessions:
86
87	\| File \| Problem \|
88	\|------\|---------\|
89	\| `aspnetcore-dev.crt` \| Often created with `0600` permissions (unreadable by `update-ca-certificates`) \|
90	\| `aspnet/https.crt` \| Old convention, may have a different fingerprint than current dev cert \|
91	\| `dotnet-dev-cert.crt` with `0600` \| Correct name but wrong permissions \|
92
93	Fix:
94	```bash
95	# Remove ALL stale cert files
96	sudo rm -f /usr/local/share/ca-certificates/aspnetcore-dev.crt
97	sudo rm -rf /usr/local/share/ca-certificates/aspnet/
98
99	# Ensure correct permissions on the dev cert (if it exists)
100	sudo chmod 644 /usr/local/share/ca-certificates/dotnet-dev-cert.crt
101	```
102
103	### Check 3: CA Bundle Inclusion
104
105	This is the most commonly failed check. The cert file exists but was never added to the bundle.
106
107	```bash
108	openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt \
109	/usr/local/share/ca-certificates/dotnet-dev-cert.crt
110	```
111
112	\| Result \| Meaning \|
113	\|--------\|---------\|
114	\| `dotnet-dev-cert.crt: O

People who liked this also viewed

6 picks

Type

dotnet-devcert-trust

329installs98forks

View on GitHub

How to install dotnet-devcert-trust?

aaronontheweb/dotnet-skills/dotnet-devcert-trust

$npx -y skills add Aaronontheweb/dotnet-skills --skill dotnet-devcert-trust

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# .NET Dev Certificate Trust on Linux
2
3	## When to Use This Skill
4
5	Use this skill when:
6	- Redis TLS connections fail with `UntrustedRoot` or `RemoteCertificateNameMismatch` in Aspire
7	- `dotnet dev-certs https --check --trust` returns exit code 7
8	- HTTPS localhost connections fail with certificate validation errors
9	- After running `dotnet dev-certs https --clean` and needing to restore trust
10	- Setting up a new Linux dev machine for .NET HTTPS development
11	- Aspire dashboard or inter-service gRPC calls fail with TLS errors
12	- Upgrading from Aspire < 13.1.0 (which didn't use TLS on Redis by default)
13
14	## The Problem
15
16	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:
17
18	1. It does not export the certificate to the system CA directory
19	2. It does not run `update-ca-certificates` to rebuild the CA bundle
20	3. It does not add the cert to browser trust stores (NSS/NSSDB)
21	4. The `--trust` flag silently succeeds but the cert remains untrusted
22
23	This means .NET applications, OpenSSL, curl, and browsers all reject the dev certificate — even though `dotnet dev-certs https --check` reports it exists.
24
25	### Why This Surfaces with Aspire 13.1.0+
26
27	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:
28
29	```
30	System.Security.Authentication.AuthenticationException:
31	The remote certificate is invalid because of errors in the certificate chain: UntrustedRoot
32	```
33
34	## How Linux Certificate Trust Works
35
36	Understanding the architecture prevents cargo-cult debugging:
37
38	```
39	┌─────────────────────────────────────────────────────┐
40	│ Application (.NET, curl, OpenSSL) │
41	│ reads: /etc/ssl/certs/ca-certificates.crt │
42	│ (consolidated CA bundle) │
43	└──────────────────────┬──────────────────────────────┘
44	│ built by
45	┌──────────────────────▼──────────────────────────────┐
46	│ update-ca-certificates │
47	│ reads from: │
48	│ /usr/share/ca-certificates/ (distro CAs) │
49	│ /usr/local/share/ca-certificates/ (local CAs) │
50	│ writes to: │
51	│ /etc/ssl/certs/ca-certificates.crt (bundle) │
52	│ /etc/ssl/certs/*.pem (individual symlinks) │
53	└─────────────────────────────────────────────────────┘
54	```
55
56	Key insight: Placing a `.crt` file in `/usr/local/share/ca-certificates/` is necessary but not sufficient. The consolidated bundle at `/etc/ssl/certs/ca-certificates.crt` must be rebuilt by running `update-ca-certificates`. Applications read the bundle, not the individual files.
57
58	## 5-Point Diagnostic Procedure
59
60	Run these checks in order. Stop at the first FAIL and apply its fix before continuing.
61
62	### Check 1: Dev Cert Existence
63
64	```bash
65	dotnet dev-certs https --check
66	echo "Exit code: $?"
67	```
68
69	\| Exit Code \| Meaning \| Action \|
70	\|-----------\|---------\|--------\|
71	\| 0 \| Cert exists in user store \| PASS — continue \|
72	\| Non-zero \| No valid dev cert \| Run `dotnet dev-certs https` \|
73
74	### Check 2: System Trust Store — Single Cert, Correct Permissions
75
76	```bash
77	ls -la /usr/local/share/ca-certificates/ \| grep -iE 'dotnet\|aspnet'
78	```
79
80	\| Result \| Meaning \|
81	\|--------\|---------\|
82	\| Only `dotnet-dev-cert.crt` with `-rw-r--r--` (644) \| PASS \|
83	\| Multiple cert files, wrong permissions, or stale `aspnet*` files \| FAIL \|
84
85	Common stale files from previous sessions:
86
87	\| File \| Problem \|
88	\|------\|---------\|
89	\| `aspnetcore-dev.crt` \| Often created with `0600` permissions (unreadable by `update-ca-certificates`) \|
90	\| `aspnet/https.crt` \| Old convention, may have a different fingerprint than current dev cert \|
91	\| `dotnet-dev-cert.crt` with `0600` \| Correct name but wrong permissions \|
92
93	Fix:
94	```bash
95	# Remove ALL stale cert files
96	sudo rm -f /usr/local/share/ca-certificates/aspnetcore-dev.crt
97	sudo rm -rf /usr/local/share/ca-certificates/aspnet/
98
99	# Ensure correct permissions on the dev cert (if it exists)
100	sudo chmod 644 /usr/local/share/ca-certificates/dotnet-dev-cert.crt
101	```
102
103	### Check 3: CA Bundle Inclusion
104
105	This is the most commonly failed check. The cert file exists but was never added to the bundle.
106
107	```bash
108	openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt \
109	/usr/local/share/ca-certificates/dotnet-dev-cert.crt
110	```
111
112	\| Result \| Meaning \|
113	\|--------\|---------\|
114	\| `dotnet-dev-cert.crt: O

People who liked this also viewed

6 picks

Type