Add support for self-signed certificates

Author: fguillot

LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2016-2022 Frederic Guillot
+Copyright (c) Frederic Guillot
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.rst

@@ -12,7 +12,7 @@ Installation
 
 .. code-block:: bash
 
-    pip install kanboard
+    python3 -m pip install kanboard
 
 
 This library is compatible with Python >= 3.5.
@@ -32,7 +32,7 @@ Examples
 Methods and arguments are the same as the JSON-RPC procedures described in the
 `official documentation <https://docs.kanboard.org/v1/api/>`_.
 
-Python methods are dynamically mapped to the API procedures. **You must use named arguments.**
+Python methods are dynamically mapped to the API procedures: **You must use named arguments**.
 
 By default, calls are made synchronously, meaning that they will block the program until completed.
 
@@ -68,6 +68,49 @@ Create a new task
     project_id = kb.create_project(name='My project')
     task_id = kb.create_task(project_id=project_id, title='My task title')
 
+SSL connection and self-signed certificates
+===========================================
+
+Example with a valid certificate:
+
+.. code-block:: python
+
+    import kanboard
+
+    kb = kanboard.Client('https://example.org/jsonrpc.php', 'admin', 'secret')
+    kb.get_my_projects()
+
+Example with a custom certificate:
+
+.. code-block:: python
+
+    import kanboard
+
+    kb = kanboard.Client('https://example.org/jsonrpc.php', 'admin', 'secret', cafile='/path/to/my/cert.pem')
+    kb.get_my_projects()
+
+Example with a custom certificate and hostname mismatch:
+
+.. code-block:: python
+
+    import kanboard
+
+    kb = kanboard.Client(url='https://example.org/jsonrpc.php',
+                         username='admin',
+                         password='secret',
+                         cafile='/path/to/my/cert.pem',
+                         ignore_hostname_verification=True)
+    kb.get_my_projects()
+
+Ignore invalid/expired certificates and hostname mismatches, which will make your application vulnerable to man-in-the-middle (MitM) attacks:
+
+.. code-block:: python
+
+    import kanboard
+
+    kb = kanboard.Client('https://example.org/jsonrpc.php', 'admin', 'secret', insecure=True)
+    kb.get_my_projects()
+
 Asynchronous I/O
 ================
 

kanboard.py

@@ -1,6 +1,6 @@
 # The MIT License (MIT)
 #
-# Copyright (c) 2016-2022 Frederic Guillot
+# Copyright (c) Frederic Guillot
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -24,6 +24,8 @@
 import base64
 import functools
 import asyncio
+import ssl
+from typing import Dict, Optional
 from urllib import request as http
 
 
@@ -52,12 +54,14 @@ class Client:
     """
 
     def __init__(self,
-                 url,
-                 username,
-                 password,
-                 auth_header=DEFAULT_AUTH_HEADER,
-                 cafile=None,
-                 loop=None):
+                 url: str,
+                 username: str,
+                 password: str,
+                 auth_header: str = DEFAULT_AUTH_HEADER,
+                 cafile: Optional[str] = None,
+                 insecure: bool = False,
+                 ignore_hostname_verification: bool = False,
+                 loop: Optional[asyncio.AbstractEventLoop] = None):
         """
         Constructor
 
@@ -66,22 +70,26 @@ def __init__(self,
             username: API username or real username
             password: API token or user password
             auth_header: API HTTP header
-            cafile: path to a custom CA certificate
-            loop: an asyncio event loop. Default: asyncio.get_event_loop()
+            cafile: Path to a custom CA certificate
+            insecure: Ignore SSL certificate errors and ignore hostname mismatches
+            ignore_hostname_verification: Ignore SSL certificate hostname verification
+            loop: An asyncio event loop. Default: asyncio.get_event_loop()
         """
         self._url = url
         self._username = username
         self._password = password
         self._auth_header = auth_header
         self._cafile = cafile
+        self._insecure = insecure
+        self._ignore_hostname_verification = ignore_hostname_verification
 
         if not loop:
             try:
                 self._event_loop = asyncio.get_event_loop()
             except RuntimeError:
                 self._event_loop = asyncio.new_event_loop()
 
-    def __getattr__(self, name):
+    def __getattr__(self, name: str):
         if self.is_async_method_name(name):
             async def function(*args, **kwargs):
                 return await self._event_loop.run_in_executor(
@@ -96,20 +104,20 @@ def function(*args, **kwargs):
             return function
 
     @staticmethod
-    def is_async_method_name(funcname):
+    def is_async_method_name(funcname: str) -> bool:
         return funcname.endswith(ASYNC_FUNCNAME_MARKER)
 
     @staticmethod
-    def get_funcname_from_async_name(funcname):
+    def get_funcname_from_async_name(funcname: str) -> str:
         return funcname[:len(funcname) - len(ASYNC_FUNCNAME_MARKER)]
 
     @staticmethod
-    def _to_camel_case(snake_str):
+    def _to_camel_case(snake_str: str) -> str:
         components = snake_str.split('_')
         return components[0] + ''.join(x.title() for x in components[1:])
 
     @staticmethod
-    def _parse_response(response):
+    def _parse_response(response: bytes):
         try:
             body = json.loads(response.decode(errors='ignore'))
 
@@ -121,20 +129,26 @@ def _parse_response(response):
         except ValueError:
             return None
 
-    def _do_request(self, headers, body):
+    def _do_request(self, headers: Dict[str, str], body: Dict):
         try:
             request = http.Request(self._url,
                                    headers=headers,
                                    data=json.dumps(body).encode())
-            if self._cafile:
-                response = http.urlopen(request, cafile=self._cafile).read()
-            else:
-                response = http.urlopen(request).read()
+
+            ssl_context = ssl.create_default_context(cafile=self._cafile)
+            if self._insecure:
+                ssl_context.check_hostname = False
+                ssl_context.verify_mode = ssl.CERT_NONE
+
+            if self._ignore_hostname_verification:
+                ssl_context.check_hostname = False
+
+            response = http.urlopen(request, context=ssl_context).read()
         except Exception as e:
             raise ClientError(str(e))
         return self._parse_response(response)
 
-    def execute(self, method, **kwargs):
+    def execute(self, method: str, **kwargs):
         """
         Call remote API procedure
 

setup.py

@@ -1,6 +1,6 @@
 # The MIT License (MIT)
 #
-# Copyright (c) 2016-2022 Frederic Guillot
+# Copyright (c) Frederic Guillot
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal

test_kanboard.py

@@ -1,6 +1,6 @@
 # The MIT License (MIT)
 #
-# Copyright (c) 2016-2022 Frederic Guillot
+# Copyright (c) Frederic Guillot
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal