SSL

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

Spring Boot provides the ability to configure SSL trust material that can be applied to several types of connections in order to support secure communications. Configuration properties with the prefix spring.ssl.bundle can be used to specify named sets of trust material and associated information.

Configuring SSL With Java KeyStore Files

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

Configuration properties with the prefix spring.ssl.bundle.jks can be used to configure bundles of trust material created with the Java keytool utility and stored in Java KeyStore files in the JKS or PKCS12 format. Each bundle has a user-provided name that can be used to reference the bundle.

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

When used to secure an embedded web server, a keystore is typically configured with a Java KeyStore containing a certificate and private key as shown in this example:

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

当用于保护客户端连接时，通常会使用包含服务器证书的 Java 密钥库配置一个 truststore，如下例所示：

When used to secure a client-side connection, a truststore is typically configured with a Java KeyStore containing the server certificate as shown in this example:

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

请参阅 {code-spring-boot-autoconfigure-src}/ssl/JksSslBundleProperties.java[JksSslBundleProperties] 了解受支持属性的完整集。

See {code-spring-boot-autoconfigure-src}/ssl/JksSslBundleProperties.java[JksSslBundleProperties] for the full set of supported properties.

Configuring SSL With PEM-encoded Certificates

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

Configuration properties with the prefix spring.ssl.bundle.pem can be used to configure bundles of trust material in the form of PEM-encoded text. Each bundle has a user-provided name that can be used to reference the bundle.

当用于保护嵌入式 Web 服务器时，通常会按照以下示例使用证书和私钥配置一个 keystore：

When used to secure an embedded web server, a keystore is typically configured with a certificate and private key as shown in this example:

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

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

When used to secure a client-side connection, a truststore is typically configured with the server certificate as shown in this example:

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

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

PEM content can be used directly for both the certificate and private-key properties. If the property values contain BEGIN and END markers then they will be treated as PEM content rather than a resource location.

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

The following example shows how a truststore certificate can be defined:

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

请参阅 {code-spring-boot-autoconfigure-src}/ssl/PemSslBundleProperties.java[PemSslBundleProperties] 获取受支持的全部属性。

See {code-spring-boot-autoconfigure-src}/ssl/PemSslBundleProperties.java[PemSslBundleProperties] for the full set of supported properties.

Applying SSL Bundles

一旦使用属性进行配置，SSL 捆绑包可以在由 Spring Boot 自动配置的各种连接类型的配置属性中通过名称进行引用。有关更多信息，请参阅 embedded web servers、data technologies 和 REST clients 部分。

Once configured using properties, SSL bundles can be referred to by name in configuration properties for various types of connections that are auto-configured by Spring Boot. See the sections on embedded web servers, data technologies, and REST clients for further information.

Using SSL Bundles

Spring Boot 自动配置一个 SslBundles 类型的 bean，可以访问通过 spring.ssl.bundle 属性配置的每个已命名捆绑包。

Spring Boot auto-configures a bean of type SslBundles that provides access to each of the named bundles configured using the spring.ssl.bundle properties.

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

An SslBundle can be retrieved from the auto-configured SslBundles bean and used to create objects that are used to configure SSL connectivity in client libraries. The SslBundle provides a layered approach of obtaining these SSL objects:

getStores() provides access to the key store and trust store java.security.KeyStore instances as well as any required key store password.
getManagers() provides access to the java.net.ssl.KeyManagerFactory and java.net.ssl.TrustManagerFactory instances as well as the java.net.ssl.KeyManager and java.net.ssl.TrustManager arrays that they create.
createSslContext() provides a convenient way to obtain a new java.net.ssl.SSLContext instance.

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

In addition, the SslBundle provides details about the key being used, the protocol to use and any option that should be applied to the SSL engine.

以下示例显示了如何检索一个 SslBundle 并使用它创建一个 SSLContext：

The following example shows retrieving an SslBundle and using it to create an SSLContext:

Reloading SSL bundles

当密钥资料更改时，SSL 捆绑包可以重新加载。使用捆绑包的组件必须与可重新加载的 SSL 捆绑包兼容。当前与之兼容的组件如下：

SSL bundles can be reloaded when the key material changes. The component consuming the bundle has to be compatible with reloadable SSL bundles. Currently the following components are compatible:

Tomcat web server
Netty web server

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

To enable reloading, you need to opt-in via a configuration property as shown in this example:

    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 的连接器中轮换证书。

A file watcher is then watching the files and if they change, the SSL bundle will be reloaded. This in turn triggers a reload in the consuming component, e.g. Tomcat rotates the certificates in the SSL enabled connectors.

你可以使用 configprop:spring.ssl.bundle.watch.file.quiet-period[] 属性配置文件观察器的静默时间（确保不再发生任何更改）。

You can configure the quiet period (to make sure that there are no more changes) of the file watcher with the configprop:spring.ssl.bundle.watch.file.quiet-period[] property.