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

[configprops,yaml]
----
    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:

[configprops,yaml]
----
    spring:
      ssl:
        bundle:
          jks:
            mybundle:
              truststore:
                location: "classpath:server.p12"
                password: "secret"
----

[TIP]
====
Rather than the location to a file, its Base64 encoded content can be provided.
If you chose this option, the value of the property should start with `base64:`.
====

See javadoc:org.springframework.boot.autoconfigure.ssl.JksSslBundleProperties[] for the full set of supported properties.

NOTE: If you're using environment variables to configure the bundle, the name of the bundle is xref:features/external-config.adoc#features.external-config.typesafe-configuration-properties.relaxed-binding.maps-from-environment-variables[always converted to lowercase].



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

[configprops,yaml]
----
    spring:
      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:

[configprops,yaml]
----
    spring:
      ssl:
        bundle:
          pem:
            mybundle:
              truststore:
                certificate: "classpath:server.crt"
----

[TIP]
====
Rather than the location to a file, its Base64 encoded content can be provided.
If you chose this option, the value of the property should start with `base64:`.

PEM content can also 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:

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

See javadoc:org.springframework.boot.autoconfigure.ssl.PemSslBundleProperties[] for the full set of supported properties.

NOTE: If you're using environment variables to configure the bundle, the name of the bundle is xref:features/external-config.adoc#features.external-config.typesafe-configuration-properties.relaxed-binding.maps-from-environment-variables[always converted to lowercase].



[[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 xref:how-to:webserver.adoc#howto.webserver.configure-ssl[embedded web servers], xref:data/index.adoc[data technologies], and xref:io/rest-client.adoc[REST clients] for further information.



[[features.ssl.bundles]]
== Using SSL Bundles

Spring Boot auto-configures a bean of type javadoc:org.springframework.boot.ssl.SslBundles[] that provides access to each of the named bundles configured using the `spring.ssl.bundle` properties.

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

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

In addition, the javadoc:org.springframework.boot.ssl.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 javadoc:org.springframework.boot.ssl.SslBundle[] and using it to create an javadoc:javax.net.ssl.SSLContext[]:

include-code::MyComponent[]



[[features.ssl.reloading]]
== 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:

[configprops,yaml]
----
    spring:
      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 configprop:spring.ssl.bundle.watch.file.quiet-period[] property.
