Adding TLS

Author: feberts

README.md

@@ -10,6 +10,8 @@ A lightweight server and framework for turn-based multiplayer games.
 
 ![](.github/game_server.svg)
 
+Basic Python skills are sufficient to implement clients or add new games to the server.
+
 ## Overview
 
 ### Features
@@ -32,11 +34,11 @@ To try this project on your machine, start the server (`server/game_server.py`),
 
 ### About this project
 
-This server was developed for use in a university programming course, where students learn Python as their first programming language and have to work on projects in small groups. Both the framework and the API are designed so that the programming skills acquired during the first term are sufficient to implement new games and clients. However, the use of the server is not limited to educational scenarios.
+This server was developed for use in a university programming course, where students learn Python as their first programming language and work on projects in small groups. Both the framework and the API are designed so that the programming skills acquired during the first term are sufficient to implement new games and clients. However, the use of the server is not limited to educational scenarios.
 
 ## Operating the server
 
-To run the server in a network, edit IP and port in the configuration file (`server/config.py`). If you intend to run the server as a systemd service, you can use the provided unit file as a starting point. Server and API are implemented in plain Python. Only modules from the standard library are used. This makes the server easy to handle.
+To run the server in a network, edit IP and port in the configuration file (`server/config.py`). TLS can also be enabled there. If you intend to run the server as a systemd service, you can use the provided unit file. Server and API are implemented in plain Python. Only modules from the standard library are used. This makes the server easy to handle.
 
 ## Implementing clients
 
@@ -46,7 +48,8 @@ Module `game_server_api` provides an API for communicating with the server. It a
 - submit moves
 - retrieve the game state
 - passively observe another player
-- start a new game within the current session
+- restart a game within the current session
+- enable TLS
 
 Here is a short demo of the API usage:
 

client/game_server_api.py

@@ -26,18 +26,18 @@
 - submit moves to the server
 - retrieve the game state
 - passively observe a specific player
-- restart a game without starting a new session
+- restart a game within the current session
+- enable TLS
 """
 
 import json
+import os
 import socket
+import ssl
 import traceback
 
-class GameServerError(Exception):
-    pass
-
-class IllegalMove(Exception):
-    pass
+class GameServerError(Exception): pass
+class IllegalMove(Exception): pass
 
 class GameServerAPI:
     """
@@ -101,8 +101,9 @@ def __init__(self, server, port, game, session='auto', players=None, name=''):
         self._observer = False
 
         # tcp connections:
-        self._buffer_size = 4096 # bytes, corresponds to server-side buffer size value
+        self._buffer_size = 4096 # bytes, corresponds to server-side buffer size
         self._request_size_max = int(1e6) # bytes, updated after joining a game
+        self._tls_context = None
 
     def join(self):
         """
@@ -300,6 +301,34 @@ def restart(self):
 
         if err: raise GameServerError(err)
 
+    def enable_tls(self, cert=''):
+        """
+        Calling this function enables TLS encryption. By providing a
+        certificate, identity verification of the server is performed in
+        addition to encryption.
+
+        The server must have TLS enabled.
+
+        Parameters:
+        cert (str): certificate file (optional)
+
+        Raises:
+        GameServerError: if loading the certificate failed
+        """
+        try:
+            self._tls_context = ssl.create_default_context()
+
+            if cert:
+                cert = self._abs_path(cert)
+                self._tls_context.load_verify_locations(cert)
+            else:
+                self._tls_context.check_hostname = False
+                self._tls_context.verify_mode = ssl.CERT_NONE
+        except (FileNotFoundError, IsADirectoryError, TypeError):
+            raise GameServerError('the specified certificate file could not be found')
+        except ssl.SSLError as e:
+            raise GameServerError(f'TLS error while loading certificate: {e}')
+
     def _send(self, data):
         """
         Send data to the server and receive its response.
@@ -315,7 +344,7 @@ def _send(self, data):
         tuple(dict, str, str):
             dict: data returned by server, None in case of an error
             str: error message if a problem occurred, None otherwise
-            str: status (okay or error type)
+            str: error type in case of an error, okay otherwise
         """
         # prepare data:
         try:
@@ -328,47 +357,92 @@ def _send(self, data):
 
         # create a socket:
         with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sd:
-            try:
-                # connect to server:
-                sd.settimeout(5)
-                sd.connect((self._server, self._port))
-                sd.settimeout(None) # let server handle timeouts
-            except:
-                return self._api_error(f'unable to connect to {self._server}:{self._port}')
-
-            try:
-                # send data to server:
-                sd.sendall(request)
-
-                # receive data from server:
-                response = bytearray()
-
-                while True:
-                    data = sd.recv(self._buffer_size)
-                    if not data: break
-                    response += data
-
-                if not response: raise self._NoResponse
-                response = json.loads(response.decode())
-
-                # return data:
-                if response['status'] != 'ok': # server responded with an error
-                    return None, response['message'], response['status']
-
-                return response['data'], None, None
-
-            except socket.timeout:
-                return self._api_error('connection timed out')
-            except self._NoResponse:
-                return self._api_error('empty or no response received from server')
-            except (ConnectionResetError, BrokenPipeError):
-                return self._api_error('connection closed by server')
-            except UnicodeDecodeError:
-                return self._api_error('could not decode binary data received from server')
-            except json.decoder.JSONDecodeError:
-                return self._api_error('corrupt json received from server')
-            except:
-                return self._api_error('unexpected exception:\n' + traceback.format_exc())
+            with self._secure_socket(sd) as sd:
+                try:
+                    # connect to server:
+                    sd.settimeout(5)
+                    sd.connect((self._server, self._port))
+                    sd.settimeout(None) # let server handle timeouts
+                except ssl.SSLError as e:
+                    return self._api_error(f'TLS error: {e}')
+                except:
+                    return self._api_error(f'unable to connect to {self._server}:{self._port}')
+
+                try:
+                    # send data to server:
+                    sd.sendall(request)
+
+                    # receive server response:
+                    response = bytearray()
+
+                    while True:
+                        data = sd.recv(self._buffer_size)
+                        if not data: break
+                        response += data
+
+                    if not response: raise self._NoResponse
+                    response = json.loads(response.decode())
+
+                    # return data:
+                    if response['status'] != 'ok': # server responded with an error
+                        return None, response['message'], response['status']
+
+                    return response['data'], None, None
+
+                except socket.timeout:
+                    return self._api_error('connection timed out')
+                except self._NoResponse:
+                    return self._api_error('empty or no response received from server')
+                except (ConnectionResetError, BrokenPipeError):
+                    return self._api_error('connection closed by server')
+                except UnicodeDecodeError:
+                    return self._api_error('could not decode binary data received from server')
+                except json.decoder.JSONDecodeError:
+                    return self._api_error('corrupt json received from server')
+                except:
+                    return self._api_error('unexpected exception:\n' + traceback.format_exc())
+
+    def _secure_socket(self, socket):
+        """
+        This function wraps the socket and returns a TLS socket. TLS must be
+        enabled by calling API function enable_tls. Otherwise, the passed socket
+        is returned unmodified. If a certificate was passed to function
+        enable_tls, identity verification of the server is enabled. Without a
+        certificate, TLS is used for encryption only.
+
+        Parameters:
+        socket (socket): a regular socket
+
+        Returns:
+        socket or SSLSocket: a TLS socket, if TLS is enabled, the unmodified socket otherwise
+
+        Raises:
+        ssl.SSLError: if the creation of the TLS socket failed (lazy, raised after connect())
+        """
+        if self._tls_context:
+            return self._tls_context.wrap_socket(socket, server_hostname=self._server)
+
+        return socket
+
+    def _abs_path(self, file_name):
+        """
+        Always returns the file name with its absolute path, regardless of where
+        the file is located or from where the program was called.
+
+        Parameters:
+        file_name (str): file name with relative or absolute path
+
+        Returns:
+        str: file name with absolute path
+
+        Raises:
+        TypeError: if argument is not of type str
+        IsADirectoryError: if argument is a directory
+        """
+        if not file_name or os.path.isabs(file_name):
+            return file_name
+
+        return os.path.join(os.path.abspath(os.path.dirname(__file__)), file_name)
 
     @staticmethod
     def _api_error(message):
@@ -381,5 +455,4 @@ def _api_error(message):
     def _error(message):
         return 'Invalid argument: ' + message
 
-    class _NoResponse(Exception):
-        pass
+    class _NoResponse(Exception): pass

server/config.py

@@ -21,22 +21,28 @@
 """
 
 # SERVER:
-ip = '127.0.0.1'
+ip = '127.0.0.1' # IP or hostname
 port = 4711
 
 # FRAMEWORK:
 game_timeout = 1000 # seconds, timeout for inactive games and for joining a game
 
 # LOGGING:
-log_server_info = False # useful for debugging tcp connections (verbose)
 log_server_errors = True # errors during tcp connections
+log_server_info = False # useful for debugging tcp connections (verbose)
 log_framework_request = True # client requests
 log_framework_response = True # server responses
 log_framework_actions = True # actions performed by the framework, such as terminating games
 
 # TCP CONNECTIONS:
-# pick a higher value for request_size_max if required by a new game;
-# it should not be necessary to change buffer_size or connection_timeout
+# pick a higher value for request_size_max if required by a new game
 request_size_max = int(1e6) # bytes, prevents clients from sending too much data
+
+# it should not be necessary to change buffer_size or connection_timeout
 buffer_size = 4096 # bytes, corresponds to client-side buffer size value
 connection_timeout = 60 # seconds, timeout for tcp transactions
+
+# TLS:
+# to enable TLS, specify certificate and key (clients must enable TLS as well)
+tls_cert = ''
+tls_key = ''

server/game_server.py

@@ -28,6 +28,7 @@
 
 import json
 import socket
+import ssl
 import threading
 import traceback
 
@@ -40,7 +41,7 @@
 class ClientDisconnect(Exception): pass
 class RequestSizeExceeded(Exception): pass
 
-def handle_connection(conn, ip, port):
+def handle_connection(conn, client):
     """
     Handling a connection.
 
@@ -57,10 +58,10 @@ def handle_connection(conn, ip, port):
     possible, error messages are sent back to the client.
 
     Parameters:
-    conn (socket): connection socket
-    ip (str): client IP
-    port (int): client port
+    conn (socket or SSLSocket): connection socket
+    client (tuple(str, int)): client IP and port
     """
+    ip, port = client
     log = utility.ServerLogger(ip, port)
     log.info('connection accepted')
 
@@ -133,25 +134,63 @@ def handle_connection(conn, ip, port):
         conn.close()
         log.info('connection closed by server')
 
+def secure_socket(socket):
+    """
+    This function wraps the socket and returns a TLS socket. TLS must be enabled
+    in the config module. Otherwise, the passed socket is returned unmodified.
+    This function terminates the server program if an error occurs.
+
+    Parameters:
+    socket (socket): a regular listening socket
+
+    Returns:
+    socket or SSLSocket: a TLS socket, if TLS is enabled, the unmodified socket otherwise
+    """
+    if config.tls_cert and config.tls_key:
+        try:
+            context = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH)
+            context.minimum_version = ssl.TLSVersion.TLSv1_2
+            context.load_cert_chain(
+                certfile=utility.abs_path(config.tls_cert),
+                keyfile=utility.abs_path(config.tls_key))
+            print('TLS enabled')
+
+            return context.wrap_socket(socket, server_side=True)
+
+        except (FileNotFoundError, IsADirectoryError, TypeError):
+            exit('Error: the specified key or certificate file could not be found')
+        except ssl.SSLError as e:
+            exit(f'TLS error while loading certificate and key: {e}')
+
+    return socket
+
 print("""This is free software with ABSOLUTELY NO WARRANTY.
-Licensed under the GPL version 3 (see LICENSE).""")
+Licensed under the GPL version 3 (see LICENSE).
+""")
 
-try:
-    # create listening socket:
-    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sd:
-        sd.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
-        sd.bind((config.ip, config.port))
-        sd.listen()
+print('Server starting')
 
-        print(f'Listening on {config.ip}:{config.port}')
+# create listening socket:
+with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sd:
+    sd.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    sd.bind((config.ip, config.port))
+    sd.listen()
 
+    with secure_socket(sd) as sd:
+        print(f'Listening on {config.ip if config.ip else 'any'}:{config.port}')
+        log = utility.ServerLogger()
+
+        # accept connections and handle them in separate threads:
         while True:
-            # accept a connection:
-            conn, client = sd.accept()
-            ip, port = client
-
-            # handle connection in separate thread:
-            t = threading.Thread(target=handle_connection, args=(conn, ip, port), daemon=True)
-            t.start()
-except KeyboardInterrupt:
-    print('')
+            try:
+                conn, client = sd.accept()
+
+                threading.Thread(target=handle_connection, args=(conn, client),
+                                 daemon=True).start()
+            except KeyboardInterrupt:
+                print('\nServer shutting down')
+                exit()
+            except ssl.SSLError as e:
+                log.error(f'TLS error: {e}')
+            except:
+                log.error('unexpected exception on the server:\n' + traceback.format_exc())