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

The Will Will Web

記載著 Will 在網路世界的學習心得與技術分享

如何使用 .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)。

image

※ 請注意:在 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

如何檢查退出狀態碼:

  • Windows: echo %ERRORLEVEL%
  • Linux/macOS: 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 開發框架,歡迎踴躍報名。

 

相關連結