Cordova WebSocket（JS）：SSL/TLS双向认证客户端证书配置问询

Great question! The standard browser WebSocket API doesn't natively support attaching client certificates for mutual TLS (mTLS) authentication—but since Cordova bridges web code to native platform capabilities, you have two reliable approaches to make this work.

Option 1: Use a Cordova WebSocket Plugin with mTLS Support #

The easiest way is to leverage a dedicated plugin that extends WebSocket functionality to handle client certificates. Here's a step-by-step breakdown:

1. Install a compatible plugin
   Look for a maintained plugin like cordova-plugin-websocket-mtls (check npm or Cordova plugin registries for the latest options). Install it via:

   cordova plugin add cordova-plugin-websocket-mtls
   

2. Prepare your client certificate
   Convert your client certificate to a PKCS#12 (.p12) file—this format works seamlessly across iOS and Android. Store the .p12 file in your Cordova project's www/assets directory (or platform-specific resource folders for better performance).

3. Initialize the mTLS WebSocket connection
   Use the plugin's API to attach the client certificate when opening the connection:

   // Initialize the WebSocket with mTLS config
   const secureWebSocket = cordova.plugins.WebSocketMTLS.createConnection({
     url: 'wss://your-server-domain:your-websocket-port',
     clientCert: {
       path: 'assets/client-cert.p12',
       password: 'your-cert-password' // Omit if your cert isn't password-protected
     },
     // Optional: Trust a custom server CA if needed
     serverCaPath: 'assets/root-ca.pem'
   });
   
   // Set up connection handlers
   secureWebSocket.onOpen = () => {
     console.log('mTLS WebSocket connection established!');
     secureWebSocket.send('Hello from authenticated client!');
   };
   
   secureWebSocket.onMessage = (message) => {
     console.log('Received server message:', message.data);
   };
   
   secureWebSocket.onError = (error) => {
     console.error('Connection error:', error.message);
   };
   
   secureWebSocket.onClose = () => {
     console.log('Connection closed');
   };
   
   // Start the connection
   secureWebSocket.connect();
   

Option 2: Build a Custom Cordova Plugin (Native Bridge) #

If no pre-built plugin fits your needs, you can create a custom plugin that uses native platform APIs to handle mTLS WebSocket connections:

For Android #

Use OkHttp's WebSocket implementation, which natively supports loading client certificates:

1. In your custom plugin's Android code, configure an OkHttpClient with your client certificate:

   // Load client PKCS#12 keystore
   KeyStore keyStore = KeyStore.getInstance("PKCS12");
   InputStream inputStream = getContext().getAssets().open("client-cert.p12");
   keyStore.load(inputStream, "your-cert-password".toCharArray());
   
   // Build SSL socket factory with client cert
   SSLSocketFactory sslSocketFactory = new SSLSocketFactory(keyStore, "your-cert-password");
   OkHttpClient client = new OkHttpClient.Builder()
       .sslSocketFactory(sslSocketFactory, new X509TrustManager() {
           // Implement trust logic for your server's CA
           @Override
           public void checkClientTrusted(X509Certificate[] chain, String authType) {}
           @Override
           public void checkServerTrusted(X509Certificate[] chain, String authType) {}
           @Override
           public X509Certificate[] getAcceptedIssuers() { return new X509Certificate[0]; }
       })
       .build();
   
   // Create WebSocket connection
   Request request = new Request.Builder().url("wss://your-server-domain").build();
   WebSocket webSocket = client.newWebSocket(request, new WebSocketListener() {
       @Override
       public void onOpen(WebSocket webSocket, Response response) {
           // Send connection success event to JavaScript
           sendJSEvent("onOpen", null);
       }
   
       @Override
       public void onMessage(WebSocket webSocket, String text) {
           // Send received message to JavaScript
           sendJSEvent("onMessage", text);
       }
   
       // Implement onError, onClose handlers similarly
   });
   

2. Expose methods to JavaScript via Cordova's plugin interface to trigger the connection, send messages, and handle callbacks.

For iOS #

Use URLSessionWebSocketTask with a custom URLSessionConfiguration that includes the client certificate:

1. In your plugin's iOS code, load the PKCS#12 certificate and configure the session:

   guard let certPath = Bundle.main.path(forResource: "client-cert", ofType: "p12"),
         let certData = try? Data(contentsOf: URL(fileURLWithPath: certPath)) else {
       // Handle certificate loading error
       return
   }
   
   let configuration = URLSessionConfiguration.default
   configuration.urlCredentialStorage = nil
   configuration.requestCachePolicy = .reloadIgnoringLocalCacheData
   
   // Create credential from client cert
   let credential = URLCredential(identity: certData, password: "your-cert-password", persistence: .forSession)
   configuration.urlCredentialStorage?.set(credential, for: URLProtectionSpace(
       host: "your-server-domain",
       port: your-websocket-port,
       protocol: "wss",
       realm: nil,
       authenticationMethod: NSURLAuthenticationMethodClientCertificate
   ))
   
   // Create WebSocket task
   let session = URLSession(configuration: configuration)
   let webSocketTask = session.webSocketTask(with: URL(string: "wss://your-server-domain:your-port")!)
   webSocketTask.resume()
   
   // Handle messages, connection state, errors and pass to JavaScript
   

2. Bridge these native events to your Cordova JavaScript code using plugin callbacks.

Key Notes for Success #

• Certificate Format: PKCS#12 (.p12) is the most cross-platform friendly format for client certificates. Avoid separate .pem/.key files unless your plugin explicitly supports them.
• Certificate Placement: Ensure your certificate files are included in the app bundle. For Cordova, placing them in www/assets works, but platform-specific folders (Android assets, iOS Resources) can improve loading reliability.
• Server Validation: Double-check that your server is configured to trust the CA that signed your client certificate—otherwise, the connection will fail during the TLS handshake.
• Testing: Test the mTLS connection natively first (using Android Studio/Xcode) before integrating into Cordova. This helps isolate whether issues are with the certificate, server config, or Cordova plugin code.

内容的提问来源于stack exchange，提问作者Leonard Klausmann