Spring Boot SSL中文文档

本文为官方文档直译版本。原文链接

Spring Boot SSL中文文档

• • 引言
  • [使用 Java KeyStore 文件配置 SSL](#使用 Java KeyStore 文件配置 SSL)
  • [使用 PEM 编码证书配置 SSL](#使用 PEM 编码证书配置 SSL)
  • [应用 SSL Bundles](#应用 SSL Bundles)
  • [使用 SSL Bundles](#使用 SSL Bundles)
  • [重新加载 SSL Bundles](#重新加载 SSL Bundles)

引言

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

使用 Java KeyStore 文件配置 SSL

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

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

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

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

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

请参阅 JksSslBundleProperties 了解支持的全部属性。

使用 PEM 编码证书配置 SSL

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

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

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

用于保护客户端连接安全时，truststore通常与服务器证书一起配置，如本示例所示：

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

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

请参阅 PemSslBundleProperties，了解支持的全部属性。

应用 SSL Bundles

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

使用 SSL Bundles

Spring Boot 会自动配置一个 SslBundles 类型的 Bean，该 Bean 可访问使用 spring.ssl.bundle 属性配置的每个已命名的Bundles。

可以从自动配置的 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 的过程：

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
    }

}

重新加载 SSL Bundles

当密钥材料发生变化时，可以重新加载 SSL Bundles。使用Bundles的组件必须与可重新加载的 SSL Bundles兼容。目前兼容的组件有

• Tomcat 网络服务器
• Netty 网络服务器

如本示例所示，要启用重载，需要通过配置属性进行选择：

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

然后，文件监视器会监视这些文件，如果它们发生变化，SSL Bundles就会重新加载。这反过来又会触发消费组件的重新加载，例如 Tomcat 会轮换启用 SSL 的连接器中的证书。

你可以使用 spring.ssl.bundle.watch.file.quiet-period 属性配置文件监视器的静默期（以确保不再发生变化）。