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/ にファイルが保存されます。

内部的には 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 は TLS ハンドシェイク時の 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 6.1.4 以降、証明書バンドルが何らかの設定で参照されている場合は削除できません。

削除をクリックすると、削除の確認 ダイアログが表示されます。
キャンセル をクリックすると削除せずにダイアログを閉じます。確認をクリックすると削除処理を進めます。
確認をクリック後、以下のいずれかが発生します。
- 依存関係がなければ証明書バンドルは削除されます。
- 1つ以上の設定がバンドルを参照している場合、削除は拒否されます。バンドル使用中 ダイアログに参照元設定が表示されます。ページへ移動 をクリックして該当設定を更新または削除し、再度削除を試みるか、キャンセル でダイアログを閉じます。

管理証明書バンドルはディスクに保存され、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 6.1.4 以降、全ネームスペースの設定がバンドルを参照している場合、管理証明書バンドルまたはバンドル内の個別ファイルの削除は拒否され、400 BAD_REQUEST エラーが返されます。

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

text

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

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

text

DELETE /certs/global/name/:name

バンドル内の個別ファイルを削除する場合は同じエンドポイントに kind クエリパラメータでファイル種別を指定します。依存関係チェックはバンドル全体と個別ファイルの両方に適用されます。

force_delete クエリパラメータは API スキーマから削除されており、依存関係チェックを回避できません。既存クライアントが force_delete=true を送信しても無視され、通常の削除リクエストとして処理されます。

削除がブロックされた場合、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"]
    ]
  }
}

削除を再試行する前に、referencing_configs に示されたすべての設定を更新または削除し、バンドルを参照しない状態にしてください。

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 接続の有効化

パスワード認証

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

SSL/TLS 証明書 ​

SSL/TLS 証明書の取得 ​

証明書取得の選択肢 ​

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

サーバー証明書の発行 ​

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

EMQX における証明書管理 ​

パスベース証明書 ​

管理証明書 ​

管理証明書バンドル ​

証明書のフォーマットとファイル構成 ​

証明書ファイル構成 ​

SNI による複数証明書のサポート ​

SNI の利用方法 ​

例 ​

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

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

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

証明書バンドルの削除 ​

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

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

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

証明書バンドルの削除 ​

SSL/TLS 証明書の更新 ​

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

管理証明書の更新 ​

次のステップ ​

SSL/TLS 証明書

SSL/TLS 証明書の取得

証明書取得の選択肢

自己署名 CA 証明書の作成

サーバー証明書の発行

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

EMQX における証明書管理

パスベース証明書

管理証明書

管理証明書バンドル

証明書のフォーマットとファイル構成

証明書ファイル構成

SNI による複数証明書のサポート

SNI の利用方法

例

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

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

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

証明書バンドルの削除

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

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

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

証明書バンドルの削除

SSL/TLS 証明書の更新

パスベース証明書の更新

管理証明書の更新

次のステップ