Linux 上 .NET 开发证书信任问题解决指南：修复 Aspire Redis TLS 错误

dotnet-devcert-trust by aaronontheweb/dotnet-skills

95 周安装量

675 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/aaronontheweb/dotnet-skills --skill dotnet-devcert-trust

.NET 系统管理开发运维

🇨🇳中文介绍

Linux 上的 .NET 开发证书信任

何时使用此技能

在以下情况时使用此技能：

Aspire 中的 Redis TLS 连接因 UntrustedRoot 或 RemoteCertificateNameMismatch 而失败
dotnet dev-certs https --check --trust 返回退出代码 7
HTTPS localhost 连接因证书验证错误而失败
运行 dotnet dev-certs https --clean 后需要恢复信任
为 .NET HTTPS 开发设置新的 Linux 开发机器
Aspire 仪表板或服务间 gRPC 调用因 TLS 错误而失败
从 Aspire < 13.1.0 升级（该版本默认未在 Redis 上使用 TLS）

问题描述

在 Windows 和 macOS 上，dotnet dev-certs https --trust 会自动处理所有事情——它生成证书，将其安装到用户存储中，并将其添加到系统信任存储中。在 Linux 上，它几乎不做任何有用的事情。该命令会生成证书并将其放入用户存储中，但是：

它不将证书导出到系统 CA 目录
它不运行来重建 CA 包

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

为什么在 Aspire 13.1.0+ 中出现此问题

在 Aspire 13.1.0 之前，Redis 连接使用明文。从 13.1.0 开始，Aspire 默认在 Redis 上启用 TLS。如果您的开发证书在系统级别不受信任，Redis 连接会立即失败，并显示：

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

Linux 证书信任的工作原理

了解架构可以避免盲目调试：

┌─────────────────────────────────────────────────────┐
│ Application (.NET, curl, OpenSSL)                   │
│   reads: /etc/ssl/certs/ca-certificates.crt         │
│          (consolidated CA bundle)                    │
└──────────────────────┬──────────────────────────────┘
                       │ built by
┌──────────────────────▼──────────────────────────────┐
│ update-ca-certificates                              │
│   reads from:                                        │
│     /usr/share/ca-certificates/      (distro CAs)   │
│     /usr/local/share/ca-certificates/ (local CAs)   │
│   writes to:                                         │
│     /etc/ssl/certs/ca-certificates.crt (bundle)     │
│     /etc/ssl/certs/*.pem (individual symlinks)      │
└─────────────────────────────────────────────────────┘

关键见解： 将 .crt 文件放在 /usr/local/share/ca-certificates/ 中是必要的，但还不够。必须通过运行 update-ca-certificates 来重建 /etc/ssl/certs/ca-certificates.crt 处的合并包。应用程序读取的是包，而不是单个文件。

按顺序运行这些检查。在第一个失败处停止，并在继续之前应用其修复。

检查 1：开发证书是否存在

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

退出代码	含义	操作
0	证书存在于用户存储中	通过 — 继续
非零	没有有效的开发证书	运行 `dotnet dev-certs https`

检查 2：系统信任存储 — 单个证书，权限正确

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

结果	含义
只有 `dotnet-dev-cert.crt` 且权限为 `-rw-r--r--` (644)	通过
多个证书文件、权限错误或过时的 `aspnet*` 文件	失败

来自先前会话的常见过时文件：

文件	问题
`aspnetcore-dev.crt`	通常创建时具有 `0600` 权限（`update-ca-certificates` 无法读取）
`aspnet/https.crt`	旧约定，可能具有与当前开发证书不同的指纹
`dotnet-dev-cert.crt` 且权限为 `0600`	名称正确但权限错误

# 删除所有过时的证书文件
sudo rm -f /usr/local/share/ca-certificates/aspnetcore-dev.crt
sudo rm -rf /usr/local/share/ca-certificates/aspnet/

# 确保开发证书的权限正确（如果存在）
sudo chmod 644 /usr/local/share/ca-certificates/dotnet-dev-cert.crt

检查 3：CA 包包含情况

这是最常失败的检查。证书文件存在但从未添加到包中。

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

结果	含义
`dotnet-dev-cert.crt: OK`	通过 — 证书在合并包中
`error 20 at 0 depth lookup: unable to get local issuer certificate`	失败 — 包从未重建
`error 2 at 0 depth lookup: unable to get issuer certificate`	失败 — 相同问题，OpenSSL 版本不同

sudo update-ca-certificates
# 预期输出包括 "1 added" 或类似内容

# 重新验证
openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt \
  /usr/local/share/ca-certificates/dotnet-dev-cert.crt

检查 4：环境变量覆盖

SSL 环境变量可以将证书查找重定向到系统包之外：

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

结果	含义
全部 `<unset>`	通过
任何变量已设置	失败 — 可能重定向证书查找

修复： 从您的 shell 配置文件（~/.bashrc、~/.zshrc、~/.profile）中删除有问题的变量，并启动一个新的 shell。

检查 5：符号链接完整性

来自先前已删除证书的过时符号链接可能会混淆 OpenSSL：

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

结果	含义
无输出	通过
列出损坏的符号链接	失败

sudo update-ca-certificates --fresh
# 从头开始重建所有符号链接

当多个检查失败或您想要一个干净的状态时，运行此完整序列：

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

echo "=== .NET 开发证书信任恢复 ==="

# 步骤 1：删除所有过时的证书文件
echo "--- 删除过时的证书文件 ---"
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

# 步骤 2：清理并重新生成开发证书
echo "--- 重新生成开发证书 ---"
dotnet dev-certs https --clean
dotnet dev-certs https

# 步骤 3：导出为 PEM 并安装到系统信任存储
echo "--- 安装到系统信任存储 ---"
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

# 步骤 4：重建 CA 包（关键 — 最常被遗漏的步骤）
echo "--- 重建 CA 包 ---"
sudo update-ca-certificates

# 步骤 5：验证
echo "--- 验证 ---"
openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt \
  /usr/local/share/ca-certificates/dotnet-dev-cert.crt

echo "=== 完成！重启您的 .NET 应用程序。 ==="

将其保存为 ~/fix-devcert.sh，并在需要时使用 bash ~/fix-devcert.sh 运行。

发行版特定说明

上述流程是为 Ubuntu/Debian 编写的，可以直接使用。

CA 目录： /usr/local/share/ca-certificates/
包命令： sudo update-ca-certificates
包输出： /etc/ssl/certs/ca-certificates.crt
证书格式： 需要具有 .crt 扩展名的 PEM

Fedora / RHEL / CentOS

Fedora 使用 update-ca-trust 而不是 update-ca-certificates：

# 导出证书
dotnet dev-certs https --export-path /tmp/dotnet-dev-cert.pem --format PEM --no-password

# 安装到 Fedora 信任存储（不同的目录！）
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

# 重建信任包
sudo update-ca-trust

# 验证
openssl verify /etc/pki/ca-trust/source/anchors/dotnet-dev-cert.pem

| Ubuntu/Debian | Fedora/RHEL
---|---|---
CA 目录 | /usr/local/share/ca-certificates/ | /etc/pki/ca-trust/source/anchors/
重建命令 | update-ca-certificates | update-ca-trust
包路径 | /etc/ssl/certs/ca-certificates.crt | /etc/pki/tls/certs/ca-bundle.crt
扩展名 | .crt | .pem（任何扩展名都有效）

Arch 使用与 Fedora 相同的 update-ca-trust 方法：

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 运行一个真实的 Linux 内核，拥有自己的证书存储——与 Windows 主机分离。标准的 Ubuntu/Debian 流程有效，但请注意：

共享文件系统 (/mnt/c/) — Windows 文件系统上的证书文件具有 Windows 权限，可能不是 644。始终先复制到本机 Linux 路径。
systemd 未运行 — 一些较旧的 WSL2 设置没有 systemd，而 update-ca-certificates 钩子可能依赖它。如果命令挂起，请尝试 sudo dpkg-reconfigure ca-certificates。
Docker Desktop 集成 — 如果使用 Docker Desktop 的 WSL2 后端，容器会继承 WSL2 发行版的 CA 包。在 WSL2 中修复信任也会为容器修复它。

Aspire 特定注意事项

Redis TLS (Aspire 13.1.0+)

Aspire 13.1.0 默认在 Redis 上启用 TLS。如果您在 Redis 连接错误中看到：

则开发证书在系统级别不受信任。运行上述完整恢复流程。

Aspire 仪表板 HTTPS

Aspire 仪表板使用开发证书进行 HTTPS。如果仪表板在浏览器中显示证书警告，则证书不在浏览器的信任存储中。对于开发，点击通过警告是可以接受的——系统级信任（Redis、gRPC 等所需）是优先事项。

ASPIRE_ALLOW_UNSECURED_TRANSPORT

设置 ASPIRE_ALLOW_UNSECURED_TRANSPORT=true 是一个变通方法，而不是修复。它会禁用服务间通信的 TLS，这会：

掩盖底层的信任问题
与生产行为不匹配
可能导致与生产环境中不同的错误

请修复证书信任。

开发证书自创建之日起有效期为 1 年。当它过期时：

dotnet dev-certs https --check 将报告没有有效的证书
运行完整恢复流程以生成新证书
/usr/local/share/ca-certificates/ 中的旧证书文件将被替换
update-ca-certificates 将在包中将旧证书替换为新证书

不需要系统重启。 应用程序在下次 TLS 握手时会获取新包（重启您的应用程序）。

自动化：CI/CD 流水线

在 Linux 运行器上的 CI/CD 中，很少需要开发证书（您通常针对真实证书进行测试，或在测试工具中禁用 TLS 验证）。但是，如果您的集成测试需要受信任的开发证书：

- name: Trust .NET Dev Certificate
  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

- 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: 'Trust .NET Dev Certificate'

1. 放置了证书但从未重建包

症状： 证书文件存在于 /usr/local/share/ca-certificates/ 但 openssl verify 失败。

原因： 放置文件后从未运行 update-ca-certificates。

修复： sudo update-ca-certificates

这是最常见的错误。CA 目录是包生成过程的输入，而不是包本身。

2. 权限错误的过时证书文件

症状： update-ca-certificates 运行但报告 0 added。

原因： 具有 0600 权限的证书文件无法被 update-ca-certificates 读取（它以 root 身份运行，但通过可能检查世界可读性的进程读取文件）。文件必须是 644。

修复： sudo chmod 644 /usr/local/share/ca-certificates/*.crt

3. 来自不同会话的多个证书文件

症状： update-ca-certificates 添加了多个证书，但应用程序仍然失败。

原因： 来自先前 dotnet dev-certs https --clean / 重新生成周期的旧证书文件保留在 CA 目录中。旧证书的指纹与当前开发证书不匹配。

修复： 删除所有 dotnet* 和 aspnet* 文件，然后重新导出当前证书。

4. 清理/重新生成后指纹不匹配

症状： openssl verify 通过但 .NET 仍然报告 UntrustedRoot。

原因： /usr/local/share/ca-certificates/ 中的证书是从先前的开发证书导出的。在 dotnet dev-certs https --clean && 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 update-ca-certificates

5. 使用 --trust 并假设它有效

症状： dotnet dev-certs https --trust 返回退出代码 0 但实际上没有任何东西被信任。

原因： 在 Linux 上，--trust 尝试将证书添加到 OpenSSL 信任存储，但不调用 update-ca-certificates。从 dotnet 的角度来看操作“成功”，但包保持不变。

修复： 在 Linux 上不要依赖 --trust。遵循此技能中的手动流程。

# 生成开发证书（如果缺失）
dotnet dev-certs https

# 导出为 PEM
dotnet dev-certs https --export-path /tmp/dotnet-dev-cert.crt --format PEM --no-password

# 安装到系统信任（Ubuntu/Debian）
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
sudo update-ca-certificates

# 验证信任
openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt \
  /usr/local/share/ca-certificates/dotnet-dev-cert.crt

# 检查证书详情
openssl x509 -in /usr/local/share/ca-certificates/dotnet-dev-cert.crt -noout -subject -dates -fingerprint

# 核选项：完全清理 + 重建
dotnet dev-certs https --clean && dotnet dev-certs https

dotnet-skills:aspire-configuration — Aspire AppHost 配置，包括 TLS 设置
dotnet-skills:aspire-service-defaults — 服务默认值，包括 HTTPS 配置

🇺🇸English

.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:

It does not export the certificate to the system CA directory
It does not run update-ca-certificates to rebuild the CA bundle
It does not add the cert to browser trust stores (NSS/NSSDB)
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         │
│          (consolidated CA bundle)                    │
└──────────────────────┬──────────────────────────────┘
                       │ built by
┌──────────────────────▼──────────────────────────────┐
│ update-ca-certificates                              │
│   reads from:                                        │
│     /usr/share/ca-certificates/      (distro CAs)   │
│     /usr/local/share/ca-certificates/ (local CAs)   │
│   writes to:                                         │
│     /etc/ssl/certs/ca-certificates.crt (bundle)     │
│     /etc/ssl/certs/*.pem (individual symlinks)      │
└─────────────────────────────────────────────────────┘

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.

5-Point Diagnostic Procedure

Run these checks in order. Stop at the first FAIL and apply its fix before continuing.

Check 1: Dev Cert Existence

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

Exit Code	Meaning	Action
0	Cert exists in user store	PASS — continue
Non-zero	No valid dev cert	Run `dotnet dev-certs https`

Check 2: System Trust Store — Single Cert, Correct Permissions

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

Result	Meaning
Only `dotnet-dev-cert.crt` with `-rw-r--r--` (644)	PASS
Multiple cert files, wrong permissions, or stale `aspnet*` files	FAIL

Common stale files from previous sessions:

File	Problem
`aspnetcore-dev.crt`	Often created with `0600` permissions (unreadable by `update-ca-certificates`)
`aspnet/https.crt`	Old convention, may have a different fingerprint than current dev cert
`dotnet-dev-cert.crt` with `0600`	Correct name but wrong permissions

Fix:

# Remove ALL stale cert files
sudo rm -f /usr/local/share/ca-certificates/aspnetcore-dev.crt
sudo rm -rf /usr/local/share/ca-certificates/aspnet/

# Ensure correct permissions on the dev cert (if it exists)
sudo chmod 644 /usr/local/share/ca-certificates/dotnet-dev-cert.crt

Check 3: CA Bundle Inclusion

This is the most commonly failed check. The cert file exists but was never added to the bundle.

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

Result	Meaning
`dotnet-dev-cert.crt: OK`	PASS — cert is in the consolidated bundle
`error 20 at 0 depth lookup: unable to get local issuer certificate`	FAIL — bundle was never rebuilt
`error 2 at 0 depth lookup: unable to get issuer certificate`	FAIL — same issue, different OpenSSL version

Fix:

sudo update-ca-certificates
# Expected output includes "1 added" or similar

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

Check 4: Environment Variable Overrides

SSL environment variables can redirect certificate lookups away from the system bundle:

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

Result	Meaning
All `<unset>`	PASS
Any variable set	FAIL — may redirect cert lookups

Fix: Remove the offending variables from your shell profile (~/.bashrc, ~/.zshrc, ~/.profile) and start a new shell.

Check 5: Symlink Integrity

Stale symlinks from previously removed certificates can confuse OpenSSL:

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

Result	Meaning
No output	PASS
Broken symlinks listed	FAIL

Fix:

sudo update-ca-certificates --fresh
# Rebuilds ALL symlinks from scratch

Full Recovery Procedure

When multiple checks fail or you want a clean slate, run this complete sequence:

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

echo "=== .NET Dev Certificate Trust Recovery ==="

# Step 1: Remove ALL stale certificate files
echo "--- Removing stale certificate files ---"
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

# Step 2: Clean and regenerate dev cert
echo "--- Regenerating dev certificate ---"
dotnet dev-certs https --clean
dotnet dev-certs https

# Step 3: Export as PEM and install to system trust store
echo "--- Installing to system trust store ---"
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

# Step 4: Rebuild CA bundle (CRITICAL — most commonly missed step)
echo "--- Rebuilding CA bundle ---"
sudo update-ca-certificates

# Step 5: Verify
echo "--- Verifying ---"
openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt \
  /usr/local/share/ca-certificates/dotnet-dev-cert.crt

echo "=== Done! Restart your .NET application. ==="

Save this as ~/fix-devcert.sh and run with bash ~/fix-devcert.sh when needed.

Distro-Specific Notes

Ubuntu / Debian

The procedure above is written for Ubuntu/Debian and works as-is.

CA directory: /usr/local/share/ca-certificates/
Bundle command: sudo update-ca-certificates
Bundle output: /etc/ssl/certs/ca-certificates.crt
Cert format: PEM with .crt extension required

Fedora / RHEL / CentOS

Fedora uses update-ca-trust instead of update-ca-certificates:

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

# Install to Fedora trust store (different directory!)
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

# Rebuild trust bundle
sudo update-ca-trust

# Verify
openssl verify /etc/pki/ca-trust/source/anchors/dotnet-dev-cert.pem

Key differences:

| Ubuntu/Debian | Fedora/RHEL
---|---|---
CA directory | /usr/local/share/ca-certificates/ | /etc/pki/ca-trust/source/anchors/
Rebuild command | update-ca-certificates | update-ca-trust
Bundle path | /etc/ssl/certs/ca-certificates.crt | /etc/pki/tls/certs/ca-bundle.crt
Extension | .crt | .pem (any extension works)

Arch Linux

Arch uses the same update-ca-trust approach as 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 runs a real Linux kernel with its own certificate store — separate from the Windows host. The standard Ubuntu/Debian procedure works, but watch for:

Shared filesystem (/mnt/c/) — cert files on the Windows filesystem have Windows permissions that may not be 644. Always copy to a native Linux path first.
systemd not running — some older WSL2 setups don't have systemd, which update-ca-certificates hooks may depend on. If the command hangs, try sudo dpkg-reconfigure ca-certificates instead.
Docker Desktop integration — If using Docker Desktop's WSL2 backend, containers inherit the WSL2 distro's CA bundle. Fixing trust in WSL2 fixes it for containers too.

Aspire-Specific Considerations

Redis TLS (Aspire 13.1.0+)

Aspire 13.1.0 enables TLS on Redis by default. If you see:

UntrustedRoot

in Redis connection errors, the dev cert isn't trusted at the system level. Run the full recovery procedure above.

Aspire Dashboard HTTPS

The Aspire dashboard uses the dev cert for HTTPS. If the dashboard shows certificate warnings in the browser, the cert isn't in the browser's trust store. For development, clicking through the warning is acceptable — the system-level trust (needed for Redis, gRPC, etc.) is the priority.

ASPIRE_ALLOW_UNSECURED_TRANSPORT

Setting ASPIRE_ALLOW_UNSECURED_TRANSPORT=true is a workaround , not a fix. It disables TLS for inter-service communication, which:

Masks the underlying trust issue
Doesn't match production behavior
May cause different bugs than what you'd see in production

Fix the cert trust instead.

Certificate Lifecycle

The dev cert is valid for 1 year from creation. When it expires:

dotnet dev-certs https --check will report no valid cert
Run the full recovery procedure to generate a new cert
The old cert file in /usr/local/share/ca-certificates/ will be replaced
update-ca-certificates will swap the old cert for the new one in the bundle

No system reboot is required. Applications pick up the new bundle on next TLS handshake (restart your app).

Automation: CI/CD Pipelines

In CI/CD on Linux runners, dev certs are rarely needed (you typically test against real certificates or disable TLS validation in test harnesses). However, if your integration tests require trusted dev certs:

GitHub Actions

- name: Trust .NET Dev Certificate
  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: 'Trust .NET Dev Certificate'

Common Pitfalls

1. Cert placed but bundle never rebuilt

Symptom: Cert file exists in /usr/local/share/ca-certificates/ but openssl verify fails.

Cause: update-ca-certificates was never run after placing the file.

Fix: sudo update-ca-certificates

This is the single most common mistake. The CA directory is an input to the bundle generation process, not the bundle itself.

2. Stale cert files with wrong permissions

Symptom: update-ca-certificates runs but reports 0 added.

Cause: Cert files with 0600 permissions are unreadable by update-ca-certificates (which runs as root but reads files through a process that may check world-readability). Files must be 644.

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

3. Multiple cert files from different sessions

Symptom: update-ca-certificates adds multiple certs, but applications still fail.

Cause: Old cert files from previous dotnet dev-certs https --clean / regenerate cycles remain in the CA directory. The old cert's fingerprint doesn't match the current dev cert.

Fix: Remove all dotnet* and aspnet* files, then re-export the current cert.

4. Fingerprint mismatch after clean/regenerate

Symptom: openssl verify passes but .NET still reports UntrustedRoot.

Cause: The cert in /usr/local/share/ca-certificates/ was exported from a previous dev cert. After dotnet dev-certs https --clean && dotnet dev-certs https, a new cert with a different fingerprint was generated. The system trusts the old cert, not the new one.

Fix: Re-export and reinstall:

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 update-ca-certificates

5. Using --trust and assuming it worked

Symptom: dotnet dev-certs https --trust returns exit code 0 but nothing is actually trusted.

Cause: On Linux, --trust attempts to add the cert to the OpenSSL trust store but does not callupdate-ca-certificates. The operation "succeeds" from dotnet's perspective but the bundle remains unchanged.

Fix: Don't rely on --trust on Linux. Follow the manual procedure in this skill.

Quick Reference

# Generate dev cert (if missing)
dotnet dev-certs https

# Export as PEM
dotnet dev-certs https --export-path /tmp/dotnet-dev-cert.crt --format PEM --no-password

# Install to system trust (Ubuntu/Debian)
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
sudo update-ca-certificates

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

# Check cert details
openssl x509 -in /usr/local/share/ca-certificates/dotnet-dev-cert.crt -noout -subject -dates -fingerprint

# Nuclear option: full clean + rebuild
dotnet dev-certs https --clean && dotnet dev-certs https

Related Skills

dotnet-skills:aspire-configuration — Aspire AppHost configuration including TLS settings
dotnet-skills:aspire-service-defaults — Service defaults including HTTPS configuration

Weekly Installs

Repository

aaronontheweb/d…t-skills

GitHub Stars

491

First Seen

Feb 13, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

claude-code54

codex41

opencode39

gemini-cli39

github-copilot38

kimi-cli38

Azure 升级评估与自动化工具 - 轻松迁移 Functions 计划、托管层级和 SKU

96,200 周安装

Linux 上 .NET 开发证书信任问题解决指南：修复 Aspire Redis TLS 错误

🇨🇳中文介绍

Linux 上的 .NET 开发证书信任

何时使用此技能

问题描述

相关 Skills

为什么在 Aspire 13.1.0+ 中出现此问题

Linux 证书信任的工作原理

五点诊断流程

检查 1：开发证书是否存在

检查 2：系统信任存储 — 单个证书，权限正确

检查 3：CA 包包含情况

检查 4：环境变量覆盖

检查 5：符号链接完整性

完整恢复流程

发行版特定说明

Ubuntu / Debian

Fedora / RHEL / CentOS

Arch Linux

WSL2

Aspire 特定注意事项

Redis TLS (Aspire 13.1.0+)

Aspire 仪表板 HTTPS

ASPIRE_ALLOW_UNSECURED_TRANSPORT

证书生命周期

自动化：CI/CD 流水线

GitHub Actions

Azure DevOps

常见陷阱

1. 放置了证书但从未重建包

2. 权限错误的过时证书文件

3. 来自不同会话的多个证书文件

4. 清理/重新生成后指纹不匹配

5. 使用 --trust 并假设它有效

快速参考

相关技能

🇺🇸English

.NET Dev Certificate Trust on Linux

When to Use This Skill

The Problem

Why This Surfaces with Aspire 13.1.0+

How Linux Certificate Trust Works

5-Point Diagnostic Procedure

Check 1: Dev Cert Existence

Check 2: System Trust Store — Single Cert, Correct Permissions

Check 3: CA Bundle Inclusion

Check 4: Environment Variable Overrides

Check 5: Symlink Integrity

Full Recovery Procedure

Distro-Specific Notes

Ubuntu / Debian

Fedora / RHEL / CentOS

Arch Linux

WSL2

Aspire-Specific Considerations

Redis TLS (Aspire 13.1.0+)

Aspire Dashboard HTTPS

ASPIRE_ALLOW_UNSECURED_TRANSPORT

Certificate Lifecycle

Automation: CI/CD Pipelines

GitHub Actions

Azure DevOps

Common Pitfalls

1. Cert placed but bundle never rebuilt

2. Stale cert files with wrong permissions

3. Multiple cert files from different sessions

4. Fingerprint mismatch after clean/regenerate

5. Using --trust and assuming it worked

Quick Reference

Related Skills

最新 Skills