Sam Amin 03827c1a9f Close the channel when input closes during the TLS handshake (#603)
### Motivation

`NIOSSLHandler` treats input closure during the handshake as a fatal
handshake
failure: `userInboundInputClosedTriggered` synthesises
`NIOSSLError.handshakeFailed(.sslError([.eofDuringHandshake]))`, fires
it, and
forwards `ChannelEvent.inputClosed`. Unlike every other fatal handshake
failure
it then returns without closing the channel and without leaving
`.handshaking`.

When the channel has `allowRemoteHalfClosure` set, nothing else closes
it
either — NIO deliberately does not close on FIN, and a pipeline still
waiting on
ALPN may contain no handler that owns the closure. The descriptor stays
in
`CLOSE_WAIT` for the lifetime of the process, and a graceful shutdown
that waits
on all child channels never completes.

Compare `doHandshakeStep`'s `.failed` branch, which fires the same
`handshakeFailed` error and then calls `channelClose`. Both are fatal;
only one
closed.

A related hole sits underneath. `channelClose` and `channelInactive`
complete
`shutdownPromise` and `closePromise` but never `closeOutputPromise`. A
`close(mode: .output)` issued while handshaking is buffered with its
promise
stored there, and `discardBufferedActions` only fails `.write` promises,
so that
promise was never completed: the caller hangs, or trips NIO's
leaked-promise
`fatalError`. Closing the channel on this path makes it reliably
reachable.

### Modifications

- In `userInboundInputClosedTriggered`, mark `.handshaking` and
`.additionalVerification` as fatal and call `channelClose` after firing
the
error and forwarding `inputClosed`. The post-handshake ragged-EOF branch
is
  unchanged: half closure is legitimate once the connection is up.
- Complete `closeOutputPromise` in `channelClose` and `channelInactive`,
  alongside the promises they already fail.
- Added tests for input closure during the handshake (`EmbeddedChannel`
and real
  sockets), during additional peer certificate verification — including
completing the verification callback after the close — and for the
buffered
`close(mode: .output)` promise. A control test asserts that input
closure
after the handshake still fires `uncleanShutdown`, forwards
`inputClosed`, and
  leaves the channel open.

### Result

A peer that connects and half-closes before completing the handshake no
longer
leaks a descriptor. Post-handshake half closure is unaffected.

Two observable changes for callers on the mid-handshake path: buffered
writes
now fail with `ChannelError.ioOnClosedChannel` rather than the TLS
error, and
`errorCaught` fires once rather than twice. Both match the existing
`doHandshakeStep(.failed)` behaviour.
2026-09-02 13:38:37 +00:00
2024-11-15 09:52:50 +00:00
2024-10-25 09:32:23 +01:00
2023-06-06 09:06:58 -07:00
2018-01-24 12:13:14 +00:00
2018-01-24 12:13:14 +00:00
2019-02-25 16:52:26 +00:00
2026-08-14 18:37:26 +01:00
2026-04-07 12:07:47 +00:00
2021-03-09 11:14:07 +00:00

SwiftNIO SSL

SwiftNIO SSL is a Swift package that contains an implementation of TLS based on BoringSSL. This package allows users of SwiftNIO to write protocol clients and servers that use TLS to secure data in flight.

The name is inspired primarily by the names of the library this package uses (BoringSSL), and not because we don't know the name of the protocol. We know the protocol is TLS!

To get started, check out the API docs.

Using SwiftNIO SSL

SwiftNIO SSL provides two ChannelHandlers to use to secure a data stream: the NIOSSLClientHandler and the NIOSSLServerHandler. Each of these can be added to a Channel to secure the communications on that channel.

Additionally, we provide a number of low-level primitives for configuring your TLS connections. These will be shown below.

To secure a server connection, you will need a X.509 certificate chain in a file (either PEM or DER, but PEM is far easier), and the associated private key for the leaf certificate. These objects can then be wrapped up in a TLSConfiguration object that is used to initialize the ChannelHandler.

For example:

let configuration = TLSConfiguration.makeServerConfiguration(
    certificateChain: try NIOSSLCertificate.fromPEMFile("cert.pem").map { .certificate($0) },
    privateKey: try .privateKey(.init(file: "key.pem", format: .pem))
)
let sslContext = try NIOSSLContext(configuration: configuration)

let server = ServerBootstrap(group: group)
    .childChannelInitializer { channel in
        // important: The handler must be initialized _inside_ the `childChannelInitializer`
        let handler = NIOSSLServerHandler(context: sslContext)

        [...]
        channel.pipeline.syncOperations.addHandler(handler)
        [...]
    }

For clients, it is a bit simpler as there is no need to have a certificate chain or private key (though clients may have these things). Setup for clients may be done like this:

let configuration = TLSConfiguration.makeClientConfiguration()
let sslContext = try NIOSSLContext(configuration: configuration)

let client = ClientBootstrap(group: group)
    .channelInitializer { channel in
        // important: The handler must be initialized _inside_ the `channelInitializer`
        let handler = try NIOSSLClientHandler(context: sslContext)

        [...]
        channel.pipeline.syncOperations.addHandler(handler)
        [...]
    }

The most recent versions of SwiftNIO SSL support Swift 5.7 and newer. The minimum Swift version supported by SwiftNIO SSL releases are detailed below:

SwiftNIO SSL Minimum Swift Version
2.0.0 ..< 2.14.0 5.0
2.14.0 ..< 2.19.0 5.2
2.19.0 ..< 2.23.0 5.4
2.23.0 ..< 2.23.2 5.5.2
2.23.2 ..< 2.26.0 5.6
2.26.0 ..< 2.27.0 5.7
2.27.0 ..< 2.29.3 5.8
2.29.3 ..< 2.31.0 5.9
2.31.0 ..< 2.35.0 5.10
2.35.0 ..< 2.37.0 6.0
2.37.0 ..< 6.1
S
Description
Mirror of github.com/apple/swift-nio-ssl
Readme Apache-2.0
19 MiB
0 Stars 1 Watchers 0 Forks
Languages
Assembly 33.1%
C++ 31.1%
C 26.5%
Swift 6.6%
NASL 1.8%
Other 0.9%