SSL

Spring Boot 提供了配置 SSL 信任材料的能力，該材料可應用於多種型別的連線以支援安全通訊。使用字首為 spring.ssl.bundle 的配置屬性可以指定命名的信任材料集和相關資訊。

使用 Java KeyStore 檔案配置 SSL

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

當用於保護嵌入式 Web 伺服器時，keystore 通常配置為包含證書和私鑰的 Java 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"

當用於保護客戶端連線時，truststore 通常配置為包含伺服器證書的 Java KeyStore，如本例所示

  • 屬性

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

除了檔案位置，還可以提供其Base64 編碼的內容。如果選擇此選項，屬性值應以 base64: 開頭。

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

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

使用 PEM 編碼證書配置 SSL

使用字首為 spring.ssl.bundle.pem 的配置屬性可以配置 PEM 編碼文字形式的信任材料捆綁包。每個捆綁包都有一個使用者提供的名稱，可用於引用該捆綁包。

當用於保護嵌入式 Web 伺服器時，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"

除了檔案位置，還可以提供其Base64 編碼的內容。如果選擇此選項，屬性值應以 base64: 開頭。

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

以下示例顯示瞭如何定義 truststore 證書

  • 屬性

  • YAML

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

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

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

應用 SSL 捆綁包

使用屬性配置後，可以在 Spring Boot 自動配置的各種型別連線的配置屬性中按名稱引用 SSL 捆綁包。有關更多資訊，請參閱關於嵌入式 Web 伺服器、資料技術和REST 客戶端的部分。

使用 SSL 捆綁包

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

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

此外，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 Web 伺服器

  • Netty Web 伺服器

要啟用重新載入，您需要透過配置屬性進行選擇，如本例所示

  • 屬性

  • 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 屬性配置檔案監視器的靜默期（以確保不再有更改）。