SSL

Spring Boot 提供了配置 SSL 信任材料的能力，可以應用於多種類型的連線，以支援安全通訊。帶有前綴 spring.ssl.bundle 的組態屬性可用於指定具名的信任材料集和相關資訊。

使用 Java KeyStore 檔案配置 SSL

帶有前綴 spring.ssl.bundle.jks 的組態屬性可用於配置使用 Java keytool 工具建立並儲存在 JKS 或 PKCS12 格式的 Java KeyStore 檔案中的信任材料捆綁包。每個捆綁包都有一個使用者提供的名稱，可用於參考該捆綁包。

當用於保護嵌入式網路伺服器的安全時，通常會使用包含憑證和私鑰的 Java KeyStore 配置 keystore，如下例所示

  • 屬性

  • YAML

spring.ssl.bundle.jks.mybundle.key.alias=application
spring.ssl.bundle.jks.mybundle.keystore.location=classpath:application.p12
spring.ssl.bundle.jks.mybundle.keystore.password=secret
spring.ssl.bundle.jks.mybundle.keystore.type=PKCS12
spring:
  ssl:
    bundle:
      jks:
        mybundle:
          key:
            alias: "application"
          keystore:
            location: "classpath:application.p12"
            password: "secret"
            type: "PKCS12"

當用於保護客戶端連線的安全時，通常會使用包含伺服器憑證的 Java KeyStore 配置 truststore，如下例所示

  • 屬性

  • YAML

spring.ssl.bundle.jks.mybundle.truststore.location=classpath:server.p12
spring.ssl.bundle.jks.mybundle.truststore.password=secret
spring:
  ssl:
    bundle:
      jks:
        mybundle:
          truststore:
            location: "classpath:server.p12"
            password: "secret"

請參閱 JksSslBundleProperties 以取得完整支援的屬性集。

如果您使用環境變數來配置捆綁包，則捆綁包的名稱始終轉換為小寫。

使用 PEM 編碼憑證配置 SSL

帶有前綴 spring.ssl.bundle.pem 的組態屬性可用於配置 PEM 編碼文字形式的信任材料捆綁包。每個捆綁包都有一個使用者提供的名稱，可用於參考該捆綁包。

當用於保護嵌入式網路伺服器的安全時，通常會使用憑證和私鑰配置 keystore，如下例所示

  • 屬性

  • YAML

spring.ssl.bundle.pem.mybundle.keystore.certificate=classpath:application.crt
spring.ssl.bundle.pem.mybundle.keystore.private-key=classpath:application.key
spring:
  ssl:
    bundle:
      pem:
        mybundle:
          keystore:
            certificate: "classpath:application.crt"
            private-key: "classpath:application.key"

當用於保護客戶端連線的安全時，通常會使用伺服器憑證配置 truststore，如下例所示

  • 屬性

  • YAML

spring.ssl.bundle.pem.mybundle.truststore.certificate=classpath:server.crt
spring:
  ssl:
    bundle:
      pem:
        mybundle:
          truststore:
            certificate: "classpath:server.crt"

PEM 內容可以直接用於 certificate 和 private-key 屬性。如果屬性值包含 BEGIN 和 END 標記，則它們將被視為 PEM 內容，而不是資源位置。

以下範例示範如何定義信任儲存庫憑證

  • 屬性

  • YAML

spring.ssl.bundle.pem.mybundle.truststore.certificate=-----BEGIN CERTIFICATE-----
MIID1zCCAr+gAwIBAgIUNM5QQv8IzVQsgSmmdPQNaqyzWs4wDQYJKoZIhvcNAQEL
BQAwezELMAkGA1UEBhMCWFgxEjAQBgNVBAgMCVN0YXRlTmFtZTERMA8GA1UEBwwI
...
V0IJjcmYjEZbTvpjFKznvaFiOUv+8L7jHQ1/Yf+9c3C8gSjdUfv88m17pqYXd+Ds
HEmfmNNjht130UyjNCITmLVXyy5p35vWmdf95U3uEbJSnNVtXH8qRmN9oK9mUpDb
ngX6JBJI7fw7tXoqWSLHNiBODM88fUlQSho8
-----END CERTIFICATE-----
spring:
  ssl:
    bundle:
      pem:
        mybundle:
          truststore:
            certificate: |
              -----BEGIN CERTIFICATE-----
              MIID1zCCAr+gAwIBAgIUNM5QQv8IzVQsgSmmdPQNaqyzWs4wDQYJKoZIhvcNAQEL
              BQAwezELMAkGA1UEBhMCWFgxEjAQBgNVBAgMCVN0YXRlTmFtZTERMA8GA1UEBwwI
              ...
              V0IJjcmYjEZbTvpjFKznvaFiOUv+8L7jHQ1/Yf+9c3C8gSjdUfv88m17pqYXd+Ds
              HEmfmNNjht130UyjNCITmLVXyy5p35vWmdf95U3uEbJSnNVtXH8qRmN9oK9mUpDb
              ngX6JBJI7fw7tXoqWSLHNiBODM88fUlQSho8
              -----END CERTIFICATE-----

請參閱 PemSslBundleProperties 以取得完整支援的屬性集。

如果您使用環境變數來配置捆綁包，則捆綁包的名稱始終轉換為小寫。

套用 SSL 捆綁包

使用屬性配置後，SSL 捆綁包可以通過名稱在 Spring Boot 自動配置的各種連線類型的組態屬性中引用。有關更多資訊，請參閱關於嵌入式網路伺服器、資料技術和REST 用戶端的章節。

使用 SSL 捆綁包

Spring Boot 自動配置類型為 SslBundles 的 bean，該 bean 提供對使用 spring.ssl.bundle 屬性配置的每個具名捆綁包的訪問。

可以從自動配置的 SslBundles bean 檢索 SslBundle，並用於建立用於在客戶端程式庫中配置 SSL 連線能力的物件。SslBundle 提供了獲取這些 SSL 物件的分層方法

  • getStores() 提供對金鑰儲存庫和信任儲存庫 java.security.KeyStore 實例以及任何所需的金鑰儲存庫密碼的訪問。

  • getManagers() 提供對 java.net.ssl.KeyManagerFactory 和 java.net.ssl.TrustManagerFactory 實例以及它們建立的 java.net.ssl.KeyManager 和 java.net.ssl.TrustManager 陣列的訪問。

  • createSslContext() 提供了一種獲取新的 java.net.ssl.SSLContext 實例的便捷方法。

此外，SslBundle 還提供有關正在使用的金鑰、要使用的協議以及應應用於 SSL 引擎的任何選項的詳細資訊。

以下範例示範如何檢索 SslBundle 並使用它來建立 SSLContext

  • Java

  • Kotlin

import javax.net.ssl.SSLContext;

import org.springframework.boot.ssl.SslBundle;
import org.springframework.boot.ssl.SslBundles;
import org.springframework.stereotype.Component;

@Component
public class MyComponent {

	public MyComponent(SslBundles sslBundles) {
		SslBundle sslBundle = sslBundles.getBundle("mybundle");
		SSLContext sslContext = sslBundle.createSslContext();
		// do something with the created sslContext
	}

}
import org.springframework.boot.ssl.SslBundles
import org.springframework.stereotype.Component

@Component
class MyComponent(sslBundles: SslBundles) {

    init {
        val sslBundle = sslBundles.getBundle("mybundle")
        val sslContext = sslBundle.createSslContext()
        // do something with the created sslContext
    }

}

重新載入 SSL 捆綁包

當金鑰材料變更時，可以重新載入 SSL 捆綁包。使用捆綁包的組件必須與可重新載入的 SSL 捆綁包相容。目前，以下組件相容

  • Tomcat 網路伺服器

  • Netty 網路伺服器

要啟用重新載入，您需要通過組態屬性選擇加入，如下例所示

  • 屬性

  • YAML

spring.ssl.bundle.pem.mybundle.reload-on-update=true
spring.ssl.bundle.pem.mybundle.keystore.certificate=file:/some/directory/application.crt
spring.ssl.bundle.pem.mybundle.keystore.private-key=file:/some/directory/application.key
spring:
  ssl:
    bundle:
      pem:
        mybundle:
          reload-on-update: true
          keystore:
            certificate: "file:/some/directory/application.crt"
            private-key: "file:/some/directory/application.key"

然後，檔案監視器將監視檔案，如果檔案發生變更，則將重新載入 SSL 捆綁包。這反過來觸發使用組件中的重新載入，例如，Tomcat 輪換 SSL 啟用的連接器中的憑證。

您可以使用 spring.ssl.bundle.watch.file.quiet-period 屬性配置檔案監視器的靜默期（以確保不再有變更）。