Update

Author: feberts

README.md

@@ -10,6 +10,8 @@ A lightweight server and framework for turn-based multiplayer games.
 
 ![](.github/game_server.svg)
 
+Only basic programming skills are required to implement clients or to add new games to the server.
+
 ## Overview
 
 ### Features
@@ -36,7 +38,7 @@ This server was developed for use in a university programming course, where stud
 
 ## 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. 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/cert.pem

@@ -0,0 +1,9 @@
+-----BEGIN CERTIFICATE-----
+MIIBPDCB76ADAgECAhR80LMQEzjOb5Z3qp3KxSSAEESfPjAFBgMrZXAwFDESMBAG
+A1UEAwwJbG9jYWxob3N0MB4XDTI2MDMxNzIxMTgyN1oXDTM2MDMxNDIxMTgyN1ow
+FDESMBAGA1UEAwwJbG9jYWxob3N0MCowBQYDK2VwAyEA2IItFX1uAVrek+ek0YMQ
+h+dxc8AwPrRU79NmeIZuqjCjUzBRMB0GA1UdDgQWBBT6fAh+V0x78fkUZgNEfaeq
+XNCCrDAfBgNVHSMEGDAWgBT6fAh+V0x78fkUZgNEfaeqXNCCrDAPBgNVHRMBAf8E
+BTADAQH/MAUGAytlcANBAMrDCYdBbubPvBusl2zV5DmUSD1GkM+S/Lkmy3cTXghN
+LwuiwCMepXO7f047/AN7AC21IlgyqnO8U7k6cUCF/Qk=
+-----END CERTIFICATE-----

client/echo_client.py

@@ -13,6 +13,9 @@
 from game_server_api import GameServerAPI, GameServerError, IllegalMove
 
 game = GameServerAPI(server='127.0.0.1', port=4711, game='Echo', session='mygame', players=1)
+game.enable_tls(cert='cert.pem')
+# game.enable_tls()
+# TODO TLS rausnehmen
 
 my_id = game.join()
 state = game.state()

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:
     """
@@ -103,6 +103,10 @@ def __init__(self, server, port, game, session='auto', players=None, name=''):
         # tcp connections:
         self._buffer_size = 4096 # bytes, corresponds to server-side buffer size value
         self._request_size_max = int(1e6) # bytes, updated after joining a game
+        
+        # tls:
+        self._tls_enabled = False
+        self._tls_cert = None
 
     def join(self):
         """
@@ -300,6 +304,21 @@ def restart(self):
 
         if err: raise GameServerError(err)
 
+    def enable_tls(self, cert=''):
+        """
+        Calling this function enables TLS encryption. By providing a
+        certificate, authentication of the server is performed.
+        
+        The server must have TLS enabled.
+
+        Parameters:
+        cert (str): certificate (optional)
+        """
+        assert type(cert) == str, self._error('cert')
+        
+        self._tls_enabled = True
+        self._tls_cert = self._abs_path(cert)
+
     def _send(self, data):
         """
         Send data to the server and receive its response.
@@ -328,47 +347,94 @@ 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 IndexError:
+                    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())
+
+    def _secure_socket(self, socket):
+        """
+        This function wraps the socket and returns an SSL 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, authentication of the server is enabled. Without a
+        certificate, TLS is used for encryption only.
+
+        Parameters:
+        socket (socket): a regular socket
+        
+        Returns:
+        socket or SSLSocket: an SSL socket, if TLS is enabled, a regular socket otherwise
+        
+        Raises:
+        # TODO
+        """
+        if self._tls_enabled:
+            context = ssl.create_default_context()
+
+            if self._tls_cert:
+                context.load_verify_locations(self._tls_cert)
+            else:
+                context.check_hostname = False
+                context.verify_mode = ssl.CERT_NONE
+
+            return context.wrap_socket(socket, server_hostname=self._server)
+
+        return socket
+
+    def _abs_path(self, file_path):
+        """        
+        Always returns the absolute path to the file, regardless of where the
+        file is located or from where the program was called.
+
+        Parameters:
+        file_path (str): path to file, relative or absolute
+
+        Returns:
+        str: absolute path to file
+        """
+        if not file_path or os.path.isabs(file_path):
+            return file_path
+
+        return os.path.join(os.path.abspath(os.path.dirname(__file__)), file_path)
 
     @staticmethod
     def _api_error(message):

client/wrong_cert.pem

@@ -0,0 +1,9 @@
+-----BEGIN CERTIFICATE-----
+MIIBPDCB76ADAgECAhRmDEjN38kb9dePsgI5Z9capYBbnTAFBgMrZXAwFDESMBAG
+A1UEAwwJbG9jYWxob3N0MB4XDTI2MDMyMTE1NTM0OFoXDTM2MDMxODE1NTM0OFow
+FDESMBAGA1UEAwwJbG9jYWxob3N0MCowBQYDK2VwAyEAlrlDYa/OIPhQDuZL5Rgd
+YBpVmipVvFiIjkmqBgYLcHyjUzBRMB0GA1UdDgQWBBQFoLqqFIwuVdCQik0hUJpF
+nFMYHjAfBgNVHSMEGDAWgBQFoLqqFIwuVdCQik0hUJpFnFMYHjAPBgNVHRMBAf8E
+BTADAQH/MAUGAytlcANBADShzpnkM3DtXQP5zZqOcylIqE1JDqy8VQlns0gTtvel
+4g0BvAMSLZRJJHYbzCb+3+5CjKveY/QVWWZ1CmnzWw4=
+-----END CERTIFICATE-----

client/wrong_host.pem

@@ -0,0 +1,9 @@
+-----BEGIN CERTIFICATE-----
+MIIBNjCB6aADAgECAhRC4l2QYZpbjj2PxkiJ18ZU+IyrIDAFBgMrZXAwETEPMA0G
+A1UEAwwGcXdlcnR6MB4XDTI2MDMyMTE1NTQxMloXDTM2MDMxODE1NTQxMlowETEP
+MA0GA1UEAwwGcXdlcnR6MCowBQYDK2VwAyEAe/GKS4+p+nJS7yoCPUMQafqDP5Bk
+rYUlHYOJ7A6caW+jUzBRMB0GA1UdDgQWBBQymq7ri17CZZOi8vzokKhY78BhGzAf
+BgNVHSMEGDAWgBQymq7ri17CZZOi8vzokKhY78BhGzAPBgNVHRMBAf8EBTADAQH/
+MAUGAytlcANBAIs148vo8OdMCmUGmqnW5VAuG1TVkidaoX2O//MjSM2j3LuWKEQy
+a3wKxXGpS/ZPYtOVWThXZ+fSdslG6hTWrg0=
+-----END CERTIFICATE-----

server/cert.pem

@@ -0,0 +1,9 @@
+-----BEGIN CERTIFICATE-----
+MIIBPDCB76ADAgECAhR80LMQEzjOb5Z3qp3KxSSAEESfPjAFBgMrZXAwFDESMBAG
+A1UEAwwJbG9jYWxob3N0MB4XDTI2MDMxNzIxMTgyN1oXDTM2MDMxNDIxMTgyN1ow
+FDESMBAGA1UEAwwJbG9jYWxob3N0MCowBQYDK2VwAyEA2IItFX1uAVrek+ek0YMQ
+h+dxc8AwPrRU79NmeIZuqjCjUzBRMB0GA1UdDgQWBBT6fAh+V0x78fkUZgNEfaeq
+XNCCrDAfBgNVHSMEGDAWgBT6fAh+V0x78fkUZgNEfaeqXNCCrDAPBgNVHRMBAf8E
+BTADAQH/MAUGAytlcANBAMrDCYdBbubPvBusl2zV5DmUSD1GkM+S/Lkmy3cTXghN
+LwuiwCMepXO7f047/AN7AC21IlgyqnO8U7k6cUCF/Qk=
+-----END CERTIFICATE-----

server/config.py

@@ -35,8 +35,17 @@
 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 (the client must enable TLS as well)
+tls_cert = ''
+tls_key = ''
+# TODO entfernen:
+tls_cert = 'cert.pem'
+tls_key = 'key.pem'

server/game_server.py

@@ -28,6 +28,7 @@
 
 import json
 import socket
+import ssl
 import threading
 import traceback
 
@@ -57,7 +58,7 @@ def handle_connection(conn, ip, port):
     possible, error messages are sent back to the client.
 
     Parameters:
-    conn (socket): connection socket
+    conn (socket or SSLSocket): connection socket
     ip (str): client IP
     port (int): client port
     """
@@ -133,25 +134,57 @@ 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 an SSL socket. TLS must be
+    enabled in the config module. Otherwise, the passed socket is returned
+    unmodified.
+
+    Parameters:
+    socket (socket): listening socket
+    
+    Returns:
+    socket or SSLSocket: an SSL socket, if TLS is enabled, a regular socket otherwise
+    
+    Raises:
+    # TODO
+    """
+    if config.tls_cert and config.tls_key:
+        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)
+    
+    return socket
+
 print("""This is free software with ABSOLUTELY NO WARRANTY.
 Licensed under the GPL version 3 (see LICENSE).""")
 
 try:
+    print('Server starting')
+
     # 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(f'Listening on {config.ip}:{config.port}')
+        with secure_socket(sd) as sd:
+            print(f'Listening on {config.ip}:{config.port}')
 
-        while True:
-            # accept a connection:
-            conn, client = sd.accept()
-            ip, port = client
+            # accept connections and handle them in separate threads:
+            while True:
+                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()
+                threading.Thread(
+                    target=handle_connection,
+                    args=(conn, ip, port),
+                    daemon=True).start()
 except KeyboardInterrupt:
-    print('')
+    print('\nServer shutting down')

server/key.pem

@@ -0,0 +1,3 @@
+-----BEGIN PRIVATE KEY-----
+MC4CAQAwBQYDK2VwBCIEIKAFSUn9/JAK704eqW2hKNpT+NDoMaN7zHu40jMIok6q
+-----END PRIVATE KEY-----