support for SSL protocol

Author: pavelrevak

README.md

@@ -1,16 +1,17 @@
 # Ser2tcp
 
-Simple proxy for connecting over TCP or telnet to serial port
+Simple proxy for connecting over TCP, TELNET or SSL to serial port
 
 https://github.com/cortexm/ser2tcp
 
 ## Features
 
 - can serve multiple serial ports using pyserial library
 - each serial port can have multiple servers
-- server can use TCP or TELNET protocol
+- server can use TCP, TELNET or SSL protocol
   - TCP protocol just bridge whole RAW serial stream to TCP
   - TELNET protocol will send every character immediately and not wait for ENTER, it is useful to use standard `telnet` as serial terminal
+  - SSL protocol provides encrypted TCP connection with optional mutual TLS (mTLS) client certificate verification
 - servers accepts multiple connections at one time
   - each connected client can sent to serial port
   - serial port send received data to all connected clients
@@ -119,6 +120,7 @@ Match attributes: `vid`, `pid`, `serial_number`, `manufacturer`, `product`, `loc
 - Wildcard `*` supported (e.g. `"product": "CP210*"`)
 - Matching is case-insensitive
 - Error if multiple devices match the criteria
+- Device is resolved when client connects, not at startup (device does not need to exist at startup)
 - `baudrate` is optional (default 9600, CDC devices ignore it)
 
 ### Server configuration
@@ -127,10 +129,82 @@ Match attributes: `vid`, `pid`, `serial_number`, `manufacturer`, `product`, `loc
 |-----------|-------------|---------|
 | `address` | Bind address | required |
 | `port` | TCP port | required |
-| `protocol` | `tcp` or `telnet` | required |
+| `protocol` | `tcp`, `telnet` or `ssl` | required |
+| `ssl` | SSL configuration (required for `ssl` protocol) | - |
 | `send_timeout` | Disconnect client if data cannot be sent within this time (seconds) | 5.0 |
 | `buffer_limit` | Maximum send buffer size per client (bytes), `null` for unlimited | null |
 
+#### SSL configuration
+
+For `ssl` protocol, add `ssl` object with certificate paths:
+
+```json
+{
+    "address": "0.0.0.0",
+    "port": 10003,
+    "protocol": "ssl",
+    "ssl": {
+        "certfile": "/path/to/server.crt",
+        "keyfile": "/path/to/server.key",
+        "ca_certs": "/path/to/ca.crt"
+    }
+}
+```
+
+| Parameter | Description | Required |
+|-----------|-------------|----------|
+| `certfile` | Server certificate (PEM) | yes |
+| `keyfile` | Server private key (PEM) | yes |
+| `ca_certs` | CA certificate for client verification (mTLS) | no |
+
+If `ca_certs` is specified, clients must provide a valid certificate signed by the CA.
+
+##### Creating self-signed certificates
+
+Generate CA and server certificate for testing:
+
+```bash
+# Create CA key and certificate
+openssl genrsa -out ca.key 2048
+openssl req -new -x509 -days 365 -key ca.key -out ca.crt -subj "/CN=ser2tcp CA" \
+    -addext "basicConstraints=critical,CA:TRUE" \
+    -addext "keyUsage=critical,keyCertSign,cRLSign"
+
+# Create server key and certificate signing request
+openssl genrsa -out server.key 2048
+openssl req -new -key server.key -out server.csr -subj "/CN=localhost"
+
+# Sign server certificate with CA
+openssl x509 -req -days 365 -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt
+
+# For certificate bound to specific domain/IP (SAN - Subject Alternative Name):
+openssl req -new -key server.key -out server.csr -subj "/CN=myserver.example.com" -addext "subjectAltName=DNS:myserver.example.com,DNS:localhost,IP:192.168.1.100"
+openssl x509 -req -days 365 -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -copy_extensions copy
+
+# Clean up CSR
+rm server.csr
+```
+
+For mTLS (mutual TLS with client certificates):
+
+```bash
+# Create client key and certificate
+openssl genrsa -out client.key 2048
+openssl req -new -key client.key -out client.csr -subj "/CN=client"
+openssl x509 -req -days 365 -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out client.crt
+rm client.csr
+```
+
+Testing SSL connection:
+
+```bash
+# Without client certificate
+openssl s_client -connect localhost:10003
+
+# With client certificate (mTLS)
+openssl s_client -connect localhost:10003 -cert client.crt -key client.key
+```
+
 ## Usage examples
 
 ```

ser2tcp/connection_ssl.py

@@ -0,0 +1,29 @@
+"""Connection SSL"""
+
+import ssl as _ssl
+
+import ser2tcp.connection_tcp as _connection_tcp
+
+
+class SslHandshakeError(Exception):
+    """SSL handshake failed"""
+
+
+class ConnectionSsl(_connection_tcp.ConnectionTcp):
+    """SSL/TLS connection"""
+
+    def __init__(
+            self, connection, ser, send_timeout=None, buffer_limit=None,
+            log=None, ssl_context=None):
+        sock, addr = connection
+        self._socket = None
+        try:
+            ssl_sock = ssl_context.wrap_socket(sock, server_side=True)
+        except _ssl.SSLError as err:
+            sock.close()
+            raise SslHandshakeError(f"SSL handshake failed: {err}") from err
+        super().__init__(
+            (ssl_sock, addr), ser, send_timeout, buffer_limit, log)
+
+    def _log_connected(self):
+        self._log.info("Client connected: %s:%d SSL", *self._addr)

ser2tcp/connection_tcp.py

@@ -5,11 +5,15 @@
 
 class ConnectionTcp(_connection.Connection):
     """TCP connection"""
+
     def __init__(
             self, connection, ser, send_timeout=None, buffer_limit=None,
             log=None):
         super().__init__(connection, send_timeout, buffer_limit, log)
         self._serial = ser
+        self._log_connected()
+
+    def _log_connected(self):
         self._log.info("Client connected: %s:%d TCP", *self._addr)
 
     def on_received(self, data):

ser2tcp/serial_proxy.py

@@ -36,22 +36,22 @@ def __init__(self, config, log=None):
         self._log = log if log else _logging.Logger(self.__class__.__name__)
         self._serial = None
         self._servers = []
-        self._serial_config = self.fix_serial_config(config['serial'])
+        self._serial_config = self._init_serial_config(config['serial'])
+        self._match = self._serial_config.pop('match', None)
+        port = self._serial_config.get('port')
         baudrate = self._serial_config.get('baudrate')
+        name = port if port else f"match:{self._match}"
         if baudrate:
-            self._log.info(
-                "Serial: %s %d", self._serial_config['port'], baudrate)
+            self._log.info("Serial: %s %d", name, baudrate)
         else:
-            self._log.info("Serial: %s", self._serial_config['port'])
+            self._log.info("Serial: %s", name)
         for server_config in config['servers']:
             self._servers.append(_server.Server(server_config, self, log))
 
-    def fix_serial_config(self, config):
-        """Fix serial configuration - resolve match, convert enum values"""
-        if 'port' not in config:
-            if 'match' not in config:
-                raise ValueError("Serial config must have 'port' or 'match'")
-            config['port'] = self.find_port_by_match(config.pop('match'))
+    def _init_serial_config(self, config):
+        """Initialize serial configuration - validate and convert enum values"""
+        if 'port' not in config and 'match' not in config:
+            raise ValueError("Serial config must have 'port' or 'match'")
         if 'parity' in config:
             for key, val in self.PARITY_CONFIG.items():
                 if config['parity'] == key:
@@ -106,6 +106,13 @@ def __del__(self):
     def connect(self):
         """Connect to serial port"""
         if not self._serial:
+            if self._match:
+                try:
+                    self._serial_config['port'] = self.find_port_by_match(
+                        self._match)
+                except ValueError as err:
+                    self._log.warning(err)
+                    return False
             try:
                 self._serial = _serial.Serial(**self._serial_config)
             except (_serial.SerialException, OSError) as err:

ser2tcp/server.py

@@ -2,8 +2,11 @@
 
 # pylint: disable=C0209
 
-import socket as _socket
 import logging as _logging
+import socket as _socket
+import ssl as _ssl
+
+import ser2tcp.connection_ssl as _connection_ssl
 import ser2tcp.connection_tcp as _connection_tcp
 import ser2tcp.connection_telnet as _connection_telnet
 
@@ -18,6 +21,7 @@ class Server():
     CONNECTIONS = {
         'TCP': _connection_tcp.ConnectionTcp,
         'TELNET': _connection_telnet.ConnectionTelnet,
+        'SSL': _connection_ssl.ConnectionSsl,
     }
 
     def __init__(self, config, ser, log=None):
@@ -28,6 +32,7 @@ def __init__(self, config, ser, log=None):
         self._protocol = self._config['protocol'].upper()
         self._send_timeout = self._config.get('send_timeout')
         self._buffer_limit = self._config.get('buffer_limit')
+        self._ssl_context = None
         self._socket = None
         self._log.info(
             "  Server: %s %d %s",
@@ -36,6 +41,8 @@ def __init__(self, config, ser, log=None):
             self._protocol)
         if self._protocol not in self.CONNECTIONS:
             raise ConfigError('Unknown protocol %s' % self._protocol)
+        if self._protocol == 'SSL':
+            self._ssl_context = self._create_ssl_context()
         self._socket = _socket.socket(
             _socket.AF_INET, _socket.SOCK_STREAM, _socket.IPPROTO_TCP)
         self._socket.setsockopt(_socket.SOL_SOCKET, _socket.SO_REUSEADDR, 1)
@@ -45,21 +52,40 @@ def __init__(self, config, ser, log=None):
     def __del__(self):
         self.close()
 
+    def _create_ssl_context(self):
+        """Create SSL context from config"""
+        ssl_config = self._config.get('ssl', {})
+        certfile = ssl_config.get('certfile')
+        keyfile = ssl_config.get('keyfile')
+        ca_certs = ssl_config.get('ca_certs')
+        if not certfile or not keyfile:
+            raise ConfigError('SSL protocol requires certfile and keyfile')
+        context = _ssl.SSLContext(_ssl.PROTOCOL_TLS_SERVER)
+        context.load_cert_chain(certfile, keyfile)
+        if ca_certs:
+            context.load_verify_locations(ca_certs)
+            context.verify_mode = _ssl.CERT_REQUIRED
+        return context
+
     def _client_connect(self):
         """connect to client, will accept waiting connection"""
         sock, addr = self._socket.accept()
-        if not self._connections:
-            if not self._serial.connect():
-                self._log.info("Client canceled: %s:%d", *addr)
-                sock.close()
-                return
-        connection = self.CONNECTIONS[self._protocol](
-            connection=(sock, addr),
-            ser=self._serial,
-            send_timeout=self._send_timeout,
-            buffer_limit=self._buffer_limit,
-            log=self._log,
-        )
+        kwargs = {
+            'connection': (sock, addr),
+            'ser': self._serial,
+            'send_timeout': self._send_timeout,
+            'buffer_limit': self._buffer_limit,
+            'log': self._log,
+        }
+        if self._ssl_context:
+            kwargs['ssl_context'] = self._ssl_context
+        try:
+            connection = self.CONNECTIONS[self._protocol](**kwargs)
+        except _connection_ssl.SslHandshakeError as err:
+            self._log.info("Client rejected: %s:%d (%s)", *addr, err)
+            if not self._connections:
+                self._serial.disconnect()
+            return
         if self._serial.connect():
             self._connections.append(connection)
         else:
@@ -113,7 +139,7 @@ def process_read(self, read_sockets):
                 try:
                     data = con.socket().recv(4096)
                     self._log.debug("(%s:%d): %s", *con.get_address(), data)
-                except ConnectionResetError as err:
+                except (ConnectionResetError, _ssl.SSLError) as err:
                     self._log.info("(%s:%d): %s", *con.get_address(), err)
                 if not data:
                     self._remove_connection(con)

tests/test_connection_ssl.py

@@ -0,0 +1,88 @@
+"""Tests for ConnectionSsl class"""
+
+import unittest
+import unittest.mock
+from unittest.mock import Mock
+
+from ser2tcp.connection_ssl import ConnectionSsl
+
+
+class MockSocket:
+    """Mock socket for testing"""
+    def __init__(self):
+        self.sent_data = bytearray()
+        self.closed = False
+        self._fileno = 5
+
+    def send(self, data):
+        self.sent_data.extend(data)
+        return len(data)
+
+    def close(self):
+        self.closed = True
+
+    def fileno(self):
+        return self._fileno
+
+
+class TestConnectionSsl(unittest.TestCase):
+    def _make_connection(self):
+        """Helper to create ConnectionSsl with mock socket"""
+        mock_socket = MockSocket()
+        mock_ssl_socket = MockSocket()
+        addr = ('127.0.0.1', 12345)
+        mock_serial = Mock()
+        log = Mock()
+        mock_context = Mock()
+        mock_context.wrap_socket.return_value = mock_ssl_socket
+        conn = ConnectionSsl(
+            (mock_socket, addr),
+            mock_serial,
+            log=log,
+            ssl_context=mock_context)
+        return conn, mock_serial, mock_context, mock_socket
+
+    def test_wraps_socket_with_ssl_context(self):
+        """SSL context should wrap the socket"""
+        conn, _, context, raw_socket = self._make_connection()
+        context.wrap_socket.assert_called_once_with(
+            raw_socket, server_side=True)
+
+    def test_log_connected_shows_ssl(self):
+        """Log message should show SSL protocol"""
+        mock_socket = MockSocket()
+        mock_ssl_socket = MockSocket()
+        addr = ('127.0.0.1', 12345)
+        mock_serial = Mock()
+        log = Mock()
+        mock_context = Mock()
+        mock_context.wrap_socket.return_value = mock_ssl_socket
+        conn = ConnectionSsl(
+            (mock_socket, addr),
+            mock_serial,
+            log=log,
+            ssl_context=mock_context)
+        # Check that SSL was logged (first call, before any disconnect)
+        first_call = log.info.call_args_list[0]
+        self.assertEqual(
+            first_call,
+            unittest.mock.call(
+                "Client connected: %s:%d SSL", '127.0.0.1', 12345))
+        conn.close()
+
+    def test_on_received_forwards_to_serial(self):
+        """Data should be forwarded to serial"""
+        conn, serial, _, _ = self._make_connection()
+        conn.on_received(b'hello')
+        serial.send.assert_called_once_with(b'hello')
+
+    def test_send_adds_to_buffer(self):
+        """Send should add data to buffer"""
+        conn, _, _, _ = self._make_connection()
+        result = conn.send(b'test')
+        self.assertEqual(result, 4)
+        self.assertTrue(conn.has_pending_data())
+
+
+if __name__ == "__main__":
+    unittest.main()