Expose peer certificates in request handlers (vapor#3362)

josephnoir · 0xTim · web-flow · commit c84ffd383814 · 2025-11-05T11:24:47.000Z
* Expose peer certificates in request handlers

Additional certificate information can be relevant in mTLS deployments.
Exposing the validated certificate chain to the peer makes them
available per request. This PR exposes the validated peer certificate
chain, i.e., the certificates that establish trust of the peer identity
(from the leaf to and including the root certificate).

* Address API breakage

* Add Swift ASN1 to server tests

---------

Co-authored-by: Tim Condon &lt;0xTim@users.noreply.github.com&gt;
diff --git a/Package.swift b/Package.swift
@@ -34,7 +34,7 @@ let package = Package(
         .package(url: "https://github.com/apple/swift-nio.git", from: "2.81.0"),
 
         // Bindings to OpenSSL-compatible libraries for TLS support in SwiftNIO
-        .package(url: "https://github.com/apple/swift-nio-ssl.git", from: "2.8.0"),
+        .package(url: "https://github.com/apple/swift-nio-ssl.git", from: "2.34.0"),
 
         // HTTP/2 support for SwiftNIO
         .package(url: "https://github.com/apple/swift-nio-http2.git", from: "1.28.0"),
@@ -65,6 +65,12 @@ let package = Package(
 
         // Low-level atomic operations
         .package(url: "https://github.com/apple/swift-atomics.git", from: "1.1.0"),
+
+        // X509 certificate types for the Swift ecosystem
+        .package(url: "https://github.com/apple/swift-certificates.git", from: "1.14.0"),
+
+        // Work with certificate encoding schemes
+        .package(url: "https://github.com/apple/swift-asn1.git", from: "1.0.0")
     ],
     targets: [
         // C helpers
@@ -100,6 +106,8 @@ let package = Package(
                 .product(name: "Atomics", package: "swift-atomics"),
                 .product(name: "_NIOFileSystem", package: "swift-nio"),
                 .product(name: "_NIOFileSystemFoundationCompat", package: "swift-nio"),
+                .product(name: "X509", package: "swift-certificates"),
+                .product(name: "SwiftASN1", package: "swift-asn1"),
             ],
             swiftSettings: swiftSettings
         ),
@@ -142,6 +150,7 @@ let package = Package(
             name: "VaporTests",
             dependencies: [
                 .product(name: "NIOTestUtils", package: "swift-nio"),
+                .product(name: "SwiftASN1", package: "swift-asn1"),
                 .target(name: "XCTVapor"),
                 .target(name: "VaporTesting"),
                 .target(name: "Vapor"),
diff --git a/Sources/Vapor/HTTP/Server/HTTPServer.swift b/Sources/Vapor/HTTP/Server/HTTPServer.swift
@@ -113,9 +113,19 @@ public final class HTTPServer: Server, Sendable {
 
         /// An optional callback that will be called instead of using swift-nio-ssl's regular certificate verification logic.
         /// This is the same as `NIOSSLCustomVerificationCallback` but just marked as `Sendable`
+        /// - Warning: Mutually exclusive with `customCertificateVerifyCallbackWithMetadata`.
         @preconcurrency
         public var customCertificateVerifyCallback: (@Sendable ([NIOSSLCertificate], EventLoopPromise<NIOSSLVerificationResult>) -> Void)?
-        
+
+        /// An optional callback that will be called instead of using swift-nio-ssl's regular certificate verification logic.
+        /// This is the same as `NIOSSLCustomVerificationCallbackWithMetadata` but just marked as `Sendable`.
+        ///
+        /// In contrast to `customCertificateVerifyCallback`, this callback allows returning the validate certificate
+        /// chain, which can then be accessed on the request via `Request.peerCertificateChain`.
+        /// - Warning: Mutually exclusive with `customCertificateVerifyCallback`.
+        @preconcurrency
+        public var customCertificateVerifyCallbackWithMetadata: (@Sendable ([NIOSSLCertificate], EventLoopPromise<NIOSSLVerificationResultWithMetadata>) -> Void)?
+
         /// The number of incoming TCP connections to accept per "tick" (i.e. each time through the server's event loop).
         ///
         /// Most users will never need to change this value; its primary use case is to work around benchmarking
@@ -161,6 +171,43 @@ public final class HTTPServer: Server, Sendable {
             )
         }
 
+        public init(
+            hostname: String = Self.defaultHostname,
+            port: Int = Self.defaultPort,
+            backlog: Int = 256,
+            reuseAddress: Bool = true,
+            tcpNoDelay: Bool = true,
+            responseCompression: ResponseCompressionConfiguration = .disabled,
+            requestDecompression: RequestDecompressionConfiguration = .enabled,
+            supportPipelining: Bool = true,
+            supportVersions: Set<HTTPVersionMajor>? = nil,
+            tlsConfiguration: TLSConfiguration? = nil,
+            serverName: String? = nil,
+            reportMetrics: Bool = true,
+            logger: Logger? = nil,
+            shutdownTimeout: TimeAmount = .seconds(10),
+            customCertificateVerifyCallbackWithMetadata: (@Sendable ([NIOSSLCertificate], EventLoopPromise<NIOSSLVerificationResultWithMetadata>) -> Void)?,
+            connectionsPerServerTick: UInt = 256
+        ) {
+            self.init(
+                address: .hostname(hostname, port: port),
+                backlog: backlog,
+                reuseAddress: reuseAddress,
+                tcpNoDelay: tcpNoDelay,
+                responseCompression: responseCompression,
+                requestDecompression: requestDecompression,
+                supportPipelining: supportPipelining,
+                supportVersions: supportVersions,
+                tlsConfiguration: tlsConfiguration,
+                serverName: serverName,
+                reportMetrics: reportMetrics,
+                logger: logger,
+                shutdownTimeout: shutdownTimeout,
+                customCertificateVerifyCallbackWithMetadata: customCertificateVerifyCallbackWithMetadata,
+                connectionsPerServerTick: connectionsPerServerTick
+            )
+        }
+
         public init(
             address: BindAddress,
             backlog: Int = 256,
@@ -196,10 +243,50 @@ public final class HTTPServer: Server, Sendable {
             self.logger = logger ?? Logger(label: "codes.vapor.http-server")
             self.shutdownTimeout = shutdownTimeout
             self.customCertificateVerifyCallback = customCertificateVerifyCallback
+            self.customCertificateVerifyCallbackWithMetadata = nil
+            self.connectionsPerServerTick = connectionsPerServerTick
+        }
+
+        public init(
+            address: BindAddress,
+            backlog: Int = 256,
+            reuseAddress: Bool = true,
+            tcpNoDelay: Bool = true,
+            responseCompression: ResponseCompressionConfiguration = .disabled,
+            requestDecompression: RequestDecompressionConfiguration = .enabled,
+            supportPipelining: Bool = true,
+            supportVersions: Set<HTTPVersionMajor>? = nil,
+            tlsConfiguration: TLSConfiguration? = nil,
+            serverName: String? = nil,
+            reportMetrics: Bool = true,
+            logger: Logger? = nil,
+            shutdownTimeout: TimeAmount = .seconds(10),
+            customCertificateVerifyCallbackWithMetadata: (@Sendable ([NIOSSLCertificate], EventLoopPromise<NIOSSLVerificationResultWithMetadata>) -> Void)?,
+            connectionsPerServerTick: UInt = 256
+        ) {
+            self.address = address
+            self.backlog = backlog
+            self.reuseAddress = reuseAddress
+            self.tcpNoDelay = tcpNoDelay
+            self.responseCompression = responseCompression
+            self.requestDecompression = requestDecompression
+            self.supportPipelining = supportPipelining
+            if let supportVersions = supportVersions {
+                self.supportVersions = supportVersions
+            } else {
+                self.supportVersions = tlsConfiguration == nil ? [.one] : [.one, .two]
+            }
+            self.tlsConfiguration = tlsConfiguration
+            self.serverName = serverName
+            self.reportMetrics = reportMetrics
+            self.logger = logger ?? Logger(label: "codes.vapor.http-server")
+            self.shutdownTimeout = shutdownTimeout
+            self.customCertificateVerifyCallback = nil
+            self.customCertificateVerifyCallbackWithMetadata = customCertificateVerifyCallbackWithMetadata
             self.connectionsPerServerTick = connectionsPerServerTick
         }
     }
-    
+
     public var onShutdown: EventLoopFuture<Void> {
         guard let connection = self.connection.withLockedValue({ $0 }) else {
             fatalError("Server has not started yet")
@@ -447,7 +534,11 @@ private final class HTTPServerConnection: Sendable {
                     let tlsHandler: NIOSSLServerHandler
                     do {
                         sslContext = try NIOSSLContext(configuration: tlsConfiguration)
-                        tlsHandler = NIOSSLServerHandler(context: sslContext, customVerifyCallback: configuration.customCertificateVerifyCallback)
+                        tlsHandler = NIOSSLServerHandler(
+                            context: sslContext,
+                            customVerifyCallback: configuration.customCertificateVerifyCallback,
+                            customVerifyCallbackWithMetadata: configuration.customCertificateVerifyCallbackWithMetadata
+                        )
                     } catch {
                         configuration.logger.error("Could not configure TLS: \(error)")
                         return channel.close(mode: .all)
@@ -662,9 +753,13 @@ extension ChannelPipeline {
 
 // MARK: Helper function for constructing NIOSSLServerHandler.
 extension NIOSSLServerHandler {
-    convenience init(context: NIOSSLContext, customVerifyCallback: NIOSSLCustomVerificationCallback?) {
+    convenience init(context: NIOSSLContext, customVerifyCallback: NIOSSLCustomVerificationCallback?,
+                     customVerifyCallbackWithMetadata: NIOSSLCustomVerificationCallbackWithMetadata?) {
+        precondition(customVerifyCallback == nil || customVerifyCallbackWithMetadata == nil, "Only one of customVerifyCallback and customVerifyCallbackWithMetadata can be used at a time.")
         if let callback = customVerifyCallback {
             self.init(context: context, customVerificationCallback: callback)
+        } else if let callbackWithMetadata = customVerifyCallbackWithMetadata {
+            self.init(context: context, customVerificationCallbackWithMetadata: callbackWithMetadata)
         } else {
             self.init(context: context)
         }
diff --git a/Sources/Vapor/HTTP/Server/HTTPServerRequestDecoder.swift b/Sources/Vapor/HTTP/Server/HTTPServerRequestDecoder.swift
@@ -2,6 +2,7 @@ import Logging
 import NIOCore
 import NIOHTTP1
 import Foundation
+import X509
 
 final class HTTPServerRequestDecoder: ChannelDuplexHandler, RemovableChannelHandler {
     typealias InboundIn = HTTPServerRequestPart
@@ -23,11 +24,30 @@ final class HTTPServerRequestDecoder: ChannelDuplexHandler, RemovableChannelHand
         self.application.logger
     }
     var application: Application
-    
+
+    enum CertificateChainCache {
+        case miss
+        case hit(ValidatedCertificateChain?)
+
+        mutating func lookup(_ updater: () throws -> ValidatedCertificateChain?) -> ValidatedCertificateChain? {
+            switch self {
+            case .miss:
+                let result = try? updater()
+                self = .hit(result)
+                return result
+            case .hit(let result):
+                return result
+            }
+        }
+    }
+
+    var validatedCertificateChainCache: CertificateChainCache
+
     init(application: Application) {
         self.application = application
         self.requestState = .ready
         self.bodyStreamState = .init()
+        self.validatedCertificateChainCache = .miss
     }
     
     func channelRead(context: ChannelHandlerContext, data: NIOAny) {
@@ -38,6 +58,11 @@ final class HTTPServerRequestDecoder: ChannelDuplexHandler, RemovableChannelHand
         case .head(let head):
             switch self.requestState {
             case .ready:
+                // The certificate chain will only be avalable when configuring `customCertificateVerifyCallbackWithMetadata`.
+                // Since the certificate chain is validated during the handshake, we only collect it once and cache it.
+                let peerCertificateChain = self.validatedCertificateChainCache.lookup {
+                    try? context.pipeline.syncOperations.nioSSL_peerValidatedCertificateChain()?.usingX509Certificates()
+                }
                 /// Note: It is critical that `URI.init(path:)` is used here, _NOT_ `URI.init(string:)`. The following
                 /// example illustrates why:
                 ///
@@ -57,6 +82,7 @@ final class HTTPServerRequestDecoder: ChannelDuplexHandler, RemovableChannelHand
                     version: head.version,
                     headersNoUpdate: head.headers,
                     remoteAddress: context.channel.remoteAddress,
+                    peerCertificateChain: peerCertificateChain,
                     logger: self.application.logger,
                     byteBufferAllocator: context.channel.allocator,
                     on: context.channel.eventLoop
diff --git a/Sources/Vapor/Request/Request.swift b/Sources/Vapor/Request/Request.swift
@@ -5,6 +5,7 @@ import Logging
 import RoutingKit
 import NIOConcurrencyHelpers
 import ServiceContextModule
+import X509
 
 /// Represents an HTTP request in an application.
 public final class Request: CustomStringConvertible, Sendable {
@@ -97,6 +98,12 @@ public final class Request: CustomStringConvertible, Sendable {
         return self.remoteAddress
     }
 
+    /// The validated certificate chain. This returns nil if the peer did not authenticate with a certificate. Requires
+    /// configuring a `customCertificateVerifyCallbackWithMetadata` that performs the verification.
+    public var peerCertificateChain: ValidatedCertificateChain? {
+        return self.requestBox.withLockedValue { $0.peerCertificateChain }
+    }
+
     // MARK: Content
 
     private struct _URLQueryContainer: URLQueryContainer, Sendable {
@@ -276,6 +283,7 @@ public final class Request: CustomStringConvertible, Sendable {
         var isKeepAlive: Bool
         var route: Route?
         var parameters: Parameters
+        var peerCertificateChain: ValidatedCertificateChain?
         var byteBufferAllocator: ByteBufferAllocator
     }
     
@@ -313,7 +321,66 @@ public final class Request: CustomStringConvertible, Sendable {
             self.headers.updateContentLength(body.readableBytes)
         }
     }
-    
+
+    public convenience init(
+        application: Application,
+        method: HTTPMethod = .GET,
+        url: URI = "/",
+        version: HTTPVersion = .init(major: 1, minor: 1),
+        headers: HTTPHeaders = .init(),
+        collectedBody: ByteBuffer? = nil,
+        remoteAddress: SocketAddress? = nil,
+        peerCertificateChain: ValidatedCertificateChain?,
+        logger: Logger = .init(label: "codes.vapor.request"),
+        byteBufferAllocator: ByteBufferAllocator = ByteBufferAllocator(),
+        on eventLoop: EventLoop
+    ) {
+        self.init(
+            application: application,
+            method: method,
+            url: url,
+            version: version,
+            headersNoUpdate: headers,
+            collectedBody: collectedBody,
+            remoteAddress: remoteAddress,
+            peerCertificateChain: peerCertificateChain,
+            logger: logger,
+            byteBufferAllocator: byteBufferAllocator,
+            on: eventLoop
+        )
+        if let body = collectedBody {
+            self.headers.updateContentLength(body.readableBytes)
+        }
+    }
+
+    @_disfavoredOverload
+    public convenience init(
+        application: Application,
+        method: HTTPMethod,
+        url: URI,
+        version: HTTPVersion = .init(major: 1, minor: 1),
+        headersNoUpdate headers: HTTPHeaders = .init(),
+        collectedBody: ByteBuffer? = nil,
+        remoteAddress: SocketAddress? = nil,
+        logger: Logger = .init(label: "codes.vapor.request"),
+        byteBufferAllocator: ByteBufferAllocator = ByteBufferAllocator(),
+        on eventLoop: EventLoop
+    ) {
+        self.init(
+            application: application,
+            method: method,
+            url: url,
+            version: version,
+            headersNoUpdate: headers,
+            collectedBody: collectedBody,
+            remoteAddress: remoteAddress,
+            peerCertificateChain: nil,
+            logger: logger,
+            byteBufferAllocator: byteBufferAllocator,
+            on: eventLoop
+        )
+    }
+
     public init(
         application: Application,
         method: HTTPMethod,
@@ -322,6 +389,7 @@ public final class Request: CustomStringConvertible, Sendable {
         headersNoUpdate headers: HTTPHeaders = .init(),
         collectedBody: ByteBuffer? = nil,
         remoteAddress: SocketAddress? = nil,
+        peerCertificateChain: ValidatedCertificateChain?,
         logger: Logger = .init(label: "codes.vapor.request"),
         byteBufferAllocator: ByteBufferAllocator = ByteBufferAllocator(),
         on eventLoop: EventLoop
@@ -347,6 +415,7 @@ public final class Request: CustomStringConvertible, Sendable {
             isKeepAlive: true,
             route: nil,
             parameters: .init(),
+            peerCertificateChain: peerCertificateChain,
             byteBufferAllocator: byteBufferAllocator
         )
         self.requestBox = .init(storageBox)
@@ -359,7 +428,7 @@ public final class Request: CustomStringConvertible, Sendable {
         self._storage = .init(.init())
         self.bodyStorage = .init(bodyStorage)
     }
-    
+
     /// Automatically restores tracing serviceContext around the provided closure
     func propagateTracingIfEnabled<T>(_ closure: () throws -> T) rethrows -> T {
         if self.traceAutoPropagation {
diff --git a/Sources/Vapor/Security/ValidatedCertificateChain.swift b/Sources/Vapor/Security/ValidatedCertificateChain.swift
@@ -0,0 +1,23 @@
+import X509
+import NIOSSL
+import SwiftASN1
+
+extension NIOSSLCertificate {
+    // Convert NIOSSL certificate to X509 certificate. Currently requires to go
+    // to throught the DER representation. This only used in few cases and
+    // should not impact the performance of most users.
+    @inlinable
+    func toX509Certificate() throws -> X509.Certificate {
+        let derBytes = try self.toDERBytes()
+        return try X509.Certificate(derEncoded: derBytes)
+    }
+}
+
+extension NIOSSL.ValidatedCertificateChain {
+    // The precondition holds because the `NIOSSL.ValidatedCertificateChain` always contains one `NIOSSLCertificate`.
+    @inlinable
+    func usingX509Certificates() throws -> X509.ValidatedCertificateChain {
+        // This is safe because we this certificate chain is verified in NIOSSL.
+        return .init(uncheckedCertificateChain: try self.map { try $0.toX509Certificate() })
+    }
+}
diff --git a/Tests/VaporTests/ServerTests.swift b/Tests/VaporTests/ServerTests.swift
