dotnet-devcert-trust_skill

This skill helps diagnose and fix Linux .NET HTTPS dev certificate trust issues from generation to system CA integration.

Shell

643

GitHub Stars

1

Bundled Files

2 months ago

Catalog Refreshed

4 months ago

First Indexed

Readme & install

Copy the install command, review bundled files from the catalogue, and read any extended description pulled from the listing source.

Installation

Preview and clipboard use veilstrat where the catalogue uses aiagentskills.

npx veilstrat add skill aaronontheweb/dotnet-skills --skill dotnet-devcert-trust

SKILL.md16.2 KB

Overview

This skill diagnoses and repairs .NET development HTTPS certificate trust issues on Linux. It walks through the certificate lifecycle from generation to installing the cert into the system CA bundle, and includes distro-specific guidance for Ubuntu/Debian, Fedora/RHEL, Arch, and WSL2. The goal is to restore system-level trust so .NET, curl, OpenSSL, and browsers accept the dev cert.

How this skill works

The skill runs a five-point diagnostic: check the dev cert in the user store, verify the cert file and permissions in the system CA directory, confirm the cert is included in the consolidated CA bundle, detect environment variable overrides, and validate symlink integrity. When a check fails it provides exact shell commands to fix the issue and a full recovery script that regenerates, exports, installs, and rebuilds the CA bundle. Distro-specific rebuild commands (update-ca-certificates, update-ca-trust) are provided.

When to use it

Local HTTPS to localhost returns certificate validation errors for .NET apps or browsers
dotnet dev-certs https --check returns non-zero or --trust appears to do nothing
Redis or gRPC in development fails with UntrustedRoot after Aspire 13.1.0+
You moved to a new Linux dev machine or WSL2 instance and need trusted dev certs
After cleaning dev certs (dotnet dev-certs https --clean) and the system still rejects TLS

Best practices

Always export the dev cert to PEM and copy it into the distro-specific CA directory
Run the distro’s rebuild tool (update-ca-certificates or update-ca-trust) — this is required
Ensure system cert files are world-readable (chmod 644) before rebuilding the bundle
Remove stale dotnet/aspnet cert files before installing the new cert to avoid fingerprint mismatches
Check and unset SSL_CERT_DIR, SSL_CERT_FILE, and DOTNET_SSL_CERT_DIR if trust looks overridden

Example use cases

Fixing UntrustedRoot errors when connecting to Redis secured by a dev cert
Restoring trust after regenerating the dev certificate with dotnet dev-certs https --clean
Configuring GitHub Actions or Azure DevOps runners to trust the generated dev cert for integration tests
Making the dev cert trusted inside WSL2 and containers that inherit its CA bundle
Repairing broken symlinks or stale entries in the system CA store that confuse OpenSSL

FAQ

On Linux the command only generates the user cert. It does not copy the cert into the system CA directory or rebuild the consolidated bundle, so applications still see it as untrusted.

Do I need to reboot after rebuilding the CA bundle?

No. Applications pick up the new bundle on the next TLS handshake. Restart your .NET app or service to ensure it reads the updated bundle.