從 .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
如何檢查退出狀態碼:
- 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 的開發行列了嗎?😃
相關連結