SSL 配置屬性

SSL 配置中所包含的屬性,可用來控制 Liberty 上伺服器 SSL 傳輸層的行為。這個主題疊代 SSL 配置所有可用的設定。

SSL 特性

如果要在伺服器上啟用 SSL,SSL 特性必須包含在 server.xml 檔中:

<featureManager>
  <feature>ssl-1.0</feature>
</featureManager>

SSL 預設值

您可以配置多重 SSL 配置。 如果配置了多項 SSL 配置,必須在使用 sslDefault 服務配置的 server.xml 檔中,指定預設 SSL 配置。

表 1. sslDefault 元素的屬性. 這份表格說明 sslDefault 元素的屬性。
屬性 說明 預設值
sslRef sslRef 屬性指定用來作為預設值的 SSL 配置名稱。 預設「SSL 配置」名稱是 defaultSSLConfig
server.xml 檔中,項目如下:
<sslDefault sslRef="mySSLSettings" />

SSL 配置

您利用 SSL 配置屬性,自訂 SSL 環境來配合您的需求。 server.xml 檔中的 ssl 服務配置元素可以設定這些屬性。

表 2. SSL 元素的屬性. 這份表格說明 ssl 元素的屬性。
屬性 說明 預設值
id id 屬性將唯一名稱指派給 SSL 配置物件。 沒有預設值;必須指定唯一名稱。
keyStoreRef keyStoreRef 屬性指定定義 SSL 配置金鑰儲存庫之金鑰儲存庫服務物件的名稱。 這個金鑰儲存庫用來存放建立 SSL 連線所需要的金鑰。 沒有預設值;必須指定金鑰儲存庫參照。
trustStoreRef trustStoreRef 屬性指定定義 SSL 配置信任儲存庫之金鑰儲存庫服務物件的名稱。 信任儲存庫用來存放簽署驗證所需要的憑證。 trustStoreRef 是一個選用的屬性。 如果遺漏這個參照,就會使用 keyStoreRef 所指定的金鑰儲存庫。
clientAuthentication clientAuthentication 屬性決定了是否需要 SSL 用戶端鑑別。 預設值為 false
clientAuthenticationSupported clientAuthenticationSupported 屬性決定了是否支援 SSL 用戶端鑑別。 用戶端不需要供應用戶端憑證。 如果 clientAuthentication 屬性設為 true,會改寫 clientAuthenticationSupported 屬性值。 預設值為 false
sslProtocol sslProtocol 屬性定義 SSL 信號交換通訊協定。 這個通訊協定有可能相依於 SDK,因此,如果您修改通訊協定,請確定您在執行的 SDK 支援這個值。 預設值是 SSL_TLSv2(若為 IBM® JRE)和 SSL(若為 Oracle JRE)。
securityLevel securityLevel 屬性決定了 SSL 信號交換所用的密碼組合群組。 這個屬性有下列其中一個值:
  • HIGH(128 位元密碼及以上)
  • MEDIUM(40 位元密碼)
  • WEAK(所有無加密的密碼)
  • CUSTOM(如果密碼組合群組是自訂的)
當您利用特定的密碼清單來設定 enabledCiphers 屬性時,系統會忽略這個屬性。
預設值為 HIGH
enabledCiphers enabledCiphers 屬性用來指定唯一的密碼組合清單。 請利用空格來區隔清單中的各個密碼組合。 如果設定 enabledCiphers 屬性,就會忽略 securityLevel 屬性。 沒有預設值。
serverKeyAlias serverKeyAlias 屬性指定金鑰儲存庫中用來作為 SSL 配置金鑰的金鑰名稱。 只有在金鑰儲存庫中有多個金鑰項目時,才需要這個屬性。 如果金鑰儲存庫有多個金鑰項目,且這個屬性沒有指定金鑰,JSSE 會挑選一個金鑰。 沒有預設值。
clientKeyAlias clientKeyAlias 屬性指定在啟用 clientAuthentication 時,金鑰儲存庫中用來作為 SSL 配置金鑰的金鑰名稱。 只有在金鑰儲存庫含有多個金鑰項目時,才需要這個屬性。 沒有預設值。
註:
  • SSL 信號交換利用金鑰管理程式來判斷要用的憑證別名。 金鑰管理程式未配置在 server.xml 檔中。會從 SDK 的安全內容 ssl.KeyManagerFactory.algorithm 擷取它。
  • SSL 信號交換利用信任管理程式來做信任決策。信任管理程式未配置在 server.xml 檔中。會從 SDK 的安全內容 ssl.TrustManagerFactory.algorithm 擷取它。
以下是如何在 server.xml 檔中配置 ssl 元素的範例:
<!--  Simple ssl configuration service object. This assumes there is a keystore object named -->
<!--  defaultKeyStore and a truststore object named defaultTrustStore in the server.xml file. -->
  <ssl id="myDefaultSSLConfig"
       keyStoreRef="defaultKeyStore"
       trustStoreRef="defaultTrustStore" />


<!--  A ssl configuration service object that enabled clientAuthentication -->
<!--  and specifies the TLS protocol be used. -->
  <ssl id="myDefaultSSLConfig"
       keyStoreRef="defaultKeyStore"
       trustStoreRef="defaultTrustStore"
       clientAuthentication="true"
       sslProtocol="TLS" />

<!-- An SSL configuration service object that names the serverKeyAlias -->
<!-- to be used by the handshake. This assumes there is a certificate -->
<!-- called "default" in the keystore defined by keyStoreRef. -->
  <ssl id="myDefaultSSLConfig"
       keyStoreRef="defaultKeyStore"
       serverKeyAlias="default" />

金鑰儲存庫配置

keystore 配置由載入金鑰儲存庫所需要的屬性組成。這些屬性可設在 server.xml 檔的金鑰儲存庫服務配置中。

表 3. 金鑰儲存庫元素的屬性. 這份表格說明 keystore 元素的屬性。
屬性 說明 預設值
id id 屬性定義金鑰儲存庫物件的唯一 ID。 沒有預設值,必須指定唯一名稱。
location location 屬性指定金鑰儲存庫檔的名稱。 這個值可以包括檔案的絕對路徑。 如果未提供絕對路徑,程式碼會在 ${server.output.dir}/resources/security 目錄中尋找檔案。 SSL 最低配置中,檔案的位置假設為 ${server.output.dir}/resources/security
type type 屬性指定金鑰儲存庫的類型。 請確認您在執行的 SDK 支援您指定的金鑰儲存庫類型。 預設值為 jks
password password 屬性指定用來載入金鑰儲存庫檔的密碼。密碼可以用明碼或編碼的方式來儲存。 如需密碼如何編碼的相關資訊,請參閱 securityUtility encode 選項。 必須提供。
provider provider 屬性指定用來載入金鑰儲存庫的提供者。 部分金鑰儲存庫類型需要 SDK 預設值以外的提供者。 依預設,不會指定提供者。
fileBased fileBased 屬性指定金鑰儲存庫是否為檔案型。 預設值為 true
pollingRate 伺服器檢查金鑰儲存庫檔是否有更新項目的頻率。 500ms.
updateTrigger 此方法用來觸發伺服器,以重新載入金鑰儲存庫檔。請指定 polled,讓伺服器檢查金鑰儲存庫檔的變更,指定 mbean,讓伺服器等待 mbean 重新載入金鑰儲存庫檔,或是指定 disabled,停用檔案監視。 disabled

如果 updateTrigger 屬性設為 polledmbean,伺服器可重新載入金鑰儲存庫檔。如果啟用 polled,伺服器會根據 pollingRate 屬性所設定的頻率,來監視金鑰儲存庫檔的變更。如果 updateTrigger 屬性設為 mbean,當伺服器收到 WebSphere:service=com.ibm.ws.kernel.filemonitor.FileNotificationMBean MBean 的通知時,會重新載入金鑰儲存庫檔。依預設,會停用檔案監視。

以下是如何在 server.xml 檔中配置 keystore 元素的範例:
<!-- A keystore object called defaultKeyStore provides a location, -->
<!-- type, and password. The MyKeyStoreFile.jks file is assumed -->
<!-- to be located in ${server.output.dir}/resources/security -->
<!-- This keystore is configured to be monitored every 5 seconds -->
<!-- for updates -->
   <keyStore id="defaultKeyStore"
           location="MyKeyStoreFile.jks"
           type="JKS" password="myPassword" 
           pollingRate="5s" 
           updateTrigger="polled" />

<!-- A keystore object called defaultKeyStore provides a location, -->
<!-- type, and password. The MyKeyStoreFile.jks file is assumed -->
<!-- to be located in ${server.output.dir}/resources/security -->
<!-- This keystore is configured to be reloaded when the server -->
<!-- recieves an mbean notification to do so -->
   <keyStore id="defaultKeyStore"
           location="MyKeyStoreFile.jks"
           type="JKS" password="myPassword" 
           updateTrigger="mbean" />

如果您沒有設定 server.output.dir 目錄,則 server.output.dir 目錄與 server.config.dir 目錄相同。

完整 SSL 配置範例

以下是 server.xml 檔中完整 SSL 配置的範例。 這個範例有下列 SSL 配置:
  • defaultSSLSettings
  • mySSLSettings
依預設,SSL 配置會設為 defaultSSLConfig
<featureManager>
  <feature>ssl-1.0</feature>
</featureManager>


<!-- default SSL configuration is defaultSSLSettings ->
  <sslDefault sslRef="defaultSSLSettings" />
  <ssl id="defaultSSLSettings"
       keyStoreRef="defaultKeyStore"
       trustStoreRef="defaultTrustStore"
       clientAuthenticationSupported="true" />
  <keyStore id="defaultKeyStore"
            location="key.jks"
            type="JKS" password="defaultPWD" />
  <keyStore id="defaultTrustStore"
            location="trust.jks"
            type="JKS" password="defaultPWD" />

  <ssl id="mySSLSettings"
       keyStoreRef="myKeyStore"
       trustStoreRef="myTrustStore"
       clientAuthentication="true" />
  <keyStore id="LDAPKeyStore"
            location="${server.config.dir}/myKey.p12"
            type="PKCS12"
            password="{xor}CDo9Hgw=" />
  <keyStore id="LDAPTrustStore"
            location="${server.config.dir}/myTrust.p12"
            type="PKCS12"
            password="{xor}CDo9Hgw=" />

指示主題類型的圖示 參照主題

檔名:rwlp_ssl.html