Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
37 changes: 35 additions & 2 deletions java-spiffe-provider/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -87,6 +99,8 @@ ssl.spiffe.accept=spiffe://example.org/workload | spiffe://example.org/workload2
In this `java.security` file:

* replace `<n>` 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.
Expand Down Expand Up @@ -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.<n>` 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
Expand Down Expand Up @@ -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:

Expand All @@ -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:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -24,19 +24,22 @@
* <p>
* To use this Provider, it is needed to add the following lines to the java.security file:
* <pre>
* security.provider.n=io.spiffe.SpiffeProvider
* security.provider.n=io.spiffe.provider.SpiffeProvider
* ssl.KeyManagerFactory.algorithm=Spiffe
* ssl.TrustManagerFactory.algorithm=Spiffe
* </pre>
* 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.
* <p>
* Also, to configure the accepted SPIFFE IDs, add to the java.security the list of SPIFFE IDs
* separated by the pipe character:
* <pre>
* ssl.spiffe.accept=spiffe://example.org/workload1 | spiffe://example.org/workload2,
* ssl.spiffe.accept=spiffe://example.org/workload1 | spiffe://example.org/workload2
* </pre>
* This property can also be defined as a System parameter passed through <code>-Dssl.spiffe.accept</code>:
* <pre>
* -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
* </pre>
* <p>
* To configure the `TrustManager` to accept any SPIFFE ID presented by a peer,
Expand Down Expand Up @@ -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 <code>Spiffe</code> is already registered.
* <p>
* Call this method before requesting any of the algorithms of this provider. Unlike the
* <code>security.provider.n</code> 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) {
Expand Down
Loading