dotnet-devcert-trust

.NET-Entwicklerzertifikat-Vertrauen unter Linux

Wann Sie dieses Skill verwenden sollten

Verwenden Sie dieses Skill, wenn:

• Redis-TLS-Verbindungen mit UntrustedRoot oder RemoteCertificateNameMismatch in Aspire fehlschlagen
• dotnet dev-certs https --check --trust den Exit-Code 7 zurückgibt
• HTTPS-Localhost-Verbindungen mit Zertifikatsvalidierungsfehlern fehlschlagen
• Sie nach dotnet dev-certs https --clean das Vertrauen wiederherstellen müssen
• Sie einen neuen Linux-Entwicklungsrechner für .NET-HTTPS-Entwicklung einrichten
• Das Aspire-Dashboard oder gRPC-Aufrufe zwischen Diensten mit TLS-Fehlern fehlschlagen
• Sie von Aspire < 13.1.0 aktualisieren (das standardmäßig kein TLS für Redis verwendet hat)

Das Problem

Unter Windows und macOS erledigt dotnet dev-certs https --trust alles automatisch – es erzeugt das Zertifikat, installiert es im Benutzerspeicher und fügt es dem Systemvertrauensspeicher hinzu. Unter Linux tut es fast nichts Nützliches. Der Befehl erzeugt das Zertifikat und platziert es im Benutzerspeicher, aber:

1. Es exportiert das Zertifikat nicht in das System-CA-Verzeichnis
2. Es führt nicht update-ca-certificates aus, um die CA-Bundle neu zu erstellen
3. Es fügt das Zertifikat nicht den Browser-Vertrauensspeichern (NSS/NSSDB) hinzu
4. Das --trust-Flag wird stillschweigend erfolgreich ausgeführt, aber das Zertifikat bleibt nicht vertrauenswürdig

Das bedeutet, dass .NET-Anwendungen, OpenSSL, curl und Browser das Entwicklerzertifikat alle ablehnen – obwohl dotnet dev-certs https --check meldet, dass es existiert.

Warum dies mit Aspire 13.1.0+ auftritt

Vor Aspire 13.1.0 verwendeten Redis-Verbindungen Klartext. Ab 13.1.0 aktiviert Aspire standardmäßig TLS für Redis. Wenn Ihr Entwicklerzertifikat nicht auf Systemebene vertrauenswürdig ist, schlagen Redis-Verbindungen sofort fehl mit:

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

Wie Linux-Zertifikatsvertrauen funktioniert

Das Verständnis der Architektur verhindert Debugging nach dem Gießkannenprinzip:

┌─────────────────────────────────────────────────────┐
│ Anwendung (.NET, curl, OpenSSL)                      │
│   liest: /etc/ssl/certs/ca-certificates.crt          │
│          (konsolidierte CA-Bundle)                   │
└──────────────────────┬──────────────────────────────┘
                       │ erstellt von
┌──────────────────────▼──────────────────────────────┐
│ update-ca-certificates                              │
│   liest von:                                         │
│     /usr/share/ca-certificates/      (Distro-CAs)   │
│     /usr/local/share/ca-certificates/ (lokale CAs)  │
│   schreibt in:                                       │
│     /etc/ssl/certs/ca-certificates.crt (Bundle)     │
│     /etc/ssl/certs/*.pem (einzelne Symlinks)        │
└─────────────────────────────────────────────────────┘

Wichtige Erkenntnis: Das Platzieren einer .crt-Datei in /usr/local/share/ca-certificates/ ist notwendig, aber nicht ausreichend. Die konsolidierte Bundle-Datei unter /etc/ssl/certs/ca-certificates.crt muss durch Ausführen von update-ca-certificates neu erstellt werden. Anwendungen lesen die Bundle-Datei, nicht die einzelnen Dateien.

5-Punkte-Diagnoseprozedur

Führen Sie diese Prüfungen in der Reihenfolge durch. Stoppen Sie beim ersten FEHLER und wenden Sie dessen Korrektur an, bevor Sie fortfahren.

Prüfung 1: Existenz des Entwicklerzertifikats

dotnet dev-certs https --check
echo "Exit-Code: $?"

Exit-Code	Bedeutung	Aktion
0	Zertifikat existiert im Benutzerspeicher	BESTANDEN – fortfahren
Nicht-Null	Kein gültiges Entwicklerzertifikat	Führen Sie dotnet dev-certs https aus

Prüfung 2: Systemvertrauensspeicher – Einzelnes Zertifikat, korrekte Berechtigungen

ls -la /usr/local/share/ca-certificates/ | grep -iE 'dotnet|aspnet'

Ergebnis	Bedeutung
Nur dotnet-dev-cert.crt mit -rw-r--r-- (644)	BESTANDEN
Mehrere Zertifikatsdateien, falsche Berechtigungen oder veraltete aspnet*-Dateien	FEHLER

Häufige veraltete Dateien aus vorherigen Sitzungen:

Datei	Problem
aspnetcore-dev.crt	Oft mit Berechtigungen 0600 erstellt (für update-ca-certificates nicht lesbar)
aspnet/https.crt	Alte Konvention, möglicherweise mit einem anderen Fingerabdruck als das aktuelle Entwicklerzertifikat
dotnet-dev-cert.crt mit 0600	Korrekter Name, aber falsche Berechtigungen

Korrektur:

# Entfernen Sie ALLE veralteten Zertifikatsdateien
sudo rm -f /usr/local/share/ca-certificates/aspnetcore-dev.crt
sudo rm -rf /usr/local/share/ca-certificates/aspnet/

# Stellen Sie korrekte Berechtigungen für das Entwicklerzertifikat sicher (falls vorhanden)
sudo chmod 644 /usr/local/share/ca-certificates/dotnet-dev-cert.crt

Prüfung 3: Einbindung in die CA-Bundle

Dies ist die am häufigsten fehlgeschlagene Prüfung. Die Zertifikatsdatei existiert, wurde aber nie zur Bundle-Datei hinzugefügt.

openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt \
  /usr/local/share/ca-certificates/dotnet-dev-cert.crt

Ergebnis	Bedeutung
dotnet-dev-cert.crt: OK	BESTANDEN – Zertifikat ist in der konsolidierten Bundle-Datei
error 20 at 0 depth lookup: unable to get local issuer certificate	FEHLER – Bundle wurde nie neu erstellt
error 2 at 0 depth lookup: unable to get issuer certificate	FEHLER – gleiches Problem, andere OpenSSL-Version

Korrektur:

sudo update-ca-certificates
# Erwartete Ausgabe enthält "1 added" oder ähnlich

# Erneute Überprüfung
openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt \
  /usr/local/share/ca-certificates/dotnet-dev-cert.crt

Prüfung 4: Überschreibungen durch Umgebungsvariablen

SSL-Umgebungsvariablen können die Zertifikatssuche von der System-Bundle-Datei wegleiten:

echo "SSL_CERT_DIR=${SSL_CERT_DIR:-<nicht gesetzt>}"
echo "SSL_CERT_FILE=${SSL_CERT_FILE:-<nicht gesetzt>}"
echo "DOTNET_SSL_CERT_DIR=${DOTNET_SSL_CERT_DIR:-<nicht gesetzt>}"
echo "DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER=${DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER:-<nicht gesetzt>}"

Ergebnis	Bedeutung
Alle <nicht gesetzt>	BESTANDEN
Irgendeine Variable gesetzt	FEHLER – könnte die Zertifikatssuche umleiten

Korrektur: Entfernen Sie die störenden Variablen aus Ihrem Shell-Profil (~/.bashrc, ~/.zshrc, ~/.profile) und starten Sie eine neue Shell.

Prüfung 5: Integrität der symbolischen Links

Veraltete symbolische Links von zuvor entfernten Zertifikaten können OpenSSL verwirren:

find /etc/ssl/certs/ -xtype l 2>/dev/null | head -5

Ergebnis	Bedeutung
Keine Ausgabe	BESTANDEN
Defekte symbolische Links aufgelistet	FEHLER

Korrektur:

sudo update-ca-certificates --fresh
# Erstellt ALLE symbolischen Links von Grund auf neu

Vollständige Wiederherstellungsprozedur

Wenn mehrere Prüfungen fehlschlagen oder Sie eine saubere Ausgangsbasis wünschen, führen Sie diese vollständige Sequenz aus:

#!/usr/bin/env bash
set -euo pipefail

echo "=== .NET-Entwicklerzertifikat-Vertrauenswiederherstellung ==="

# Schritt 1: Entfernen Sie ALLE veralteten Zertifikatsdateien
echo "--- Entfernen veralteter Zertifikatsdateien ---"
sudo rm -f /usr/local/share/ca-certificates/aspnetcore-dev.crt
sudo rm -rf /usr/local/share/ca-certificates/aspnet/
sudo rm -f /usr/local/share/ca-certificates/dotnet-dev-cert.crt

# Schritt 2: Bereinigen und Neuerstellen des Entwicklerzertifikats
echo "--- Neuerstellen des Entwicklerzertifikats ---"
dotnet dev-certs https --clean
dotnet dev-certs https

# Schritt 3: Als PEM exportieren und im Systemvertrauensspeicher installieren
echo "--- Installieren im Systemvertrauensspeicher ---"
dotnet dev-certs https --export-path /tmp/dotnet-dev-cert.crt --format PEM --no-password
sudo cp /tmp/dotnet-dev-cert.crt /usr/local/share/ca-certificates/dotnet-dev-cert.crt
sudo chmod 644 /usr/local/share/ca-certificates/dotnet-dev-cert.crt
rm /tmp/dotnet-dev-cert.crt

# Schritt 4: CA-Bundle neuerstellen (KRITISCH – am häufigsten übersehener Schritt)
echo "--- Neuerstellen der CA-Bundle ---"
sudo update-ca-certificates

# Schritt 5: Überprüfung
echo "--- Überprüfung ---"
openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt \
  /usr/local/share/ca-certificates/dotnet-dev-cert.crt

echo "=== Fertig! Starten Sie Ihre .NET-Anwendung neu. ==="

Speichern Sie dies als ~/fix-devcert.sh und führen Sie es bei Bedarf mit bash ~/fix-devcert.sh aus.

Distri-spezifische Hinweise

Ubuntu / Debian

Die obige Prozedur ist für Ubuntu/Debian geschrieben und funktioniert unverändert.

• CA-Verzeichnis: /usr/local/share/ca-certificates/
• Bundle-Befehl: sudo update-ca-certificates
• Bundle-Ausgabe: /etc/ssl/certs/ca-certificates.crt
• Zertifikatsformat: PEM mit Erweiterung .crt erforderlich

Fedora / RHEL / CentOS

Fedora verwendet update-ca-trust anstelle von update-ca-certificates:

# Zertifikat exportieren
dotnet dev-certs https --export-path /tmp/dotnet-dev-cert.pem --format PEM --no-password

# Im Fedora-Vertrauensspeicher installieren (anderes Verzeichnis!)
sudo cp /tmp/dotnet-dev-cert.pem /etc/pki/ca-trust/source/anchors/dotnet-dev-cert.pem
sudo chmod 644 /etc/pki/ca-trust/source/anchors/dotnet-dev-cert.pem
rm /tmp/dotnet-dev-cert.pem

# Vertrauensbundle neuerstellen
sudo update-ca-trust

# Überprüfung
openssl verify /etc/pki/ca-trust/source/anchors/dotnet-dev-cert.pem

Wichtige Unterschiede:

	Ubuntu/Debian	Fedora/RHEL
CA-Verzeichnis	/usr/local/share/ca-certificates/	/etc/pki/ca-trust/source/anchors/
Neuerstellungsbefehl	update-ca-certificates	update-ca-trust
Bundle-Pfad	/etc/ssl/certs/ca-certificates.crt	/etc/pki/tls/certs/ca-bundle.crt
Erweiterung	.crt	.pem (jede Erweiterung funktioniert)

Arch Linux

Arch verwendet denselben update-ca-trust-Ansatz wie Fedora:

sudo cp /tmp/dotnet-dev-cert.pem /etc/ca-certificates/trust-source/anchors/dotnet-dev-cert.pem
sudo chmod 644 /etc/ca-certificates/trust-source/anchors/dotnet-dev-cert.pem
sudo update-ca-trust

WSL2

WSL2 führt einen echten Linux-Kernel mit einem eigenen Zertifikatsspeicher aus – getrennt vom Windows-Host. Die Standardprozedur für Ubuntu/Debian funktioniert, aber achten Sie auf:

1. Gemeinsames Dateisystem (/mnt/c/) – Zertifikatsdateien auf dem Windows-Dateisystem haben Windows-Berechtigungen, die möglicherweise nicht 644 sind. Kopieren Sie immer zuerst in einen nativen Linux-Pfad.
2. systemd läuft nicht – Einige ältere WSL2-Setups haben kein systemd, von dem update-ca-certificates-Hooks abhängen können. Wenn der Befehl hängt, versuchen Sie stattdessen sudo dpkg-reconfigure ca-certificates.
3. Docker Desktop-Integration – Wenn Sie das WSL2-Backend von Docker Desktop verwenden, erben Container die CA-Bundle der WSL2-Distribution. Das Beheben des Vertrauens in WSL2 behebt es auch für Container.

Aspire-spezifische Überlegungen

Redis TLS (Aspire 13.1.0+)

Aspire 13.1.0 aktiviert standardmäßig TLS für Redis. Wenn Sie Folgendes sehen:

UntrustedRoot

in Redis-Verbindungsfehlern, ist das Entwicklerzertifikat nicht auf Systemebene vertrauenswürdig. Führen Sie die obige vollständige Wiederherstellungsprozedur aus.

Aspire-Dashboard HTTPS

Das Aspire-Dashboard verwendet das Entwicklerzertifikat für HTTPS. Wenn das Dashboard Zertifikatswarnungen im Browser anzeigt, ist das Zertifikat nicht im Vertrauensspeicher des Browsers. Für die Entwicklung ist das Durchklicken der Warnung akzeptabel – das Vertrauen auf Systemebene (benötigt für Redis, gRPC usw.) hat Priorität.

ASPIRE_ALLOW_UNSECURED_TRANSPORT

Das Setzen von ASPIRE_ALLOW_UNSECURED_TRANSPORT=true ist ein Workaround, keine Korrektur. Es deaktiviert TLS für die Kommunikation zwischen Diensten, was:

• Das zugrunde liegende Vertrauensproblem verdeckt
• Nicht dem Produktionsverhalten entspricht
• Andere Fehler verursachen kann als in der Produktion

Beheben Sie stattdessen das Zertifikatsvertrauen.

Zertifikatslebenszyklus

Das Entwicklerzertifikat ist ab dem Zeitpunkt der Erstellung 1 Jahr gültig. Wenn es abläuft:

1. dotnet dev-certs https --check meldet kein gültiges Zertifikat
2. Führen Sie die vollständige Wiederherstellungsprozedur aus, um ein neues Zertifikat zu generieren
3. Die alte Zertifikatsdatei in /usr/local/share/ca-certificates/ wird ersetzt
4. update-ca-certificates tauscht das alte Zertifikat gegen das neue in der Bundle-Datei aus

Es ist kein Systemneustart erforderlich. Anwendungen übernehmen die neue Bundle-Datei beim nächsten TLS-Handshake (starten Sie Ihre App neu).

Automatisierung: CI/CD-Pipelines

In CI/CD auf Linux-Runnern werden Entwicklerzertifikate selten benötigt (normalerweise testen Sie mit echten Zertifikaten oder deaktivieren die TLS-Validierung in Test-Harness). Wenn Ihre Integrationstests jedoch vertrauenswürdige Entwicklerzertifikate erfordern:

GitHub Actions

- name: .NET-Entwicklerzertifikat vertrauen
  run: |
    dotnet dev-certs https
    dotnet dev-certs https --export-path /tmp/dotnet-dev-cert.crt --format PEM --no-password
    sudo cp /tmp/dotnet-dev-cert.crt /usr/local/share/ca-certificates/dotnet-dev-cert.crt
    sudo chmod 644 /usr/local/share/ca-certificates/dotnet-dev-cert.crt
    rm /tmp/dotnet-dev-cert.crt
    sudo update-ca-certificates

Azure DevOps

- script: |
    dotnet dev-certs https
    dotnet dev-certs https --export-path /tmp/dotnet-dev-cert.crt --format PEM --no-password
    sudo cp /tmp/dotnet-dev-cert.crt /usr/local/share/ca-certificates/dotnet-dev-cert.crt
    sudo chmod 644 /usr/local/share/ca-certificates/dotnet-dev-cert.crt
    rm /tmp/dotnet-dev-cert.crt
    sudo update-ca-certificates
  displayName: '.NET-Entwicklerzertifikat vertrauen'

Häufige Fehler

1. Zertifikat platziert, aber Bundle nie neu erstellt

Symptom: Zertifikatsdatei existiert in /usr/local/share/ca-certificates/, aber openssl verify schlägt fehl.

Ursache: update-ca-certificates wurde nach dem Platzieren der Datei nie ausgeführt.

Korrektur: sudo update-ca-certificates

Dies ist der mit Abstand häufigste Fehler. Das CA-Verzeichnis ist eine Eingabe für den Bundle-Erstellungsprozess, nicht die Bundle-Datei selbst.

2. Veraltete Zertifikatsdateien mit falschen Berechtigungen

Symptom: update-ca-certificates wird ausgeführt, meldet aber 0 added.

Ursache: Zertifikatsdateien mit Berechtigungen 0600 sind für update-ca-certificates nicht lesbar (wird als root ausgeführt, liest Dateien aber möglicherweise durch einen Prozess, der die Weltlesbarkeit überprüft). Dateien müssen 644 sein.

Korrektur: sudo chmod 644 /usr/local/share/ca-certificates/*.crt

3. Mehrere Zertifikatsdateien aus verschiedenen Sitzungen

Symptom: update-ca-certificates fügt mehrere Zertifikate hinzu, aber die Anwendungen schlagen immer noch fehl.

Ursache: Alte Zertifikatsdateien aus vorherigen dotnet dev-certs https --clean / Neuerstellungszyklen verbleiben im CA-Verzeichnis. Der Fingerabdruck des alten Zertifikats stimmt nicht mit dem aktuellen Entwicklerzertifikat überein.

Korrektur: Entfernen Sie alle dotnet*- und aspnet*-Dateien und exportieren Sie dann das aktuelle Zertifikat erneut.

4. Fingerabdruck-Konflikt nach Bereinigung/Neuerstellung

Symptom: openssl verify ist erfolgreich, aber .NET meldet immer noch UntrustedRoot.

Ursache: Das Zertifikat in /usr/local/share/ca-certificates/ wurde von einem vorherigen Entwicklerzertifikat exportiert. Nach dotnet dev-certs https --clean && dotnet dev-certs https hat ein neues Zertifikat einen anderen Fingerabdruck. Die Bundle-Datei enthält noch den alten Fingerabdruck, nicht den neuen.

Korrektur: Löschen Sie die alte Zertifikatsdatei und exportieren Sie das aktuelle Zertifikat erneut, dann führen Sie sudo update-ca-certificates aus.

5. Gemischte Änderungszeitstempel in der Bundle-Datei

Symptom: update-ca-certificates läuft ohne Fehler, aber openssl verify schlägt fehl.

Ursache: Die Bundle-Datei /etc/ssl/certs/ca-certificates.crt wurde nicht korrekt aktualisiert. Dies kann passieren, wenn Sie die Bundle-Datei manuell bearbeitet haben oder wenn ein anderes Tool die Bundle-Datei überschrieben hat.

Korrektur: Führen Sie sudo update-ca-certificates --fresh aus, um die Bundle-Datei und alle symbolischen Links von Grund auf neu zu erstellen.