为代理程序通信启用 SSL

缺省情况下,Build Forge 组件设置为在启用 SSL 时使用某些端口和安全性设置。

要启用 Build Forge 和代理程序之间的 SSL 通信,需要执行以下操作:

配置代理程序使用 SSL

  1. 如果该代理程序正在运行,请停止该代理程序。
  2. 将证书的 .PEM 文件置于该代理程序的根安装目录。

    要快速实施和测试 SSL,可以从 Build Forge 安装中复制 .PEM 文件。这些文件位于 <bfinstall>/keystore

    SSL 的最佳实践是对每个代理程序使用不同的证书:

    1. 对以下每一项创建不同的密钥库文件(.PEM):
      • 专用密钥(密钥)
      • 专用密钥的公共证书(证书)
      • 受信签署者(CA 或认证中心)
    2. 如果要针对代理程序使用唯一的证书(而不是 Build Forge 引擎证书的副本),请将针对代理程序的证书添加至 Build Forge 的认证中心密钥库 <bfinstall>/keystore/buildForgeCA.pem 中。 如果正在运行多个引擎(冗余引擎),请将该证书添加至每个引擎的认证中心密钥库。
    3. 如果您要在 System z 上使用 kdb,请使用 gskkeyman 创建 kdb。
    4. 如果您要使用系统授权工具 (SAF) 密钥环,请使用 RACF 创建密钥环,并将证书连接到该密钥环。
  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. 对于在 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。 您可以选择 SAF 密钥环或 kdb。SAF 密钥环由 <userid>/<keyring> 指定。

  5. 启动代理程序。代理程序必须正在运行,以测试控制台发出的连接。

在服务器定义中启用 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
goSending 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

代理程序上密钥库密码出错时的示例输出

如果代理程序端上配置的密钥库密码错误,那么该密码将同时显示在引擎输出和代理程序输出中。

引擎输出(摘录):


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

代理程序输出(摘录):


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

代理程序输出中的错误代码

该列表包含可能遇到的某些其他错误代码及导致这些错误代码的原因:


反馈