From a03f857059758c67ba734e3e39638b4c0c993117 Mon Sep 17 00:00:00 2001 From: Scott Frederick Date: Thu, 20 Apr 2023 22:03:58 -0700 Subject: [PATCH] Document update SSL support Add a new SSL section to the reference documentation to describe SSL bundles. See gh-34814 --- .../src/docs/asciidoc/features.adoc | 2 + .../src/docs/asciidoc/features/ssl.adoc | 99 +++++++++++++++++++ .../src/docs/asciidoc/howto/webserver.adoc | 10 ++ .../features/ssl/bundles/MyComponent.java | 35 +++++++ 4 files changed, 146 insertions(+) create mode 100644 spring-boot-project/spring-boot-docs/src/docs/asciidoc/features/ssl.adoc create mode 100644 spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/features/ssl/bundles/MyComponent.java diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/features.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/features.adoc index d42c2951d2..2f75b39902 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/features.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/features.adoc @@ -30,4 +30,6 @@ include::features/developing-auto-configuration.adoc[] include::features/kotlin.adoc[] +include::features/ssl.adoc[] + include::features/whats-next.adoc[] diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/features/ssl.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/features/ssl.adoc new file mode 100644 index 0000000000..de53ec48de --- /dev/null +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/features/ssl.adoc @@ -0,0 +1,99 @@ +[[features.ssl]] +== SSL +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. + + + +[[features.ssl.jks]] +=== Configuring SSL With Java KeyStore Files +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. + +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: + +[source,yaml,indent=0,subs="verbatim",configblocks] +---- + spring: + ssl: + bundle: + jks: + mybundle: + key: + alias: "application" + keystore: + location: "classpath:application.p12" + password: "secret" + type: "PKCS12" +---- + +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: + +[source,yaml,indent=0,subs="verbatim",configblocks] +---- + spring: + ssl: + bundle: + jks: + mybundle: + truststore: + location: "classpath:server.p12" + password: "secret" +---- + +See {spring-boot-autoconfigure-module-code}/ssl/JksSslBundleProperties.java[JksSslBundleProperties] for the full set of supported properties. + + + +[[features.ssl.pem]] +=== Configuring SSL With PEM-encoded Certificates +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. + +When used to secure an embedded web server, a `keystore` is typically configured with a certificate and private key as shown in this example: + +[source,yaml,indent=0,subs="verbatim",configblocks] +---- + spring: + ssl: + bundle: + pem: + mybundle: + keystore: + certificate: "classpath:application.crt" + private-key: "classpath:application.key" +---- + +When used to secure an embedded web server, a `truststore` is typically configured with the server certificate as shown in this example: + +[source,yaml,indent=0,subs="verbatim",configblocks] +---- + spring: + ssl: + bundle: + pem: + mybundle: + truststore: + certificate: "classpath:server.crt" +---- + +See {spring-boot-autoconfigure-module-code}/ssl/PemSslBundleProperties.java[PemSslBundleProperties] for the full set of supported properties. + + + +[[features.ssl.applying]] +=== Applying SSL Bundles +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 <> and <> for further information. + + + +[[features.ssl.bundles]] +=== Using SSL Bundles +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. +An `SslBundle` can be retrieved from the auto-configured `SslBundles` bean and used to create a `javax.net.ssl.SSLContext` or objects of other types from the `java.net.ssl` package that are typically used to configure SSL connectivity in other APIs. + +The following example shows retrieving an `SslBundle` and using it to create an `SSLContext`: + +include::code:MyComponent[] + diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/howto/webserver.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/howto/webserver.adoc index b012866c03..19d7625cf2 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/howto/webserver.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/howto/webserver.adoc @@ -207,6 +207,16 @@ The following example shows setting SSL properties using PEM-encoded certificate trust-certificate: "classpath:ca-cert.crt" ---- +Alternatively, the SSL trust material can be configured in an <> and applied to the web server as shown in this example: + +[source,yaml,indent=0,subs="verbatim",configprops,configblocks] +---- + server: + port: 8443 + ssl: + bundle: "example" +---- + See {spring-boot-module-code}/web/server/Ssl.java[`Ssl`] for details of all of the supported properties. Using configuration such as the preceding example means the application no longer supports a plain HTTP connector at port 8080. diff --git a/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/features/ssl/bundles/MyComponent.java b/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/features/ssl/bundles/MyComponent.java new file mode 100644 index 0000000000..a7e99fdbb3 --- /dev/null +++ b/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/features/ssl/bundles/MyComponent.java @@ -0,0 +1,35 @@ +/* + * Copyright 2012-2019 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.springframework.boot.docs.features.ssl.bundles; + +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 { + + @SuppressWarnings("unused") + public MyComponent(SslBundles sslBundles) { + SslBundle sslBundle = sslBundles.getBundle("mybundle"); + SSLContext sslContext = sslBundle.createSslContext(); + // do something with the created sslContext + } + +}