如何使用 .NET Core 2.1 內建的 dev-certs 命令管理開發環境的自簽憑證

從 .NET Core 2.1 開始，.NET Core SDK 就內建了 SSL 憑證管理工具 ( dotnet dev-certs )，透過 dotnet new 建立的 ASP.NET Core 專案範本，Kestrel Web Server 也會預設啟用含有 HTTPS 的加密網站連結。以往我們在開發環境設立一張「有效的 SSL 憑證」還挺麻煩的，我之前還寫過好幾篇文章分享。今天我就來介紹 .NET Core SDK 2.1 內建的標準作法。

首先，你可以先用 dotnet dev-certs --help 命令查詢一下基本用法：

G:\>dotnet dev-certs --help


Usage: dotnet dev-certs [options] [command]

Options:
  -h|--help  Show help information

Commands:
  https

Use "dotnet dev-certs [command] --help" for more information about a command.

這時你會發現只有一個 https 命令可用，所以我們繼續查詢用法：

G:\>dotnet dev-certs https --help


Usage: dotnet dev-certs https [options]

Options:
  -ep|--export-path  Full path to the exported certificate
  -p|--password      Password to use when exporting the certificate with the private key into a pfx file
  -c|--check         Check for the existence of the certificate but do not perform any action
  --clean            Cleans all HTTPS development certificates from the machine.
  -t|--trust         Trust the certificate on the current platform
  -v|--verbose       Display more debug information.
  -q|--quiet         Display warnings and errors only.
  -h|--help          Show help information

在不同的作業系統下，使用的方式會有些許不同，但還是在 Windows 底下最簡單，我們先來看看使用的情境有哪些。

建立 SSL 憑證並自動註冊到個人憑證儲存區

無論在哪個作業系統平台，直接輸入 dotnet dev-certs https 就會自動建立自簽憑證！

不過，你在用瀏覽器測試的時候，還是會看到「無效憑證」的錯誤訊息。

※ 請注意：在 Linux/macOS 作業系統，憑證預設會安裝到 ~/.dotnet/corefx/cryptography/x509stores/my/ 目錄下。

建立 SSL 憑證並自動註冊到受信任的根憑證授權單位

在 Windows 作業系統，只要加上 --trust 參數，就可以全自動完成註冊，註冊完成後，在本機使用瀏覽器測試，就可以看到安全網頁，很棒吧！

G:\>dotnet dev-certs https --trust
Trusting the HTTPS development certificate was requested. A confirmation prompt will be displayed if the certificate was not previously trusted. Click yes on the prompt to trust the certificate.
A valid HTTPS certificate is already present.

執行的過程中會跳出安全性警告，此時按下 " 是(Y) " 即可註冊到受信任的根憑證授權單位(CA)。

※ 請注意：在 Linux/macOS 作業系統下，並沒有 --trust 參數可用。

自動移除註冊到受信任的根憑證授權單位開發用憑證

只要加上 --clean 參數，就會自動移除憑證。如果是 Windows 平台，他會連帶將「個人」與「根憑證授權單位」憑證儲存區內的憑證全部移除。如果是 Linux/macOS 的話，則會自動從 ~/.dotnet/corefx/cryptography/x509stores/my/ 目錄移除憑證。

G:\>dotnet dev-certs https --clean
Cleaning HTTPS development certificates from the machine. A prompt might get displayed to confirm the removal of some of the certificates.

移除根憑證的過程中，一樣會跳出安全性警告，此時按下 " 是(Y) " 就可以成功刪除憑證。

檢查是否已成功安裝開發用憑證

使用 --check 可以用來檢查憑證是否有成功設定，但是畫面上完全沒有訊息。他只會回應 Console 一個退出狀態碼而已，如果是狀態碼為 0 ，就代表 SSL 憑證已經正確設定。如果是 6 的話，就代表找不到憑證可用。

G:\>dotnet dev-certs https --check

如何檢查退出狀態碼：

echo %ERRORLEVEL%
echo $?

匯出自簽憑證 (包含設定密碼)

有時候我們會需要將憑證匯出，以便將憑證移到其他主機或用戶端，方便進一步測試。此時你可以透過以下命令產生 PFX 格式的憑證，並設定金鑰密碼：

dotnet dev-certs https --export-path ./localhost.pfx --password 123456

如果你想要將 PFX 憑證轉為 PEM 格式的話 (Linux/macOS 下常用 PEM 格式)，可以用以下 OpenSSL 命令進行轉換 (需輸入憑證密碼)：

openssl pkcs12 -in localhost.pfx -out localhost.pem -nodes

結語

新版的 .NET Core 2.1 不但執行效能大幅提升，在開發 工具 方面也不斷改進，真的非常棒，你開始投入 ASP.NET Core 的開發行列了嗎？我們在 2018-08-07 (二) 與 2018-08-26 (日) 各舉辦一場 進階的 ASP.NET Core 訓練課程 ，讓目前已經有在開發 ASP.NET MVC 或 ASP.NET Web API 的開發者，用一天的時間完整掌握 ASP.NET Core 開發框架，歡迎踴躍報名。

相關連結