跳到主要内容

SSL

DeepSeek V3 中英对照 SSL

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

使用 Java KeyStore 文件配置 SSL​

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

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

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
properties

当用于保护客户端连接时，truststore 通常配置为包含服务器证书的 Java KeyStore，如下例所示：

spring.ssl.bundle.jks.mybundle.truststore.location=classpath:server.p12
spring.ssl.bundle.jks.mybundle.truststore.password=secret
properties
提示

除了文件的位置外，还可以提供其 Base64 编码的内容。如果选择此选项，属性的值应以 base64: 开头。

请参阅 JksSslBundleProperties 以获取完整的支持属性列表。

备注

如果您使用环境变量来配置 bundle，bundle 的名称将始终转换为小写。

使用 PEM 编码的证书配置 SSL​

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

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

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

当用于保护客户端连接时，truststore 通常会配置服务器证书，如以下示例所示：

spring.ssl.bundle.pem.mybundle.truststore.certificate=classpath:server.crt
properties
提示

除了提供文件路径外，还可以提供文件的 Base64 编码内容。如果选择此选项，属性的值应以 base64: 开头。

PEM 内容也可以直接用于 certificate 和 private-key 属性。如果属性值包含 BEGIN 和 END 标记，则它们将被视为 PEM 内容，而不是资源路径。

以下示例展示了如何定义信任库证书：

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

完整支持的属性集请参见 PemSslBundleProperties。

备注

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

应用 SSL 捆绑包​

一旦通过属性配置完成，SSL 包就可以在由 Spring Boot 自动配置的各种类型连接的配置属性中通过名称引用。有关更多信息，请参阅 嵌入式 Web 服务器、数据技术 和 REST 客户端 部分。

使用 SSL 捆绑包​

Spring Boot 自动配置了一个类型为 SslBundles 的 bean，它提供了对使用 spring.ssl.bundle 属性配置的每个命名 bundle 的访问。

SslBundle 可以从自动配置的 SslBundles bean 中获取，并用于创建用于在客户端库中配置 SSL 连接的对象。SslBundle 提供了一种分层的机制来获取这些 SSL 对象：

此外，SslBundle 提供了关于所使用的密钥、要使用的协议以及应应用于 SSL 引擎的任何选项的详细信息。

以下示例展示了如何检索 SslBundle 并使用它来创建 SSLContext：

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
    }

}
java

重新加载 SSL 包​

当密钥材料发生变化时，SSL 捆绑包可以重新加载。使用该捆绑包的组件必须与可重新加载的 SSL 捆绑包兼容。目前以下组件是兼容的：

  • Tomcat Web 服务器

  • Netty Web 服务器

要启用重新加载功能，您需要通过配置属性进行选择加入，如下例所示：

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
properties

文件监视器会持续监控这些文件，一旦它们发生变化，SSL 证书包将会被重新加载。这进而会触发使用该证书的组件进行重新加载，例如，Tomcat 会在启用了 SSL 的连接器中轮换证书。

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