Rational BuildForge 如何启用 SSL，以使 Build Forge 组件之间进行SSL通信

悠悠 2022-08-05 13:27 186阅读 0赞

BuildForge有不同的组件组成，各部分之间通过服务层或者网络通信进行协作，默认使用明文，但在一些环境下需要使用安全通信，可以通过启用SSL实现BuildForge的安全通信。

**内部接口**  
       Build Forge 由 Web 界面组件（Apache Web 服务器和 PHP）、服务层组件和引擎组件构成。Web 界面和引擎组件是服务层组件的客户机。API 程序客户机也是服务层组件的客户机。  
  
服务层入站     Apache Tomcat 应用程序服务器端口 49150  
                   服务层组件使用 SSL 配置以进行入站通信。 该配置在 Build Forge 控制台上的 管理→ 安全性 → SSL 处进行定义。 使用的   缺省值为 缺省 JSSE 入站 SSL 。

服务层客户机出站  
                   Apache Tomcat 应用程序服务器端口 49150  
                   服务层组件的出站通信。该配置在 Build Forge 控制台上的 管理 → 安全性 → SSL 处进行定义。 所使用的缺省值为 缺省 JSSE 出站 SSL 。  
          
          
          
 **外部接口**  
外部接口是 Build Forge 用于与外部系统对话的接口。外部接口是指以下另个组件之间的通讯  
         1 Build Forge 引擎与代理程序进行通信。  
         2 Build Forge 服务层组件与数据库进行通信。  
       
      Build Forge 引擎与代理程序通信     为该接口启用 SSL 需要以下操作：  
                 1 配置代理程序。它需要更改代理程序配置文件并将证书置于代理程序主机上。  
                 2 对使用代理程序的每个服务器资源启用 SSL 通信。在控制台上的服务器面板中执行该操作。  
                 （详细操作：为代理程序通信启用SSL）  
  
     Build Forge 服务层组件与数据库的通信  该接口的 SSL 配置在数据库的设备驱动程序中进行定义。  
             
**     一 为客户机和内部连接启用 SSL**  
        缺省情况下，Build Forge 组件设置为在启用 SSL 时使用某些端口和安全性设置。  
        要启用从客户机到 Build Forge 以及 Build Forge 内部组件之间的 SSL 连接，请严格按照指定的顺序执行以下操作：  
             **在控制台中，转至 管理 → 安全性 。**  
                   将 已启用 SSL 设置为“是”。此时会显示几个其他属性。将它们保留为缺省值。如果需要，可在以后对它们进行定制。  
                   单击 保存 。将在 Build Forge 数据库中保存 SSL 配置。  
                   单击 更新主 BFClient.conf 。SSL 配置用于更新 BFClient.conf 文件。 要允许Build Forge使用这些设置，它们必须在此文件中。  
            **停止并重新启动 Build Forge。这是必需的** 。  
          一旦证明系统在使用缺省设置，您就可以编辑影响 SSL 的属性。  
         注意  
            如果希望客户机使用 SSL 但是不希望在内部客户机（Web接口组件和引擎组件）与服务层组件之间使用 SSL，请执行以下操作：  
             手动编辑 BFClient.conf 文件。它在 <bfinstall> 中。  
                    更改 bf\_services\_preferred\_protocol=ssl为bf\_services\_preferred\_protocol= tcp  
                
  
             如果已在物理上对 Build Forge 主机进行了保护，那么此配置将提高性能而安全风险极小。  
        在已锁定的系统上重新启用 TCP 通信  
             如果 SSL 中存在错误配置，那么系统会拒绝您访问。  
             要获取对已锁定系统的访问权，请执行以下操作：  
               1 停止 Build Forge。  
                    在 <bfinstall> 目录中，使用文本编辑器打开 bfclient.conf 文件。  
               2 按如下所述更改协议属性：  
                     bf\_services\_preferred\_protocol=tcp  
              3 启动 Build Forge。  
              4您应该能够登录。  
           注意  
              更改协议并不会禁用安全登录认证，它在缺省情况下是启用的。用户被重定向到安全连接，该安全连接允许登录凭证到 Build Forge 的安全通信。  
           
         **二 为代理程序通信启用 SSL**  
             Build Forge 组件在缺省情况下设置为在启用 SSL 的情况下使用某些端口和安全性设置。  
            要启用 Build Forge 和代理程序之间的 SSL 通信，需要执行以下操作：  
                  先决条件：启用SSL以进行客户机通信和内部通信。 请参阅为客户机和内部连接启用 SSL。  
                  配置每个代理程序。该任务包括：  
                        将证书添加至代理程序主机  
                        编辑代理程序的 bfagent.conf 文件。  
                        在控制台中，在连接至代理程序的每个服务器定义中启用 SSL。  
            配置代理程序使用 SSL  
                  1. 如果该代理程序正在运行，请停止该代理程序。  
                  2. 将证书的 .PEM 文件置于该代理程序的根安装目录。  
                     要快速实施和测试 SSL，可以从 Build Forge 安装中复制 .PEM 文件。这些文件位于<bfinstall>/keystore。  
             
                     SSL 的最佳实践是对每个代理程序使用不同的证书：  
                        a. 对以下每一项创建不同的密钥库文件（.PEM）：  
                            专用密钥（密钥）  
                            专用密钥的公共证书（证书）  
                            受信签署者（CA 或认证中心）  
                       b. 如果正在使用代理程序的唯一证书（而不是 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

还需要指定加解密的模块和配置文件

password\_encrypt\_module C:/Program Files/IBM/BuildForge Agent/bfcrypt.dll;C:/Program Files/IBM/Build Forge/bfpwcrypt.conf  
                4. 启动代理程序。代理程序必须正运行，以便测试控制台发出的连接。  
                     在服务器定义中启用 SSL  
                     该控制台使用服务器定义连接至代理程序。  
                     对于连接至启用了 SSL 的代理程序的每个服务器定义，执行以下操作：  
                        在控制台中，转至 服务器 面板。  
                        单击服务器定义名称。  
                        在服务器定义的 详细信息 选项卡中：  
                        将 启用 SSL 设置为“是”。  
                        单击 保存 。  
                        单击 测试连接 。  
                         
   **三 对与代理程序的 SSL 通信进行故障诊断**  
          **3.1 以下核对表描述了启用 SSL 时的常见问题** ：  
           **A代理程序**  
               （a）尽管在安全性和服务器定义中启用了 SSL，但是未配置代理程序 SSL。  
               （b）Build Forge 引擎不信任代理程序的证书。该代理程序证书需要添加至该引擎的 CA 密钥库：<bfinstall>/keystore/buildForgeCA.pem  
               （c）BFAgent.conf 中指定的密钥库密码不正确。  
               （d）在 BFAgent.conf 中指定了客户机认证，但引擎的证书尚未添加至代理程序的认证中心buildForgeCA.pem。  
            **B Build Forge 控制台**  
                       在控制台上启用了 SSL。它尚未保存，或在保存之前单击了 更新主 Bfclient.conf ，或在保存之后从未单击 更新主 Bfclient.conf 。

**C 服务器定义**

未成功启用 SSL。必须单击 保存 ，然后单击 测试连接 。

**D  引擎和代理程序设置相匹配**

握手协议不匹配。引擎 SSL 配置和代理程序 SSL 配置的握手协议必须设置为相同的值：TLSv1 或 SSLv3。缺省值为 TLSv1。  
                    密码套件不匹配。在引擎 SSL 配置和代理程序 SSL 配置中指定的密码套件必须具有公共的密码。缺省的密码套件组ALL。                     
 **      3.2启用调试消息**  
            可以在引擎和代理程序中启用调试。启用调试后，将产生更多的详细输出，这些输出有助于识别配置中的问题。  
              **启用引擎调试：**  
                 1. 在启用了 SSL 的服务器定义所用的环境中，添加以下变量：  
                       BFDEBUG\_SECURITY=1  
                 2. 停止引擎，并重新启动该引擎。  
                       在 Windows 上，请在前台启动引擎。输出将显示在命令窗口中。  
                       在 UNIX 或 Linux 上，请在打开调试的前提下启动引擎：  
                      cd <bfinstall>/rc  
                      ./buildforge start  
                     引擎的输出将转至 <bfinstall>/log 中的引擎日志文件。  
        **     启用代理程序调试：**  
                 1. 停止代理程序。  
                 2. 将下行添加至 BFAgent.conf：  
                     activity\_log bfagent.log  
                     在本示例中，代理程序将输出写入 bfagent.log 中。 可以指定不同的文件名。                       
                     注意 如果代理程序作为服务运行，指定绝对路径。  
                 3. 启动代理程序。     
           **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 : 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 errorerror: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\_password\_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 对象时出现问题。该错误可能是内部错误。