エージェント通信への SSL の有効化

Build Forge コンポーネントはデフォルトでセットアップされ、 SSL が有効である場合には特定のポートとセキュリティー設定を使用します。

Build Forge とエージェントとの間の SSL 通信を有効にするには、 以下を実行する必要があります。

エージェントでの SSL の構成

  1. エージェントが稼働中である場合は、停止してください。
  2. エージェントのルート・インストール・ディレクトリーに、証明書の .PEM ファイルを配置します。

    Build Forge インストールから .PEM ファイルをコピーすると、 SSL を簡単にインプリメントおよびテストできます。 このファイルは <bfinstall>/keystore にあります。

    SSL のベスト・プラクティスは、各エージェントに個別の証明書を使用することです。

    1. 以下のそれぞれについて、個別の鍵ストア・ファイル (.PEM) を作成します。
      • 秘密鍵 (key)
      • 秘密鍵用のパブリック証明書 (cert)
      • 信頼された署名者 (ca つまり認証局)
    2. エージェントに (Build Forge エンジンの証明書のコピーではなく) 固有の証明書を使用している場合は、そのエージェントの証明書を Build Forge の認証局鍵ストア <bfinstall>/keystore/buildForgeCA.pem に追加します。 複数のエンジン (冗長化エンジン) を実行している場合は、各エンジンの認証局鍵ストアに証明書を追加します。
  3. 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 におけるパスワードの暗号化 を参照してください。

    エージェントに接続する際にクライアント認証を必須にする場合は、 以下の行のコメントを外してください。 
    ssl_client_authentication true
    この設定では、エージェントの認証局鍵ストア buildForgeCA.pem に、 エンジンの証明書を追加する必要があります。
    固有の暗号を使用する場合は、以下の行のコメントを外して、 使用する暗号リストを追加します。 
    ssl_cipher_override cipher_list
  4. エージェントを開始します。 コンソールからの接続をテストするには、エージェントが稼働中である必要があります。

サーバー定義での SSL の有効化

コンソールは、サーバー定義を使用してエージェントに接続します。

SSL 有効化エージェントに接続する各サーバー定義について、以下を実行します。

エージェントとの SSL 通信のトラブルシューティング

以下のチェックリストは、SSL 有効化の際に共通する問題について説明します。

デバッグ・メッセージの有効化

エンジンおよびエージェントでデバッグを有効にできます。 デバッグを有効にすると、構成上の問題識別に役立つ、追加の明細出力が 生成されます。

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 ---

エージェント出力のエラー・コード

以下は、検出される可能性のあるその他いくつかのエラー・コードと、その理由を示すリストです。

フィードバック