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

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

* fix(plugin-cassandra): distinguish a malformed client key from an encrypted one

Author: datlechin

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
 

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,60 @@ 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.clientKeyInvalid(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()
+            throw Self.privateKeyLoadError(keyPEM: keyString, hasPassphrase: passphrase != nil, keyPath: keyPath)
+        }
+    }
+
+    static func isEncryptedPrivateKey(_ pem: String) -> Bool {
+        pem.contains("ENCRYPTED PRIVATE KEY") || (pem.contains("Proc-Type:") && pem.contains("ENCRYPTED"))
+    }
+
+    static func privateKeyLoadError(keyPEM: String, hasPassphrase: Bool, keyPath: String) -> SSLHandshakeError {
+        guard isEncryptedPrivateKey(keyPEM) else {
+            return .clientKeyInvalid(serverMessage: "The client key at \(keyPath) is not a valid private key")
+        }
+        if hasPassphrase {
+            return .clientKeyPassphraseIncorrect(serverMessage: "The passphrase for the client key at \(keyPath) is incorrect")
+        }
+        return .clientKeyPassphraseRequired(serverMessage: "The client key at \(keyPath) is encrypted. Enter its passphrase.")
+    }
+
     func close() {
         if let session {
             let closeFuture = cass_session_close(session)
@@ -921,6 +993,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 +1004,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 {

Plugins/TableProPluginKit/SSLHandshakeError.swift

@@ -8,6 +8,9 @@ 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)
+    case clientKeyInvalid(serverMessage: String)
 
     public var serverMessage: String {
         switch self {
@@ -16,6 +19,9 @@ public enum SSLHandshakeError: Error, LocalizedError, Sendable {
              .untrustedCertificate(let msg),
              .hostnameMismatch(let msg),
              .clientCertRequired(let msg),
+             .clientKeyPassphraseRequired(let msg),
+             .clientKeyPassphraseIncorrect(let msg),
+             .clientKeyInvalid(let msg),
              .cipherMismatch(let msg),
              .unknown(let msg):
             return msg
@@ -34,6 +40,12 @@ 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 .clientKeyInvalid:
+            return String(localized: "The client private key could not be read. It may be malformed or in an unsupported format.")
         case .cipherMismatch:
             return String(localized: "The server and TablePro could not agree on a TLS cipher or protocol version.")
         case .unknown:
@@ -86,6 +98,12 @@ 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 .clientKeyInvalid:
+            return String(localized: "Check that the Client Key path points to a valid PEM private key.")
         case .cipherMismatch:
             return String(localized: "Update the server's TLS configuration or use a newer database server version that supports modern ciphers.")
         case .unknown:

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

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",

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,

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)
             }

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
         )

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
         )

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
             ),