Allow the peer's validated certificate chain to be returned in the custom verification handler #553

aryan-25 · 2025-08-11T14:27:07Z

Motivation:

Users are currently able to register a custom callback in NIOSSLClientHandler and NIOSSLServerHandler for verifiying the certificates presented by the peer. However, there is no mechanism for storing additional metadata for future use. This change adds support for the peer's validated certificate chain to be returned from the custom verification callback and later be accessed from the handler.

Modifications:

Added a new custom verification callback type NIOSSLCustomVerificationCallbackWithMetadata.
- This type is identical to the existing NIOSSLCustomVerificationCallback, with the exception that callers must complete the callback with a NIOSSLVerificationResultWithMetadata (also introduced in this change). This result type can either be initialized with no fields, or with a validated certificate chain.
Added properties/methods to NIOSSLHandler, Channel, and ChannelPipeline for accessing the validated certificate chain.

Result:

Users are now able to store the peer's validated certificate chain from the custom verification callback and use the result downstream.

…stom verification handler Motivation: Users are currently able to register a custom callback in `NIOSSLClientHandler` and `NIOSSLServerHandler` for verifiying the certificates presented by the peer. However, there is no mechanism for storing additional metadata for future use. This change adds support for the peer's validated certificate chain to be returned from the custom verification callback and later be accessed from the handler. Modifications: - Added a new custom verification callback type `NIOSSLCustomVerificationCallbackWithMetadata`. - This type is identical to the existing `NIOSSLCustomVerificationCallback`, with the exception that callers must complete the callback with a `NIOSSLVerificationResultWithMetadata` (introduced in this change). This result type can either be initialized with no fields, or with a validated certificate chain. - Added properties/methods to `NIOSSLHandler`, `Channel`, and `ChannelPipeline` for accessing the validated certificate chain. Result: Users are now able to store the peer's validated certificate chain from the custom verification callback and use the result downstream.

josephnoir

I like it. I left two questions that should be easily resolvable. Just want to make sure we are using the right words.

josephnoir · 2025-08-13T08:13:26Z

Sources/NIOSSL/NIOSSLClientHandler.swift

+    /// - Note: Use ``init(context:serverHostname:customVerificationCallbackWithMetadata:)`` to provide a custom
+    ///   verification callback where metadata such as the peer's *validated* certificate chain can be returned.
+    ///   This data can then be accessed from the handler.


At the moment the only thing the metadata includes is the validated certificate chain. "Such as" implies that there could be more. Is this a subtle hint for a future extension or should we be direct here and state that this only includes the chain?

Fair point. I feel it is best to be direct here. I will remove "metadata such as".

josephnoir · 2025-08-13T08:34:23Z

Sources/NIOSSL/NIOSSLClientHandler.swift

+    ///       - This callback is provided the certificates presented by the peer. NIOSSL will not have pre-processed
+    ///       them. Therefore, a validated chain must be derived *within* this callback (potentially involving fetching
+    ///       additional intermediate certificates). The *validated* certificate chain returned in the promise result
+    ///       **must** be a verified path to a trusted root. Importantly, the certificate chain presented by the peer
+    ///       should not be assumed to be valid.


"Certificate chain" itself might not be a very well-defined term.

Here, it refers to both, the certificate chain presented by the client and the validated certificate chain that is the result of verification. However, they differ in so far, that a client can present more certificates than necessary for the verification and the client's certificates do not include the root.

In contrast, what we call validated certificate chain should include a leaf certificate in the front, a root certificate at the end, and the intermediate certificates that trace trust form the leaf to the root in between them.

It might very well be the best word we can use, I am easily convinced here. I just want to make sure we have given it enough thought. Just to offer a few alternatives.

chain of trust (these are the certificates that establish trust from leaf to root)

full validated chain (full includes the certificate chain of the client and the root)

certificate path (IIRC the verification process is usually called path verification in the RFCs?)

Yeah, the peer hasn't provided a chain, it's provided a blob.

You are saying "verified certificate chain" is a good term to refer to the set of certificates that establishes trust for a client (leaf, intermediates, root), but we could update the comment and remove the last sentence or potentially replace "certificate chain" there with "sets of certificates"?

I agree with your points.

I have removed documentation stating that the peer provides a certificate chain. Open for suggestions about the validatedCertificateChain naming

Lukasa · 2025-08-13T09:12:58Z

Sources/NIOSSL/SSLCallbacks.swift

+public struct VerificationMetadata: Sendable, Hashable {
+    /// A container for the validated certificate chain: an array of certificates forming a verified chain of trust
+    /// from the peer's leaf certificate to a trusted root certificate.
+    var validatedCertificateChain: ValidatedCertificateChain?


This should be public.

Lukasa · 2025-08-13T09:13:15Z

Sources/NIOSSL/SSLCallbacks.swift

+    /// The certificate was not verified.
+    case failed
+
+    static let certificateVerified: Self = .certificateVerified(.init())


This may want to be public

Lukasa · 2025-08-13T09:14:13Z

Sources/NIOSSL/SSLCallbacks.swift

+        // Prepares the promise that will be provided as an argument to the callback. Since different callbacks have
+        // different result types, the generic `transformResult` closure is required for converting the specific result
+        // type into ``CustomVerifyManager/PendingResult``.
+        func preparePromise<T>(


Should be private.

Also this looks like it's static.

Lukasa · 2025-08-13T09:16:11Z

Sources/NIOSSL/SSLCallbacks.swift

+                        connection.customVerificationManager == nil
+                            || connection.customVerificationManager?.result == .some(.pendingResult)
+                    )
+                    connection.customVerificationManager?.result = transformResult(result)


So this will have the awkward effect of triggering a heap allocation of this closure. Is there any way we can recover the transformResult function without needing to close over it?

I have addressed this by:

Introducing a new fileprivate protocol PendingResultConvertible that requires a static function to convert Result<Self, any Error> to CustomVerifyManager.PendingResult

Adding conformance to both result types (NIOSSLVerificationResult and NIOSSLVerificationResultWithMetadata)

Constraining the generic parameter in preparePromise to types conforming to the new protocol, and then simply calling the pendingResult function on the result.

However, this has introduced some complexity and redirection. We could also simply overload the preparePromise function for both result types---the function itself isn't too long.

Lukasa · 2025-08-13T09:16:55Z

Sources/NIOSSL/SSLCallbacks.swift

+
+/// Represents a *validated* certificate chain, an array of certificates forming a verified path from the peer's
+/// certificate to a trusted root certificate.
+public struct ValidatedCertificateChain: Sendable, Collection, Hashable {


If you implement Collection, it's almost always a good idea to implement RandomAccessCollection if you can. Here, we can.

Good to know this. I have added the RandomAccessCollection conformance.

Lukasa · 2025-08-13T09:17:19Z

Sources/NIOSSL/SSLCallbacks.swift

+
+/// Represents a *validated* certificate chain, an array of certificates forming a verified path from the peer's
+/// certificate to a trusted root certificate.
+public struct ValidatedCertificateChain: Sendable, Collection, Hashable {


Should we offer a computed property for the leaf?

czechboy0 · 2025-08-14T14:29:10Z

Sources/NIOSSL/SSLCallbacks.swift

+    }
+
+    /// Returns the first element of the chain: the leaf certificate.
+    public var leaf: NIOSSLCertificate? {


Have we considered requiring >0 certs in the validated chain, and thus making this non-optional?

If I get a validated chain with a nil leaf... what does it mean? What does that tell me? What can I do with it?

Agreed. I have added a precondition to the initializer requiring >= 1 certificate and made the leaf property non-optional.

…ValidatedCertificateChain

Lukasa · 2025-08-15T13:51:17Z

Sources/NIOSSL/SSLCallbacks.swift

+    case failed
+
+    /// The certificate was successfully verified with no metadata returned.
+    public static let certificateVerified: Self = .certificateVerified(.init())


I'm not entirely convinced this is a helper we want, actually. Users seem unlikely to want to use the new API and then return nothing.

Agreed, I have removed this now.

Lukasa · 2025-08-15T13:53:37Z

Tests/NIOSSLTests/NIOSSLIntegrationTest.swift

@@ -2365,6 +2364,57 @@ class NIOSSLIntegrationTest: XCTestCase {
        XCTAssertEqual(certificates.withLockedValue { $0 }, [NIOSSLIntegrationTest.cert])
    }

+    func testExtractingCertificateChainFromCustomVerificationCallback() throws {


Can I suggest that we also add tests to confirm:

The failure path

Delayed success (i.e. return success later on, from the main thread).

Agreed, I have added tests for these two cases.

glbrntt · 2025-08-19T12:21:44Z

Sources/NIOSSL/NIOSSLClientHandler.swift

+        customVerificationCallbackWithMetadata: @escaping NIOSSLCustomVerificationCallbackWithMetadata,
+        configuration: Configuration


Closures should generally go last in parameter lists

glbrntt · 2025-08-19T12:24:49Z

Sources/NIOSSL/NIOSSLServerHandler.swift

+    public convenience init(
+        context: NIOSSLContext,
+        customVerificationCallbackWithMetadata: @escaping NIOSSLCustomVerificationCallbackWithMetadata,
+        configuration: Configuration


nit: closures should generally go last in parameter lists

glbrntt · 2025-08-19T12:26:47Z

Sources/NIOSSL/SSLCallbacks.swift

+    public var validatedCertificateChain: ValidatedCertificateChain?
+
+    /// Creates an instance with empty metadata.
+    public init() {


Why two inits vs. one which accepts an optional ValidatedCertificateChain?

glbrntt · 2025-08-19T12:32:24Z

Sources/NIOSSL/SSLCallbacks.swift

+    /// - Important: Do not blindly pass in the array of certificates presented by the peer; the array *must* represent
+    ///   a fully validated and trusted chain.


FWIW: you can also document preconditions: - Precondition: .... It'd be worth adding that the chain must have at least one certificate in.

aryan-25 added 2 commits August 11, 2025 15:25

Update docs

9b7a901

aryan-25 marked this pull request as ready for review August 12, 2025 10:02

josephnoir added the 🆕 semver/minor Adds new public API. label Aug 12, 2025

Improve documentation

302ad6c

josephnoir reviewed Aug 13, 2025

View reviewed changes

Lukasa reviewed Aug 13, 2025

View reviewed changes

Refactor

2561d46

czechboy0 reviewed Aug 14, 2025

View reviewed changes

aryan-25 added 2 commits August 15, 2025 12:00

Enforce a minimum of one certificate to be provided for constructing …

0e303f6

…ValidatedCertificateChain

Merge branch 'main' into as-peer-certificate-chain

403cd9b

Lukasa reviewed Aug 15, 2025

View reviewed changes

Add tests

555d178

glbrntt reviewed Aug 19, 2025

View reviewed changes

aryan-25 added 2 commits August 19, 2025 14:14

Refactor

1aac5cf

Update documentation

aff3e41

glbrntt approved these changes Aug 20, 2025

View reviewed changes

josephnoir merged commit 1d4afc6 into apple:main Aug 21, 2025
46 checks passed

		customVerificationCallbackWithMetadata: @escaping NIOSSLCustomVerificationCallbackWithMetadata,
		configuration: Configuration

		/// - Important: Do not blindly pass in the array of certificates presented by the peer; the array must represent
		/// a fully validated and trusted chain.

Allow the peer's validated certificate chain to be returned in the custom verification handler #553

Allow the peer's validated certificate chain to be returned in the custom verification handler #553

Conversation

aryan-25 commented Aug 11, 2025

Uh oh!

josephnoir left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!