エージェント通信への SSL の有効化
Build Forge® コンポーネントはデフォルトでセットアップされ、 SSL が有効である場合には特定のポートとセキュリティー設定を使用します。
Build Forge® とエージェントとの間の SSL 通信を有効にするには、 以下を実行する必要があります。
- UNIX コンピューターで、エージェントをホストするコンピューターに GCC ライブラリーがインストールされているようにします。
- 前提条件: クライアント通信および内部通信用に SSL を有効にします。 クライアントおよび内部接続用の SSL の有効化を参照してください。
- 各エージェントを構成します。このタスクには、以下が含まれます。
- エージェント・ホストへの証明書の追加
- エージェント用に bfagent.conf ファイルを編集
- コンソールで、エージェントに接続するサーバー定義ごとに SSL を有効にします。
エージェントでの SSL の構成
- エージェントが稼働中である場合は、停止してください。
- エージェントのルート・インストール・ディレクトリーに、証明書の .PEM ファイルを配置します。
SSL を迅速にインプリメントおよびテストするには、Build Forge インストールから .PEM ファイルをコピーします。 このファイルは <bfinstall>/keystore にあります。注: エージェント・バージョン (bfagent -v) が 8.0 ではない、または 8.0 より低い場合、エージェントのインストール・フォルダーで古いエージェント openssl ユーティリティーを使用して、新しい buildForgeKeyStore.p12 から buildForgeKey.pem を再生成し、古いエージェントを使用できるようにする必要があります。 次に例を示します。
.openssl pkcs12 -in buildForgeKeyStore.p12 -passin pass:<bfpassword> -passout pass:<bfpassword> -out buildForgeKey.pem
SSL のベスト・プラクティスは、各エージェントに個別の証明書を使用することです。
- 以下のそれぞれについて、個別の鍵ストア・ファイル (.PEM) を作成します。
- 秘密鍵 (key)
- 秘密鍵用のパブリック証明書 (cert)
- 信頼された署名者 (ca つまり認証局)
- エージェントに (Build Forge® エンジンの証明書のコピーではなく) 固有の証明書を使用している場合は、そのエージェントの証明書を Build Forge® の認証局鍵ストア <bfinstall>/keystore/buildForgeCA.pem に追加します。 複数のエンジン (冗長化エンジン) を実行している場合は、各エンジンの認証局鍵ストアに証明書を追加します。
- kdb を System z で使用する場合は、gskkeyman で kdb を作成してください。
- System Authorization Facility (SAF) 鍵リングを使用する場合は、RACF で鍵リングを作成し、その鍵リングに証明書を結び付けてください。
- 以下のそれぞれについて、個別の鍵ストア・ファイル (.PEM) を作成します。
- BFAgent.conf を編集します。以下の行は、ファイル内で
コメント化されています。コメント接頭部を削除してください。
ssl_key_location buildForgeKey.pem ssl_key_password password ssl_cert_location buildForgeCert.pem ssl_ca_location buildForgeCA.pem ssl_protocol TLSv1 ssl_cipher_group ALL
password は、buildForgeKey.pem 鍵ストアのパスワードです。 暗号化する場合は、buildforge.conf および bfagent.conf におけるパスワードの暗号化を参照してください。
エージェントに接続する際にクライアント認証を必須にする場合は、 以下の行のコメントを外してください。
この設定では、エージェントの認証局鍵ストア buildForgeCA.pem に、 エンジンの証明書を追加する必要があります。ssl_client_authentication true
固有の暗号を使用する場合は、以下の行のコメントを外して、 使用する暗号リストを追加します。ssl_cipher_override cipher_list
- System z で稼働しているエージェントの場合は、BFAgent.conf を編集し、以下の行のコメントを外してください。
gsk_ssl_key_location <root/cert SAF> gsk_ssl_key_location /etc/key.kdb gsk_ssl_kdb_password <password> gsk_keyring_label <certificate label> gsk_ssl_protocol ALL gsk_ssl_cipher_v2 6321 gsk_ssl_cipher_v3 0906030201 gsk_ssl_client_authentication true gsk_password_encrypt false
gsk_ssl_key_location は、1 つだけ使用してください。 SAF 鍵リングと kdb のいずれかを選択できます。 SAF 鍵リングは、<userid>/<keyring> で指定します。
- エージェントを開始します。 コンソールからの接続をテストするには、エージェントが稼働中である必要があります。
サーバー定義での SSL の有効化
コンソールは、サーバー定義を使用してエージェントに接続します。
SSL 有効化エージェントに接続する各サーバー定義について、以下を実行します。
- コンソールで、「サーバー」パネルに移動します。
- サーバー定義名をクリックします。
- サーバー定義の「詳細」タブで、以下を行います。
- 「SSL 有効化」を「はい」に設定します。
- 「保存」をクリックします。
- 「接続のテスト」をクリックします。
エージェントとの SSL 通信のトラブルシューティング
以下のチェックリストは、SSL 有効化の際に共通する問題について説明します。
- エージェント
- エージェント SSL は構成されていませんが、セキュリティーおよび サーバー定義において SSL が有効化されています。
- エージェント用の証明書は、Build
Forge® エンジンによって信頼されません。以下のようにして、エンジンの CA 鍵ストアにエージェントの証明書を追加する必要があります。
<bfinstall>/keystore/buildForgeCA.pem
- BFAgent.conf に指定された鍵ストアのパスワードが間違っています。
- BFAgent.conf にクライアント認証が指定されていますが、 エンジンの証明書がエージェントの認証局 buildForgeCA.pem に追加されていません。
- Build
Forge® コンソール
- コンソールで SSL が有効化されました。保存しなかったか、保存前に「マスター BFClient.conf の更新」をクリックしています。または、保存後に「マスター BFClient.conf の更新」をクリックしていません。
- サーバー定義
- SSL が正常に有効化されませんでした。「保存」をクリックしてから「接続のテスト」をクリックしてください。
- エンジンとエージェントの設定の一致
- ハンドシェーク・プロトコルが一致していません。エンジンの SSL 構成とエージェントの SSL 構成の両方で、ハンドシェーク・プロトコルは同じ値 (TLSv1 または SSLv3) に設定する必要があります。デフォルト値は TLSv1 です。
- 暗号スイートが一致していません。エンジンの SSL 構成とエージェント の SSL 構成に指定された暗号スイートでは、共通する暗号が必要です。デフォルトの暗号スイート・グループは ALL です。
デバッグ・メッセージの有効化
エンジンおよびエージェントでデバッグを有効にできます。 デバッグを有効にすると、構成上の問題識別に役立つ、追加の明細出力が 生成されます。- エンジンのデバッグを有効にする手順は、以下のとおりです。
- SSL 有効化サーバー定義によって使用される環境で、以下の変数を追加します。
BFDEBUG_SECURITY=1
- エンジンを停止し、再始動します。
- Windows の場合は、エンジンをフォアグラウンドで開始してください。 出力はコマンド・ウィンドウに表示されます。
- UNIX または Linux の場合は、デバッグをオンにしてエンジンを開始してください。
エンジンからの出力は、<bfinstall>/log 内のエンジン・ログ・ファイルに記載されます。cd <bfinstall>/rc ./buildforge start
- SSL 有効化サーバー定義によって使用される環境で、以下の変数を追加します。
- エージェントのデバッグを有効化する手順は、以下のとおりです。
- エージェントを停止します。
- BFAgent.conf に以下の行を追加します。
この例の場合、エージェントは出力を bfagent.log に書き込みます。 出力先として、別のファイル名を指定できます。activity_log bfagent.log
注: エージェントがサービスとして稼働する場合は、絶対パスを指定してください。 - エージェントを開始します。
SSL 接続が正しく確立された場合のエンジンのデバッグ出力例
エンジンがエージェントへの接続に成功すると、以下のような出力が生成されます。
SSL_ca_file: ./keystore/buildForgeCA.pem
SSL_cert_file: ./keystore/buildForgeCert.pem
SSL_key_file: ./keystore/buildForgeKey.pem
SSL_verify_mode: 0x01
SSL_version: TLSv1
SSL_cipher_list: ALL
SSL_use_cert: 1
Making as SSL connection using socket IO::Socket::INET=GLOB(0x1e8f0f4).
SSL connection to agent.
DEBUG: .../IO/Socket/SSL.pm:1387: new ctx 80662848
DEBUG: .../IO/Socket/SSL.pm:880: dont start handshake: IO::Socket::SSL=GLOB(0x1e8f0f4)
DEBUG: .../IO/Socket/SSL.pm:284: ssl handshake not started
DEBUG: .../IO/Socket/SSL.pm:327: Net::SSLeay::connect -> 1
DEBUG: .../IO/Socket/SSL.pm:382: ssl handshake done
Socket is of type: ref(IO::Socket::SSL=GLOB(0x1e8f0f4))
ReadyLine: 202 HELLO TLS - BuildForge Agent v_VERSION_
.
Storing Agent Version [999.999.999.999-999-9999] for [08974C8E-6C3B-1014-972D-D9B2901D9F42]
cmd ping
username pbirk
encpass c1713f4a31af3f1300f7b2414a24559c4d6097e07310cf9c412e
go
Sending agent request...
SSL 接続が正常に確立された場合のエージェントのデバッグ出力例
正常に稼働しているエージェントが SSL 接続を確立すると、以下のような出力が生成されます。
[2256] main.c : 409: === NEW AGENT ===
[2256] io.c : 264: In start_SSL
[2256] io.c : 89: Key location: buildForgeKey.pem
[2256] bfpwdlocloader.c: 134: Looking for password locator: ssl_key_password_locator
[2256] bfpwdlocloader.c: 244: Looking for password for prop
ssl_key_password from bfagent.conf.
[2256] bfcryptloader.c : 202: Loading password encryption module.
[2256] bfcryptloader.c : 276: Password encryption property
password_encrypt_module is not configured.
[2256] bfcryptloader.c : 539: Password decoded.
[2256] io.c : 98: Cert location: buildForgeCert.pem
[2256] bfpwdlocloader.c: 134: Looking for password locator:
ssl_cert_password_locator
[2256] bfpwdlocloader.c: 244: Looking for password for prop
ssl_cert_password from bfagent.conf.
[2256] io.c : 153: Setting key password in default userdata.
[2256] io.c : 160: Getting private key from PEM.
[2256] io.c : 166: Checking private key from PEM.
[2256] io.c : 172: Getting CA store information.
[2256] bfpwdlocloader.c: 134: Looking for password locator:
ssl_ca_password_locator
[2256] bfpwdlocloader.c: 244: Looking for password for prop
ssl_ca_password from bfagent.conf.
[2256] io.c : 178: CA location: buildForgeCert.pem
[2256] io.c : 184: Checking the CA store.
[2256] io.c : 230: Returning from init_CTX.
[2256] io.c : 281: Calling SSL_new
[2256] io.c : 294: Calling SSL_accept.
[2256] io.c : 346: Cipher chosen: AES256-SHA
[2256] io.c : 367: ssl_state = SS_CERTIFIED
エージェントで不適切な鍵ストアのパスワードが使用された場合の出力例
エージェント・サイドの鍵ストアのパスワード構成が間違っていると、エンジンとエージェント両方の出力に示されます。
エンジンの出力 (excerpt):
SSL_use_cert: 1
Making as SSL connection using socket IO::Socket::INET=GLOB(0x1e8f0f4).
SSL connection to agent.
DEBUG: .../IO/Socket/SSL.pm:1387: new ctx 80662848
DEBUG: .../IO/Socket/SSL.pm:880: dont start handshake: IO::Socket::SSL=GLOB(0x1e8f0f4)
DEBUG: .../IO/Socket/SSL.pm:284: ssl handshake not started
DEBUG: .../IO/Socket/SSL.pm:327: Net::SSLeay::connect -> -1
DEBUG: .../IO/Socket/SSL.pm:1135: SSL connect attempt failed with unknown error
error:1408F10B:SSL routines:SSL3_GET_RECORD:wrong version number
DEBUG: .../IO/Socket/SSL.pm:333: fatal SSL error: SSL connect attempt failed with unknown error
error:1408F10B:SSL routines:SSL3_GET_RECORD:wrong version number
DEBUG: .../IO/Socket/SSL.pm:1422: free ctx 80662848 open=80662848 80566656
DEBUG: .../IO/Socket/SSL.pm:1425: OK free ctx 80662848
エージェントの出力 (excerpt):
[ 5272] io.c : 98: Cert location: buildForgeCert.pem
[ 5272] bfpwdlocloader.c: 134: Looking for password locator: ssl_cert_passwor
d_locator
[ 5272] bfpwdlocloader.c: 244: Looking for password for prop ssl_cert_password from bfagent.conf.
[ 5272] io.c : 153: Setting key password in default userdata.
[ 5272] io.c : 160: Getting private key from PEM.
[ 5272] io.c : 218: Failure reason: SSLErrorBadPKeyFile
[ 5272] io.c : 221: OpenSSL error string: error:00000000:lib(0):func(0):reason(0)
[ 5272] io.c : 281: Calling SSL_new
[ 5272] platform.c :2693: platform_release_credentials
[ 5272] main.c : 412: --- EXITING ---
エージェント出力のエラー・コード
以下は、検出される可能性のあるその他いくつかのエラー・コードと、その理由を示すリストです。
- SSLErrorBadCA: buildForgeCA.pem に署名者をロード中に問題が発生しました。 これは、署名者の追加方法に起因する、ファイル・フォーマット上の問題である可能性があります。
- SSLErrorBadCert: buildForgeCert.pem に証明書をロード中に問題が発生しました。 証明書の秘密鍵が一致しないか、PEM 内の秘密鍵が破損しています。
- SSLErrorBadPKeyFile: BFAgent.conf 内の ssl_key_password プロパティー に指定された、buildForgeKey.pem パスワードで問題が発生しました。
- SSLErrorBadPKey: SSL_CTX_check_private_key から 1 以外の値が返されました。秘密鍵のフォーマットが無効であるか、秘密鍵が証明書と一致しません。
- SSLErrorFIPSEnablement: FIPS 有効化中にエラーが発生しました。 このエラーは通常、FIPS のセルフ・チェック中に検出された問題が原因です。 このエラーは内部エラーであると考えられます。
- SSLErrorInvalidCipher: 暗号の仕様が、OpenSSL で許可される内容に一致していません。 BFAgent.conf の ssl_cipher_group プロパティーまたは ssl_cipher_override プロパティーに指定された暗号を確認してください。
- SSLErrorNoCtx: 新規 SSL CTX オブジェクトの作成中に問題が発生しました。 このエラーは内部エラーであると考えられます。