Skip to content
Open
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
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
* Add `X509Bundle.marshal()` and `JwtBundle.marshal()` to serialize bundles as PEM certificates and as a JWKS document, the formats read by `parse`
* Publish a `java-spiffe-bom` Bill of Materials to align the versions of the java-spiffe modules.
* Add `X509Svid.marshalCertificates()` and `X509Svid.marshalPrivateKey()` to serialize an X.509-SVID as PEM certificates and a PEM PKCS#8 private key, the formats read by `parse` and `load`, and `marshalRawCertificates()` and `marshalRawPrivateKey()` for the ASN.1 DER formats read by `parseRaw` (#515)
* Add a `spiffeIdVerifier` option to `SpiffeSslContextFactory.SslContextOptions`, so an `SSLContext` can verify peer SPIFFE IDs with a custom `SpiffeIdVerifier` instead of a fixed set of accepted SPIFFE IDs

### Fixed

Expand Down
31 changes: 31 additions & 0 deletions java-spiffe-provider/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,37 @@ Alternatively, a different Workload API address can be used by passing it to the
See [HttpsClient example](src/test/java/io/spiffe/provider/examples/mtls/HttpsClient.java) that defines a Supplier for providing
the list of SPIFFE IDs from a file.

### Verify peer SPIFFE IDs with a custom verifier

When the accepted SPIFFE IDs are not known in advance as a fixed set, configure a `SpiffeIdVerifier` instead of a
Supplier of SPIFFE IDs. The verifier is called during each TLS handshake, after the peer's certificate chain has been
verified against the X.509 bundles, with the peer's SPIFFE ID and certificate chain. Throwing a
`SpiffeVerificationException` rejects the peer and fails the handshake. For example, to accept any workload in the
`example.org` trust domain:

```
TrustDomain trustDomain = TrustDomain.parse("example.org");
SpiffeIdVerifier memberOfTrustDomain = (spiffeId, verifiedChain) -> {
if (!spiffeId.memberOf(trustDomain)) {
throw new SpiffeVerificationException(
String.format("SPIFFE ID %s is not a member of trust domain %s", spiffeId, trustDomain));
}
};

SslContextOptions options = SslContextOptions
.builder()
.x509Source(source)
.spiffeIdVerifier(memberOfTrustDomain)
.build();

SSLContext sslContext = SpiffeSslContextFactory.getSslContext(options);
```

A `spiffeIdVerifier` cannot be combined with `acceptedSpiffeIdsSupplier` or `acceptAnySpiffeId`: `getSslContext`
throws an `IllegalArgumentException` if the options configure either of them together with a verifier. A
`SpiffeTrustManager` can also be created directly with a `SpiffeIdVerifier`, see
[Configure it programmatically](#configure-it-programmatically).

## Plug Java SPIFFE Provider into Java Security architecture

Java Security Providers are configured in the master security properties file `<java-home>/jre/lib/security/java.security`.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -30,11 +30,16 @@ private SpiffeSslContextFactory() {
* that are backed by the Workload API via an {@link DefaultX509Source}.
*
* @param options {@link SslContextOptions}. The option {@link DefaultX509Source} must be not null.
* If the option <code>acceptedSpiffeIdsSupplier</code> is not provided, the Set of accepted SPIFFE IDs
* is read from the Security or System Property <code>ssl.spiffe.accept</code>.
* The SPIFFE IDs of the peers are verified with the <code>spiffeIdVerifier</code>, checked
* against the <code>acceptedSpiffeIdsSupplier</code>, or accepted if <code>acceptAnySpiffeId</code>
* is set. One of them must be configured.
* If the sslProtocol is not provided, the default TLSv1.2 is used.
* @return an initialized {@link SSLContext}
* @throws IllegalArgumentException if the {@link DefaultX509Source} is not provided in the options
* @throws IllegalArgumentException if the {@link DefaultX509Source} is not provided in the options,
* if neither a <code>spiffeIdVerifier</code>, an
* <code>acceptedSpiffeIdsSupplier</code> nor <code>acceptAnySpiffeId</code>
* is configured, or if a <code>spiffeIdVerifier</code> is configured together
* with an <code>acceptedSpiffeIdsSupplier</code> or <code>acceptAnySpiffeId</code>
* @throws NoSuchAlgorithmException if there is a problem creating the SSL context
* @throws KeyManagementException if there is a problem initializing the SSL context
*/
Expand All @@ -46,9 +51,16 @@ public static SSLContext getSslContext(SslContextOptions options)
throw new IllegalArgumentException("x509Source option must not be null, an X.509 Source must be provided");
}

if (!options.acceptAnySpiffeId && options.acceptedSpiffeIdsSupplier == null) {
throw new IllegalArgumentException("SSL context should be configured either with a Supplier " +
"of accepted SPIFFE IDs or with acceptAnySpiffeId=true");
if (options.spiffeIdVerifier != null
&& (options.acceptAnySpiffeId || options.acceptedSpiffeIdsSupplier != null)) {
throw new IllegalArgumentException("SSL context should not be configured with a SPIFFE ID verifier " +
"together with a Supplier of accepted SPIFFE IDs or with acceptAnySpiffeId=true");
}

if (options.spiffeIdVerifier == null
&& !options.acceptAnySpiffeId && options.acceptedSpiffeIdsSupplier == null) {
throw new IllegalArgumentException("SSL context should be configured either with a SPIFFE ID verifier, " +
"with a Supplier of accepted SPIFFE IDs or with acceptAnySpiffeId=true");
}

final SSLContext sslContext = newSslContext(options);
Expand All @@ -60,6 +72,10 @@ public static SSLContext getSslContext(SslContextOptions options)
}

private static TrustManager[] newTrustManager(final SslContextOptions options) {
if (options.spiffeIdVerifier != null) {
return new TrustManager[]{new SpiffeTrustManager(options.x509Source, options.spiffeIdVerifier)};
}

if (options.acceptAnySpiffeId) {
return new SpiffeTrustManagerFactory().engineGetTrustManagersAcceptAnySpiffeId(options.x509Source);
}
Expand Down Expand Up @@ -95,23 +111,38 @@ private static SSLContext newSslContext(final SslContextOptions options) throws
* <p>
* <code>acceptAnySpiffeId</code> Flag that indicates that any {@link SpiffeId} will be accepted for a
* secure socket connection. This config overrules the <code>acceptedSpiffeIdsSupplier</code> property.
* <p>
* <code>spiffeIdVerifier</code> A {@link SpiffeIdVerifier} that decides whether the {@link SpiffeId} of a peer
* is accepted for a secure socket connection. It cannot be combined with <code>acceptedSpiffeIdsSupplier</code>
* or <code>acceptAnySpiffeId</code>.
*/
public static class SslContextOptions {

private String sslProtocol;
private X509Source x509Source;
private Supplier<Set<SpiffeId>> acceptedSpiffeIdsSupplier;
private boolean acceptAnySpiffeId;
private SpiffeIdVerifier spiffeIdVerifier;

public SslContextOptions(
final String sslProtocol,
final X509Source x509Source,
final Supplier<Set<SpiffeId>> acceptedSpiffeIdsSupplier,
final boolean acceptAnySpiffeId) {
this(sslProtocol, x509Source, acceptedSpiffeIdsSupplier, acceptAnySpiffeId, null);
}

public SslContextOptions(
final String sslProtocol,
final X509Source x509Source,
final Supplier<Set<SpiffeId>> acceptedSpiffeIdsSupplier,
final boolean acceptAnySpiffeId,
final SpiffeIdVerifier spiffeIdVerifier) {
this.x509Source = x509Source;
this.acceptedSpiffeIdsSupplier = acceptedSpiffeIdsSupplier;
this.sslProtocol = sslProtocol;
this.acceptAnySpiffeId = acceptAnySpiffeId;
this.spiffeIdVerifier = spiffeIdVerifier;
}

public String getSslProtocol() {
Expand All @@ -130,6 +161,10 @@ public boolean isAcceptAnySpiffeId() {
return acceptAnySpiffeId;
}

public SpiffeIdVerifier getSpiffeIdVerifier() {
return spiffeIdVerifier;
}

public static SslContextOptionsBuilder builder() {
return new SslContextOptionsBuilder();
}
Expand All @@ -139,6 +174,7 @@ public static class SslContextOptionsBuilder {
private X509Source x509Source;
private Supplier<Set<SpiffeId>> acceptedSpiffeIdsSupplier;
private boolean acceptAnySpiffeId;
private SpiffeIdVerifier spiffeIdVerifier;

SslContextOptionsBuilder() {
}
Expand All @@ -164,12 +200,18 @@ public SslContextOptionsBuilder acceptAnySpiffeId() {
return this;
}

public SslContextOptionsBuilder spiffeIdVerifier(SpiffeIdVerifier spiffeIdVerifier) {
this.spiffeIdVerifier = spiffeIdVerifier;
return this;
}

public SslContextOptions build() {
return new SslContextOptions(
sslProtocol,
x509Source,
acceptedSpiffeIdsSupplier,
acceptAnySpiffeId
acceptAnySpiffeId,
spiffeIdVerifier
);
}
}
Expand All @@ -182,12 +224,13 @@ public boolean equals(Object o) {
return acceptAnySpiffeId == that.acceptAnySpiffeId
&& Objects.equals(sslProtocol, that.sslProtocol)
&& Objects.equals(x509Source, that.x509Source)
&& Objects.equals(acceptedSpiffeIdsSupplier, that.acceptedSpiffeIdsSupplier);
&& Objects.equals(acceptedSpiffeIdsSupplier, that.acceptedSpiffeIdsSupplier)
&& Objects.equals(spiffeIdVerifier, that.spiffeIdVerifier);
}

@Override
public int hashCode() {
return Objects.hash(sslProtocol, x509Source, acceptedSpiffeIdsSupplier, acceptAnySpiffeId);
return Objects.hash(sslProtocol, x509Source, acceptedSpiffeIdsSupplier, acceptAnySpiffeId, spiffeIdVerifier);
}

@Override
Expand All @@ -197,6 +240,7 @@ public String toString() {
", x509Source=" + x509Source +
", acceptedSpiffeIdsSupplier=" + acceptedSpiffeIdsSupplier +
", acceptAnySpiffeId=" + acceptAnySpiffeId +
", spiffeIdVerifier=" + spiffeIdVerifier +
')';
}
}
Expand Down
Loading
Loading