Skip to content

feat(provider): accept a SpiffeIdVerifier in SslContextOptions - #521

Open
NopeCharon wants to merge 1 commit into
spiffe:mainfrom
NopeCharon:feat/ssl-context-spiffe-id-verifier
Open

NopeCharon wants to merge 1 commit into
spiffe:mainfrom
NopeCharon:feat/ssl-context-spiffe-id-verifier

Conversation

@NopeCharon

Copy link
Copy Markdown
Contributor

What

Adds a spiffeIdVerifier option to SpiffeSslContextFactory.SslContextOptions, so an SSLContext built by SpiffeSslContextFactory can check peer SPIFFE IDs with a custom SpiffeIdVerifier:

TrustDomain trustDomain = TrustDomain.parse("example.org");
SslContextOptions options = SslContextOptions
        .builder()
        .x509Source(x509Source)
        .spiffeIdVerifier((spiffeId, verifiedChain) -> {
            if (!spiffeId.memberOf(trustDomain)) {
                throw new SpiffeVerificationException("SPIFFE ID " + spiffeId + " is not authorized");
            }
        })
        .build();
SSLContext sslContext = SpiffeSslContextFactory.getSslContext(options);

Details:

  • SslContextOptions gets a spiffeIdVerifier(...) builder method, a getSpiffeIdVerifier() getter, and a constructor that takes the verifier. The existing 4-argument constructor delegates to it.
  • When a verifier is set, getSslContext builds the SpiffeTrustManager with it. The trust manager verifies the chain against the bundles first, then calls the verifier with the peer's SPIFFE ID and chain, as it already does for verifiers passed to its constructor.
  • A verifier makes the whole authorization decision. If acceptedSpiffeIdsSupplier or acceptAnySpiffeId is also set, getSslContext throws IllegalArgumentException instead of letting one option silently override the other.
  • The supplier and acceptAnySpiffeId options behave as before. The one visible change is the message of the IllegalArgumentException thrown when no option is configured, which now mentions the verifier.
  • No SpiffeTrustManagerFactory overload is added. engineGetTrustManagers(BundleSource, SpiffeIdVerifier) would make existing engineGetTrustManagers(source, null) calls ambiguous at compile time.
  • The provider README has a "Verify peer SPIFFE IDs with a custom verifier" section. The changelog lists the option under Unreleased.

Why

#77 added SpiffeIdVerifier to SpiffeTrustManager so applications can accept peers by rule instead of from a fixed set of IDs. Examples are any workload in a trust domain, a path prefix, or a lookup in another system. go-spiffe offers the same thing with tlsconfig.Authorizer. SpiffeSslContextFactory is the documented way to get an SSLContext backed by the Workload API, but it only took a Supplier<Set<SpiffeId>> or acceptAnySpiffeId. To use a verifier, callers had to create the key manager and trust manager and initialize the SSLContext themselves.

Compatibility: this only adds a constructor, a getter and a builder method. :java-spiffe-provider:japicmp passes.

How tested

  • SpiffeSslContextFactoryTest:
    • an SSLContext is created with only a verifier, and the options return it
    • a verifier combined with acceptedSpiffeIdsSupplier, or with acceptAnySpiffeId, throws IllegalArgumentException
    • mutual TLS handshake between two in-memory SSLEngines, with SVIDs and a bundle generated for the test: the verifier is called on both sides, with the peer's SPIFFE ID and certificate chain
    • a verifier that throws SpiffeVerificationException fails the handshake with an SSLHandshakeException caused by that exception
    • the existing "no option configured" test checks the updated message
  • The two handshake tests fail when getSslContext ignores the verifier.
  • Commands, on JDK 17: ./gradlew :java-spiffe-provider:test :java-spiffe-provider:javadoc :java-spiffe-provider:japicmp (92 provider tests pass).

SpiffeTrustManager can verify peer SPIFFE IDs with a SpiffeIdVerifier
callback, which lets an application accept peers by rule (a trust
domain, a path prefix, a lookup in another system) instead of from a
fixed set of IDs. SpiffeSslContextFactory, the documented way to build
an SSLContext backed by the Workload API, only accepted a Supplier of
accepted SPIFFE IDs or acceptAnySpiffeId, so using a verifier meant
creating the key and trust managers and initializing the SSLContext by
hand.

Add a spiffeIdVerifier option to SslContextOptions, with a builder
method, a getter and a constructor that takes it. getSslContext creates
the SpiffeTrustManager with the verifier when it is set.

A verifier is a complete authorization decision on its own, so
combining it with acceptedSpiffeIdsSupplier or acceptAnySpiffeId is
rejected with an IllegalArgumentException instead of letting one
silently override the other. The existing behavior of the supplier and
acceptAnySpiffeId options is unchanged, and the error raised when no
option is configured now also mentions the verifier.

Document the option in the provider README with an example that accepts
any workload in a trust domain, and add a changelog entry.

Signed-off-by: NopeCharon <115794254+NopeCharon@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant