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
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
* 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
* Add `SpiffeIdVerifier.acceptAny()`, `acceptId()`, `acceptOneOf()` and `acceptMemberOf()` factory methods for verifiers that accept any SPIFFE ID, a specific SPIFFE ID, one of a set of SPIFFE IDs, or any SPIFFE ID in a trust domain

### Fixed

Expand Down
46 changes: 32 additions & 14 deletions java-spiffe-provider/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,30 +48,48 @@ 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:
To accept peers by rule instead of from a Supplier of SPIFFE IDs, configure a `SpiffeIdVerifier`. 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.

```
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));
}
};
`SpiffeIdVerifier` has factory methods for the common cases:

| Factory method | Accepts |
|------------------------------------------------|----------------------------------------------------------|
| `SpiffeIdVerifier.acceptAny()` | any SPIFFE ID |
| `SpiffeIdVerifier.acceptId(spiffeId)` | only the given SPIFFE ID |
| `SpiffeIdVerifier.acceptOneOf(spiffeIds)` | any of the given SPIFFE IDs (varargs or a `Collection`) |
| `SpiffeIdVerifier.acceptMemberOf(trustDomain)` | any SPIFFE ID in the given trust domain |

For example, to accept any workload in the `example.org` trust domain:

```
SslContextOptions options = SslContextOptions
.builder()
.x509Source(source)
.spiffeIdVerifier(memberOfTrustDomain)
.spiffeIdVerifier(SpiffeIdVerifier.acceptMemberOf(TrustDomain.parse("example.org")))
.build();

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

`acceptOneOf` copies the SPIFFE IDs when it is called. To accept a set of SPIFFE IDs that changes over time, use
`acceptedSpiffeIdsSupplier` instead.

For other rules, implement `SpiffeIdVerifier`. For example, to accept only workloads under the `/backend` path of the
`example.org` trust domain:

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

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
Expand Down
Original file line number Diff line number Diff line change
@@ -1,9 +1,22 @@
package io.spiffe.provider;

import io.spiffe.spiffeid.SpiffeId;
import io.spiffe.spiffeid.TrustDomain;

import java.security.cert.X509Certificate;
import java.util.Arrays;
import java.util.Collection;
import java.util.HashSet;
import java.util.Objects;
import java.util.Set;

/**
* Verifies the SPIFFE ID of a peer's X.509-SVID during a TLS handshake.
* <p>
* A verifier is called after the peer's certificate chain has been verified against the X.509 bundles, and decides
* whether the peer is authorized. The static factory methods return verifiers for the common cases: accepting any
* SPIFFE ID, a specific SPIFFE ID, one of a set of SPIFFE IDs, or any SPIFFE ID in a trust domain.
*/
public interface SpiffeIdVerifier {
/**
* Verify that an X509-SVID is acceptable. This method receives the SPIFFE ID of the SVID and the certificate
Expand All @@ -14,4 +27,90 @@ public interface SpiffeIdVerifier {
* @throws SpiffeVerificationException if there was an error verifying the SPIFFE ID or it wasn't considered valid.
*/
public void verify(SpiffeId spiffeId, X509Certificate[] verifiedChain) throws SpiffeVerificationException;

/**
* Returns a verifier that accepts any SPIFFE ID.
*
* @return a {@link SpiffeIdVerifier} that accepts any SPIFFE ID
*/
static SpiffeIdVerifier acceptAny() {
return (spiffeId, verifiedChain) -> {
};
}

/**
* Returns a verifier that accepts only the given SPIFFE ID.
*
* @param allowedSpiffeId the SPIFFE ID to accept
* @return a {@link SpiffeIdVerifier} that accepts only {@code allowedSpiffeId}
* @throws NullPointerException if {@code allowedSpiffeId} is null
*/
static SpiffeIdVerifier acceptId(final SpiffeId allowedSpiffeId) {
Objects.requireNonNull(allowedSpiffeId, "allowedSpiffeId must not be null");
return (spiffeId, verifiedChain) -> {
if (!allowedSpiffeId.equals(spiffeId)) {
throw new SpiffeVerificationException(
String.format("SPIFFE ID %s in X.509 certificate is not accepted", spiffeId));
}
};
}

/**
* Returns a verifier that accepts any of the given SPIFFE IDs.
* <p>
* The SPIFFE IDs are copied, so later changes to the array don't affect the verifier. A verifier created without
* SPIFFE IDs rejects every SPIFFE ID.
*
* @param allowedSpiffeIds the SPIFFE IDs to accept
* @return a {@link SpiffeIdVerifier} that accepts only the SPIFFE IDs in {@code allowedSpiffeIds}
* @throws NullPointerException if {@code allowedSpiffeIds} or any of its elements is null
*/
static SpiffeIdVerifier acceptOneOf(final SpiffeId... allowedSpiffeIds) {
Objects.requireNonNull(allowedSpiffeIds, "allowedSpiffeIds must not be null");
return acceptOneOf(Arrays.asList(allowedSpiffeIds));
}

/**
* Returns a verifier that accepts any of the given SPIFFE IDs.
* <p>
* The SPIFFE IDs are copied, so later changes to the collection don't affect the verifier. To accept a set of
* SPIFFE IDs that changes over time, create a {@link SpiffeTrustManager} with a {@link java.util.function.Supplier}
* of SPIFFE IDs, or set {@code acceptedSpiffeIdsSupplier} in the
* {@link SpiffeSslContextFactory.SslContextOptions}. A verifier created with an empty collection rejects every
* SPIFFE ID.
*
* @param allowedSpiffeIds the SPIFFE IDs to accept
* @return a {@link SpiffeIdVerifier} that accepts only the SPIFFE IDs in {@code allowedSpiffeIds}
* @throws NullPointerException if {@code allowedSpiffeIds} or any of its elements is null
*/
static SpiffeIdVerifier acceptOneOf(final Collection<SpiffeId> allowedSpiffeIds) {
Objects.requireNonNull(allowedSpiffeIds, "allowedSpiffeIds must not be null");
final Set<SpiffeId> allowed = new HashSet<>();
for (SpiffeId allowedSpiffeId : allowedSpiffeIds) {
allowed.add(Objects.requireNonNull(allowedSpiffeId, "allowedSpiffeIds must not contain null elements"));
}
return (spiffeId, verifiedChain) -> {
if (!allowed.contains(spiffeId)) {
throw new SpiffeVerificationException(
String.format("SPIFFE ID %s in X.509 certificate is not accepted", spiffeId));
}
};
}

/**
* Returns a verifier that accepts any SPIFFE ID in the given trust domain.
*
* @param trustDomain the trust domain whose SPIFFE IDs are accepted
* @return a {@link SpiffeIdVerifier} that accepts only SPIFFE IDs that are members of {@code trustDomain}
* @throws NullPointerException if {@code trustDomain} is null
*/
static SpiffeIdVerifier acceptMemberOf(final TrustDomain trustDomain) {
Objects.requireNonNull(trustDomain, "trustDomain must not be null");
return (spiffeId, verifiedChain) -> {
if (spiffeId == null || !spiffeId.memberOf(trustDomain)) {
throw new SpiffeVerificationException(String.format(
"SPIFFE ID %s in X.509 certificate is not a member of trust domain %s", spiffeId, trustDomain));
}
};
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -26,9 +26,6 @@
*/
public final class SpiffeTrustManager extends X509ExtendedTrustManager {

private static final SpiffeIdVerifier ALLOW_ANY_SPIFFE_ID_VERIFIER = (spiffeId, verifiedChain) -> {
};

private final BundleSource<X509Bundle> x509BundleSource;
private final SpiffeIdVerifier spiffeIdVerifier;

Expand Down Expand Up @@ -80,7 +77,7 @@ public SpiffeTrustManager(BundleSource<X509Bundle> x509BundleSource,
public SpiffeTrustManager(BundleSource<X509Bundle> x509BundleSource) {
Objects.requireNonNull(x509BundleSource, "x509BundleSource must not be null");
this.x509BundleSource = x509BundleSource;
this.spiffeIdVerifier = ALLOW_ANY_SPIFFE_ID_VERIFIER;
this.spiffeIdVerifier = SpiffeIdVerifier.acceptAny();
}

/**
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,173 @@
package io.spiffe.provider;

import io.spiffe.spiffeid.SpiffeId;
import io.spiffe.spiffeid.TrustDomain;
import org.junit.jupiter.api.Test;

import java.security.cert.X509Certificate;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;

import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;

class SpiffeIdVerifierTest {

private static final X509Certificate[] CHAIN = new X509Certificate[0];

private static final TrustDomain TRUST_DOMAIN = TrustDomain.parse("example.org");
private static final SpiffeId SPIFFE_ID_1 = SpiffeId.parse("spiffe://example.org/workload1");
private static final SpiffeId SPIFFE_ID_2 = SpiffeId.parse("spiffe://example.org/workload2");
private static final SpiffeId SPIFFE_ID_3 = SpiffeId.parse("spiffe://example.org/workload3");
private static final SpiffeId OTHER_DOMAIN_SPIFFE_ID = SpiffeId.parse("spiffe://other.org/workload1");

@Test
void acceptAny_acceptsAnySpiffeId() {
SpiffeIdVerifier verifier = SpiffeIdVerifier.acceptAny();

assertDoesNotThrow(() -> verifier.verify(SPIFFE_ID_1, CHAIN));
assertDoesNotThrow(() -> verifier.verify(OTHER_DOMAIN_SPIFFE_ID, CHAIN));
assertDoesNotThrow(() -> verifier.verify(TRUST_DOMAIN.newSpiffeId(), CHAIN));
}

@Test
void acceptId_acceptsTheGivenSpiffeId() {
SpiffeIdVerifier verifier = SpiffeIdVerifier.acceptId(SPIFFE_ID_1);

assertDoesNotThrow(() -> verifier.verify(SpiffeId.parse("spiffe://example.org/workload1"), CHAIN));
}

@Test
void acceptId_rejectsOtherSpiffeIds() {
SpiffeIdVerifier verifier = SpiffeIdVerifier.acceptId(SPIFFE_ID_1);

SpiffeVerificationException e = assertThrows(SpiffeVerificationException.class,
() -> verifier.verify(SPIFFE_ID_2, CHAIN));
assertEquals("SPIFFE ID spiffe://example.org/workload2 in X.509 certificate is not accepted", e.getMessage());
assertThrows(SpiffeVerificationException.class, () -> verifier.verify(OTHER_DOMAIN_SPIFFE_ID, CHAIN));
assertThrows(SpiffeVerificationException.class,
() -> verifier.verify(SpiffeId.parse("spiffe://example.org/workload1/child"), CHAIN));
}

@Test
void acceptId_nullSpiffeId() {
NullPointerException e = assertThrows(NullPointerException.class, () -> SpiffeIdVerifier.acceptId(null));
assertEquals("allowedSpiffeId must not be null", e.getMessage());
}

@Test
void acceptOneOf_array_acceptsTheGivenSpiffeIds() {
SpiffeIdVerifier verifier = SpiffeIdVerifier.acceptOneOf(SPIFFE_ID_1, SPIFFE_ID_2);

assertDoesNotThrow(() -> verifier.verify(SPIFFE_ID_1, CHAIN));
assertDoesNotThrow(() -> verifier.verify(SPIFFE_ID_2, CHAIN));
SpiffeVerificationException e = assertThrows(SpiffeVerificationException.class,
() -> verifier.verify(SPIFFE_ID_3, CHAIN));
assertEquals("SPIFFE ID spiffe://example.org/workload3 in X.509 certificate is not accepted", e.getMessage());
}

@Test
void acceptOneOf_collection_acceptsTheGivenSpiffeIds() {
SpiffeIdVerifier verifier = SpiffeIdVerifier.acceptOneOf(Arrays.asList(SPIFFE_ID_1, SPIFFE_ID_2));

assertDoesNotThrow(() -> verifier.verify(SPIFFE_ID_1, CHAIN));
assertDoesNotThrow(() -> verifier.verify(SPIFFE_ID_2, CHAIN));
SpiffeVerificationException e = assertThrows(SpiffeVerificationException.class,
() -> verifier.verify(SPIFFE_ID_3, CHAIN));
assertEquals("SPIFFE ID spiffe://example.org/workload3 in X.509 certificate is not accepted", e.getMessage());
}

@Test
void acceptOneOf_array_copiesTheSpiffeIds() {
SpiffeId[] allowedSpiffeIds = {SPIFFE_ID_1};
SpiffeIdVerifier verifier = SpiffeIdVerifier.acceptOneOf(allowedSpiffeIds);

allowedSpiffeIds[0] = SPIFFE_ID_2;

assertDoesNotThrow(() -> verifier.verify(SPIFFE_ID_1, CHAIN));
assertThrows(SpiffeVerificationException.class, () -> verifier.verify(SPIFFE_ID_2, CHAIN));
}

@Test
void acceptOneOf_collection_copiesTheSpiffeIds() {
List<SpiffeId> allowedSpiffeIds = new ArrayList<>(Collections.singletonList(SPIFFE_ID_1));
SpiffeIdVerifier verifier = SpiffeIdVerifier.acceptOneOf(allowedSpiffeIds);

allowedSpiffeIds.add(SPIFFE_ID_2);
allowedSpiffeIds.remove(SPIFFE_ID_1);

assertDoesNotThrow(() -> verifier.verify(SPIFFE_ID_1, CHAIN));
assertThrows(SpiffeVerificationException.class, () -> verifier.verify(SPIFFE_ID_2, CHAIN));
}

@Test
void acceptOneOf_noSpiffeIds_rejectsEverySpiffeId() {
SpiffeIdVerifier arrayVerifier = SpiffeIdVerifier.acceptOneOf();
SpiffeIdVerifier collectionVerifier = SpiffeIdVerifier.acceptOneOf(Collections.emptySet());

assertThrows(SpiffeVerificationException.class, () -> arrayVerifier.verify(SPIFFE_ID_1, CHAIN));
assertThrows(SpiffeVerificationException.class, () -> collectionVerifier.verify(SPIFFE_ID_1, CHAIN));
}

@Test
void acceptOneOf_nullArguments() {
NullPointerException e = assertThrows(NullPointerException.class,
() -> SpiffeIdVerifier.acceptOneOf((SpiffeId[]) null));
assertEquals("allowedSpiffeIds must not be null", e.getMessage());

e = assertThrows(NullPointerException.class,
() -> SpiffeIdVerifier.acceptOneOf((List<SpiffeId>) null));
assertEquals("allowedSpiffeIds must not be null", e.getMessage());
}

@Test
void acceptOneOf_nullElement() {
NullPointerException e = assertThrows(NullPointerException.class,
() -> SpiffeIdVerifier.acceptOneOf(SPIFFE_ID_1, null));
assertEquals("allowedSpiffeIds must not contain null elements", e.getMessage());

e = assertThrows(NullPointerException.class,
() -> SpiffeIdVerifier.acceptOneOf(Arrays.asList(SPIFFE_ID_1, null)));
assertEquals("allowedSpiffeIds must not contain null elements", e.getMessage());
}

@Test
void acceptMemberOf_acceptsSpiffeIdsInTheTrustDomain() {
SpiffeIdVerifier verifier = SpiffeIdVerifier.acceptMemberOf(TRUST_DOMAIN);

assertDoesNotThrow(() -> verifier.verify(SPIFFE_ID_1, CHAIN));
assertDoesNotThrow(() -> verifier.verify(SPIFFE_ID_2, CHAIN));
assertDoesNotThrow(() -> verifier.verify(SpiffeId.parse("spiffe://EXAMPLE.org/workload1/child"), CHAIN));
}

@Test
void acceptMemberOf_rejectsSpiffeIdsInOtherTrustDomains() {
SpiffeIdVerifier verifier = SpiffeIdVerifier.acceptMemberOf(TRUST_DOMAIN);

SpiffeVerificationException e = assertThrows(SpiffeVerificationException.class,
() -> verifier.verify(OTHER_DOMAIN_SPIFFE_ID, CHAIN));
assertEquals("SPIFFE ID spiffe://other.org/workload1 in X.509 certificate is not a member of trust domain example.org",
e.getMessage());
assertThrows(SpiffeVerificationException.class,
() -> verifier.verify(SpiffeId.parse("spiffe://example.org.other/workload1"), CHAIN));
}

@Test
void verifiers_rejectNullSpiffeId() {
assertThrows(SpiffeVerificationException.class,
() -> SpiffeIdVerifier.acceptId(SPIFFE_ID_1).verify(null, CHAIN));
assertThrows(SpiffeVerificationException.class,
() -> SpiffeIdVerifier.acceptOneOf(SPIFFE_ID_1).verify(null, CHAIN));
assertThrows(SpiffeVerificationException.class,
() -> SpiffeIdVerifier.acceptMemberOf(TRUST_DOMAIN).verify(null, CHAIN));
}

@Test
void acceptMemberOf_nullTrustDomain() {
NullPointerException e = assertThrows(NullPointerException.class, () -> SpiffeIdVerifier.acceptMemberOf(null));
assertEquals("trustDomain must not be null", e.getMessage());
}
}
Loading
Loading