TLS証明書管理

このページでは、EMQX Cloud APIを使用して特定のデプロイメントのTLS証明書を管理する方法（追加、表示、更新、削除）について説明します。

このAPIはEMQX DedicatedおよびDedicated Flex v5デプロイメント、ならびにプラットフォームアカウント下で作成されたEMQX v4（4.4.x）デプロイメントに適用されます。BYOC TLS証明書の更新はサポートしていません。

証明書入力要件

• cert は1つ以上のPEMエンコードされたX.509バージョン1またはバージョン3の証明書を含む必要があります。サーバー証明書を最初に置き、その後に発行順に中間証明書を配置してください。チェーンには最大5枚の証明書まで含めることができます。
• サーバー証明書は現在有効であり、かつ有効期限まで少なくとも5日以上残っている必要があります。
• 証明書ブロック間には空白文字のみ許可されます。余分なテキスト、秘密鍵ブロック、不完全なブロック、PEMマーカーの不一致は拒否されます。
• 証明書およびその識別名（DN）は正しくエンコードされている必要があります。DNにcountryNameが含まれる場合、その値は2文字のPrintableStringでなければなりません。証明書のシリアル番号はゼロまたは正の値である必要があります。
• MD5署名はサポートされません。チェーン内で子証明書に続く発行者証明書もSHA-1を使用してはなりません。
• 提出されたチェーンの隣接する各ペアについて、子証明書の発行者名は次の証明書のサブジェクト名と一致し、子証明書の署名は次の証明書の公開鍵で検証可能でなければなりません。
• 各発行証明書はCA証明書である必要があります。Key Usage拡張が含まれている場合、その拡張は証明書署名を許可している必要があります。
• リーフ証明書がEC公開鍵を使用する場合、サポートされる曲線はP-256、P-384、P-521です。
• key はパスワードなしのPKCS#1またはPKCS#8 PEM形式の秘密鍵で、サーバー証明書と一致している必要があります。
• 双方向TLSの場合はcacertが必須です。これは1つ以上の信頼されたクライアントCA証明書を含むことができ、それぞれ個別に検証されます。これらの証明書は順序付けられたチェーンを形成する必要はありません。これらの要件はサーバー証明書チェーンにのみ適用されます：証明書は5枚以下で、最初の証明書は有効期限まで少なくとも5日以上残っている必要があります。

APIはTLS/SSL設定の保存または適用前に証明書入力を検証します。検証に失敗した場合、現在の証明書および設定は変更されません。証明書検証エラーはHTTP 400で返され、リクエストフィールド、入力内の証明書位置（1から開始）、および理由が示されます。

指定デプロイメントのTLS証明書ステータス取得

URI

GET /deployments/{deployment_id}/tls

TIP

このメソッドは60分間に60回までのリクエスト制限があります。{deployment_id}はデプロイメント名ではなくデプロイメントIDです。

リクエスト

なし

レスポンス

• 200:

名前	型	説明
tlsType	String	TLSタイプ：'one-way'（片方向）、'two-way'（双方向）
expire	String	証明書の有効期限
status	String	TLS証明書のステータス：'running'（稼働中）、'pending'（作成中）

• 401: APIキー認証失敗
• 403: APIキーアクセス権なし
• 404: デプロイメントが見つかりません
• 429: リクエスト制限超過

リクエスト例

curl -u key:secret -X GET {api}/deployments/ge6a1a75/tls

レスポンス例

{
  "expire": "2034-05-22 02:43:21",
  "status": "running",
  "tlsType": "one-way"
}

指定デプロイメントのTLS証明書作成

URI

POST /deployments/{deployment_id}/tls

TIP

このメソッドは60分間に6回までのリクエスト制限があります。{deployment_id}はデプロイメント名ではなくデプロイメントIDです。

リクエスト

名前	型	説明
tlsType	String	TLSタイプ：'one-way'（片方向）、'two-way'（双方向）
cert	String	公開鍵証明書
key	String	秘密鍵
cacert	String	クライアントCA証明書。証明書タイプが'two-way'の場合に必須

レスポンス

• 201:

名前	型	説明
tlsType	String	TLSタイプ：'one-way'、'two-way'
expire	String	証明書の有効期限
status	String	TLS証明書のステータス：'running'（稼働中）、'pending'（作成中）

• 400: 証明書、チェーン、有効期限、秘密鍵、または鍵/証明書の一致が無効
• 401: APIキー認証失敗
• 403: APIキーアクセス権なし
• 404: デプロイメントが見つかりません
• 422: 必須フィールドの欠如またはリクエストプロパティが無効。tlsTypeがtwo-wayの場合、cacertが必須
• 429: リクエスト制限超過

リクエスト例

curl -u key:secret \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "tlsType": "one-way",
    "cert": "-----BEGIN CERTIFICATE-----\nMII...tH6j7afSg==\n-----END CERTIFICATE-----",
    "key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEA5bdg8Rt5A7...AjQzYRdov4inpzw==\n-----END RSA PRIVATE KEY-----"
  }' \
  {api}/deployments/ge6a1a75/tls

レスポンス例

{
  "expire": "2034-05-22 02:43:21",
  "status": "pending",
  "tlsType": "one-way"
}

指定デプロイメントのTLS証明書更新

URI

PUT /deployments/{deployment_id}/tls

TIP

このメソッドは60分間に6回までのリクエスト制限があります。{deployment_id}はデプロイメント名ではなくデプロイメントIDです。

リクエスト

名前	型	説明
tlsType	String	TLSタイプ：'one-way'（片方向）、'two-way'（双方向）
cert	String	公開鍵証明書
key	String	秘密鍵
cacert	String	クライアントCA証明書。証明書タイプが'two-way'の場合に必須

レスポンス

• 200:

名前	型	説明
tlsType	String	TLSタイプ：'one-way'、'two-way'
expire	String	証明書の有効期限
status	String	TLS証明書のステータス：'running'（稼働中）、'pending'（作成中）

• 400: 証明書、チェーン、有効期限、秘密鍵、または鍵/証明書の一致が無効
• 401: APIキー認証失敗
• 403: APIキーアクセス権なし
• 404: デプロイメントが見つかりません
• 422: 必須フィールドの欠如またはリクエストプロパティが無効。tlsTypeがtwo-wayの場合、cacertが必須
• 429: リクエスト制限超過

リクエスト例

curl -u key:secret \
  -X PUT \
  -H 'Content-Type: application/json' \
  -d '{
    "tlsType": "one-way",
    "cert": "-----BEGIN CERTIFICATE-----\nMII...tH6j7afSg==\n-----END CERTIFICATE-----",
    "key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEA5bdg8Rt5A7...AjQzYRdov4inpzw==\n-----END RSA PRIVATE KEY-----"
  }' \
  {api}/deployments/ge6a1a75/tls

レスポンス例

{
  "expire": "2034-05-22 02:43:21",
  "status": "pending",
  "tlsType": "one-way"
}

指定デプロイメントのTLS証明書削除

URI

DELETE /deployments/{deployment_id}/tls

TIP

このメソッドは60分間に6回までのリクエスト制限があります。{deployment_id}はデプロイメント名ではなくデプロイメントIDです。

リクエスト

なし

レスポンス

• 401: APIキー認証失敗
• 403: APIキーアクセス権なし
• 404: デプロイメントが見つかりません
• 429: リクエスト制限超過

リクエスト例

curl -u key:secret -X DELETE {api}/deployments/ge6a1a75/tls

レスポンス例

// HTTPステータスレスポンスコード
204