fix(plugin-cassandra): apply client certificate and key passphrase to SSL connections

datlechin · datlechin · commit caeb76ff80ca · 2026-05-30T18:31:12.000+07:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -48,6 +48,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Opening a table (Return or double-click in the sidebar) moves keyboard focus into the data grid so you can navigate cells with the arrow keys. Arrowing the sidebar still previews tables without taking focus. (#1490)
 - Moving a connection into or out of a group now syncs across devices, instead of leaving it ungrouped on your other Macs.
 - Opening a table on a connection with many tables no longer stalls for several seconds while autocomplete and table metadata load. Background schema introspection now runs on separate connections instead of waiting behind, or blocking, the query that fills the grid. (#1483)
+- Cassandra SSL connections that use a client certificate now have a Key Passphrase field for an encrypted private key, and report a clear "key is encrypted" or "passphrase is incorrect" message instead of a generic handshake failure. The passphrase is stored in the Keychain. (#1487)
 
 ## [0.46.0] - 2026-05-28
 
diff --git a/Plugins/CassandraDriverPlugin/CassandraPlugin.swift b/Plugins/CassandraDriverPlugin/CassandraPlugin.swift
@@ -137,7 +137,10 @@ private actor CassandraConnectionActor {
         password: String?,
         keyspace: String?,
         sslMode: SSLMode,
-        sslCaCertPath: String?
+        sslCaCertPath: String?,
+        sslClientCertPath: String?,
+        sslClientKeyPath: String?,
+        sslClientKeyPassphrase: String?
     ) throws {
         cluster = cass_cluster_new()
         guard let cluster else {
@@ -183,6 +186,21 @@ private actor CassandraConnectionActor {
                 }
             }
 
+            let trimmedClientCertPath = sslClientCertPath?.trimmingCharacters(in: .whitespaces) ?? ""
+            let trimmedClientKeyPath = sslClientKeyPath?.trimmingCharacters(in: .whitespaces) ?? ""
+            if !trimmedClientCertPath.isEmpty || !trimmedClientKeyPath.isEmpty {
+                try applyClientCertificate(
+                    to: ssl,
+                    certPath: trimmedClientCertPath,
+                    keyPath: trimmedClientKeyPath,
+                    keyPassphrase: sslClientKeyPassphrase
+                ) {
+                    cass_ssl_free(ssl)
+                    cass_cluster_free(cluster)
+                    self.cluster = nil
+                }
+            }
+
             cass_cluster_set_ssl(cluster, ssl)
             cass_ssl_free(ssl)
         }
@@ -235,6 +253,49 @@ private actor CassandraConnectionActor {
         Self.logger.info("Connected to Cassandra at \(host):\(port)")
     }
 
+    private func applyClientCertificate(
+        to ssl: OpaquePointer,
+        certPath: String,
+        keyPath: String,
+        keyPassphrase: String?,
+        cleanup: () -> Void
+    ) throws {
+        guard !certPath.isEmpty else {
+            cleanup()
+            throw SSLHandshakeError.clientCertRequired(serverMessage: "A client certificate is required when a client key is set")
+        }
+        guard !keyPath.isEmpty else {
+            cleanup()
+            throw SSLHandshakeError.clientCertRequired(serverMessage: "A client key is required when a client certificate is set")
+        }
+
+        guard let certData = FileManager.default.contents(atPath: certPath),
+              let certString = String(data: certData, encoding: .utf8) else {
+            cleanup()
+            throw SSLHandshakeError.clientCertRequired(serverMessage: "Could not read client certificate at \(certPath)")
+        }
+        let certResult = cass_ssl_set_cert(ssl, certString)
+        if certResult != CASS_OK {
+            cleanup()
+            throw SSLHandshakeError.clientCertRequired(serverMessage: "Client certificate at \(certPath) is not a valid PEM")
+        }
+
+        guard let keyData = FileManager.default.contents(atPath: keyPath),
+              let keyString = String(data: keyData, encoding: .utf8) else {
+            cleanup()
+            throw SSLHandshakeError.clientCertRequired(serverMessage: "Could not read client key at \(keyPath)")
+        }
+        let passphrase = keyPassphrase?.isEmpty == false ? keyPassphrase : nil
+        let keyResult = cass_ssl_set_private_key(ssl, keyString, passphrase)
+        if keyResult != CASS_OK {
+            cleanup()
+            if passphrase == nil {
+                throw SSLHandshakeError.clientKeyPassphraseRequired(serverMessage: "The client key at \(keyPath) is encrypted. Enter its passphrase.")
+            }
+            throw SSLHandshakeError.clientKeyPassphraseIncorrect(serverMessage: "The passphrase for the client key at \(keyPath) is incorrect.")
+        }
+    }
+
     func close() {
         if let session {
             let closeFuture = cass_session_close(session)
@@ -921,6 +982,9 @@ internal final class CassandraPluginDriver: PluginDatabaseDriver, @unchecked Sen
         let keyspace = config.database.isEmpty ? nil : config.database
         let legacyCaPath = config.additionalFields["sslCaCertPath"]
         let resolvedCaPath = config.ssl.caCertificatePath.isEmpty ? legacyCaPath : config.ssl.caCertificatePath
+        let clientCertPath = config.ssl.clientCertificatePath.isEmpty ? nil : config.ssl.clientCertificatePath
+        let clientKeyPath = config.ssl.clientKeyPath.isEmpty ? nil : config.ssl.clientKeyPath
+        let clientKeyPassphrase = config.additionalFields["sslClientKeyPassphrase"]
 
         try await connectionActor.connect(
             host: config.host,
@@ -929,7 +993,10 @@ internal final class CassandraPluginDriver: PluginDatabaseDriver, @unchecked Sen
             password: config.password.isEmpty ? nil : config.password,
             keyspace: keyspace,
             sslMode: config.ssl.mode,
-            sslCaCertPath: resolvedCaPath
+            sslCaCertPath: resolvedCaPath,
+            sslClientCertPath: clientCertPath,
+            sslClientKeyPath: clientKeyPath,
+            sslClientKeyPassphrase: clientKeyPassphrase
         )
 
         if let keyspace {
diff --git a/Plugins/TableProPluginKit/SSLHandshakeError.swift b/Plugins/TableProPluginKit/SSLHandshakeError.swift
@@ -8,6 +8,8 @@ public enum SSLHandshakeError: Error, LocalizedError, Sendable {
     case clientCertRequired(serverMessage: String)
     case cipherMismatch(serverMessage: String)
     case unknown(serverMessage: String)
+    case clientKeyPassphraseRequired(serverMessage: String)
+    case clientKeyPassphraseIncorrect(serverMessage: String)
 
     public var serverMessage: String {
         switch self {
@@ -16,6 +18,8 @@ public enum SSLHandshakeError: Error, LocalizedError, Sendable {
              .untrustedCertificate(let msg),
              .hostnameMismatch(let msg),
              .clientCertRequired(let msg),
+             .clientKeyPassphraseRequired(let msg),
+             .clientKeyPassphraseIncorrect(let msg),
              .cipherMismatch(let msg),
              .unknown(let msg):
             return msg
@@ -34,6 +38,10 @@ public enum SSLHandshakeError: Error, LocalizedError, Sendable {
             return String(localized: "The server's TLS certificate does not match the hostname being connected to.")
         case .clientCertRequired:
             return String(localized: "The server requires a client certificate for TLS mutual authentication.")
+        case .clientKeyPassphraseRequired:
+            return String(localized: "The client private key is encrypted and needs a passphrase.")
+        case .clientKeyPassphraseIncorrect:
+            return String(localized: "The passphrase for the client private key is incorrect.")
         case .cipherMismatch:
             return String(localized: "The server and TablePro could not agree on a TLS cipher or protocol version.")
         case .unknown:
@@ -86,6 +94,10 @@ public enum SSLHandshakeError: Error, LocalizedError, Sendable {
             return String(localized: "Switch SSL Mode to Verify CA (validates the CA chain but skips hostname check), or update the host field to match the certificate.")
         case .clientCertRequired:
             return String(localized: "Provide the client certificate and key paths in the SSL tab.")
+        case .clientKeyPassphraseRequired:
+            return String(localized: "Open the connection editor, switch to the SSL tab, and enter the Key Passphrase.")
+        case .clientKeyPassphraseIncorrect:
+            return String(localized: "Open the connection editor, switch to the SSL tab, and correct the Key Passphrase.")
         case .cipherMismatch:
             return String(localized: "Update the server's TLS configuration or use a newer database server version that supports modern ciphers.")
         case .unknown:
diff --git a/TablePro/Core/Database/DatabaseDriver.swift b/TablePro/Core/Database/DatabaseDriver.swift
@@ -432,6 +432,10 @@ enum DatabaseDriverFactory {
         }
         var ssl = connection.sslConfig
         var additionalFields = buildAdditionalFields(for: connection, plugin: plugin)
+        if let sslClientKeyPassphrase = ConnectionStorage.shared.loadSSLClientKeyPassphrase(for: connection.id),
+           !sslClientKeyPassphrase.isEmpty {
+            additionalFields["sslClientKeyPassphrase"] = sslClientKeyPassphrase
+        }
         if connection.usesAWSIAM {
             if ssl.mode == .disabled || ssl.mode == .preferred {
                 ssl.mode = .required
diff --git a/TablePro/Core/Plugins/PluginMetadataRegistry+RegistryDefaults.swift b/TablePro/Core/Plugins/PluginMetadataRegistry+RegistryDefaults.swift
@@ -882,7 +882,8 @@ extension PluginMetadataRegistry {
                     supportsAddIndex: false,
                     supportsDropIndex: false,
                     supportsModifyPrimaryKey: false,
-                    supportsOpportunisticTLS: false
+                    supportsOpportunisticTLS: false,
+                    supportsClientKeyPassphrase: true
                 ),
                 schema: PluginMetadataSnapshot.SchemaInfo(
                     defaultSchemaName: "public",
@@ -944,7 +945,8 @@ extension PluginMetadataRegistry {
                     supportsAddIndex: false,
                     supportsDropIndex: false,
                     supportsModifyPrimaryKey: false,
-                    supportsOpportunisticTLS: false
+                    supportsOpportunisticTLS: false,
+                    supportsClientKeyPassphrase: true
                 ),
                 schema: PluginMetadataSnapshot.SchemaInfo(
                     defaultSchemaName: "public",
diff --git a/TablePro/Core/Plugins/PluginMetadataRegistry.swift b/TablePro/Core/Plugins/PluginMetadataRegistry.swift
@@ -57,6 +57,7 @@ struct PluginMetadataSnapshot: Sendable {
         var defaultSSLMode: SSLMode = .disabled
         var supportsOpportunisticTLS: Bool = true
         var supportsCloudflareTunnel: Bool = true
+        var supportsClientKeyPassphrase: Bool = false
 
         static let defaults = CapabilityFlags(
             supportsSchemaSwitching: false,
@@ -938,7 +939,8 @@ final class PluginMetadataRegistry: @unchecked Sendable {
                 supportsModifyPrimaryKey: driverType.supportsModifyPrimaryKey,
                 defaultSSLMode: existingSnapshot?.capabilities.defaultSSLMode ?? .disabled,
                 supportsOpportunisticTLS: existingSnapshot?.capabilities.supportsOpportunisticTLS ?? true,
-                supportsCloudflareTunnel: driverType.supportsSSH
+                supportsCloudflareTunnel: driverType.supportsSSH,
+                supportsClientKeyPassphrase: existingSnapshot?.capabilities.supportsClientKeyPassphrase ?? false
             ),
             schema: PluginMetadataSnapshot.SchemaInfo(
                 defaultSchemaName: driverType.defaultSchemaName,
diff --git a/TablePro/Core/Services/Export/ConnectionExportService.swift b/TablePro/Core/Services/Export/ConnectionExportService.swift
@@ -266,6 +266,7 @@ enum ConnectionExportService {
             let password = ConnectionStorage.shared.loadPassword(for: connection.id)
             let sshPassword = ConnectionStorage.shared.loadSSHPassword(for: connection.id)
             let keyPassphrase = ConnectionStorage.shared.loadKeyPassphrase(for: connection.id)
+            let sslClientKeyPassphrase = ConnectionStorage.shared.loadSSLClientKeyPassphrase(for: connection.id)
             let totpSecret = ConnectionStorage.shared.loadTOTPSecret(for: connection.id)
 
             // Collect plugin-specific secure fields
@@ -291,13 +292,15 @@ enum ConnectionExportService {
             }
 
             let hasAnyCredential = password != nil || sshPassword != nil
-                || keyPassphrase != nil || totpSecret != nil || pluginSecureFields != nil
+                || keyPassphrase != nil || sslClientKeyPassphrase != nil
+                || totpSecret != nil || pluginSecureFields != nil
 
             if hasAnyCredential {
                 credentialsMap[String(index)] = ExportableCredentials(
                     password: password,
                     sshPassword: sshPassword,
                     keyPassphrase: keyPassphrase,
+                    sslClientKeyPassphrase: sslClientKeyPassphrase,
                     totpSecret: totpSecret,
                     pluginSecureFields: pluginSecureFields
                 )
@@ -376,6 +379,9 @@ enum ConnectionExportService {
             if let keyPassphrase = creds.keyPassphrase {
                 ConnectionStorage.shared.saveKeyPassphrase(keyPassphrase, for: connectionId)
             }
+            if let sslClientKeyPassphrase = creds.sslClientKeyPassphrase {
+                ConnectionStorage.shared.saveSSLClientKeyPassphrase(sslClientKeyPassphrase, for: connectionId)
+            }
             if let totpSecret = creds.totpSecret {
                 ConnectionStorage.shared.saveTOTPSecret(totpSecret, for: connectionId)
             }
diff --git a/TablePro/Core/Services/Export/ForeignApp/BeekeeperStudioImporter.swift b/TablePro/Core/Services/Export/ForeignApp/BeekeeperStudioImporter.swift
@@ -247,6 +247,7 @@ struct BeekeeperStudioImporter: ForeignAppImporter {
             password: decrypt(row.password, key: key),
             sshPassword: decrypt(row.sshPassword, key: key),
             keyPassphrase: decrypt(row.sshKeyfilePassword, key: key),
+            sslClientKeyPassphrase: nil,
             totpSecret: nil,
             pluginSecureFields: nil
         )
diff --git a/TablePro/Core/Services/Export/ForeignApp/DBeaverImporter.swift b/TablePro/Core/Services/Export/ForeignApp/DBeaverImporter.swift
@@ -371,6 +371,7 @@ struct DBeaverImporter: ForeignAppImporter {
             password: password,
             sshPassword: sshPassword,
             keyPassphrase: nil,
+            sslClientKeyPassphrase: nil,
             totpSecret: nil,
             pluginSecureFields: nil
         )
diff --git a/TablePro/Core/Services/Export/ForeignApp/DataGripImporter.swift b/TablePro/Core/Services/Export/ForeignApp/DataGripImporter.swift
@@ -156,6 +156,7 @@ struct DataGripImporter: ForeignAppImporter {
                 password: password,
                 sshPassword: sshPassword,
                 keyPassphrase: keyPassphrase,
+                sslClientKeyPassphrase: nil,
                 totpSecret: nil,
                 pluginSecureFields: nil
             ),
diff --git a/TablePro/Core/Services/Export/ForeignApp/SequelAceImporter.swift b/TablePro/Core/Services/Export/ForeignApp/SequelAceImporter.swift
@@ -286,6 +286,7 @@ struct SequelAceImporter: ForeignAppImporter {
             password: dbPassword,
             sshPassword: sshPassword,
             keyPassphrase: nil,
+            sslClientKeyPassphrase: nil,
             totpSecret: nil,
             pluginSecureFields: nil
         )
diff --git a/TablePro/Core/Services/Export/ForeignApp/TablePlusImporter.swift b/TablePro/Core/Services/Export/ForeignApp/TablePlusImporter.swift
@@ -261,6 +261,7 @@ struct TablePlusImporter: ForeignAppImporter {
             password: dbPassword,
             sshPassword: sshPassword,
             keyPassphrase: keyPassphrase,
+            sslClientKeyPassphrase: nil,
             totpSecret: nil,
             pluginSecureFields: nil
         )
diff --git a/TablePro/Core/Storage/ConnectionStorage.swift b/TablePro/Core/Storage/ConnectionStorage.swift
@@ -210,6 +210,7 @@ final class ConnectionStorage {
         deletePassword(for: connection.id)
         deleteSSHPassword(for: connection.id)
         deleteKeyPassphrase(for: connection.id)
+        deleteSSLClientKeyPassphrase(for: connection.id)
         deleteTOTPSecret(for: connection.id)
         deleteCloudflareTokenId(for: connection.id)
         deleteCloudflareTokenSecret(for: connection.id)
@@ -240,6 +241,7 @@ final class ConnectionStorage {
             deletePassword(for: conn.id)
             deleteSSHPassword(for: conn.id)
             deleteKeyPassphrase(for: conn.id)
+            deleteSSLClientKeyPassphrase(for: conn.id)
             deleteTOTPSecret(for: conn.id)
             deleteCloudflareTokenId(for: conn.id)
             deleteCloudflareTokenSecret(for: conn.id)
@@ -306,6 +308,9 @@ final class ConnectionStorage {
         if let keyPassphrase = loadKeyPassphrase(for: connection.id) {
             saveKeyPassphrase(keyPassphrase, for: newId)
         }
+        if let sslKeyPassphrase = loadSSLClientKeyPassphrase(for: connection.id) {
+            saveSSLClientKeyPassphrase(sslKeyPassphrase, for: newId)
+        }
         if let totpSecret = loadTOTPSecret(for: connection.id) {
             saveTOTPSecret(totpSecret, for: newId)
         }
@@ -371,6 +376,23 @@ final class ConnectionStorage {
         keychain.delete(forKey: key)
     }
 
+    // MARK: - SSL Client Key Passphrase Storage
+
+    func saveSSLClientKeyPassphrase(_ passphrase: String, for connectionId: UUID) {
+        let key = "com.TablePro.sslkeypassphrase.\(connectionId.uuidString)"
+        keychain.writeString(passphrase, forKey: key)
+    }
+
+    func loadSSLClientKeyPassphrase(for connectionId: UUID) -> String? {
+        let key = "com.TablePro.sslkeypassphrase.\(connectionId.uuidString)"
+        return resolveString(.init(label: "SSL client key passphrase", connectionId: connectionId), forKey: key)
+    }
+
+    func deleteSSLClientKeyPassphrase(for connectionId: UUID) {
+        let key = "com.TablePro.sslkeypassphrase.\(connectionId.uuidString)"
+        keychain.delete(forKey: key)
+    }
+
     // MARK: - Plugin Secure Field Storage
 
     func savePluginSecureField(_ value: String, fieldId: String, for connectionId: UUID) {
diff --git a/TablePro/Models/Connection/ConnectionExport.swift b/TablePro/Models/Connection/ConnectionExport.swift
@@ -136,6 +136,7 @@ struct ExportableCredentials: Codable {
     let password: String?
     let sshPassword: String?
     let keyPassphrase: String?
+    let sslClientKeyPassphrase: String?
     let totpSecret: String?
     let pluginSecureFields: [String: String]?
 }
diff --git a/TablePro/Models/Connection/DatabaseConnection.swift b/TablePro/Models/Connection/DatabaseConnection.swift
@@ -113,6 +113,10 @@ extension DatabaseType {
         PluginMetadataRegistry.shared.snapshot(forTypeId: rawValue)?.capabilities.supportsOpportunisticTLS ?? true
     }
 
+    var supportsClientKeyPassphrase: Bool {
+        PluginMetadataRegistry.shared.snapshot(forTypeId: rawValue)?.capabilities.supportsClientKeyPassphrase ?? false
+    }
+
     var sslPaneTooltip: String {
         switch rawValue {
         case "PostgreSQL", "Redshift", "CockroachDB":
diff --git a/TablePro/Views/Connection/ConnectionSSLView.swift b/TablePro/Views/Connection/ConnectionSSLView.swift
@@ -15,6 +15,7 @@ struct ConnectionSSLView: View {
     @Binding var sslCaCertPath: String
     @Binding var sslClientCertPath: String
     @Binding var sslClientKeyPath: String
+    @Binding var sslClientKeyPassphrase: String
 
     private var supportsPerConnectionCertPaths: Bool { databaseType != .mssql }
 
@@ -103,6 +104,14 @@ struct ConnectionSSLView: View {
                                 .controlSize(.small)
                             }
                         }
+                        if databaseType.supportsClientKeyPassphrase,
+                           !sslClientKeyPath.trimmingCharacters(in: .whitespaces).isEmpty {
+                            LabeledContent(String(localized: "Key Passphrase")) {
+                                SecureField(
+                                    "", text: $sslClientKeyPassphrase,
+                                    prompt: Text(String(localized: "Required only for an encrypted key")))
+                            }
+                        }
                     } header: {
                         Text(String(localized: "Client Certificates"))
                     } footer: {
diff --git a/TablePro/Views/ConnectionForm/ConnectionFormCoordinator.swift b/TablePro/Views/ConnectionForm/ConnectionFormCoordinator.swift
diff --git a/TablePro/Views/ConnectionForm/Panes/SSLPaneView.swift b/TablePro/Views/ConnectionForm/Panes/SSLPaneView.swift
diff --git a/TablePro/Views/ConnectionForm/ViewModels/SSLPaneViewModel.swift b/TablePro/Views/ConnectionForm/ViewModels/SSLPaneViewModel.swift
diff --git a/TableProTests/Plugins/SSLConfigurationTests.swift b/TableProTests/Plugins/SSLConfigurationTests.swift
diff --git a/TableProTests/Plugins/SSLHandshakeErrorTests.swift b/TableProTests/Plugins/SSLHandshakeErrorTests.swift
diff --git a/docs/databases/cassandra.mdx b/docs/databases/cassandra.mdx
diff --git a/docs/features/ssl.mdx b/docs/features/ssl.mdx

Original file line number	Diff line number	Diff line change
`@@ -247,6 +247,7 @@ struct BeekeeperStudioImporter: ForeignAppImporter {`
`247`	`247`	`password: decrypt(row.password, key: key),`
`248`	`248`	`sshPassword: decrypt(row.sshPassword, key: key),`
`249`	`249`	`keyPassphrase: decrypt(row.sshKeyfilePassword, key: key),`
	`250`	`+ sslClientKeyPassphrase: nil,`
`250`	`251`	`totpSecret: nil,`
`251`	`252`	`pluginSecureFields: nil`
`252`	`253`	`)`
Original file line number	Diff line number	Diff line change
`@@ -371,6 +371,7 @@ struct DBeaverImporter: ForeignAppImporter {`
`371`	`371`	`password: password,`
`372`	`372`	`sshPassword: sshPassword,`
`373`	`373`	`keyPassphrase: nil,`
	`374`	`+ sslClientKeyPassphrase: nil,`
`374`	`375`	`totpSecret: nil,`
`375`	`376`	`pluginSecureFields: nil`
`376`	`377`	`)`