dotnet-devcert-trust

Linux での .NET 開発証明書の信頼

このスキルを使用するタイミング

以下の場合にこのスキルを使用します。

• Aspire で UntrustedRoot または RemoteCertificateNameMismatch が発生し、Redis の TLS 接続に失敗する
• dotnet dev-certs https --check --trust が終了コード 7 を返す
• HTTPS の localhost 接続が証明書の検証エラーで失敗する
• dotnet dev-certs https --clean の実行後に信頼を復元する必要がある
• .NET の HTTPS 開発用に新しい Linux 開発マシンをセットアップする
• Aspire ダッシュボードまたはサービス間の gRPC 呼び出しが TLS エラーで失敗する
• Redis でデフォルトの TLS が使用されなかった Aspire < 13.1.0 からアップグレードする

問題

Windows と macOS では、dotnet dev-certs https --trust がすべて自動で処理します。証明書を生成し、ユーザーストアにインストールして、システムの信頼ストアに追加します。Linux では、ほとんど何も役に立つことをしません。このコマンドは証明書を生成してユーザーストアに配置しますが、次の処理は行いません。

1. 証明書をシステム CA ディレクトリにエクスポートしません
2. CA バンドルを再構築するために update-ca-certificates を実行しません
3. ブラウザーの信頼ストア（NSS/NSSDB）に証明書を追加しません
4. --trust フラグは警告なしで成功しますが、証明書は信頼されないままです

そのため、dotnet dev-certs https --check で証明書が存在すると報告されても、.NET アプリケーション、OpenSSL、curl、ブラウザーはすべて開発証明書を拒否します。

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)      │
└─────────────────────────────────────────────────────┘

重要なポイント： /usr/local/share/ca-certificates/ に .crt ファイルを配置することは必要ですが、それだけでは不十分です。update-ca-certificates を実行して、統合バンドル /etc/ssl/certs/ca-certificates.crt を再構築する必要があります。アプリケーションが読み取るのは個々のファイルではなく、バンドルです。

5 項目の診断手順

これらのチェックを順番に実行します。最初に FAIL が出た時点で止め、次に進む前にその修正を適用してください。

チェック 1：開発証明書の存在確認

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

終了コード	意味	対応
0	ユーザーストアに証明書が存在する	PASS — 続行
0 以外	有効な開発証明書がない	dotnet dev-certs https を実行

チェック 2：システム信頼ストア — 証明書が 1 つで、権限が適切であること

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

結果	意味
dotnet-dev-cert.crt のみで、権限が -rw-r--r--（644）	PASS
複数の証明書ファイル、権限の誤り、または古い aspnet* ファイルがある	FAIL

以前のセッションでよく残る古いファイル：

ファイル	問題
aspnetcore-dev.crt	0600 の権限で作成されていることが多く、update-ca-certificates から読み取れません
aspnet/https.crt	古い命名規則のファイルで、現在の開発証明書とはフィンガープリントが異なる場合があります
0600 の dotnet-dev-cert.crt	名前は正しいものの、権限が誤っています

修正：

# 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

チェック 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	PASS — 証明書は統合バンドルに含まれています
error 20 at 0 depth lookup: unable to get local issuer certificate	FAIL — バンドルが再構築されていません
error 2 at 0 depth lookup: unable to get issuer certificate	FAIL — 同じ問題ですが、OpenSSL のバージョンが異なります

修正：

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

チェック 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>	PASS
いずれかの変数が設定されている	FAIL — 証明書の参照先が変更される可能性があります

修正： 問題のある変数をシェルの設定ファイル（~/.bashrc、~/.zshrc、~/.profile）から削除し、新しいシェルを起動します。

チェック 5：シンボリックリンクの整合性

以前削除した証明書への古いシンボリックリンクが残っていると、OpenSSL が混乱することがあります。

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

結果	意味
出力なし	PASS
壊れたシンボリックリンクが表示される	FAIL

修正方法：

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

完全な復旧手順

複数のチェックに失敗した場合や、まっさらな状態にしたい場合は、この一連の手順を実行してください。

#!/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. ==="

これを ~/fix-devcert.sh として保存し、必要に応じて bash ~/fix-devcert.sh を実行してください。

ディストリビューション固有の注意事項

Ubuntu / Debian

上記の手順は 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-certificates の代わりに update-ca-trust を使用します。

# 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

主な違い：

	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 Linux

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

WSL2 は独自の証明書ストアを持つ実際の Linux カーネルを実行しており、Windows ホストとは別です。標準の Ubuntu/Debian の手順を使用できますが、次の点に注意してください。

1. 共有ファイルシステム（/mnt/c/） — Windows ファイルシステム上の証明書ファイルは、Windows のアクセス許可が設定されており、644 になっていない場合があります。必ず最初に Linux のネイティブパスへコピーしてください。
2. systemd が実行されていない — 古い WSL2 環境の一部では systemd がなく、update-ca-certificates のフックが依存している場合があります。コマンドがハングする場合は、代わりに sudo dpkg-reconfigure ca-certificates を試してください。
3. Docker Desktop との統合 — Docker Desktop の WSL2 バックエンドを使用している場合、コンテナーは WSL2 ディストリビューションの CA バンドルを継承します。WSL2 で信頼設定を修正すれば、コンテナーでも修正されます。

Aspire 固有の考慮事項

Redis TLS（Aspire 13.1.0 以降）

Aspire 13.1.0 では、Redis の TLS がデフォルトで有効になります。次のエラーが表示される場合：

UntrustedRoot

Redis 接続エラーにこの内容が含まれている場合、開発用証明書がシステムレベルで信頼されていません。上記の完全な復旧手順を実行してください。

Aspire ダッシュボードの HTTPS

Aspire ダッシュボードでは、HTTPS に開発用証明書を使用します。ブラウザーでダッシュボードに証明書の警告が表示される場合、その証明書はブラウザーの信頼ストアに登録されていません。開発中は警告を無視して先に進んでも問題ありません。優先すべきなのは、Redis、gRPC などで必要となるシステムレベルの信頼設定です。

ASPIRE_ALLOW_UNSECURED_TRANSPORT

ASPIRE_ALLOW_UNSECURED_TRANSPORT=true の設定は回避策であり、修正ではありません。サービス間通信の TLS を無効にするため、次の問題があります。

• 根本にある信頼の問題を覆い隠します
• 本番環境の動作と一致しません
• 本番環境で発生するものとは異なるバグを引き起こす可能性があります

代わりに、証明書の信頼設定を修正してください。

証明書のライフサイクル

開発用証明書の有効期間は、作成から 1 年間です。有効期限が切れた場合：

1. dotnet dev-certs https --check は有効な証明書がないと報告します
2. 完全な復旧手順を実行して、新しい証明書を生成します
3. /usr/local/share/ca-certificates/ 内の古い証明書ファイルが置き換えられます
4. update-ca-certificates によって、バンドル内の古い証明書が新しい証明書に置き換えられます

システムの再起動は必要ありません。 アプリケーションは次回の TLS ハンドシェイク時に新しいバンドルを読み込みます（アプリを再起動してください）。

自動化：CI/CD パイプライン

Linux ランナー上の CI/CD では、開発用証明書が必要になることはほとんどありません（通常は実際の証明書を使用するか、テストハーネスで TLS 検証を無効にします）。ただし、統合テストで信頼された開発用証明書が必要な場合：

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'

よくある落とし穴

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 に頼らないでください。このスキルの手動手順に従ってください。

クイックリファレンス

# 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

関連スキル

• dotnet-skills:aspire-configuration — TLS 設定を含む Aspire AppHost の構成
• dotnet-skills:aspire-service-defaults — HTTPS 設定を含むサービスの既定値