managing-tls-certificates

TLS 証明書の管理

CockroachDB クラスターの TLS 証明書を管理します。CA 証明書のダウンロード、クライアント証明書認証の設定、証明書のローテーション、一般的な SSL/TLS 接続エラーのトラブルシューティングを扱います。CockroachDB Cloud（TLS は常時有効）とセルフホスト環境の証明書ライフサイクル管理の両方に対応しています。

このスキルを使用する場面

• アプリケーションクライアント（DBeaver、TypeORM、psql、Go、Python、Java）からの SSL/TLS 接続エラーのトラブルシューティング
• CockroachDB Cloud でのクライアント証明書認証の設定
• Cloud クラスターへのカスタム Client CA のアップロード
• 証明書のローテーションまたは更新（Cloud またはセルフホスト）
• Kafka への CDC changefeed 用 mTLS の設定
• Cloud クラスターの CA 証明書のダウンロードまたは場所の確認

前提条件

CockroachDB Cloud：

• ccloud CLI で認証済み（ccloud auth login）
• Cloud Console へのアクセス（CA 証明書のダウンロード用）
• Cluster Admin ロール（クライアント CA の設定用）

セルフホスト：

• cockroach cert CLI を利用可能
• クラスターのノードへの管理者アクセス
• OpenSSL（証明書の検査と生成用）

アクセスを確認する：

# Cloud
ccloud auth whoami
ccloud cluster list

# Self-hosted — check existing certificates
cockroach cert list --certs-dir=<certs-directory>

設定の決定事項

作業を進める前に、ユーザーのデプロイモデルを確認します。該当する選択肢を尋ねてから、以下の関連セクションのみを実行してください。

決定 1 — デプロイモデル：

• CockroachDB Cloud： TLS は常時有効で、クラスター CA は Cockroach Labs が管理します。CA のダウンロード、クライアント証明書認証、Cloud 証明書のローテーションについてはパート 1 に従ってください。
• セルフホスト： CA、ノード、クライアント証明書のライフサイクルをすべて手動で管理します。証明書の作成、ローテーション、管理についてはパート 2 に従ってください。

パート 3（トラブルシューティング）とパート 4（CDC 用 mTLS）は、どちらのデプロイモデルにも適用されます。

手順

パート 1：CockroachDB Cloud の TLS

決定 1 でユーザーが CockroachDB Cloud を選択した場合は、このパートに従ってください。

CockroachDB Cloud では、すべての接続で TLS が必須です。クラスター CA 証明書は Cockroach Labs が管理します。

1.1 CA 証明書をダウンロードする

CA 証明書は、クラスターの正当性をクライアントが検証するために必要です。

# Download via ccloud CLI
ccloud cluster cert <cluster-id>

# Or download from the Cloud Console:
# Cluster > Connect > Download CA Cert

CA 証明書は、こちらからも入手できます：https://cockroachlabs.cloud/clusters/<cluster-id>/cert

ダウンロード後の一般的な CA 証明書の保存場所：

• macOS：~/.postgresql/root.crt
• Linux：~/.postgresql/root.crt または /etc/cockroach-certs/ca.crt
• Windows：%APPDATA%\postgresql\root.crt

1.2 クライアント証明書認証を設定する

クライアント証明書認証では、パスワードの代わりに証明書でクライアントの身元を証明する、相互 TLS（mTLS）を使用します。

ステップ 1：クラスターに Client CA をアップロードする

Client CA はクライアント証明書に署名します。これはクラスターの CA とは別のものです。

# Upload a Client CA certificate via ccloud CLI
ccloud cluster cert set-client-ca <cluster-id> --cert-file <client-ca.crt>

ステップ 2：Client CA で署名したクライアント証明書を作成する

# Generate a client key and certificate signing request
openssl genrsa -out client.<username>.key 2048
openssl req -new -key client.<username>.key \
  -out client.<username>.csr \
  -subj "/CN=<username>"

# Sign the CSR with your Client CA
openssl x509 -req -in client.<username>.csr \
  -CA client-ca.crt -CAkey client-ca.key \
  -CAcreateserial \
  -out client.<username>.crt \
  -days 365

ステップ 3：クライアント証明書を使用して接続する

cockroach sql \
  --url "postgresql://<username>@<cluster-host>:26257/defaultdb?sslmode=verify-full&sslrootcert=<ca.crt>&sslcert=client.<username>.crt&sslkey=client.<username>.key"

クライアントごとの接続文字列については、接続例のリファレンスを参照してください。

1.3 証明書のローテーション（Cloud）

クライアント証明書は、有効期限が切れる前にローテーションする必要があります。クラスター CA 証明書は Cockroach Labs が管理し、自動的にローテーションされます。

クライアント証明書のローテーション：

1. 同じ Client CA（または新しい Client CA）で署名した新しいクライアント証明書を生成します
2. 新しい証明書をアプリケーションクライアントにデプロイします
3. 新しい証明書で接続できることを確認します
4. アプリケーションクライアントから古い証明書を削除します

Client CA のローテーション：

1. 新しい Client CA を生成します
2. 新しい Client CA をクラスターにアップロードします（移行期間中は複数の CA に対応しています）
3. 新しい CA で署名した新しいクライアント証明書を発行します
4. すべてのアプリケーションに新しいクライアント証明書をデプロイします
5. すべてのクライアントの移行が完了したら、古い Client CA を削除します

パート 2：セルフホスト環境での証明書管理

決定 1 でユーザーが セルフホスト を選択した場合は、このパートに従ってください。

セルフホストの CockroachDB では、CA、ノード、クライアント証明書のライフサイクルを手動で管理する必要があります。

2.1 認証局の初期化

# Create the CA certificate and key
cockroach cert create-ca \
  --certs-dir=certs \
  --ca-key=my-safe-directory/ca.key

2.2 ノード証明書の作成

# Create a node certificate for each node
cockroach cert create-node \
  <node-hostname> \
  <node-ip> \
  localhost \
  127.0.0.1 \
  --certs-dir=certs \
  --ca-key=my-safe-directory/ca.key

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

# Create a client certificate for root user
cockroach cert create-client root \
  --certs-dir=certs \
  --ca-key=my-safe-directory/ca.key

# Create a client certificate for an application user
cockroach cert create-client <username> \
  --certs-dir=certs \
  --ca-key=my-safe-directory/ca.key

2.4 証明書のローテーション（セルフホスト）

# Check certificate expiry
cockroach cert list --certs-dir=certs

# Or with OpenSSL
openssl x509 -in certs/node.crt -noout -enddate

ローテーションの手順：

1. 既存の CA を使用して新しい証明書を生成します（または、先に CA をローテーションします）
2. 各ノードに新しい証明書をコピーします
3. 証明書を再読み込みします（SIGHUP — ダウンタイムは不要です）：

   kill -SIGHUP $(pgrep cockroach)
   

4. ノードが新しい証明書を提供していることを確認します

パート 3：SSL/TLS エラーのトラブルシューティング

包括的なエラーガイドについては、トラブルシューティングのリファレンスを参照してください。

よくあるエラーとすぐにできる対処法

「x509: certificate signed by unknown authority」

• クライアントがクラスターの CA 証明書を信頼していません
• 対処法：正しい CA 証明書をダウンロードし、接続文字列で sslrootcert を設定します

「SSL SYSCALL error: EOF detected」

• TLS ハンドシェイク中に接続が予期せず切断されました
• 対処法：ネットワーク接続、ファイアウォールのルール、および正しいポート（26257）が使用されていることを確認します

「tls: bad certificate」

• クライアント証明書がサーバーによって拒否されました
• 対処法：クライアント証明書がクラスターの信頼する CA によって署名されていることを確認します（クライアント CA をアップロードする必要があります）

「certificate has expired」

• クライアントまたはサーバーの証明書の有効期限が切れています
• 対処法：期限切れの証明書をローテーションします（上記のローテーション手順を参照してください）

診断コマンド

# Inspect a certificate
openssl x509 -in cert.crt -text -noout

# Verify certificate chain
openssl verify -CAfile ca.crt client.crt

# Test TLS connection to cluster
openssl s_client -connect <host>:26257 -CAfile ca.crt

# Check certificate expiry date
openssl x509 -in cert.crt -noout -enddate

パート 4：Kafka への CDC 変更フィードでの mTLS

CockroachDB の CDC 変更フィードでは、Kafka ブローカーへの認証に mTLS を使用できます。

-- Create a changefeed with mTLS authentication to Kafka
CREATE CHANGEFEED FOR TABLE orders
  INTO 'kafka://<kafka-broker>:9093?tls_enabled=true&ca_cert=<base64-ca>&client_cert=<base64-cert>&client_key=<base64-key>'
  WITH updated, resolved;

変更フィード URI 用の証明書の準備：

# Base64 encode certificates for use in changefeed URI
cat ca.crt | base64 -w 0    # Linux
cat ca.crt | base64          # macOS

cat client.crt | base64 -w 0
cat client.key | base64 -w 0

安全性に関する考慮事項

影響の種類	重大度	推奨事項
クライアント CA のアップロード	低	既存の接続には影響せず、新しい信頼ルートを追加するだけです
クライアント CA の削除	高	その CA によって署名されたすべてのクライアント証明書が無効になります
証明書の有効期限切れ	高	有効期限を監視し、期限切れになる前にローテーションします
誤った CA 証明書	中	クライアントは接続できなくなります。CA 証明書を更新すれば修正できます

次の操作は行わないでください：

• CA の秘密鍵を削除する — 新しい証明書の署名に必要です
• 期限切れの CA 証明書をアップロードする
• クライアントがまだ依存しているクライアント CA を削除する
• 本番クラスターで TLS を無効にする（CockroachDB Cloud では許可されていません）

ロールバック

クラウド — クライアント CA の問題：

1. 新しいクライアント CA を誤ってアップロードした場合は、正しい CA をアップロードします
2. クライアント証明書が拒否された場合は、一時的にパスワード認証に戻します
3. クラスター CA への対応が必要な場合は、CockroachDB サポートに連絡してください

セルフホスト — 証明書の問題：

1. バックアップから以前の証明書を復元します
2. 証明書を再読み込みします：kill -SIGHUP $(pgrep cockroach)
3. CA をローテーションした場合は、すべてのノードとクライアントが新しい CA を保持していることを確認します

参考資料

スキルの参考資料：

• クライアント接続の例 — 一般的なクライアント向けの接続文字列
• TLS トラブルシューティングガイド — よくある SSL/TLS エラーと対処法

関連スキル：

• auditing-cloud-cluster-security — セキュリティ体制の包括的な監査を実施する
• configuring-sso-and-scim — 証明書ベースの認証に代わる SSO

CockroachDB 公式ドキュメント：

• トランスポート層セキュリティ（TLS）
• 認証
• クライアント接続パラメーター
• cockroach cert コマンド
• セキュリティ証明書のローテーション
• クラウド証明書の管理
• CDC Kafka シンク