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
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:
-
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=PKCS12spring:
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:
-
Properties
-
YAML
spring.ssl.bundle.jks.mybundle.truststore.location=classpath:server.p12
spring.ssl.bundle.jks.mybundle.truststore.password=secretspring:
ssl:
bundle:
jks:
mybundle:
truststore:
location: "classpath:server.p12"
password: "secret"See JksSslBundleProperties for the full set of supported properties.
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:
-
Properties
-
YAML
spring.ssl.bundle.pem.mybundle.keystore.certificate=classpath:application.crt
spring.ssl.bundle.pem.mybundle.keystore.private-key=classpath:application.keyspring:
ssl:
bundle:
pem:
mybundle:
keystore:
certificate: "classpath:application.crt"
private-key: "classpath:application.key"When used to secure a client-side connection, a truststore is typically configured with the server certificate as shown in this example:
-
Properties
-
YAML
spring.ssl.bundle.pem.mybundle.truststore.certificate=classpath:server.crtspring:
ssl:
bundle:
pem:
mybundle:
truststore:
certificate: "classpath:server.crt"|
PEM content can be used directly for both the The following example shows how a truststore certificate can be defined:
|
See PemSslBundleProperties for the full set of supported properties.
|
PEM content can be used directly for both the The following example shows how a truststore certificate can be defined:
|
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 embedded web servers, data technologies, and REST clients for further information.
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 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 storejava.security.KeyStoreinstances as well as any required key store password. -
getManagers()provides access to thejava.net.ssl.KeyManagerFactoryandjava.net.ssl.TrustManagerFactoryinstances as well as thejava.net.ssl.KeyManagerandjava.net.ssl.TrustManagerarrays that they create. -
createSslContext()provides a convenient way to obtain a newjava.net.ssl.SSLContextinstance.
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.
The following example shows retrieving an SslBundle and using it to create an 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
}
}Reloading SSL bundles
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:
-
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.keyspring:
ssl:
bundle:
pem:
mybundle:
reload-on-update: true
keystore:
certificate: "file:/some/directory/application.crt"
private-key: "file:/some/directory/application.key"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.
You can configure the quiet period (to make sure that there are no more changes) of the file watcher with the spring.ssl.bundle.watch.file.quiet-period property.