SSL（安全套接字层）

Spring Boot 提供了配置 SSL 信任材料的的能力，可应用于多种类型的连接，以支持安全通信。 以 spring.ssl.bundle 为前缀的配置属性可用于指定命名的信任材料集合及相关信息。

使用 Java KeyStore 文件配置 SSL

以 spring.ssl.bundle.jks 为前缀的配置属性可用于配置通过 Java keytool 工具创建并存储于 JKS 或 PKCS12 格式 Java KeyStore 文件中的信任材料包。 每个包都有一个用户自定义的名称，可用于引用该包。

当用于保护嵌入式 Web 服务器时，通常会配置一个包含证书和私钥的 Java KeyStore，如下示例所示：

  • Properties

  • 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，如下示例所示：

  • Properties

  • 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 获取全部支持的属性。

如果你使用环境变量配置 bundle，bundle 的名称会被 始终转换为小写。

使用 PEM 编码证书配置 SSL

以 spring.ssl.bundle.pem 为前缀的配置属性可用于配置 PEM 编码文本形式的信任材料包。 每个包都有一个用户自定义的名称，可用于引用该包。

当用于保护嵌入式 Web 服务器时，通常会配置一个包含证书和私钥的 keystore，如下示例所示：

  • Properties

  • 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，如下示例所示：

  • Properties

  • 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 证书：

  • Properties

  • 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 获取全部支持的属性。

如果你使用环境变量配置 bundle，bundle 的名称会被 始终转换为小写。

应用 SSL Bundle

通过属性配置后，SSL bundle 可在 Spring Boot 自动配置的多种连接类型的配置属性中按名称引用。 更多信息请参见 嵌入式 Web 服务器、数据技术 和 REST 客户端 相关章节。

使用 SSL Bundle

Spring Boot 会自动配置一个类型为 SslBundles 的 bean，用于访问通过 spring.ssl.bundle 属性配置的每个命名 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 Bundle 热加载

当密钥材料发生变化时，SSL bundle 可以被重新加载。 消费该 bundle 的组件必须兼容可热加载的 SSL bundle。 当前支持的组件有：

  • Tomcat Web 服务器

  • Netty Web 服务器

要启用热加载，需要通过如下配置属性进行设置：

  • Properties

  • 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 bundle 会被重新加载。 这会进一步触发消费组件的重载，例如 Tomcat 会轮换 SSL 启用连接器中的证书。

你可以通过 spring.ssl.bundle.watch.file.quiet-period 属性配置文件监视器的静默期（确保没有更多变更）。