SSL/TLS証明書

SSL/TLS証明書はEMQXのセキュリティアーキテクチャの中核を成す要素です。これにより、ネットワーク通信の認証、暗号化、およびデータの整合性が提供されます。EMQXでは、以下のシナリオで安全な接続を確立するためにSSL/TLS証明書が必要です。

TLS経由のMQTT接続（MQTTS）
WebSocket Secure（WSS）経由のMQTT接続
HTTPSサービスおよびダッシュボードアクセス
TLS対応の外部接続（例：データ統合）

EMQX 6.1以降、証明書は単なるファイルパスではなく再利用可能なリソースとして扱われます。EMQXは以下の2つの証明書管理方式をサポートしています。

パスベース証明書（従来型）：設定内でファイルパスを直接参照する方式。
管理証明書（EMQX 6.1以降）：再利用可能なリソースとして管理し、名前で参照する方式。

どちらの方式も標準的なPEMエンコードファイルを使用し、EMQXのSSL/TLS実装と完全に互換性があります。

本ページでは以下のトピックを扱います。

SSL/TLS証明書の取得方法
EMQXでの証明書管理
複数証明書のサポート
SSL/TLS証明書の更新方法

SSL/TLS証明書の取得

EMQXで証明書を使用する前に、信頼できるソースから証明書を取得する必要があります。取得方法は環境やセキュリティ要件によって異なります。

証明書取得の選択肢

TLS証明書は以下の方法で取得可能です。

自己署名証明書
独自の認証局（CA）が発行する証明書です。デフォルトでは信頼されないため、テストや制御された環境での利用に推奨されます。
信頼されたCAによる証明書の申請または購入
公共または企業のCAから取得する証明書で、以下のような例があります。
- Let's Encrypt
- クラウドプロバイダー（例：Huawei Cloud、Tencent Cloud）
- 商用CA（例：DigiCert）
本番環境や企業展開では、OV（組織認証）以上の保証レベルの証明書が一般的に推奨されます。

自己署名CA証明書の作成

自己署名証明書はテスト、開発、プライベート環境で有用です。

前提条件

OpenSSLがインストールされていること。

以下のコマンドを実行し、鍵ペアを生成します。コマンド実行時に鍵を保護するパスワードの入力を求められます。このパスワードは証明書の生成、発行、検証時に必要となるため、安全に管理してください。
bash
```
openssl genrsa -des3 -out rootCA.key 2048
```
次に、鍵ペアの秘密鍵を使ってCA証明書を生成します。コマンド実行時に証明書の識別名（DN）の設定を求められます。
bash
```
openssl req -x509 -new -nodes -key rootCA.key -sha256 -days 3650 -out rootCA.crt
```

サーバー証明書の発行

先ほど作成したCA証明書を使い、EMQXのリスナーがクライアントに対して自身の身元を証明するためのサーバー証明書を発行します。サーバー証明書は通常、ホスト名、サーバー名、またはドメイン名（例：www.emqx.com）に発行されます。サーバー証明書の生成には、CAの秘密鍵（rootCA.key）、CA証明書（rootCA.crt）、およびサーバーの証明書署名要求（CSR）（server.csr）が必要です。

サーバー証明書用の鍵ペアを生成します。
bash
```
openssl genrsa -out server.key 2048
```

サーバー鍵ペアを使ってCSRを作成します。CSRはCAの秘密鍵で署名され、証明書の公開鍵ファイルが生成されてユーザーに発行されます。コマンド実行時に証明書の識別名（DN）の設定を求められます。

bash

openssl req -new -key server.key -out server.csr

以下のような情報入力を求められます。各項目の意味は以下の通りです。

bash

You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]: # 国・地域
State or Province Name (full name) [Some-State]: # 州・都道府県
Locality Name (eg, city) []: # 市区町村
Organization Name (eg, company) [Internet Widgets Pty Ltd]: # 組織名（会社名）、例：EMQ
Organizational Unit Name (eg, section) []: # 部署名、例：EMQX
Common Name (e.g. server FQDN or YOUR name) []: # 証明書を使用するサーバーのFQDN、例：mqtt.emqx.com
...

CSRを使ってサーバー証明書を生成し、有効期限を365日に設定します。

bash

openssl x509 -req -in server.csr -CA rootCA.crt -CAkey rootCA.key -CAcreateserial -out server.crt -days 365

これで証明書一式が揃います。

bash

.
├── rootCA.crt
├── rootCA.key
├── rootCA.srl
├── server.crt
├── server.csr
└── server.key

クライアント証明書の発行

クライアント証明書は双方向（相互）TLS認証に使用されます。

発行手順はサーバー証明書とほぼ同様ですが、以下の点が異なります。

Common Name（CN）はクライアントを一意に識別する情報（例：ユーザー名やクライアントID）を指定します。
証明書は同じCA証明書で署名されます。したがって、クライアント証明書も上記のCA証明書で署名可能です。

EMQXでの証明書管理

証明書を取得した後、EMQXでは2つの方法で証明書を管理および参照できます。

パスベース証明書

パスベース証明書は、リスナーやコネクターのSSLオプションで明示的にファイルパスを指定して設定します。例：

certfile
keyfile
cacertfile

パスベース証明書の特徴：

証明書ファイルはユーザーまたは外部ツールが完全に管理します。
リスナーは証明書ファイルを直接参照します。
証明書の更新は通常、ディスク上のファイルを置き換えることで行います。

EMQXはテスト用にetc/certsディレクトリにサンプル証明書を提供しています。

パスベース証明書は引き続き完全にサポートされており、すべてのEMQXバージョンと互換性があります。

管理証明書

EMQX 6.1以降、管理証明書という集中管理機構が導入されました。これはTLS証明書ファイルを一元管理し、複数のコンポーネント間で再利用可能にする仕組みです。

管理証明書は以下のリソースで参照・再利用可能です。

MQTT SSLリスナー
WSSリスナー
HTTPS / ダッシュボードリスナー
TLS対応コネクター（例：データ統合）

管理証明書はダッシュボードまたはREST APIから作成・管理でき、EMQXのデータディレクトリdata/certs2/に保存されます。

内部的には、EMQXはErlang/OTPのSSLライブラリと連携する際にパスベースのPEMパスを使用し、以下を実現しています。

既存のTLS動作との完全な後方互換性
証明書の自動リロード
証明書更新時にリスナーやコネクターの再起動不要

管理証明書バンドル

管理証明書バンドルは、TLS関連ファイルの論理的なセットを表します。内容は以下の通りです。

サーバー証明書
秘密鍵
任意のCA証明書

各バンドルは名前と任意のネームスペースで識別され、複数のリスナーやコネクターから参照可能です。

管理証明書は再利用可能なリソースであり、バンドルを更新すると、それを参照するすべてのリスナーやコネクターに自動的に反映されます。

証明書の形式とファイル構成

EMQXの管理証明書はPEMエンコードファイルを使用し、既存のTLS証明書展開方式と一貫しています。

PEMファイルを使用する利点は以下の通りです。

透明性：opensslなどの標準ツールで証明書ファイルを簡単に検査・検証可能。
互換性：Erlang/OTPのSSLライブラリがネイティブにサポートし、
- ファイルベースの証明書キャッシュ
- 更新された証明書ファイルの自動リロードを提供。

証明書ファイル構成

管理証明書バンドルは、証明書名とネームスペースで識別されるディレクトリとしてディスクに保存されます。

例：

mqtt.example.com
tenant1/certs1

管理証明書バンドルに含まれるファイル例：

ファイル名	必須	説明
`key.pem`	必須	秘密鍵
`chain.pem`	必須	証明書チェーン（ルートCAを除く）
`ca.pem`	任意	ピア検証用のルートCAバンドル
`key-password.pem`	任意	秘密鍵が暗号化されている場合の復号パスワード

SNIによる複数証明書の利用

同一リスナーに複数の管理証明書バンドルを設定した場合、EMQXはServer Name Indication（SNI）に基づいて動的に証明書を選択します。

SNIはTLS拡張機能であり、クライアントがTLSハンドシェイク中に接続先のホスト名を指定することを可能にします。

SNIの利用方法

各管理証明書参照は任意でsni値を指定可能です。
TLSハンドシェイク時に、
1. クライアントがSNIホスト名を送信
2. EMQXが設定された証明書エントリと照合
3. 一致する証明書バンドルを使用
4. 一致しない場合はリストの最初の証明書をデフォルトとして使用

これにより、単一リスナーで同一IP・ポート上に複数ドメインやテナント向けの異なるTLS証明書を安全に提供可能です。

例

hocon

listeners.ssl.default {
  bind = "0.0.0.0:8883"

  ssl_options {
    managed_certs = [
      {
        bundle_name = "default-cert"
        sni = "example.com"
      },
      {
        bundle_name = "example-cert-1"
        sni = "mqtt.example.com"
      }
    ]
  }
}

管理証明書バンドルの作成と管理

このセクションでは、ダッシュボードおよびREST APIを使った管理証明書バンドルの作成と管理方法を説明します。作成後、証明書バンドルは選択可能となり、複数のリスナーやコネクターで再利用できます。

ダッシュボードからの証明書バンドル作成

ダッシュボードから直接管理証明書バンドルを作成できます。

管理 -> 証明書 に移動します。
+ 作成 をクリックします。
管理証明書の作成パネルで以下の情報を入力します。
- 名前（必須）：管理証明書バンドルの一意の名前。
- ネームスペース：管理証明書バンドルをグローバルネームスペースまたは特定のテナントネームスペースに作成するかを制御します。
  デフォルトではオフで、バンドルはグローバル（global）ネームスペースに作成されます。有効にするとテナントネームスペースを選択してその中に作成可能です。
  - グローバル管理者はglobalネームスペースおよび任意のテナント（非グローバル）ネームスペースに作成可能。
  - ネームスペーススコープのユーザーは自身のネームスペース内にのみ作成可能。
- TLS証明書（必須）：PEM形式のサーバー証明書。証明書内容を直接ペーストするか、ファイル選択でアップロード可能。必要に応じて完全な証明書チェーンを含めてください。
- TLSキー（必須）：サーバー証明書に対応するPEM形式の秘密鍵。内容を直接ペーストするかファイルアップロード可能。
- キーのパスワード：秘密鍵が暗号化されている場合のパスフレーズ（任意）。
- CA証明書：PEM形式の認証局証明書（任意）。主に以下の場合に必要です。
  - 双方向（相互）TLS認証を行う場合
  - CA証明書を必要とするコネクターで再利用する場合
作成をクリックして管理証明書バンドルを保存します。

ダッシュボードでの証明書バンドル管理

作成した証明書バンドルはダッシュボードの証明書一覧に表示され、管理可能です。

画面上部のネームスペースドロップダウンでグローバルネームスペースと特定テナント（非グローバル）ネームスペースを切り替えられます。選択に応じて一覧が自動更新されます。
各証明書バンドルは名前と利用可能な操作が表示されます。

この画面から以下の操作が可能です。

選択したネームスペースの証明書バンドルの閲覧
証明書バンドルの編集（証明書内容、秘密鍵、CA証明書の更新）
不要になった証明書バンドルの削除

証明書バンドルの削除

証明書バンドルの削除をクリックすると、EMQXは現在そのバンドルを参照しているリスナーやコネクターがあるかを確認します。

依存がなければ即座に削除されます。
依存がある場合は警告が表示され、強制削除するかどうかを確認されます。強制削除を実行すると、参照中でも証明書バンドルが削除されます。

::: caution 使用中の証明書バンドルを強制削除すると、依存するリスナーやコネクターは証明書設定を失います。影響を受けたコネクターはエラーを報告し、新しいTLS接続の確立に失敗する可能性があります。強制削除後は依存リソースの更新や再設定を行ってください。 :::

管理証明書バンドルはディスクに保存され、EMQXが自動的にリロードします。管理証明書の更新にEMQXの再起動は不要です。

certificate_bundle_list

REST APIによる証明書バンドル管理

ダッシュボードに加え、EMQXはTLS証明書ファイル管理用のREST APIも提供しています。APIで作成した管理証明書はダッシュボードで作成したものと同一で、リスナーやコネクターから同様に参照可能です。

証明書ファイルのアップロード

管理証明書バンドルの作成または更新のために証明書ファイルをアップロードします。

対応ファイル種別：

key：秘密鍵
chain：証明書チェーン（ルートCAを除く）
ca：CA証明書バンドル
key-password：秘密鍵復号用パスワード

ネームスペースを指定して証明書ファイルをアップロード：

POST /certs/ns/:namespace/name/:name?file=key|chain|ca|key-password

グローバルネームスペースにアップロード：

POST /certs/global/name/:name?file=key|chain|ca|key-password

証明書バンドル一覧の取得

ネームスペース内の管理証明書バンドル一覧を取得：

GET /certs/ns/:namespace/list

グローバルネームスペースの管理証明書バンドル一覧を取得：

GET /certs/global/list

証明書バンドルの削除

管理証明書バンドルまたはバンドル内の個別証明書ファイルを削除する前に、EMQXは全ネームスペースの設定で参照されているかをチェックします。依存がある場合、force_delete=trueが指定されていなければ400 BAD_REQUESTエラーで失敗します。

ネームスペースから管理証明書バンドル全体を削除：

DELETE /certs/ns/:namespace/name/:name

グローバルネームスペースから管理証明書バンドル全体を削除：

DELETE /certs/global/name/:name

force_deleteクエリパラメータは、バンドル内の個別ファイル削除時（kindクエリパラメータ指定時）にも適用されます。

クエリパラメータ

パラメータ	型	デフォルト	説明
`force_delete`	Boolean	`false`	`true`の場合、他の設定で参照されていてもバンドルやファイルを削除します。`false`（デフォルト）では依存がある場合`400`エラーになります。

削除がブロックされた場合、400レスポンスボディにreferencing_configsフィールドが含まれ、どの設定が参照しているかがネームスペースごとに示されます。例：

json

{
  "code": "BAD_REQUEST",
  "message": "Cannot delete file or bundle while configurations are depending on it",
  "referencing_configs": {
    "global": [
      ["connectors", "http", "my-connector"]
    ]
  }
}

::: caution force_delete=trueを設定すると、アクティブな依存関係があっても証明書バンドルが削除されます。参照しているリスナーやコネクターはTLS証明書設定を失い、新しい安全な接続の確立に失敗する可能性があります。強制削除後は影響を受けるリソースの再設定を行ってください。 :::

SSL/TLS証明書の更新

SSL/TLS証明書は有効期限切れ前に更新し、安全な接続を維持する必要があります。EMQXでの証明書更新方法は管理方式によって異なります。

パスベース証明書の更新

パスベース証明書は設定内でファイルパスを直接参照しています（例：certfile、keyfile、cacertfile）。

更新手順：

既存の証明書ファイルを./etcまたは/etc/emqx/etcディレクトリ内で新しい証明書、秘密鍵、CAファイルに置き換えます。
設定で参照するファイルパスは変更しないようにします。

EMQXは更新された証明書ファイルを自動的にリロードします。

証明書ファイルは定期的にチェックおよびリロードされます。
デフォルトでは120秒ごとにリロードされます。
多くの場合、リスナーの再起動は不要です。

管理証明書の更新

管理証明書は証明書バンドルを変更することで更新します。

更新手順：

ダッシュボードまたは管理証明書APIを使い、既存の管理証明書バンドルに新しい証明書、秘密鍵、またはCA証明書をアップロードします。

更新後：

管理証明書を参照するすべてのリスナーやTLS対応コンポーネントは自動的に更新された証明書を使用します。
リスナーやEMQXの再起動は不要です。

管理証明書は再利用を前提として設計されており、バンドルの更新は参照するすべてのリソースに影響します。

次のステップ

SSL/TLS証明書を取得したら、クライアントのSSL/TLS接続を有効化できます。

SSL/TLS接続の有効化

Kubernetes

EMQX Operator

EMQX クラスター管理

API リファレンス

パスワード認証

監視

アクセスコントロール

統合

管理

OpenTelemetry との統合

エンドツーエンドトレース

プラグインカタログ

JT/T 808 ゲートウェイ

GB/T 32960 ゲートウェイ

Volcengine RTC

シナリオ

GPT-Realtime

SSL/TLS証明書 ​

SSL/TLS証明書の取得 ​

証明書取得の選択肢 ​

自己署名CA証明書の作成 ​

サーバー証明書の発行 ​

クライアント証明書の発行 ​

EMQXでの証明書管理 ​

パスベース証明書 ​

管理証明書 ​

管理証明書バンドル ​

証明書の形式とファイル構成 ​

証明書ファイル構成 ​

SNIによる複数証明書の利用 ​

SNIの利用方法 ​

例 ​

管理証明書バンドルの作成と管理 ​

ダッシュボードからの証明書バンドル作成 ​

ダッシュボードでの証明書バンドル管理 ​

証明書バンドルの削除 ​

REST APIによる証明書バンドル管理 ​

証明書ファイルのアップロード ​

証明書バンドル一覧の取得 ​

証明書バンドルの削除 ​

SSL/TLS証明書の更新 ​

パスベース証明書の更新 ​

管理証明書の更新 ​

次のステップ ​

SSL/TLS証明書

SSL/TLS証明書の取得

証明書取得の選択肢

自己署名CA証明書の作成

サーバー証明書の発行

クライアント証明書の発行

EMQXでの証明書管理

パスベース証明書

管理証明書

管理証明書バンドル

証明書の形式とファイル構成

証明書ファイル構成

SNIによる複数証明書の利用

SNIの利用方法

例

管理証明書バンドルの作成と管理

ダッシュボードからの証明書バンドル作成

ダッシュボードでの証明書バンドル管理

証明書バンドルの削除

REST APIによる証明書バンドル管理

証明書ファイルのアップロード

証明書バンドル一覧の取得

証明書バンドルの削除

SSL/TLS証明書の更新

パスベース証明書の更新

管理証明書の更新

次のステップ