Add TLS feature for Modbus synchronous (#446)

* Add TLS feature for Modbus synchronous

Modbus.org released MODBUS/TCP Security Protocol Specification [1],
which focuses variant of the Mobdbus/TCP protocol utilizing Transport
Layer Security (TLS). This patch enables the Modbus over TLS feature as
ModbusTlsClient with the Python builtin module ssl - TLS/SSL wrapper for
socket objects.

[1]: http://modbus.org/docs/MB-TCP-Security-v21_2018-07-24.pdf

* Implement MODBUS TLS synchronous server

Since we have the MODBUS TLS synchronous client, we can also have the
MODBUS TLS synchronous server.

examples/common/synchronous_server.py

@@ -12,6 +12,7 @@
 # import the various server implementations
 # --------------------------------------------------------------------------- #
 from pymodbus.server.sync import StartTcpServer
+from pymodbus.server.sync import StartTlsServer
 from pymodbus.server.sync import StartUdpServer
 from pymodbus.server.sync import StartSerialServer
 
@@ -117,6 +118,10 @@ def run_server():
     # StartTcpServer(context, identity=identity,
     #                framer=ModbusRtuFramer, address=("0.0.0.0", 5020))
 
+    # TLS
+    # StartTlsServer(context, identity=identity, certfile="server.crt",
+    #                keyfile="server.key", address=("0.0.0.0", 8020))
+
     # Udp:
     # StartUdpServer(context, identity=identity, address=("0.0.0.0", 5020))
 

examples/contrib/modbus_tls_client.py

@@ -0,0 +1,34 @@
+#!/usr/bin/env python
+"""
+Simple Modbus TCP over TLS client
+---------------------------------------------------------------------------
+
+This is a simple example of writing a modbus TCP over TLS client that uses
+Python builtin module ssl - TLS/SSL wrapper for socket objects for the TLS
+feature.
+"""
+# -------------------------------------------------------------------------- #
+# import neccessary libraries
+# -------------------------------------------------------------------------- #
+import ssl
+from pymodbus.client.sync import ModbusTlsClient
+
+# -------------------------------------------------------------------------- #
+# the TLS detail security can be set in SSLContext which is the context here
+# -------------------------------------------------------------------------- #
+context = ssl.create_default_context()
+context.options |= ssl.OP_NO_SSLv2
+context.options |= ssl.OP_NO_SSLv3
+context.options |= ssl.OP_NO_TLSv1
+context.options |= ssl.OP_NO_TLSv1_1
+
+# -------------------------------------------------------------------------- #
+# pass SSLContext which is the context here to ModbusTcpClient()
+# -------------------------------------------------------------------------- #
+client = ModbusTlsClient('test.host.com', 8020, sslctx=context)
+client.connect()
+
+result = client.read_coils(1, 8)
+print(result.bits)
+
+client.close()

pymodbus/client/sync.py

@@ -2,6 +2,7 @@
 import select
 import serial
 import time
+import ssl
 import sys
 from functools import partial
 from pymodbus.constants import Defaults
@@ -13,6 +14,7 @@
 from pymodbus.transaction import DictTransactionManager
 from pymodbus.transaction import ModbusSocketFramer, ModbusBinaryFramer
 from pymodbus.transaction import ModbusAsciiFramer, ModbusRtuFramer
+from pymodbus.transaction import ModbusTlsFramer
 from pymodbus.client.common import ModbusClientMixin
 
 # --------------------------------------------------------------------------- #
@@ -297,6 +299,116 @@ def __repr__(self):
             "port={self.port}, timeout={self.timeout}>"
         ).format(self.__class__.__name__, hex(id(self)), self=self)
 
+# --------------------------------------------------------------------------- #
+# Modbus TLS Client Transport Implementation
+# --------------------------------------------------------------------------- #
+
+
+class ModbusTlsClient(ModbusTcpClient):
+    """ Implementation of a modbus tls client
+    """
+
+    def __init__(self, host='localhost', port=Defaults.TLSPort, sslctx=None,
+        framer=ModbusTlsFramer, **kwargs):
+        """ Initialize a client instance
+
+        :param host: The host to connect to (default localhost)
+        :param port: The modbus port to connect to (default 802)
+        :param sslctx: The SSLContext to use for TLS (default None and auto create)
+        :param source_address: The source address tuple to bind to (default ('', 0))
+        :param timeout: The timeout to use for this socket (default Defaults.Timeout)
+        :param framer: The modbus framer to use (default ModbusSocketFramer)
+
+        .. note:: The host argument will accept ipv4 and ipv6 hosts
+        """
+        self.sslctx = sslctx
+        if self.sslctx is None:
+            self.sslctx = ssl.create_default_context()
+            # According to MODBUS/TCP Security Protocol Specification, it is
+            # TLSv2 at least
+            self.sslctx.options |= ssl.OP_NO_TLSv1_1
+            self.sslctx.options |= ssl.OP_NO_TLSv1
+            self.sslctx.options |= ssl.OP_NO_SSLv3
+            self.sslctx.options |= ssl.OP_NO_SSLv2
+        ModbusTcpClient.__init__(self, host, port, framer, **kwargs)
+
+    def connect(self):
+        """ Connect to the modbus tls server
+
+        :returns: True if connection succeeded, False otherwise
+        """
+        if self.socket: return True
+        try:
+            sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            sock.bind(self.source_address)
+            self.socket = self.sslctx.wrap_socket(sock, server_side=False,
+                                                  server_hostname=self.host)
+            self.socket.settimeout(self.timeout)
+            self.socket.connect((self.host, self.port))
+        except socket.error as msg:
+            _logger.error('Connection to (%s, %s) '
+                          'failed: %s' % (self.host, self.port, msg))
+            self.close()
+        return self.socket is not None
+
+    def _recv(self, size):
+        """ Reads data from the underlying descriptor
+
+        :param size: The number of bytes to read
+        :return: The bytes read
+        """
+        if not self.socket:
+            raise ConnectionException(self.__str__())
+
+        # socket.recv(size) waits until it gets some data from the host but
+        # not necessarily the entire response that can be fragmented in
+        # many packets.
+        # To avoid the splitted responses to be recognized as invalid
+        # messages and to be discarded, loops socket.recv until full data
+        # is received or timeout is expired.
+        # If timeout expires returns the read data, also if its length is
+        # less than the expected size.
+        timeout = self.timeout
+
+        # If size isn't specified read 1 byte at a time.
+        if size is None:
+            recv_size = 1
+        else:
+            recv_size = size
+
+        data = b''
+        time_ = time.time()
+        end = time_ + timeout
+        while recv_size > 0:
+            data += self.socket.recv(recv_size)
+            time_ = time.time()
+
+            # If size isn't specified continue to read until timeout expires.
+            if size:
+                recv_size = size - len(data)
+
+            # Timeout is reduced also if some data has been received in order
+            # to avoid infinite loops when there isn't an expected response
+            # size and the slave sends noisy data continuosly.
+            if time_ > end:
+                break
+
+        return data
+
+    def __str__(self):
+        """ Builds a string representation of the connection
+
+        :returns: The string representation
+        """
+        return "ModbusTlsClient(%s:%s)" % (self.host, self.port)
+
+    def __repr__(self):
+        return (
+            "<{} at {} socket={self.socket}, ipaddr={self.host}, "
+            "port={self.port}, sslctx={self.sslctx}, timeout={self.timeout}>"
+        ).format(self.__class__.__name__, hex(id(self)), self=self)
+
+
 # --------------------------------------------------------------------------- #
 # Modbus UDP Client Transport Implementation
 # --------------------------------------------------------------------------- #
@@ -594,5 +706,5 @@ def __repr__(self):
 
 
 __all__ = [
-    "ModbusTcpClient", "ModbusUdpClient", "ModbusSerialClient"
+    "ModbusTcpClient", "ModbusTlsClient", "ModbusUdpClient", "ModbusSerialClient"
 ]

pymodbus/constants.py

@@ -15,6 +15,10 @@ class Defaults(Singleton):
 
        The default modbus tcp server port (502)
 
+    .. attribute:: TLSPort
+
+       The default modbus tcp over tls server port (802)
+
     .. attribute:: Retries
 
        The default number of times a client should retry the given
@@ -99,6 +103,7 @@ class Defaults(Singleton):
 
     '''
     Port                = 502
+    TLSPort             = 802
     Retries             = 3
     RetryOnEmpty        = False
     Timeout             = 3

pymodbus/framer/__init__.py

@@ -8,6 +8,8 @@
 # Transaction Id, Protocol ID, Length, Unit ID, Function Code
 SOCKET_FRAME_HEADER = BYTE_ORDER + 'HHH' + FRAME_HEADER
 
+# Function Code
+TLS_FRAME_HEADER = BYTE_ORDER + 'B'
 
 class ModbusFramer(IModbusFramer):
     """