# 如何使用 .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` 就會自動建立自簽憑證！

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

![](https://stwillblogassets.blob.core.windows.net/files/images/external/stwillblogassets.blob.core.windows.net/2fc58ce02b630df1858c-image_3135.png)

**※ 請注意**：在 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.
```

![](https://stwillblogassets.blob.core.windows.net/files/images/external/user-images.githubusercontent.com/ead362ad4c8960f509cb-43679624-afa43af8-985a-11e8-96b7-e08f468a99f9.png)

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

![image](https://stwillblogassets.blob.core.windows.net/files/images/external/stwillblogassets.blob.core.windows.net/2782f03b3a87d1b79d3a-image_3136.png "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)**" 就可以成功刪除憑證。

![](https://stwillblogassets.blob.core.windows.net/files/images/external/stwillblogassets.blob.core.windows.net/4a4f9b52fb905cba2961-image_3137.png)

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

使用 `--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 的開發行列了嗎？😃

**相關連結**

-   [ASP.NET Core 2.1.0-preview1: Improvements for using HTTPS | ASP.NET Blog](https://blogs.msdn.microsoft.com/webdev/2018/02/27/asp-net-core-2-1-https-improvements/)
-   [Improvements to HTTPS · Issue #2308 · aspnet/Home](https://github.com/aspnet/Home/issues/2308)
-   [2.1 Improvements to HTTPS · Issue #5393 · aspnet/Docs](https://github.com/aspnet/Docs/issues/5393)
-   [NuGet Gallery | dotnet-dev-certs 2.1.1](https://www.nuget.org/packages/dotnet-dev-certs)