Add support for additional TLS trust roots (#284)

Until now `TLSConfiguration` has support for specifying trust roots
using _one_ of the following:

* Path to file or directory with certificates, or
* A list of `NIOSSLCertificate` the caller has in their hand, or
* The system default.

It's potentially useful to specify a combination of these, e.g. the
system default _and_ some additional provided certificates.

This patch adds a new field, `TLSConfiguration.additionalTrustRoots`
which will be used in combination with the existing
`TLSConfiguration.trustRoots`.

`TLSConfigurationTest` needed the following changes:
* Stop using `connectInMemory` for testing successful handshakes on
  Darwin because it is not thread-safe when used with a verify callback.
* Add Extended Key Usage extenstions to the keys used in tests to
  satisfy the stricter requirements of the Security.framework verifier.

Author: simonjbeaumont

Sources/NIOSSL/SSLConnection.swift

@@ -46,7 +46,7 @@ enum AsyncOperationResult<T> {
 /// used to create the connection.
 internal final class SSLConnection {
     private let ssl: OpaquePointer
-    private let parentContext: NIOSSLContext
+    internal let parentContext: NIOSSLContext
     private var bio: ByteBufferBIO?
     internal var expectedHostname: String?
     internal var role: ConnectionRole?

Sources/NIOSSL/SSLContext.swift

@@ -159,10 +159,30 @@ public final class NIOSSLContext {
         returnCode = CNIOBoringSSL_SSL_CTX_set_cipher_list(context, configuration.cipherSuites)
         precondition(1 == returnCode)
 
+        // On non-Linux platforms, when using the platform default trust roots, we make use of a
+        // custom verify callback. If we have also been presented with additional trust roots of
+        // type `.file`, we take the opportunity now to load them in memory to avoid doing so
+        // repeatedly on the request path.
+        //
+        // However, to avoid closely coupling this code with other parts (e.g. the platform-specific
+        // concerns, and the defaulting of `trustRoots` to `.default` when `nil`), we unilaterally
+        // convert any `additionalTrustRoots` of type `.file` to `.certificates`.
+        var configuration = configuration
+        configuration.additionalTrustRoots = try configuration.additionalTrustRoots.map { trustRoots in
+            switch trustRoots {
+            case .file(let path):
+                return .certificates(try NIOSSLCertificate.fromPEMFile(path))
+            default:
+                return trustRoots
+            }
+        }
+
         // Configure certificate validation
-        try NIOSSLContext.configureCertificateValidation(context: context,
-                                                      verification: configuration.certificateVerification,
-                                                      trustRoots: configuration.trustRoots)
+        try NIOSSLContext.configureCertificateValidation(
+            context: context,
+            verification: configuration.certificateVerification,
+            trustRoots: configuration.trustRoots,
+            additionalTrustRoots: configuration.additionalTrustRoots)
 
         // Configure verification algorithms
         if let verifySignatureAlgorithms = configuration.verifySignatureAlgorithms {
@@ -189,7 +209,7 @@ public final class NIOSSLContext {
                 throw BoringSSLError.unknownError(errorStack)
             }
         }
-        
+
         // If we were given a certificate chain to use, load it and its associated private key. Before
         // we do, set up a passphrase callback if we need to.
         if let callbackManager = callbackManager {
@@ -383,10 +403,9 @@ extension NIOSSLContext {
     }
 }
 
-
 // Configuring certificate verification
 extension NIOSSLContext {
-    private static func configureCertificateValidation(context: OpaquePointer, verification: CertificateVerification, trustRoots: NIOSSLTrustRoots?) throws {
+    private static func configureCertificateValidation(context: OpaquePointer, verification: CertificateVerification, trustRoots: NIOSSLTrustRoots?, additionalTrustRoots: [NIOSSLAdditionalTrustRoots]) throws {
         // If validation is turned on, set the trust roots and turn on cert validation.
         switch verification {
         case .fullVerification, .noHostnameVerification:
@@ -398,14 +417,18 @@ extension NIOSSLContext {
             let trustParams = CNIOBoringSSL_SSL_CTX_get0_param(context)!
             CNIOBoringSSL_X509_VERIFY_PARAM_set_flags(trustParams, CUnsignedLong(X509_V_FLAG_TRUSTED_FIRST))
 
-            switch trustRoots {
-            case .some(.default), .none:
-                try NIOSSLContext.platformDefaultConfiguration(context: context)
-            case .some(.file(let f)):
-                try NIOSSLContext.loadVerifyLocations(f, context: context)
-            case .some(.certificates(let certs)):
-                try certs.forEach { try NIOSSLContext.addRootCertificate($0, context: context) }
+            func configureTrustRoots(trustRoots: NIOSSLTrustRoots) throws {
+                switch trustRoots {
+                case .default:
+                    try NIOSSLContext.platformDefaultConfiguration(context: context)
+                case .file(let path):
+                    try NIOSSLContext.loadVerifyLocations(path, context: context)
+                case .certificates(let certs):
+                    try certs.forEach { try NIOSSLContext.addRootCertificate($0, context: context) }
+                }
             }
+            try configureTrustRoots(trustRoots: trustRoots ?? .default)
+            try additionalTrustRoots.forEach { try configureTrustRoots(trustRoots: .init(from: $0)) }
         default:
             break
         }

Sources/NIOSSL/SecurityFrameworkCertificateVerification.swift

@@ -28,8 +28,12 @@ import Security
 extension SSLConnection {
     func performSecurityFrameworkValidation(promise: EventLoopPromise<NIOSSLVerificationResult>) {
         do {
+            guard case .default = self.parentContext.configuration.trustRoots ?? .default else {
+                preconditionFailure("This callback should only be used if we are using the system-default trust.")
+            }
+
             // Ok, time to kick off a validation. Let's get some certificate buffers.
-            let certificates: [SecCertificate] = try self.withPeerCertificateChainBuffers { buffers in
+            let peerCertificates: [SecCertificate] = try self.withPeerCertificateChainBuffers { buffers in
                 guard let buffers = buffers else {
                     throw NIOSSLError.unableToValidateCertificate
                 }
@@ -47,11 +51,33 @@ extension SSLConnection {
             var trust: SecTrust? = nil
             var result: OSStatus
             let policy = SecPolicyCreateSSL(self.role! == .client, self.expectedHostname as CFString?)
-            result = SecTrustCreateWithCertificates(certificates as CFArray, policy, &trust)
+            result = SecTrustCreateWithCertificates(peerCertificates as CFArray, policy, &trust)
             guard result == errSecSuccess, let actualTrust = trust else {
                 throw NIOSSLError.unableToValidateCertificate
             }
 
+            // If there are additional trust roots then we need to add them to the SecTrust as anchors.
+            let additionalAnchorCertificates: [SecCertificate] = try self.parentContext.configuration.additionalTrustRoots.flatMap { trustRoots -> [NIOSSLCertificate] in
+                guard case .certificates(let certs) = trustRoots else {
+                    preconditionFailure("This callback happens on the request path, file-based additional trust roots should be pre-loaded when creating the SSLContext.")
+                }
+                return certs
+            }.map {
+                guard let secCert = SecCertificateCreateWithData(nil, Data(try $0.toDERBytes()) as CFData) else {
+                    throw NIOSSLError.failedToLoadCertificate
+                }
+                return secCert
+            }
+            if !additionalAnchorCertificates.isEmpty {
+                // To use additional anchors _and_ the built-in ones we must reenable the built-in ones expicitly.
+                guard SecTrustSetAnchorCertificatesOnly(actualTrust, false) == errSecSuccess else {
+                    throw NIOSSLError.failedToLoadCertificate
+                }
+                guard SecTrustSetAnchorCertificates(actualTrust, additionalAnchorCertificates as CFArray) == errSecSuccess else {
+                    throw NIOSSLError.failedToLoadCertificate
+                }
+            }
+
             // We create a DispatchQueue here to be called back on, as this validation may perform network activity.
             let callbackQueue = DispatchQueue(label: "io.swiftnio.ssl.validationCallbackQueue")
 

Sources/NIOSSL/TLSConfiguration.swift

@@ -42,9 +42,43 @@ public enum NIOSSLPrivateKeySource {
 
 /// Places NIOSSL can obtain a trust store from.
 public enum NIOSSLTrustRoots {
+    /// Path to either a file of CA certificates in PEM format, or a directory containing CA certificates in PEM format.
+    ///
+    /// If a path to a file is provided, the file can contain several CA certificates identified by
+    ///
+    ///     -----BEGIN CERTIFICATE-----
+    ///     ... (CA certificate in base64 encoding) ...
+    ///     -----END CERTIFICATE-----
+    ///
+    /// sequences. Before, between, and after the certificates, text is allowed which can be used e.g.
+    /// for descriptions of the certificates.
+    ///
+    /// If a path to a directory is provided, the files each contain one CA certificate in PEM format.
     case file(String)
+
+    /// A list of certificates.
     case certificates([NIOSSLCertificate])
+
+    /// The system default root of trust.
     case `default`
+
+    internal init(from trustRoots: NIOSSLAdditionalTrustRoots) {
+        switch trustRoots {
+        case .file(let path):
+            self = .file(path)
+        case .certificates(let certs):
+            self = .certificates(certs)
+        }
+    }
+}
+
+/// Places NIOSSL can obtain additional trust roots from.
+public enum NIOSSLAdditionalTrustRoots {
+    /// See `NIOSSLTrustRoots.file`
+    case file(String)
+
+    /// See `NIOSSLTrustRoots.certificates`
+    case certificates([NIOSSLCertificate])
 }
 
 /// Formats NIOSSL supports for serializing keys and certificates.
@@ -179,8 +213,14 @@ public struct TLSConfiguration {
 
     /// The trust roots to use to validate certificates. This only needs to be provided if you intend to validate
     /// certificates.
+    ///
+    /// - NOTE: If certificate validation is enabled and `trustRoots` is `nil` then the system default root of
+    /// trust is used (as if `trustRoots` had been explicitly set to `.default`).
     public var trustRoots: NIOSSLTrustRoots?
 
+    /// Additional trust roots to use to validate certificates, used in addition to `trustRoots`.
+    public var additionalTrustRoots: [NIOSSLAdditionalTrustRoots]
+
     /// The certificates to offer during negotiation. If not present, no certificates will be offered.
     public var certificateChain: [NIOSSLCertificateSource]
 
@@ -224,14 +264,16 @@ public struct TLSConfiguration {
                  applicationProtocols: [String],
                  shutdownTimeout: TimeAmount,
                  keyLogCallback: NIOSSLKeyLogCallback?,
-                 renegotiationSupport: NIORenegotiationSupport) {
+                 renegotiationSupport: NIORenegotiationSupport,
+                 additionalTrustRoots: [NIOSSLAdditionalTrustRoots]) {
         self.cipherSuites = cipherSuites
         self.verifySignatureAlgorithms = verifySignatureAlgorithms
         self.signingSignatureAlgorithms = signingSignatureAlgorithms
         self.minimumTLSVersion = minimumTLSVersion
         self.maximumTLSVersion = maximumTLSVersion
         self.certificateVerification = certificateVerification
         self.trustRoots = trustRoots
+        self.additionalTrustRoots = additionalTrustRoots
         self.certificateChain = certificateChain
         self.privateKey = privateKey
         self.encodedApplicationProtocols = []
@@ -267,7 +309,8 @@ public struct TLSConfiguration {
                                 applicationProtocols: applicationProtocols,
                                 shutdownTimeout: shutdownTimeout,
                                 keyLogCallback: keyLogCallback,
-                                renegotiationSupport: .none)  // Servers never support renegotiation: there's no point.
+                                renegotiationSupport: .none,  // Servers never support renegotiation: there's no point.
+                                additionalTrustRoots: [])
     }
 
     /// Create a TLS configuration for use with server-side contexts.
@@ -298,7 +341,41 @@ public struct TLSConfiguration {
                                 applicationProtocols: applicationProtocols,
                                 shutdownTimeout: shutdownTimeout,
                                 keyLogCallback: keyLogCallback,
-                                renegotiationSupport: .none)  // Servers never support renegotiation: there's no point.
+                                renegotiationSupport: .none,  // Servers never support renegotiation: there's no point.
+                                additionalTrustRoots: [])
+    }
+
+    /// Create a TLS configuration for use with server-side contexts.
+    ///
+    /// This provides sensible defaults while requiring that you provide any data that is necessary
+    /// for server-side function. For client use, try `forClient` instead.
+    public static func forServer(certificateChain: [NIOSSLCertificateSource],
+                                 privateKey: NIOSSLPrivateKeySource,
+                                 cipherSuites: String = defaultCipherSuites,
+                                 verifySignatureAlgorithms: [SignatureAlgorithm]? = nil,
+                                 signingSignatureAlgorithms: [SignatureAlgorithm]? = nil,
+                                 minimumTLSVersion: TLSVersion = .tlsv1,
+                                 maximumTLSVersion: TLSVersion? = nil,
+                                 certificateVerification: CertificateVerification = .none,
+                                 trustRoots: NIOSSLTrustRoots = .default,
+                                 applicationProtocols: [String] = [],
+                                 shutdownTimeout: TimeAmount = .seconds(5),
+                                 keyLogCallback: NIOSSLKeyLogCallback? = nil,
+                                 additionalTrustRoots: [NIOSSLAdditionalTrustRoots]) -> TLSConfiguration {
+        return TLSConfiguration(cipherSuites: cipherSuites,
+                                verifySignatureAlgorithms: verifySignatureAlgorithms,
+                                signingSignatureAlgorithms: signingSignatureAlgorithms,
+                                minimumTLSVersion: minimumTLSVersion,
+                                maximumTLSVersion: maximumTLSVersion,
+                                certificateVerification: certificateVerification,
+                                trustRoots: trustRoots,
+                                certificateChain: certificateChain,
+                                privateKey: privateKey,
+                                applicationProtocols: applicationProtocols,
+                                shutdownTimeout: shutdownTimeout,
+                                keyLogCallback: keyLogCallback,
+                                renegotiationSupport: .none,  // Servers never support renegotiation: there's no point.
+                                additionalTrustRoots: additionalTrustRoots)
     }
 
     /// Creates a TLS configuration for use with client-side contexts.
@@ -327,7 +404,8 @@ public struct TLSConfiguration {
                                 applicationProtocols: applicationProtocols,
                                 shutdownTimeout: shutdownTimeout,
                                 keyLogCallback: keyLogCallback,
-                                renegotiationSupport: .none)  // Default value is here for backward-compatibility.
+                                renegotiationSupport: .none,  // Default value is here for backward-compatibility.
+                                additionalTrustRoots: [])
     }
 
 
@@ -358,7 +436,8 @@ public struct TLSConfiguration {
                                 applicationProtocols: applicationProtocols,
                                 shutdownTimeout: shutdownTimeout,
                                 keyLogCallback: keyLogCallback,
-                                renegotiationSupport: renegotiationSupport)
+                                renegotiationSupport: renegotiationSupport,
+                                additionalTrustRoots: [])
     }
 
     /// Creates a TLS configuration for use with client-side contexts.
@@ -390,6 +469,41 @@ public struct TLSConfiguration {
                                 applicationProtocols: applicationProtocols,
                                 shutdownTimeout: shutdownTimeout,
                                 keyLogCallback: keyLogCallback,
-                                renegotiationSupport: renegotiationSupport)
+                                renegotiationSupport: renegotiationSupport,
+                                additionalTrustRoots: [])
+    }
+
+    /// Creates a TLS configuration for use with client-side contexts.
+    ///
+    /// This provides sensible defaults, and can be used without customisation. For server-side
+    /// contexts, you should use `forServer` instead.
+    public static func forClient(cipherSuites: String = defaultCipherSuites,
+                                 verifySignatureAlgorithms: [SignatureAlgorithm]? = nil,
+                                 signingSignatureAlgorithms: [SignatureAlgorithm]? = nil,
+                                 minimumTLSVersion: TLSVersion = .tlsv1,
+                                 maximumTLSVersion: TLSVersion? = nil,
+                                 certificateVerification: CertificateVerification = .fullVerification,
+                                 trustRoots: NIOSSLTrustRoots = .default,
+                                 certificateChain: [NIOSSLCertificateSource] = [],
+                                 privateKey: NIOSSLPrivateKeySource? = nil,
+                                 applicationProtocols: [String] = [],
+                                 shutdownTimeout: TimeAmount = .seconds(5),
+                                 keyLogCallback: NIOSSLKeyLogCallback? = nil,
+                                 renegotiationSupport: NIORenegotiationSupport = .none,
+                                 additionalTrustRoots: [NIOSSLAdditionalTrustRoots]) -> TLSConfiguration {
+        return TLSConfiguration(cipherSuites: cipherSuites,
+                                verifySignatureAlgorithms: verifySignatureAlgorithms,
+                                signingSignatureAlgorithms: signingSignatureAlgorithms,
+                                minimumTLSVersion: minimumTLSVersion,
+                                maximumTLSVersion: maximumTLSVersion,
+                                certificateVerification: certificateVerification,
+                                trustRoots: trustRoots,
+                                certificateChain: certificateChain,
+                                privateKey: privateKey,
+                                applicationProtocols: applicationProtocols,
+                                shutdownTimeout: shutdownTimeout,
+                                keyLogCallback: keyLogCallback,
+                                renegotiationSupport: renegotiationSupport,
+                                additionalTrustRoots: additionalTrustRoots)
     }
 }

Tests/NIOSSLTests/NIOSSLTestHelpers.swift

@@ -474,6 +474,7 @@ func generateSelfSignedCert() -> (NIOSSLCertificate, NIOSSLPrivateKey) {
     addExtension(x509: x, nid: NID_basic_constraints, value: "critical,CA:FALSE")
     addExtension(x509: x, nid: NID_subject_key_identifier, value: "hash")
     addExtension(x509: x, nid: NID_subject_alt_name, value: "DNS:localhost")
+    addExtension(x509: x, nid: NID_ext_key_usage, value: "critical,serverAuth,clientAuth")
 
     CNIOBoringSSL_X509_sign(x, pkey, CNIOBoringSSL_EVP_sha256())