SSL 配置屬性
SSL 配置中所包含的屬性,可用來控制 Liberty 上伺服器 SSL 傳輸層的行為。這個主題疊代 SSL 配置所有可用的設定。
SSL 特性
如果要在伺服器上啟用 SSL,SSL 特性必須包含在 server.xml 檔中:
<featureManager>
<feature>ssl-1.0</feature>
</featureManager>
SSL 預設值
您可以配置多重 SSL 配置。 如果配置了多項 SSL 配置,必須在使用 sslDefault 服務配置的 server.xml 檔中,指定預設 SSL 配置。
屬性 | 說明 | 預設值 |
---|---|---|
sslRef | sslRef 屬性指定用來作為預設值的 SSL 配置名稱。 | 預設「SSL 配置」名稱是 defaultSSLConfig。 |
在 server.xml 檔中,項目如下:
<sslDefault sslRef="mySSLSettings" />
SSL 配置
您利用 SSL 配置屬性,自訂 SSL 環境來配合您的需求。 server.xml 檔中的 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。 |
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 檔的金鑰儲存庫服務配置中。
屬性 | 說明 | 預設值 |
---|---|---|
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 屬性設為 polled 或 mbean,伺服器可重新載入金鑰儲存庫檔。如果啟用 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
<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=" />