啟用 SSL 來進行代理程式通訊

依預設,Build Forge 元件會設定為在啟用 SSL 時,使用特定的埠和安全設定。

如果要在 Build Forge 和代理程式之間啟用 SSL 通訊,您需要執行下列動作:

配置代理程式使用 SSL

  1. 如果代理程式在執行中,請將它停止。
  2. 將憑證的 .PEM 檔放在代理程式的安裝根目錄中。

    如果要快速實作並測試 SSL,您可以從 Build Forge 安裝架構複製 .PEM 檔。這些檔案位於 <bfinstall>/keystore 中。

    SSL 的最佳實務是對每一個代理程式使用個別的憑證:

    1. 對下列每一項建立個別的金鑰儲存庫檔 (.PEM):
      • 私密金鑰 (key)
      • 私密金鑰的公開憑證 (cert)
      • 授信簽章者(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
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

代理程式的金鑰儲存庫密碼不正確時的範例輸出

如果配置在代理程式端的金鑰儲存庫密碼是錯誤的,其會顯示在引擎和代理程式輸出中。

引擎輸出(摘錄):


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

代理程式輸出中的錯誤碼

這份清單包含您可能會遇到的一些其他錯誤碼和其原因:


意見