# DedicatedプランでのTLS/SSL設定

EMQX Dedicatedエディションではカスタマイズされた証明書検証を推奨しており、片方向および双方向のTLS/SSLを提供しています。本セクションでは、証明書検証の概要と、デプロイメントにおけるTLS/SSLプロトコルの設定方法および設定が成功したかどうかのテスト方法を紹介します。

以下の表は、片方向認証と双方向認証モードにおける各種証明書の要件をまとめたものです。

| 認証モード               | 自己署名証明書 | サーバー証明書 | 証明書チェーン | 秘密鍵       | クライアントCA証明書 |
| ------------------------ | ------------- | -------------- | -------------- | ------------ | -------------------- |
| 片方向認証               | 可            | 必須           | 必須           | 必須         | 不要                 |
| 双方向認証               | 可            | 必須           | 必須           | 必須         | 必須                 |

## 証明書の要件

- 証明書は暗号化アルゴリズムと鍵長を指定する必要があります。EMQXプラットフォームは以下のアルゴリズムをサポートしています：

  - 1024ビットRSA（RSA_1024）
  - 2048ビットRSA（RSA_2048）
  - 256ビットECDSA（ECC）
  - 384ビットECDSA（ECC）

- 証明書（証明書チェーンを含む場合あり）：EMQXプラットフォームは**x509**形式の証明書アップロードをサポートしています。**証明書ファイル（.crtまたは.pem）と関連する証明書チェーンファイルを1つに結合してアップロードしてください**。証明書が認証局によって発行されている場合、正しく認識されるために証明書チェーンを含めることが重要です。

- 証明書は有効である必要があります。有効期間の開始および終了の**60日前以内**の証明書はインポートできません。

- 証明書、秘密鍵、証明書チェーンはすべて**PEMエンコード**である必要があります。

- 秘密鍵はパスワードなしである必要があります。

- 秘密鍵はPKCS#1およびPKCS#8をサポートします。

- 証明書の暗号化アルゴリズムは署名CAの暗号化アルゴリズムと一致している必要があります。例えば、署名CAの鍵タイプがRSAの場合、証明書の鍵タイプもRSAでなければなりません。

- フォーマット例：

  - 証明書フォーマット

  ```bash
  -----BEGIN CERTIFICATE-----
  Base64でエンコードされた証明書
  -----END CERTIFICATE----- 
  ```

  - 秘密鍵フォーマット

  ```bash
  -----BEGIN (RSA/EC) PRIVATE KEY-----
  Base64でエンコードされた秘密鍵
  -----END (RSA/EC) PRIVATE KEY----- 
  ```

## 片方向TLS/SSLの設定

以下の手順では、[EMQX Platform Console](<https://cloud-intl.emqx.com/console>)で片方向TLS/SSLを設定し、TLS/SSL設定済みのクライアント接続をテストする方法を案内します。セットアップの各ステップは[片方向TLS/SSLチュートリアル](https://www.youtube.com/embed/kkb1D4lXbFo/?autoplay=1&null)でもご覧いただけます。

1. EMQX Platform Consoleにログインします。
2. デプロイメントの**Overview**ページで、**+TLS/SSL Config**ボタンをクリックして証明書を設定します。ファイルをアップロードするか、証明書の内容を直接入力できます。
    - **TLS/SSL Type**：片方向（クライアントのみがサーバー側証明書を検証）を選択します。
    - **Certificate and Certificate Chain**：カスタムサーバー側証明書（証明書発行時に第三者機関から提供される証明書チェーンを含む）。
    - **Certificate Private Key**：秘密鍵を入力します。
3. すべての項目を入力後、**Confirm**をクリックします。デプロイメントのOverviewページに戻ると、**TLS/SSL Config**に証明書情報が表示されます。

### MQTTXクライアントで片方向TLSをテストする

テスト前に認証情報を作成していることを確認してください。詳細は[認証](./auth_overview.md)を参照してください。[MQTTXクライアント](https://mqttx.app/)を使ってEMQX Platformに接続し、TLS/SSL設定をテストできます。

1. MQTTXクライアントで新しい接続を作成します。

   **General**セクションに以下の情報を入力します：

   - **Name**：接続名を入力します。
   - **Client ID**：クライアントIDはランダム生成されます。更新ボタンをクリックすると再生成できます。
   - **Host**：ドロップダウンリストからプロトコルを選択し、デプロイ済みの接続アドレスとポートを入力します。
     - MQTT over TLSを使用する場合は、`mqtts://` とポート `8883` を選択します。
     - WebSocket over TLSを使用する場合は、`wss://` とポート `8084` を選択します。

   - **Username** と **Password**：作成済みの認証情報を入力します。
   - **SSL/TLS**：トグルスイッチをクリックしてSSL/TLSを有効にします。
   - **SSL Secure**：トグルスイッチをクリックしてSSL Secureを有効にします。
   - **Certificate**：必要に応じて証明書を選択します。
     - CA認証局による証明書の場合は**CA signed server**を選択します。
     - 自己署名証明書の場合は**Self signed**を選択し、自己署名サーバー側CA証明書を提供します。自己署名TLS/SSL証明書の作成方法は[自己署名TLS/SSL証明書の作成](#create-self-signed-tsl-ssl-certificate)を参照してください。

2. **Connect**をクリックします。

![mqttx_tls](./_assets/mqttx_tls.png)

## 双方向TLS/SSLの設定

以下の手順では、[EMQX Platform Console](<https://cloud-intl.emqx.com/console>)で双方向TLS/SSLを設定し、TLS/SSL設定済みのクライアント接続をテストする方法を案内します。セットアップの各ステップは[双方向TLS/SSLチュートリアル](https://www.youtube.com/embed/VzygGJXgVI4/?autoplay=1&null)でもご覧いただけます。

1. EMQX Platform Consoleにログインします。
2. デプロイメントの**Overview**ページで、**+TLS/SSL Config**ボタンをクリックして証明書を設定します。ファイルをアップロードするか、証明書の内容を直接入力できます。
    - **TLS/SSL Type**：双方向（クライアントとサーバーがお互いの証明書を検証）を選択します。
    - **Certificate and Certificate Chain**：カスタムサーバー側証明書（証明書発行時に第三者機関から提供される証明書チェーンを含む）。
    - **Certificate Private Key**：秘密鍵を入力します。
    - **Client CA Certificate**：双方向を選択した場合はクライアントCA証明書を提供する必要があります。
3. すべての項目を入力後、**Confirm**をクリックします。デプロイメントのOverviewページに戻ると、**TLS/SSL Config**に証明書情報が表示されます。

### MQTTXクライアントで双方向TLSをテストする

テスト前に認証情報を作成していることを確認してください。詳細は[認証](./auth_overview.md)を参照してください。[MQTTXクライアント](https://mqttx.app/)を使ってEMQX Platformに接続し、TLS/SSL設定をテストできます。

1. MQTTXクライアントで新しい接続を作成します。

   **General**セクションに以下の情報を入力します：

   - **Name**：接続名を入力します。
   - **Client ID**：クライアントIDはランダム生成されます。更新ボタンをクリックすると再生成できます。
   - **Host**：ドロップダウンリストからプロトコルを選択し、デプロイ済みの接続アドレスとポートを入力します。
     - MQTT over TLSを使用する場合は、`mqtts://` とポート `8883` を選択します。
     - WebSocket over TLSを使用する場合は、`wss://` とポート `8084` を選択します。

   - **Username** と **Password**：作成済みの認証情報を入力します。
   - **SSL/TLS**：トグルスイッチをクリックしてSSL/TLSを有効にします。
   - **SSL Secure**：トグルスイッチをクリックしてSSL Secureを有効にします。
   - **Certificate**：必要に応じて証明書を選択します。
     - サーバー側CAがCA認証局により認証されている場合は**Self signed**を選択し、**CA File**欄に証明書を入力します。自己署名TLS/SSL証明書の作成方法は[自己署名TLS/SSL証明書の作成](#create-self-signed-tsl-ssl-certificate)を参照してください。
     - 自己署名サーバー側証明書の場合は**Self signed**を選択し、自己署名サーバー側CA証明書を提供します。
     - 双方向TLSではクライアント証明書ファイルとクライアント秘密鍵ファイルも入力する必要があります。

2. **Connect**をクリックします。

![mqttx_tls](./_assets/mqttx_tls_shuang.png)

## 自己署名TLS/SSL証明書の作成

以下の手順では自己署名TLS/SSL証明書の作成方法を案内します。セットアップの各ステップは[自己署名TLS/SSL証明書作成チュートリアル](https://www.youtube.com/embed/kYL0pQ0GC3k/?autoplay=1&null)でもご覧いただけます。

::: tip 前提条件

[OpenSSL](https://www.openssl.org/)がインストールされていることを確認してください。

:::

### サーバー側CA証明書の生成

以下のコマンドでサーバー側CA証明書を生成できます。`subj`は実際の用途に合わせて調整してください。

```bash
openssl req \
    -new \
    -newkey rsa:2048 \
    -days 365 \
    -nodes \
    -x509 \
    -subj "/C=CN/O=EMQ Technologies Co., Ltd/CN=EMQ CA" \
    -keyout server-ca.key \
    -out server-ca.crt
```

### サーバー側証明書の作成

1. サーバー側秘密鍵 `server.key` を生成します。

```bash
openssl genrsa -out server.key 2048
```

2. `openssl.cnf` ファイルを作成します。`IP.1` または `DNS.1` のアドレスはデプロイメントのアドレスに置き換えてください。

```
cat << EOF > ./openssl.cnf
[policy_match]
countryName             = match
stateOrProvinceName     = optional
organizationName        = optional
organizationalUnitName  = optional
commonName              = supplied
emailAddress            = optional

[req]
default_bits       = 2048
distinguished_name = req_distinguished_name
req_extensions     = req_ext
x509_extensions    = v3_req
prompt             = no

[req_distinguished_name]
commonName          = Server

[req_ext]
subjectAltName = @alt_names

[v3_req]
subjectAltName = @alt_names

[alt_names]
# EMQXデプロイメント接続アドレス
# IP.1 = <IP接続アドレス>
DNS.1 = <ドメイン接続アドレス>
EOF
```

3. サーバー側証明書署名要求ファイル `server.csr` を生成します。

```bash
openssl req -new -key server.key -config openssl.cnf -out server.csr
```

4. CA証明書でサーバー側証明書を署名し、`server.crt` を作成します。

```bash
openssl x509 -req \
    -days 365 \
    -sha256 \
    -in server.csr \
    -CA server-ca.crt \
    -CAkey server-ca.key \
    -CAcreateserial -out server.crt \
    -extensions v3_req -extfile openssl.cnf
```

5. サーバー側証明書の情報を確認します。

```bash
openssl x509 -noout -text -in server.crt
```

6. 証明書を検証します。

```bash
openssl verify -CAfile server-ca.crt server.crt
```

### クライアント証明書の作成

双方向認証の場合、まずクライアントCA証明書を生成する必要があります。

#### クライアントCA証明書の生成

以下のコマンドでクライアントCA証明書を生成できます。`subj`は実際の用途に合わせて調整してください。

```bash
openssl req \
    -new \
    -newkey rsa:2048 \
    -days 365 \
    -nodes \
    -x509 \
    -subj "/C=CN/O=EMQ Technologies Co., Ltd/CN=EMQ CA" \
    -keyout client-ca.key \
    -out client-ca.crt
```

1. クライアント側秘密鍵 `client.key` を生成します。

```bash
openssl genrsa -out client.key 2048
```

2. クライアント側証明書署名要求ファイル `client.csr` を生成します。

```bash
openssl req -new -key client.key -out client.csr -subj "/CN=Client"
```

3. CA証明書でクライアント側証明書を署名し、`client.crt` を作成します。

```bash
openssl x509 -req -days 365 -sha256 -in client.csr -CA client-ca.crt -CAkey client-ca.key -CAcreateserial -out client.crt
```

4. クライアント側証明書の情報を確認します。

```bash
openssl x509 -noout -text -in client.crt
```

5. 証明書を検証します。

```bash
openssl verify -CAfile client-ca.crt client.crt
```

## 証明書の削除

証明書を削除すると、ポート `8883` と `8084` でのクライアント接続が切断されます。削除が業務に影響を与えないことを必ず確認してください。

1. [EMQX Platform Console](<https://cloud-intl.emqx.com/console>)にログインします。
2. **TLS/SSL Config** セクションの証明書の削除アイコンをクリックします。
3. ダイアログで **OK** をクリックして削除を完了します。

## FAQ

1. **証明書に複数の証明書が含まれている場合**

   購入した証明書には中間証明書が含まれていることがあります。証明書をテキスト形式で開くと、ユーザー証明書、中間証明書、ルート証明書の順に複数の証明書が含まれています。一般的に、証明書はユーザー証明書と複数の中間証明書で構成されているため、ユーザー証明書と中間証明書を分離し、中間証明書を証明書チェーンとして入力する必要があります。

   ```bash
   -----BEGIN CERTIFICATE-----
   
   ユーザー証明書
   
   -----END CERTIFICATE-----
   
   -----BEGIN CERTIFICATE-----
   
   中間証明書
   
   -----END CERTIFICATE-----
   
   -----BEGIN CERTIFICATE-----
   
   ルート証明書
   
   -----END CERTIFICATE-----
   ```

2. **証明書チェーンが不足している場合**

   証明書チェーンの補完はこちらをご参照ください：https://myssl.com/chain_download.html

3. **双方向TLS（mTLS）使用時にユーザー名とパスワード認証を無効にできますか？**

   はい、**相互TLS（mTLS）**を使用する場合、ユーザー名とパスワード認証を無効にすることが可能です。ただし、セキュリティ上の理由から両方の認証方式を有効にしておくことを強く推奨します。デバイス証明書が漏洩した場合、不正なデバイスがEMQX Platformに接続できてしまうリスクがあるためです。

   もしユーザー名/パスワード認証を無効にしたい場合は、サポート[チケット](../feature/tickets)を提出してください。SREチームがデプロイメントのポート8883および8084での無効化を支援します。

4. **証明書のCommon Name（CN）をユーザー名またはクライアントIDにマッピングできますか？**

   はい、EMQX Platformでは証明書のCNをユーザー名またはクライアントIDにマッピングできます。このマッピングを有効にするにはサポートチケットを提出してください。SREチームが設定を行います。

   **重要な注意点：**

   - **CNをクライアントIDにマッピングする場合**：CNは一意である必要があります。同じCNを複数のクライアントが共有すると、クライアントIDの重複により接続が切断されます。
   - **CNをユーザー名にマッピングする場合**：一般的に安全で、接続の競合を防ぎつつ本人確認が可能です。

5. **ユーザー名/パスワード認証を無効にし、CNをユーザー名にマッピングした場合、漏洩した証明書の接続をどうやってブロックできますか？**

   証明書が漏洩しCNをユーザー名にマッピングしている場合は、該当ユーザー名を[ブラックリスト](../deployments/blacklist)に追加することで、該当デバイスの接続を防止できます。