diff --git a/CHANGELOG.md b/CHANGELOG.md index a7fdfd59..e2245f17 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,10 @@ * Check core and provider binary compatibility against the latest stable Maven Central release. * Bump `io.netty:netty-transport-native-kqueue` to 4.2.17.Final to match the Netty version used by gRPC, and fail `check` when the macOS transport modules drift from it. +### Documentation + +* Document `SpiffeProvider.install()` in the provider README, and explain that the JDK loads the providers declared in `java.security` with the system class loader, so a provider packaged inside an application archive, such as a Spring Boot executable jar, must be installed programmatically + ## [0.8.17] - 2026-04-20 ### Fixed diff --git a/java-spiffe-provider/README.md b/java-spiffe-provider/README.md index 8ab9be58..2b523302 100644 --- a/java-spiffe-provider/README.md +++ b/java-spiffe-provider/README.md @@ -69,6 +69,18 @@ In the case of testing the provider in Mac OS, the name of the jar will be `java The `java-spiffe-provider` jar should be on the classpath. +#### Class loading + +The JDK loads the providers listed in the security properties with the system class loader, and silently skips a +provider that it cannot load. A `java-spiffe-provider` jar that is only visible to a class loader created by the +application is therefore not found, for example when it is packaged inside a Spring Boot executable jar (`BOOT-INF/lib`) +or a web application archive (`WEB-INF/lib`). Requesting a `Spiffe` algorithm then fails with errors such as +`java.security.KeyStoreException: Spiffe not found`. In that case, +[install the provider programmatically](#install-the-provider-programmatically). + +To check whether the provider was loaded, start the JVM with `-Djava.security.debug=jca`: the JDK logs an +`Error loading` message for `io.spiffe.provider.SpiffeProvider` when it cannot load it. + ### Extend `java.security` properties file The master security properties file can be extended. Create a file `java.security` with the following content: @@ -87,6 +99,8 @@ ssl.spiffe.accept=spiffe://example.org/workload | spiffe://example.org/workload2 In this `java.security` file: * replace `` following the order of the `# List of Providers` in the master file. +It must be the number that follows the last provider in that list: the JDK stops reading providers at the first +missing number, so a provider declared after a gap is ignored. * replace the value of the custom property `ssl.spiffe.accept` with the SPIFFE IDs of the workloads that are allowed to connect, separated by the pipe character. @@ -135,6 +149,23 @@ The socket endpoint can be configured defining an environment variable named `SP export SPIFFE_ENDPOINT_SOCKET=/tmp/agent.sock ``` +### Install the provider programmatically + +The provider can also be registered at runtime, which works regardless of the class loader that loads the +`java-spiffe-provider` jar: + +``` + SpiffeProvider.install(); +``` + +`SpiffeProvider.install()` adds the provider at the end of the list of providers, unless a provider named `Spiffe` is +already registered, so it can also be used together with the `security.provider.` entry. +Call it during application startup, before any code requests a `Spiffe` `KeyStore`, `KeyManagerFactory` or +`TrustManagerFactory`, for example before an embedded web server configured with the `Spiffe` KeyStore type starts. + +The properties described above, such as `ssl.KeyManagerFactory.algorithm`, `ssl.TrustManagerFactory.algorithm` and +`ssl.spiffe.accept`, are still read when the provider is installed this way. + ## Use Cases ### Connect to Postgres DB using TLS and the SPIFFE SslSocketFactory @@ -169,7 +200,8 @@ If this property is not configured, any SPIFFE ID will be accepted in a TLS conn ### Configure a Tomcat connector -***Prerequisite***: Having the SPIFFE Provider configured through the `java.security`. +***Prerequisite***: Having the SPIFFE Provider configured through the `java.security`, or +[installed programmatically](#install-the-provider-programmatically). A Tomcat TLS connector that uses the `Spiffe` KeyStore can be configured as follows: @@ -185,7 +217,8 @@ A Tomcat TLS connector that uses the `Spiffe` KeyStore can be configured as foll ### Create mTLS GRPC server and client -Prerequisite: Having the SPIFFE Provider configured through the `java.security`. +Prerequisite: Having the SPIFFE Provider configured through the `java.security`, or +[installed programmatically](#install-the-provider-programmatically). A `GRPC Server` using an SSL context backed by the Workload API: diff --git a/java-spiffe-provider/src/main/java/io/spiffe/provider/SpiffeProvider.java b/java-spiffe-provider/src/main/java/io/spiffe/provider/SpiffeProvider.java index 1ef49d90..8b1c7fc4 100644 --- a/java-spiffe-provider/src/main/java/io/spiffe/provider/SpiffeProvider.java +++ b/java-spiffe-provider/src/main/java/io/spiffe/provider/SpiffeProvider.java @@ -24,19 +24,22 @@ *

* To use this Provider, it is needed to add the following lines to the java.security file: *

- *      security.provider.n=io.spiffe.SpiffeProvider
+ *      security.provider.n=io.spiffe.provider.SpiffeProvider
  *      ssl.KeyManagerFactory.algorithm=Spiffe
  *      ssl.TrustManagerFactory.algorithm=Spiffe
  * 
+ * The JDK loads the providers declared in the java.security file with the system class loader. If this class + * is not visible to it, for example because the application loads its libraries with its own class loader, + * register the provider by calling {@link #install()} instead. *

* Also, to configure the accepted SPIFFE IDs, add to the java.security the list of SPIFFE IDs * separated by the pipe character: *

- *      ssl.spiffe.accept=spiffe://example.org/workload1 | spiffe://example.org/workload2,
+ *      ssl.spiffe.accept=spiffe://example.org/workload1 | spiffe://example.org/workload2
  * 
* This property can also be defined as a System parameter passed through -Dssl.spiffe.accept: *
- *      -Dssl.spiffe.accept=ssl.spiffe.accept=spiffe://example.org/workload1 | spiffe://example.org/workload2
+ *      -Dssl.spiffe.accept=spiffe://example.org/workload1 | spiffe://example.org/workload2
  * 
*

* To configure the `TrustManager` to accept any SPIFFE ID presented by a peer, @@ -69,7 +72,12 @@ public SpiffeProvider() { /** - * Installs this provider implementation. + * Installs this provider implementation, adding it at the end of the list of security providers, + * unless a provider named Spiffe is already registered. + *

+ * Call this method before requesting any of the algorithms of this provider. Unlike the + * security.provider.n entry in the java.security file, it does not depend on this class + * being visible to the system class loader. */ public static void install() { if (Security.getProvider(PROVIDER_NAME) == null) {