SwiftNIO SSL

SwiftNIO SSL provides two primary ChannelHandlers to secure data streams within a SwiftNIO Channel:

1. NIOSSLClientHandler: Used by clients to initiate and manage TLS connections.
2. NIOSSLServerHandler: Used by servers to handle incoming TLS connections.

These handlers are initialized using a NIOSSLContext. The context is configured via a TLSConfiguration object, which defines the TLS parameters such as certificate chains and private keys.

Client TLS setup is simpler than server setup as a certificate chain and private key are typically not required. You can use TLSConfiguration.makeClientConfiguration() to create a default configuration, wrap it in a NIOSSLContext, and then use NIOSSLClientHandler in your client bootstrap.

Important: The NIOSSLClientHandler must be initialized inside the channelInitializer of your ClientBootstrap.

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)
        [...] 
    }

Use TLSConfiguration to define the security parameters for your TLS connection. Depending on your role (client or server), use the following methods:

• For Clients:
  • Use TLSConfiguration.clientDefault for a standard configuration.
  • Use makeClientConfiguration() for more granular control.
• For Servers:
  • Use makeServerConfiguration(certificateChain:privateKey:) to provide the necessary identity (certificate and private key) for the server.
• For Pre-Shared Key (PSK):
  • Use makePreSharedKeyConfiguration() when using PSK instead of certificate-based authentication.

// Example: Creating a server configuration
let config = try TLSConfiguration.makeServerConfiguration(
    certificateChain: [.certificate(myCert)],
    privateKey: .privateKey(myKey)
)

The NIOTLSServer sample application demonstrates how to implement a TLS server. You can run the sample using the Swift Package Manager. By default, it starts a server listening on ::1 (localhost) at port 4433 using TLS.

swift run NIOTLSServer

The NIOSSLHTTP1Client sample application is a tool for testing HTTPS client functionality. You can invoke it via the Swift CLI to fetch content from a server using SSL/TLS. It supports targeting specific hosts and ports via URL strings.

# Get content from a default server (::1, port 4433) using SSL/TLS
swift run NIOSSLHTTP1Client

# Get content from a specific domain (example.com, port 443) using SSL/TLS
swift run NIOSSLHTTP1Client "https://example.com"

# Get content from a specific domain and port (example.com, port 4433) using SSL/TLS
swift run NIOSSLHTTP1Client "https://example.com:4433"

The docker-compose.yaml file is not intended to be run directly. Instead, you must combine it with OS-specific and Swift-version-specific compose files to ensure the correct environment.

To run integration tests, use the following pattern: docker-compose -f docker/docker-compose.yaml -f docker/docker-compose.<os>.<swift>.yaml run test

docker-compose -f docker/docker-compose.yaml -f docker/docker-compose.1804.50.yaml run test

If certificate validation fails on macOS or iOS, you can inspect the system logs to find detailed error messages. These logs can help identify if the failure is due to certificate formatting, missing extensions, or chain validation problems.

Use the following command to view the last minute of security-related logs:

# macOS/iOS system logs often contain detailed certificate validation errors
log show --predicate 'subsystem == "com.apple.security"' --last 1m

You can override the default curve list in TLSConfiguration.curves to change the key exchange behavior.

To support only post-quantum key exchange, set the curves to [.x25519_MLKEM768].

To disable post-quantum key exchange and use only classical curves, set the curves to [.x25519, .secp256r1, .secp384r1].

// Support only post-quantum key exchange
tlsConfiguration.curves = [.x25519_MLKEM768]

// Disable post-quantum and use only classical curves
tlsConfiguration.curves = [.x25519, .secp256r1, .secp384r1]

To check if two TLSConfiguration objects are functionally equivalent or to use them in a hash-based collection, use:

• bestEffortEquals(_:): Compares two configurations, ignoring certain non-essential differences.
• bestEffortHash(into:): Computes a hash of the configuration based on its effective security parameters.