pjfanning opened a new pull request, #3462: URL: https://github.com/apache/pekko/pull/3462
## Motivation The Artery `SSLEngineProvider` trait exposes `verifyClientSession` and `verifyServerSession`. `ArteryTcpTransport` invokes them after every successful TLS handshake and fails the connection when they return `Some(cause)`: https://github.com/apache/pekko/blob/main/remote/src/main/scala/org/apache/pekko/remote/artery/tcp/ArteryTcpTransport.scala#L145 https://github.com/apache/pekko/blob/main/remote/src/main/scala/org/apache/pekko/remote/artery/tcp/ArteryTcpTransport.scala#L261 The mechanism works and needs no code change, but it was only described in the `RotatingKeysSSLEngineProvider` section of the docs. Users on the default JKS-based `ConfigSSLEngineProvider` (whose `verify*` methods return `None`) had no indication that overriding them is a supported extension point. ## Changes Adds a "Custom post-handshake session verification" subsection to `remote-security.md`, under the existing SSL/TLS configuration section: - Documents both callbacks and their return contract. - States that `hostname-verification=on` is preferred when peer hostnames are known, so the verifier is not presented as a substitute for it. - Explains the dependency on `require-mutual-authentication` — with it off, the accepting side gets no peer certificate and `getPeerCertificates` throws `SSLPeerUnverifiedException`. - Notes the callbacks run on every handshake and should avoid blocking I/O such as CRL/OCSP lookups. - Cross-references `RotatingKeysSSLEngineProvider` as the built-in user of the same mechanism. The example is a compiled snippet (`docs/src/test/scala/docs/remoting/SSLEngineProviderDocSpec.scala`) pulled in with `@@snip`, following the convention used elsewhere in the docs, so it cannot silently rot. It covers the shared-internal-CA case: every node's certificate is signed by the same CA and therefore accepted by the trust-store, but only a subset should be allowed into a given cluster. Docs only — no production code or configuration is changed. ## Tests - `sbt docs/Test/compile` passes; the snippet compiles against the real `ConfigSSLEngineProvider` API. - `sbt docs/scalafmt` run; the snippet is unchanged by it. - `sbt docs/headerCreateAll` generated the license header on the new file. - `sbt docs/paradox` was not run locally; relying on CI to validate the `@@snip` reference and link rendering. - No MiMa run: no public API, binary shape, or serialization change. ## References - `SSLEngineProvider` trait: `remote/src/main/scala/org/apache/pekko/remote/artery/tcp/SSLEngineProvider.scala` - Existing no-op implementations: `remote/src/main/scala/org/apache/pekko/remote/artery/tcp/ConfigSSLEngineProvider.scala` - Reference implementation using the hook: `remote/src/main/scala/org/apache/pekko/remote/artery/tcp/ssl/RotatingKeysSSLEngineProvider.scala` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
